Auth: required. Send an ivy_ API key (Authorization: Bearer ivy_… or X-Ivy-Api-Key), a Clerk session JWT (Authorization: Bearer …) or the Clerk __session cookie (browser sessions). See Authentication.

Queue one tool run as an asynchronous job owned by the caller. The response carries the new job id and its initial status; read the job back with GET /api/v1/jobs/{job_id} until it reaches a terminal status.

Request

Request body

tool_namestring

Tool to run, e.g. esmfold.

tool_input_parametersobject

The tool's input parameters.

job_titlestring

Human-readable title for the job.

project_idstring (uuid)

Project to file the job under. You must have access to it.

chat_idstring

Chat to attach the job to. You must own it.

Example

{
  "tool_name": "esmfold",
  "tool_input_parameters": {
    "protein_sequence": "MKFLILLFNILCLFPVLAADNH"
  },
  "job_title": "ESMFold test"
}

Responses

`201` Created

Job successfully created and dispatched

Response shape:

idstring (uuid)

Unique identifier for the created job. Use this to poll status or connect to WebSocket.

task_idstring | null

Modal task ID. May be null initially if job is queued.

job_typestring

Type of computation (echoed from request)

job_titlestring | null

Human-readable job title (echoed from request)

statusstring

Initial job status (typically 'pending')

created_atstring (date-time)

Job creation timestamp

updated_atstring (date-time)

Last update timestamp

messagestring

Human-readable status message

org_idstring | null

Organization ID if provided

team_idstring (uuid) | null

Team ID if provided

campaign_idstring (uuid) | null

Campaign ID if provided

campaign_scopeenum ("org" | "team" | "user") | null

Campaign scope if provided

chat_idstring | null

Chat ID if provided

credits_reservednumber

Credits held from your balance for this job when it was submitted. A hold is not the final charge: the job is charged when it finishes, against this hold. Absent when no hold was placed (for example, on an unlimited plan); the job is still charged when it finishes. An /api/v1/orchestrate turn reports the holds of the jobs it submitted in usage.gpu.

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

POST /api/v1/jobs

Request

Request body

Example

Responses

`201` Created

`400` Bad Request

`401` Unauthorized

`402`

`403` Forbidden

`404` Not Found

`429` Too Many Requests

`500` Internal Server Error