API reference

Artifacts

Stored job results: list them by workflow port, inspect a manifest, upload inputs, download a whole zip or one record (?record=), and delete.

On this page

List your artifacts

GET/api/v1/artifacts

API key or token

One item per chainable manifest port.

Default never exposes job-row port=archive as a selectable bind port. Pass include_archive=true for /workflows/storage so users can download the job zip. Expired artifacts are omitted. Metadata-only. Search, source, sort and total apply across all pages.

Parameters

Query parameters
Name	Type	Description
`limit`	`integer`	Limits: `≥ 1, ≤ 100`
`offset`	`integer`	Limits: `≥ 0`
`data_kind`	`string`
`data_format`	`string`
`run_id`	`string`
`include_archive`	`boolean`	When true, also list zip `archive` ports, as the storage library does. By default only chainable ports are listed. Default: `false`
`q`	`string`	Words to match, all of them, against the artifact id, upload name, job or run name, tool, and output ports. Limits: `max length 200`
`source`	`string`	`run`, `job` or `upload`. One of: `"run", "job", "upload"`
`sort`	`string`	`newest` (default), `oldest`, `expiring` (soonest first, never-expiring last) or `largest`. Default: `"newest"`One of: `"newest", "oldest", "expiring", "largest"`

Example request

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

from cognichem_client import CogniChem

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

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

Responses

Successful Response · application/json · ArtifactListResponse

Response fields
Field	Type	Description
`has_more`	`boolean`	Default: `false`
`items[]`required	`ArtifactListItem[]`
items.`artifact_id`required	`string`
items.`created_at`	`string \| null`
items.`data_format`required	`string`
items.`data_kind`required	`string`
items.`expires_at`	`string \| null`
items.`is_virtual`	`boolean`	Default: `false`
items.`job_id`	`string \| null`
items.`job_name`	`string \| null`
items.`job_type`	`string \| null`
items.`name`	`string \| null`
items.`port`required	`string`
items.`record_count`	`integer`	Default: `0`
items.`run_id`	`string \| null`
items.`run_name`	`string \| null`
items.`size_bytes`	`integer`	Default: `0`
items.`step_id`	`string \| null`
`next_offset`	`integer \| null`
`total`	`integer \| null`

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.

Upload a CogniChem-compatible library artifact

POST/api/v1/artifacts

API key or token

cognichem_zip: validated result.zip with chainable manifest ports. raw_file: server packages an allowlisted PDB/SDF/SMILES file, mechanism, CSV compound table (table/csv), or PNG / JPEG figure (image/png or image/jpeg; at most 10 MB and 25 megapixels, metadata stripped).

Call GET /artifacts/usage as a preflight. Oversized bodies are rejected via Content-Length before the file is read into memory.

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

multipart/form-data

Request fields
Field	Type	Description
`data_format`	`string \| null`	Required for `raw_file` (e.g. pdb)
`data_kind`	`string \| null`	Required for `raw_file` (e.g. protein_structure)
`file`required	`string`	CogniChem zip or raw allowlisted file
`mode`required	`string`	`cognichem_zip` or `raw_file`

Example request

curl -X POST "https://api.cognichem.com/api/v1/artifacts" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F 'mode=MODE'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.artifacts.upload("file.zip")
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 · ArtifactResponse

Response fields
Field	Type	Description
`content_type`	`string`	Default: `"application/octet-stream"`
`created_at`	`string \| null`
`derived_from`	`string \| null`
`expires_at`	`string \| null`
`id`required	`string`
`is_virtual`	`boolean`	Default: `false`
`job_id`	`string \| null`
`job_name`	`string \| null`
`job_type`	`string \| null`
`manifest`	`object`
`name`	`string \| null`
`ports[]`	`ArtifactPortSummary[]`
ports.`data_format`required	`string`
ports.`data_kind`required	`string`
ports.`port`required	`string`
ports.`record_count`	`integer`	Default: `0`
`run_id`	`string \| null`
`run_name`	`string \| null`
`size_bytes`	`integer`	Default: `0`
`step_id`	`string \| null`

Example 201 response

{
  "content_type": "application/zip",
  "created_at": "2026-07-31T12:00:00+00:00",
  "expires_at": "2026-08-30T12:00:00+00:00",
  "id": "art-01JTESTEXAMPLE0000000000",
  "job_id": "job-abc123",
  "manifest": {
    "job_type": "autodockvina",
    "manifest_version": 1,
    "ports": {
      "archive": {
        "format": "zip",
        "kind": "archive",
        "record_count": 1,
        "records": [
          {
            "files": {
              "primary": "."
            },
            "id": "all"
          }
        ]
      },
      "poses": {
        "format": "pdbqt",
        "kind": "docking_poses",
        "record_count": 1,
        "records": [
          {
            "files": {
              "primary": "pocket-1/lig-0007_out.pdbqt"
            },
            "id": "lig-0007",
            "metrics": {
              "binding_affinity_kcal_mol": -9.4
            }
          }
        ]
      }
    },
    "warnings": []
  },
  "size_bytes": 4096
}

