Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    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.

    Parameters

    Query parameters
    NameTypeDescription
    limitinteger

    Limits: ≥ 1, ≤ 100

    offsetinteger

    Limits: ≥ 0

    data_kindstring
    data_formatstring
    run_idstring
    include_archiveboolean

    When true, also list zip archive ports, as the storage library does. By default only chainable ports are listed.

    Default: false

    Example request

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

    Responses

    Successful Response · application/json · ArtifactListResponse

    Response fields
    FieldTypeDescription
    has_moreboolean

    Default: false

    items[]requiredArtifactListItem[]
    items.artifact_idrequiredstring
    items.created_atstring | null
    items.data_formatrequiredstring
    items.data_kindrequiredstring
    items.expires_atstring | null
    items.is_virtualboolean

    Default: false

    items.job_idstring | null
    items.job_namestring | null
    items.job_typestring | null
    items.portrequiredstring
    items.record_countinteger

    Default: 0

    items.run_idstring | null
    items.run_namestring | null
    items.size_bytesinteger

    Default: 0

    items.step_idstring | null
    next_offsetinteger | null

    Upload a CogniChem-compatible library artifact

    POST/api/v1/artifacts

    API key or token

    Register a durable library artifact from an upload.

    cognichem_zip: validated result.zip with chainable manifest ports. raw_file: server packages an allowlisted PDB/SDF/SMILES file.

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

    Parameters

    Headers
    NameTypeDescription
    Idempotency-Keystring

    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
    FieldTypeDescription
    data_formatstring | null

    Required for raw_file (e.g. pdb)

    data_kindstring | null

    Required for raw_file (e.g. protein_structure)

    filerequiredstring

    CogniChem zip or raw allowlisted file

    moderequiredstring

    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'

    Responses

    Successful Response · application/json · ArtifactResponse

    Response fields
    FieldTypeDescription
    content_typestring

    Default: "application/octet-stream"

    created_atstring | null
    expires_atstring | null
    idrequiredstring
    job_idstring | null
    manifestobject
    size_bytesinteger

    Default: 0

    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
}

    Get artifact storage usage

    GET/api/v1/artifacts/usage

    API key or token

    Return used_bytes, quota_bytes, artifact_count, and tier.

    Example request

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

    Responses

    Successful Response · application/json · ArtifactUsageResponse

    Response fields
    FieldTypeDescription
    artifact_countrequiredinteger
    quota_bytesrequiredinteger
    tierrequiredinteger
    used_bytesrequiredinteger

    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
    NameTypeDescription
    artifact_idrequiredstring

    Example request

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

    Responses

    Successful Response · application/json · ArtifactResponse

    Response fields
    FieldTypeDescription
    content_typestring

    Default: "application/octet-stream"

    created_atstring | null
    expires_atstring | null
    idrequiredstring
    job_idstring | null
    manifestobject
    size_bytesinteger

    Default: 0

    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
}

    Delete an artifact

    DELETE/api/v1/artifacts/{artifact_id}

    API key or token

    Delete volume prefix and metadata for an owned artifact.

    Parameters

    Path parameters
    NameTypeDescription
    artifact_idrequiredstring

    Example request

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

    Responses

    Successful Response · application/json · MessageResponse

    Response fields
    FieldTypeDescription
    messagerequiredstring

    The message content.

    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
    NameTypeDescription
    artifact_idrequiredstring
    Query parameters
    NameTypeDescription
    recordstring

    When set, stream one manifest record member via volume-side extract. Omit for whole result.zip.

    portstring

    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"

    Responses

    Successful Response · application/json

    Response fields: any