Jobs REST API

The Jobs API is how you run computational biology tools — protein structure prediction, molecular docking, ADMET analysis, and more — over HTTP. Reach for it when you want to submit a job, poll it to completion, and pull back results from your own server, CLI, or CI pipeline. The public guest orchestrator is the no-account entry point; authenticated job routes add persistence and account-scoped history. This page is the primary building block that sibling pages extend: Batch Jobs fan one tool out across many inputs, and Artifacts & Storage handles downloading the outputs a completed job produces.

Jobs API

Submit, monitor, and manage computational biology jobs. A submitted job runs on the compute backend; the web app records it against your account and forwards status back to you.

Base URL: https://www.ivybiosciences.com/api

Every route takes Authorization: Bearer ivy_... (or a Clerk JWT) unless its reference page says otherwise. The ivybloom CLI wraps the same operations (ivybloom jobs ...).

Submit Job

POST /api/v1/jobs (reference) takes tool_name and tool_input_parameters, plus optional project_id, job_title and chat_id.

curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "esmfold",
    "tool_input_parameters": {"protein_sequence": "MKFLILLFNILCLFPVLAADNH"},
    "job_title": "ESMFold test"
  }'

The response carries the new job's id and its initial status (PENDING).

Get Job Status

GET /api/v1/jobs/:jobId (reference) returns the current status and progress along with the rest of the record. To follow a job without polling, use the SSE job stream.

Get Job Details

GET /api/v1/jobs/:jobId (reference) returns the full job record, including the results and output artifact references of a finished job. GET /api/v1/jobs/batch?ids=... (reference) reads several jobs in one call. To download a finished job's files, GET /api/v1/jobs/:jobId/artifacts (reference) returns short-lived download links; see Artifacts & Storage.

List Jobs

GET /api/v1/jobs (reference) returns your jobs, 15 per page by default. Filter with projectId, status, type, q, start and end; page with page and pageSize.

Cancel or Rerun a Job

POST /api/v1/jobs/:jobId/cancel (reference) cancels a job that has not finished. POST /api/v1/jobs/:jobId/resubmit (reference) runs a job again as a new job, optionally with changed parameters. GET /api/v1/jobs/pricing (reference) lists the credit price of each tool before you submit.

Job Lineage

GET /api/v1/jobs/:jobId/lineage (reference) lists which job outputs fed a job you can read: one row per producer output, with the producer job, the output and the input slot it filled. A row includes the output's data type and preview only when you can read the producer job. POST /api/v1/jobs/:jobId/lineage (reference) records those sources for a job you can write to; every producer job must be one you can read, and every output must belong to its producer job, or nothing is recorded.

curl -X POST https://www.ivybiosciences.com/api/v1/jobs/<job_id>/lineage \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {"producer_job_id": "<producer_job_id>", "producer_output_id": "<output_id>", "input_slot": "protein_structure"}
    ]
  }'

Plates, readouts and other per-job data

The plate, readout and QC data you see on a job in the app is also under /api/v1/jobs/{jobId}/, with the same API key and the same access rules as the app: a project viewer can read a job's data but not change it, extract/pdb and extract/sdf serve only the job's owner, and a key scoped to some projects reaches only jobs in those projects. On most routes a job you cannot reach returns 404, the same as a job that does not exist; the reference gives each route's responses.

• Plate: read and save wells (plate), save the plate type (plate-config), list plate types (plate-types), undo the last plate update (undo).
• Readouts and QC: read and save readouts (readouts), upload a readout file (readouts/upload), read QC (qc, qc/metrics).
• Dose-response: fit curves (fit-curves), read stored fits (curve-fits).
• Candidates and ordering: study candidates (candidates), procurement items (procurement).
• Results and downloads: a result file's summary or raw text (artifact-content), which follow-up exports a job supports (context), a download link for one file by type (download/{artifactType}, including the generated fits, qc and procurement files) and the plate map CSV (download/plate-map).
• Files and records: a PDB or SDF from the job's ZIP output (extract/pdb, extract/sdf), extracted files (extractions), checkpoints (checkpoints), snapshots (snapshots/list), the latest manifest (manifest/latest, manifest/fetch), and SHA-256 checks of output files (artifacts/verify, artifacts/list-verifications).

Each route's parameters, bodies and responses are in the API reference.

curl https://www.ivybiosciences.com/api/v1/jobs/<job_id>/readouts \
  -H "Authorization: Bearer ivy_your_key"

Job Lifecycle

Full Status Enum

Read next

• Batch Jobs — fan-out parallel job submission
• Job Types Catalog — the tools you can submit
• Artifacts & Storage — download job outputs
• SSE Streaming — real-time status updates
• SDK Jobs — TypeScript SDK wrapper