Utilities API · Docs

Submit a utility process

POST/api/v1/utils/submit

API key or tokenCounts toward monthly limits

Endpoint to submit a utility 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 · UtilsSubmitRequest

Request fields
Field	Type	Description
`payload`required	`object`	The payload containing necessary data for the utility operation.
`utility_type`required	`string`	The type of utility to be performed (e.g., "convert").

Example request

curl -X POST "https://api.cognichem.com/api/v1/utils/submit" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "payload": {
    "input_data": "CCC",
    "input_format": "smiles",
    "output_format": "pdbblock"
  },
  "utility_type": "convert"
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.submit(
    utility_type="convert",
    payload={
        "input_data": "CCC",
        "input_format": "smiles",
        "output_format": "pdbblock",
    },
)
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.

List utility processes

GET/api/v1/utils/list

API key or token

Endpoint to list all utility jobs submitted by the current user.

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.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 utility status

GET/api/v1/utils/status

API key or token

Endpoint to get the status of a specific utility job.

Parameters

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

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.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 a utility result

GET/api/v1/utils/result

API key or token

Endpoint to get the result of a completed utility job.

Parameters

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

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.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 · UtilsResultResponse

Response fields
Field	Type	Description
`data`required	`any`	The result data from the utility operation.

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 a utility process

DELETE/api/v1/utils/delete

API key or token

Endpoint to delete a utility 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/utils/delete?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.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 a utility process

POST/api/v1/utils/cancel

API key or token

Cancel a running utility 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/utils/cancel?process_id=PROCESS_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.utils.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.