Inference API · Docs

Submit an inference request

POST/api/v1/inference/submit

API key or tokenCounts toward monthly limits

Endpoint to submit a molecule inference job.

Parameters

Headers
Name	Type	Description
`Idempotency-Key`	`string`	A unique key (a UUID) for this request. Retrying with the same key and body returns the first result instead of repeating the work; the same key with a different body is a 409.

Request body

application/json · InferenceSubmitRequest

Request fields
Field	Type	Description
`model_name`required	`string`	The name of the model to use for inference.
`model_type`required	`string`	The type of the model for inference (e.g., "mpnn").
`payload`required	`object`	The input data for the inference.

Example request

curl -X POST "https://api.cognichem.com/api/v1/inference/submit" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "public-model-example",
  "model_type": "mpnn",
  "payload": {
    "input_data": [
      "CCO"
    ],
    "input_format": "smiles",
    "is_public_model": true
  }
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.submit(
    model_type="mpnn",
    model_name="public-model-example",
    payload={
        "input_data": ["CCO"],
        "input_format": "smiles",
        "is_public_model": True,
    },
)
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY. The SDK sends an Idempotency-Key; pass idempotency_key= to reuse one when you retry.

Responses

Successful Response · application/json · JobSubmitResponse

Response fields
Field	Type	Description
`process_id`required	`string`	Unique identifier of the submitted job.

Example 200 response

{
  "process_id": "fc-01HZXY9ABCDEF1234567890"
}

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Submit a batch of inference requests

POST/api/v1/inference/submit-batch

API key or tokenCounts toward monthly limits

Submit several molecule inference jobs in one request (sequential).

Parameters

Headers
Name	Type	Description
`Idempotency-Key`	`string`	A unique key (a UUID) for this request. Retrying with the same key and body returns the first result instead of repeating the work; the same key with a different body is a 409.

Request body

application/json · InferenceSubmitBatchRequest

Request fields
Field	Type	Description
`jobs[]`required	`InferenceSubmitRequest[]`	Non-empty list; capped to limit accidental overload. Limits: `min items 1, max items 50`
jobs.`model_name`required	`string`	The name of the model to use for inference.
jobs.`model_type`required	`string`	The type of the model for inference (e.g., "mpnn").
jobs.`payload`required	`object`	The input data for the inference.

Example request

curl -X POST "https://api.cognichem.com/api/v1/inference/submit-batch" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "jobs": [
    {
      "model_name": "public-model-example",
      "model_type": "mpnn",
      "payload": {
        "input_data": [
          "CCO"
        ],
        "input_format": "smiles",
        "is_public_model": true
      }
    }
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.submit_batch(
    [
        {
            "model_name": "public-model-example",
            "model_type": "mpnn",
            "payload": {
                "input_data": ["CCO"],
                "input_format": "smiles",
                "is_public_model": True,
            },
        },
    ],
)
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY. The SDK sends an Idempotency-Key; pass idempotency_key= to reuse one when you retry.

Responses

Successful Response · application/json · JobSubmitMultipleResponse

Response fields
Field	Type	Description
`process_ids[]`	`string[]`	List of unique identifiers for the submitted jobs. Default: `[]`

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

List inference requests

GET/api/v1/inference/list

API key or token

Endpoint to list all molecule inference job process IDs for the current user.

Example request

curl "https://api.cognichem.com/api/v1/inference/list" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.list()
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · ListPIDsResponse

Response fields
Field	Type	Description
`process_ids[]`	`string[]`	List of process IDs. Default: `[]`

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get inference status

GET/api/v1/inference/status

API key or token

Endpoint to get the status of a molecule inference job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/inference/status?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.status("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · JobStatusResponse

Response fields
Field	Type	Description
`message`	`string \| null`	An optional message providing additional information about the job status.
`process_id`required	`string`	The unique identifier for the job process.
`result_artifact_id`	`string \| null`	Durable result artifact id when `public.jobs.result_artifact_id` is set. Agents should inspect / `?record=` this id instead of downloading whole-zip `GET /jobs/result`.
`status`required	`string`	Closed set from cognichem-jobs-domain: `queued\|dispatched\|running\|completed\|error\|cancelled`. One of: `"queued", "dispatched", "running", "completed", "error", "cancelled"`

Example 200 response

{
  "process_id": "fc-01HZXY9ABCDEF1234567890",
  "result_artifact_id": "art-01HZXY9ABCDEF1234567890",
  "status": "completed"
}

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get an inference result

GET/api/v1/inference/result

API key or token

Endpoint to get the result of a completed molecule inference job.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl "https://api.cognichem.com/api/v1/inference/result?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.result("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · InferenceResultResponse

Response fields
Field	Type	Description
`data`required	`object`	The list of predictions from the MPNN model and the model's `unit`, among other data specified by input payload flags.

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Delete an inference request

DELETE/api/v1/inference/delete

API key or token

Endpoint to delete a molecule inference job record for the current user.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/inference/delete?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.delete("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · MessageResponse

Response fields
Field	Type	Description
`message`required	`string`	The message content.

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Cancel an inference request

POST/api/v1/inference/cancel

API key or token

Cancel a running inference process and mark it terminal.

Parameters

Query parameters
Name	Type	Description
`process_id`required	`string`

Example request

curl -X POST "https://api.cognichem.com/api/v1/inference/cancel?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.inference.cancel("PROCESS_ID")
print(result)

Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.

Responses

Successful Response · application/json · MessageResponse

Response fields
Field	Type	Description
`message`required	`string`	The message content.

Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	Conflict (e.g. idempotency key reuse with a different body).
`413`	Request body or workflow spec exceeds size caps.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.