REST API reference

The Gnosys REST API lives at https://gnosyslabs.com/v1/*. The full machine-readable schema is at /v1/openapi.json — point your favourite OpenAPI tool (Postman, Insomnia, openapi-generator) at it to generate clients in any language.

This page is the human summary. For Python integration use the official SDK rather than building your own HTTP client; the SDK handles retries, auth, and error mapping.

Base URL

https://gnosyslabs.com

Authentication

Every endpoint requires an Authorization: Bearer gn_live_... header. Issue keys from the dashboard at /dashboard/api-keys.

curl -H "Authorization: Bearer $GNOSYS_API_KEY" \
     https://gnosyslabs.com/v1/api-keys

Responses include X-Request-Id — quote it in support tickets so we can find your call in our logs.

Endpoints

POST /v1/runs

Submit a new run. Returns 202 immediately with a run_id; poll for completion.

curl -X POST \
     -H "Authorization: Bearer $GNOSYS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "tabular",
       "strategist": {
         "kind": "hp_sweep",
         "key": "C",
         "values": [0.001, 0.01, 0.1, 1.0, 10.0]
       },
       "spec_template": {
         "spec_id": "_t",
         "name": "first run",
         "hypothesis": "regularisation strength",
         "task": "classification",
         "dataset_id": "synthetic_binary",
         "model_family": "logistic",
         "hyperparameters": {"C": 1.0}
       },
       "max_iterations": 4
     }' \
     https://gnosyslabs.com/v1/runs

Response (202):

{
  "run_id": "8e3c…",
  "status": "queued",
  "domain": "tabular",
  "created_at": "2026-05-08T16:00:00Z",
  "links": {
    "self": "/v1/runs/8e3c…",
    "iterations": "/v1/runs/8e3c…/iterations",
    "findings": "/v1/findings?run_id=8e3c…"
  }
}

Domains

• tabular — classification + regression on uploaded CSV / parquet (the SaaS product). Also tabular_regression as an alias.
• strategy — agent-code + RL competitions (preview, design-partner contracts only). See What's coming.

Strategists

Four strategist.kind values:

• fixed — emit specs once, no iteration. Requires specs: [...].
• hp_sweep — coarse grid then refine around the best. Requires spec_template, key, values. Optional: log_scale (bool), refine_n (int), patience (int), max_total_specs (int). No LLM cost — works on free tier.
• agent / llm — LLM proposes pipelines each round, sees prior validation findings as feedback. Requires spec_template. Set llm: {provider, model, ...}. Optional llm_critic: {enabled: true} for pre-execute adversarial review. Requires Starter+.

Sandboxed code execution

For tabular runs that need a higher ceiling than the curated spec space, pass enable_code_exec: true and (optionally) sandbox_config. The platform routes the run through the tabular_code executor, which runs LLM-generated Python in a Docker sandbox. Honest-eval fires the same way on the results.

{
  "domain": "tabular",
  "enable_code_exec": true,
  "sandbox_config": {
    "timeout_s": 600,
    "max_memory_mb": 4096
  },
  ...
}

Termination

The run loop stops on the first of these to fire:

• max_iterations (required, default 5)
• tier_reached: "paper" — stop once any record clears the strict promotion gate
• no_progress_window: 2 — stop if no improvement for N rounds

GET /v1/runs/{run_id}

{
  "run_id": "8e3c…",
  "tenant_id": "...",
  "domain": "tabular",
  "strategist": "fixed",
  "status": "completed",
  "error": null,
  "pipeline_run_id": "saas-8e3c…",
  "created_at": "...",
  "started_at": "...",
  "completed_at": "..."
}

status ∈ {queued, running, completed, failed}. Poll until terminal.

GET /v1/runs/{run_id}/progress

JSONL event stream. Long-poll style: the server holds the connection open and writes each event as a single JSON line. Use it to drive a live dashboard or to log the loop into your own observability stack.

Event types include iteration_start, spec_proposed, execution_started, validator_finding, tier_decision, iteration_end, run_complete.

GET /v1/runs/{run_id}/model_card

Returns a self-contained HTML model card (one document, inline CSS and SVG charts). Compliance-friendly artefact you can save to disk or attach to a model-risk review.

Query param: format=html (only supported value in v1). Other values return 400.

curl -H "Authorization: Bearer $GNOSYS_API_KEY" \
     https://gnosyslabs.com/v1/runs/8e3c…/model_card?format=html \
     -o model_card.html

POST /v1/runs/{run_id}/predict

Score new rows against the run's kept-spec ensemble. Multipart upload of CSV or parquet.

curl -X POST \
     -H "Authorization: Bearer $GNOSYS_API_KEY" \
     -F "file=@test.csv" \
     "https://gnosyslabs.com/v1/runs/8e3c…/predict?top_n=3"

Optional top_n selects only the top-N kept specs by primary score; default is to ensemble all kept specs. The returned probabilities are MCGrad-calibrated.

Status codes:

• 409 — run hasn't completed or kept zero specs.
• 422 — input columns don't match the model's features.
• 413 — upload exceeds GNOSYS_DATASET_MAX_BYTES.

POST /v1/runs/{run_id}/submission

Package the top spec as either a single main.py (tabular code runs) or a tarball with model artefacts (RL / strategy runs). Designed to drop directly into a Kaggle-style submission slot.

POST /v1/datasets

Multipart upload of CSV or parquet. Body params: file (required), name (required), task (classification / regression), target_column (required).

curl -X POST \
     -H "Authorization: Bearer $GNOSYS_API_KEY" \
     -F "file=@spaceship_titanic.csv" \
     -F "name=spaceship-titanic-train" \
     -F "task=classification" \
     -F "target_column=Transported" \
     https://gnosyslabs.com/v1/datasets

Returns the dataset_id you pass into the run's spec_template.

GET /v1/findings

Query validation findings. Filters AND together.

Response: list of finding objects with validator, severity, stage, detail, payload, spec_id, created_at.

GET /v1/correlations

Specs flagged by multiple validators.

curl -H "Authorization: Bearer $GNOSYS_API_KEY" \
     "https://gnosyslabs.com/v1/correlations?validators=llm_critic&validators=honest_eval.shuffled_label&mode=and&severity=blocker"

Returns specs satisfying the AND/OR predicate plus their findings inline.

Error responses

Every error returns JSON with at least detail describing what went wrong.

Rate limits

Per-tenant burst limit of 30 / min on the Starter plan, 60 / min on Team, 300 / min on Enterprise. The Free tier caps at 10 / min. The limit applies to POST /v1/runs only; reads are unrestricted.

Per-tenant monthly quota:

• Free: 5 runs / month
• Starter: 100 runs + 1M LLM tokens
• Team: 1000 runs + 10M LLM tokens
• Enterprise: unlimited

See Plans + limits for full pricing.

Versioning

The API is versioned by URL prefix. The current version is v1. Backwards-incompatible changes will introduce v2 rather than breaking v1. Within v1, additive changes (new fields, new endpoints, new optional params) ship without notice; clients should tolerate unknown fields.

OpenAPI schema

The full machine-readable schema is at /v1/openapi.json. Use it with:

• openapi-generator to generate clients in 50+ languages
• Insomnia / Postman to explore interactively
• Custom tooling — the schema is plain JSON

Found a typo? Tell us.