Error statuses
Status	When
`400`	Missing fields or unsupported mode
`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`	File/zip exceeds size cap or storage quota
`422`	Invalid zip/manifest or unsupported raw kind/format
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get artifact storage usage

GET/api/v1/artifacts/usage

API key or token

Return used_bytes, quota_bytes, artifact_count and tier.

Also by_source (bytes and count per run / job / upload), ttl_days for the caller's tier and the upload / download limits.

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.artifacts.usage()
print(result)

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

Responses

Successful Response · application/json · ArtifactUsageResponse

Response fields
Field	Type	Description
`artifact_count`required	`integer`
`by_source`	`ArtifactUsageBySource \| null`
by_source.`job`	`ArtifactSourceUsage`	Bytes and artifact count from one source.
by_source.job.`bytes`	`integer`	Default: `0`
by_source.job.`count`	`integer`	Default: `0`
by_source.`run`	`ArtifactSourceUsage`	Bytes and artifact count from one source.
by_source.run.`bytes`	`integer`	Default: `0`
by_source.run.`count`	`integer`	Default: `0`
by_source.`upload`	`ArtifactSourceUsage`	Bytes and artifact count from one source.
by_source.upload.`bytes`	`integer`	Default: `0`
by_source.upload.`count`	`integer`	Default: `0`
`limits`	`ArtifactLimits \| null`
limits.`download_max_bytes`required	`integer`
limits.`image_upload_max_bytes`required	`integer`
limits.`link_max_bytes`	`integer \| null`
limits.`raw_upload_max_bytes`required	`integer`
limits.`zip_upload_max_bytes`required	`integer`
`quota_bytes`required	`integer`
`tier`required	`integer`
`ttl_days`	`integer \| null`
`used_bytes`required	`integer`

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.

What deleting artifacts would touch

GET/api/v1/artifacts/impact

API key or token

Per artifact: derived artifacts deleted with it, jobs whose result it is, saved models trained from it, and active runs that produced or reference it. Advisory only; deletes are never blocked.

Parameters

Query parameters
Name	Type	Description
`ids`required	`string[]`	Artifact ids (at most 50). Ids you don't own are left out. Limits: `min items 1, max items 50`

Example request

curl "https://api.cognichem.com/api/v1/artifacts/impact?ids=IDS" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

import os

import httpx

response = httpx.get(
    "https://api.cognichem.com/api/v1/artifacts/impact",
    params={"ids": "IDS"},
    headers={"X-Api-Key": os.environ["COGNICHEM_API_KEY"]},
)
response.raise_for_status()
print(response.json())

Uses httpx; the Python SDK has no method for this endpoint.

Responses

Successful Response · application/json · ArtifactImpactResponse

Response fields
Field	Type	Description
`items[]`required	`ArtifactImpact[]`
items.`artifact_id`required	`string`
items.`derived[]`	`string[]`
items.`jobs[]`	`ArtifactImpactJob[]`
items.jobs.`artifact_id`	`string \| null`
items.jobs.`id`required	`string`
items.jobs.`job_name`	`string \| null`
items.jobs.`job_type`	`string \| null`
items.`models[]`	`ArtifactImpactModel[]`
items.models.`id`required	`string`
items.models.`model_type`	`string \| null`
items.models.`name`	`string \| null`
items.`runs[]`	`ArtifactImpactRun[]`
items.runs.`id`required	`string`
items.runs.`run_name`	`string \| null`
items.runs.`status`	`string \| null`

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 several artifacts

POST/api/v1/artifacts/bulk-delete

API key or token

Delete up to 50 artifacts, each with its derived artifacts.

Reports every id as deleted, not_found or failed; one failure doesn't stop the rest. deleted also lists derived artifacts removed with them. Send an Idempotency-Key to make a retry safe.

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 · BulkDeleteArtifactsRequest

Request fields
Field	Type	Description
`artifact_ids[]`required	`string[]`	Limits: `min items 1, max items 50`

Example request

curl -X POST "https://api.cognichem.com/api/v1/artifacts/bulk-delete" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "artifact_ids": [
    "ARTIFACT_IDS"
  ]
}'

import os
import uuid

import httpx

