The HTTP API, end to end

Endpoints

All workflow routes live under /v1 and require a bearer token. Health and metrics routes are unauthenticated (infra-internal, no data).

Authentication

Pass your key as a bearer token on every /v1/workflows and /v1/artifacts request. Per-tenant keys carry fixed-window quotas enforced atomically across gateway replicas; the gateway only ever stores a hash of the key.

  -H "Authorization: Bearer $FOLDFORGE_API_KEY"

Submit a workflow

A workflow is a DAG of steps. Each step names a tool (rfdiffusion, proteinmpnn, boltz, af2), optional depends_on edges, and tool-specific params. The orchestrator validates the DAG (unique ids, no dangling deps, no cycles) before scheduling.

curl -X POST https://api.your-foldforge/v1/workflows \
  -H "Authorization: Bearer $FOLDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "design-then-fold",
    "steps": [
      { "id": "design", "tool": "rfdiffusion",
        "params": { "contigs": "100-100", "num_designs": 3 } },
      { "id": "seqs",   "tool": "proteinmpnn",
        "depends_on": ["design"],
        "params": { "num_sequences": 5 } },
      { "id": "fold",   "tool": "af2",
        "depends_on": ["seqs"],
        "params": { "msa_cache_policy": "USE_CACHE" } }
    ]
  }'

The response carries the workflow id and initial state. Use it to poll, stream, retry or cancel.

Get & list

Fetch a single workflow (with per-step status and progress), or list with pagination and an optional label filter.

curl https://api.your-foldforge/v1/workflows/$ID -H "Authorization: Bearer $KEY"
curl "https://api.your-foldforge/v1/workflows?limit=20" -H "Authorization: Bearer $KEY"

Stream progress

Subscribe to a workflow's event stream as Server-Sent Events. Frames carry whole-workflow state transitions and per-step progress as it runs; the stream is resumable across reconnects.

curl -N https://api.your-foldforge/v1/workflows/$ID/events \
  -H "Authorization: Bearer $KEY"

Retry & cancel

Retry re-queues only the failed steps of a workflow. Cancelling actually kills the GPU subprocess group, so the accelerator is freed rather than finishing work no one is waiting for.

curl -X POST https://api.your-foldforge/v1/workflows/$ID/retry  -H "Authorization: Bearer $KEY"
curl -X DELETE https://api.your-foldforge/v1/workflows/$ID     -H "Authorization: Bearer $KEY"

Artifacts

Results — predicted structures (PDB / CIF), designed sequences, and MSAs — are stored in S3-compatible object storage and referenced by key. Download streams straight through the gateway; large blobs never get inlined into API responses.

curl https://api.your-foldforge/v1/artifacts/artifacts/$SHA.pdb \
  -H "Authorization: Bearer $KEY" -o result.pdb

Health & metrics

Three unauthenticated, infra-internal routes: /v1/healthz (liveness — process is up), /v1/readyz (readiness — pings the orchestrator and DB end to end), and /metrics (Prometheus scrape).