Skip to content

api.md

Latest commit

 

History

History
227 lines (158 loc) · 5.71 KB

api.md

File metadata and controls

227 lines (158 loc) · 5.71 KB
Raw

API Reference

This document covers all public endpoints exposed by the FastAPI backend.

Base URL (default): http://127.0.0.1:8642

  • REST prefix: /api
  • Progress WebSocket: /api/jobs/{job_id}/progress

Authentication

Authentication is optional and controlled by server startup config.

  • If API key authentication is enabled (--api-key or AF3_API_KEY), send:
    • Authorization: Bearer <token> for HTTP requests, or
    • ?token=<token> query parameter for WebSocket.
  • If API key authentication is disabled, no token is required.

Error Handling

  • Validation failures in request schemas return FastAPI 422 responses.
  • Domain-level validation in /api/validate is returned in the response body (valid=false) instead of raising an HTTP error.
  • Common status codes: 400, 403, 404, 409, 422, 429, 500, 502, 504.

Jobs Endpoints

POST /api/jobs

Submit a new prediction job.

  • Request body: JobSubmission
    • Includes job metadata, sequences/entities, seeds, optional restraints, and runtime overrides.
  • Response: JobCreated
    • Includes job ID and initial status.
  • Errors:
    • 429 when queue capacity is exceeded.

GET /api/jobs

List jobs with filters and pagination.

  • Query parameters:
    • status (optional)
    • search (optional)
    • page (>= 1)
    • page_size (1-100)
  • Response: PaginatedJobs
    • Includes list of JobSummary items and pagination metadata.

GET /api/jobs/{job_id}

Get full details for one job.

  • Response: JobDetail
  • Errors:
    • 404 when job is not found.

POST /api/jobs/{job_id}/cancel

Cancel a pending or running job.

  • Response: { "status": "cancelled" }
  • Errors:
    • 404 if job does not exist.
    • 400 if job is already terminal.
    • 409 if cancellation races with terminal completion.

DELETE /api/jobs/{job_id}

Delete a terminal job (completed, failed, cancelled).

  • Response: { "status": "deleted" }
  • Errors:
    • 404 if job does not exist.
    • 400 if job is still pending/running.

Results Endpoints

GET /api/jobs/{job_id}/results

Return aggregate confidence output for a completed job.

  • Response: ConfidenceResult
    • Top-level metrics, sample list, best sample index, complex flag.
  • Errors:
    • 404 missing job or confidence file.
    • 400 job not completed.
    • 500 confidence file cannot be parsed.

GET /api/jobs/{job_id}/results/confidence/{sample_index}

Return per-sample confidence details.

  • Response: SampleConfidence
    • Includes per-sample pLDDT/PAE arrays and optional restraint satisfaction details.
  • Errors:
    • 404 missing job or sample.

GET /api/jobs/{job_id}/results/confidence-json

Download raw confidence JSON file.

  • Response: application/json file response.
  • Errors:
    • 404 missing job or confidence file.
    • 400 job not completed.

GET /api/jobs/{job_id}/results/download

Download ZIP archive of job outputs.

  • Response: ZIP stream (application/zip)
  • Errors:
    • 404 missing job or output directory.
    • 400 job not completed.

POST /api/jobs/{job_id}/results/open-directory

Open output directory in Finder.

  • Response: { "status": "opened" }
  • Security limits:
    • Localhost only request origin.
    • macOS only.
  • Errors:
    • 400 when unsupported platform.
    • 403 when not local request.
    • 404 missing job or directory.

GET /api/jobs/{job_id}/results/structure/{rank}

Download one ranked structure as mmCIF.

  • Response: chemical/x-mmcif file response.
  • Errors:
    • 404 missing job or structure file.
    • 400 job not completed.

Validation and Cache

POST /api/validate

Run input validation without starting a job.

  • Request body: ValidationRequest
  • Response: ValidationResult
    • valid boolean
    • error list
    • estimated memory and sequence stats

POST /api/cache/check

Check if MSA/template data is already cached for input sequences.

  • Request body: CacheCheckRequest
  • Response: CacheCheckResponse
    • cached boolean
    • optional cache key, timestamp, and size

System

GET /api/system/status

Return backend readiness and runtime environment info.

  • Response: SystemStatus
    • Model loaded state
    • Hardware summary
    • Queue size
    • Version/build metadata
    • Pipeline mode flag

Structure Import

POST /api/structure/parse

Parse an uploaded structure file (.pdb, .cif, .mmcif) into supported input JSON.

  • Request: multipart/form-data with file field
  • Response: StructureParseResult
  • Errors:
    • 422 on unsupported extension or parse failure.

GET /api/structure/fetch/{pdb_id}

Fetch a structure by PDB ID from RCSB and convert to input JSON.

  • Response: StructureParseResult
  • Errors:
    • 422 malformed PDB ID or value errors.
    • 404 PDB ID not found upstream.
    • 504 upstream timeout.
    • 502 upstream service or network failure.

WebSocket Progress Stream

WS /api/jobs/{job_id}/progress

Real-time job progress stream used by the web UI.

  • Message payload: serialized progress objects (type, stage/progress fields, terminal events).
  • Idle keepalive: periodic ping payloads.
  • Authentication:
    • If API key is enabled, token query parameter is required.
  • Origin policy:
    • Origin must match host, localhost, or configured CORS origins.
  • Close/error codes:
    • 4001 invalid or missing token.
    • 4003 origin rejected.
    • 4004 unknown job.

Minimal curl Examples

# System status
curl http://127.0.0.1:8642/api/system/status

# Submit job
curl -X POST http://127.0.0.1:8642/api/jobs \
  -H 'Content-Type: application/json' \
  -d @examples/desi1_monomer.json

# Validate without enqueueing
curl -X POST http://127.0.0.1:8642/api/validate \
  -H 'Content-Type: application/json' \
  -d @examples/desi1_monomer.json