response = httpx.post(
    "https://api.cognichem.com/api/v1/artifacts/bulk-delete",
    headers={"X-Api-Key": os.environ["COGNICHEM_API_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json={"artifact_ids": ["ARTIFACT_IDS"]},
)
response.raise_for_status()
print(response.json())

Uses httpx; the Python SDK has no method for this endpoint.

Responses

Successful Response · application/json · BulkDeleteArtifactsResponse

Response fields
Field	Type	Description
`deleted[]`	`string[]`
`failed[]`	`BulkDeleteFailure[]`
failed.`artifact_id`required	`string`
failed.`detail`required	`string`
`not_found[]`	`string[]`

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 artifact

GET/api/v1/artifacts/{artifact_id}

API key or token

Return metadata and manifest summary for an owned artifact.

Parameters

Path parameters
Name	Type	Description
`artifact_id`required	`string`

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.artifacts.get("ARTIFACT_ID")
print(result)

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

Responses

Successful Response · application/json · ArtifactResponse

Response fields
Field	Type	Description
`content_type`	`string`	Default: `"application/octet-stream"`
`created_at`	`string \| null`
`derived_from`	`string \| null`
`expires_at`	`string \| null`
`id`required	`string`
`is_virtual`	`boolean`	Default: `false`
`job_id`	`string \| null`
`job_name`	`string \| null`
`job_type`	`string \| null`
`manifest`	`object`
`name`	`string \| null`
`ports[]`	`ArtifactPortSummary[]`
ports.`data_format`required	`string`
ports.`data_kind`required	`string`
ports.`port`required	`string`
ports.`record_count`	`integer`	Default: `0`
`run_id`	`string \| null`
`run_name`	`string \| null`
`size_bytes`	`integer`	Default: `0`
`step_id`	`string \| null`

Example 200 response

{
  "content_type": "application/zip",
  "created_at": "2026-07-31T12:00:00+00:00",
  "expires_at": "2026-08-30T12:00:00+00:00",
  "id": "art-01JTESTEXAMPLE0000000000",
  "job_id": "job-abc123",
  "manifest": {
    "job_type": "autodockvina",
    "manifest_version": 1,
    "ports": {
      "archive": {
        "format": "zip",
        "kind": "archive",
        "record_count": 1,
        "records": [
          {
            "files": {
              "primary": "."
            },
            "id": "all"
          }
        ]
      },
      "poses": {
        "format": "pdbqt",
        "kind": "docking_poses",
        "record_count": 1,
        "records": [
          {
            "files": {
              "primary": "pocket-1/lig-0007_out.pdbqt"
            },
            "id": "lig-0007",
            "metrics": {
              "binding_affinity_kcal_mol": -9.4
            }
          }
        ]
      }
    },
    "warnings": []
  },
  "size_bytes": 4096
}

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 artifact

DELETE/api/v1/artifacts/{artifact_id}

API key or token

Delete an owned artifact, its volume bytes, and its derived artifacts.

Jobs whose result was deleted lose their result link; see GET /artifacts/impact first.

Parameters

Path parameters
Name	Type	Description
`artifact_id`required	`string`

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/artifacts/ARTIFACT_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.artifacts.delete("ARTIFACT_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.

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.

Download artifact zip or one record member

GET/api/v1/artifacts/{artifact_id}/download

API key or token

Stream result.zip or a single record member.

Without record: whole-zip (virtual artifacts → 409). With record: volume-side member extract; virtual hops to parent.

Parameters

Path parameters
Name	Type	Description
`artifact_id`required	`string`

Query parameters
Name	Type	Description
`record`	`string`	When set, stream one manifest record member via volume-side extract. Omit for whole `result.zip`.
`port`	`string`	Optional port scope when record id is ambiguous.

Example request

curl "https://api.cognichem.com/api/v1/artifacts/ARTIFACT_ID/download" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.artifacts.download("ARTIFACT_ID", save_path=".")
print(result)

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

Responses

Successful Response · application/json

Response fields: any

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`	Artifact missing/not owned, or with `?record=`: `record_not_found` / `parent_not_found`.
`409`	Virtual whole-zip (no `record`), or `ambiguous_record` / `record_has_no_file` / `record_member_invalid`.
`410`	Virtual `?record=` when parent expired (`parent_expired`).
`413`	Whole zip or record member exceeds download size cap.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get a link that downloads the whole zip

POST/api/v1/artifacts/{artifact_id}/download-link

API key or token

Sign a link that streams the artifact's whole result.zip, at sizes above the direct download's limit.

Open the url before expires_at (a few minutes); the browser saves the file as it arrives. The link names this one artifact only.

Parameters

Path parameters
Name	Type	Description
`artifact_id`required	`string`

Example request

curl -X POST "https://api.cognichem.com/api/v1/artifacts/ARTIFACT_ID/download-link" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

import os

import httpx

response = httpx.post(
    "https://api.cognichem.com/api/v1/artifacts/ARTIFACT_ID/download-link",
    headers={"X-Api-Key": os.environ["COGNICHEM_API_KEY"]},
)
response.raise_for_status()
print(response.json())

Uses httpx; the Python SDK has no method for this endpoint.

Responses

Successful Response · application/json · ArtifactDownloadLinkResponse

Response fields
Field	Type	Description
`expires_at`required	`string`
`filename`required	`string`
`size_bytes`required	`integer`
`url`required	`string`	Open within a few minutes; it downloads the zip.

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`	Artifact missing, expired, or not yours.
`409`	Virtual artifact: it has no zip; download records.
`413`	Zip exceeds the download link size limit.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Download links are not available here.