API reference

Workflows

Validate and estimate workflows, start and track runs, and save or share workflow definitions.

On this page

Validate a WorkflowSpec

POST/api/v1/workflows/validate

API key or token

Dry-run validate a WorkflowSpec.

Well-formed but invalid specs return 200 with valid: false. Oversized specs (over_cap_bytes) return 413 with Diagnostic[]. No database writes beyond authentication / tier lookup.

Request body

application/json · ValidateWorkflowRequest

Request fields
Field	Type	Description
`params`	`object \| null`	Optional runtime param values. Omit for dry-run without bind completeness; supply to check missing_param / unknown_param.
`spec`required	`object`	WorkflowSpec document (may include top-level graph_layout).

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/validate" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spec": {
    "limits": {
      "on_step_failure": "fail_fast"
    },
    "name": "vina-boltz-linear",
    "params": {},
    "spec_version": 1,
    "steps": [
      {
        "id": "dock",
        "inputs": {},
        "job_type": "autodockvina",
        "mode": "batch",
        "resource": "cpu",
        "type": "job"
      },
      {
        "id": "repredict",
        "inputs": {
          "ligands": {
            "$from": "dock.poses"
          }
        },
        "job_type": "boltz2",
        "mode": "batch",
        "resource": "a10",
        "type": "job"
      }
    ]
  }
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.validate(
    {
        "limits": {"on_step_failure": "fail_fast"},
        "name": "vina-boltz-linear",
        "params": {},
        "spec_version": 1,
        "steps": [
            {
                "id": "dock",
                "inputs": {},
                "job_type": "autodockvina",
                "mode": "batch",
                "resource": "cpu",
                "type": "job",
            },
            {
                "id": "repredict",
                "inputs": {"ligands": {"$from": "dock.poses"}},
                "job_type": "boltz2",
                "mode": "batch",
                "resource": "a10",
                "type": "job",
            },
        ],
    },
)
print(result)

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

Responses

Always returned for a well-formed envelope. `valid: false` with Diagnostic[] in `errors` when the spec is invalid. Malformed request bodies use the shared envelope 422 (Pydantic loc/msg). Caller tier is passed so `fanout_tier_capped` warnings can fire. · application/json · ValidateWorkflowResponse

Response fields
Field	Type	Description
`errors[]`required	`DiagnosticModel[]`
errors.`code`required	`string`
errors.`message`required	`string`
errors.`path`	`string \| null`
errors.`port`	`string \| null`
errors.`step_id`	`string \| null`
`order[]`required	`string[]`
`step_count`required	`integer`
`valid`required	`boolean`
`warnings[]`required	`DiagnosticModel[]`
warnings.`code`required	`string`
warnings.`message`required	`string`
warnings.`path`	`string \| null`
warnings.`port`	`string \| null`
warnings.`step_id`	`string \| null`

Example 200 response

{
  "errors": [],
  "order": [
    "dock",
    "repredict"
  ],
  "step_count": 2,
  "valid": true,
  "warnings": [
    {
      "code": "params_not_supplied",
      "message": "Spec declares params but none were supplied."
    }
  ]
}

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`	Spec, graph_layout, or create-body exceeds size caps (Diagnostic[]). Create-body oversize uses `path: /create_body`; spec uses `/`; layout uses `/graph_layout`.
`422`	Request body or query failed validation.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Estimate a workflow run's cost

POST/api/v1/workflows/estimate

API key or token

Upper-bound soft-hold estimate.

Same catalog formula and caller tier as create. Validate-first; runtime params scale per-step reservations via catalog scalers. No wallet debit or run row.

Request body

application/json · EstimateWorkflowRequest

Request fields
Field	Type	Description
`params`	`object \| null`	Optional runtime param values (validate-first + payload-aware reservation scaling via catalog reservation scalers).
`spec`required	`object`	WorkflowSpec document (may include top-level graph_layout).

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/estimate" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spec": {
    "limits": {
      "on_step_failure": "fail_fast"
    },
    "name": "vina-boltz-linear",
    "params": {},
    "spec_version": 1,
    "steps": [
      {
        "id": "dock",
        "inputs": {},
        "job_type": "autodockvina",
        "mode": "batch",
        "resource": "cpu",
        "type": "job"
      },
      {
        "id": "repredict",
        "inputs": {
          "ligands": {
            "$from": "dock.poses"
          }
        },
        "job_type": "boltz2",
        "mode": "batch",
        "resource": "a10",
        "type": "job"
      }
    ]
  }
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.estimate(
    {
        "limits": {"on_step_failure": "fail_fast"},
        "name": "vina-boltz-linear",
        "params": {},
        "spec_version": 1,
        "steps": [
            {
                "id": "dock",
                "inputs": {},
                "job_type": "autodockvina",
                "mode": "batch",
                "resource": "cpu",
                "type": "job",
            },
            {
                "id": "repredict",
                "inputs": {"ligands": {"$from": "dock.poses"}},
                "job_type": "boltz2",
                "mode": "batch",
                "resource": "a10",
                "type": "job",
            },
        ],
    },
)
print(result)

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

Responses

Successful Response · application/json · EstimateWorkflowResponse

Response fields
Field	Type	Description
`assumptions[]`required	`EstimateAssumption[]`
assumptions.`cost`	`number \| null`
assumptions.`expected_runtime_sec`	`number \| null`
assumptions.`input_counts`	`map<string, EstimateInputCount> \| null`
assumptions.`job_type`	`string \| null`
assumptions.`max_fanout`	`integer \| null`
assumptions.`multiplier`	`integer`	Default: `1`
assumptions.`payload_scaled`	`boolean \| null`
assumptions.`rate_per_sec`	`number \| null`
assumptions.`reason`required	`string`
assumptions.`resource`	`string \| null`
assumptions.`scaler_inputs`	`object \| null`
assumptions.`static_k`	`integer \| null`
assumptions.`step_id`required	`string`
assumptions.`tier_cap`	`integer \| null`
assumptions.`u`	`integer \| null`
assumptions.`unit_cost`	`number \| null`
assumptions.`unresolved_binds[]`	`string[] \| null`
`per_step[]`required	`EstimateStepCost[]`
per_step.`cost`required	`number`
per_step.`step_id`required	`string`
`tier`required	`integer`
`timing_assumptions[]`	`TimingAssumption[]`
timing_assumptions.`code`required	`string`
timing_assumptions.`effective_fanout`	`integer \| null`
timing_assumptions.`max_fanout`	`integer \| null`
timing_assumptions.`message`	`string \| null`
timing_assumptions.`mode`	`string \| null`
timing_assumptions.`resource`	`string \| null`
timing_assumptions.`step_id`	`string \| null`
timing_assumptions.`tier_cap`	`integer \| null`
`total`required	`number`
`warnings[]`	`DiagnosticModel[]`
warnings.`code`required	`string`
warnings.`message`required	`string`
warnings.`path`	`string \| null`
warnings.`port`	`string \| null`
warnings.`step_id`	`string \| null`

Example 200 response

{
  "assumptions": [
    {
      "cost": 0.25,
      "input_counts": {
        "ligands": {
          "basis": "propagated",
          "count": 25,
          "exceeds_max_items": false,
          "max_items": 100,
          "source": "embed3d.molecules"
        }
      },
      "job_type": "autodockvina",
      "multiplier": 1,
      "reason": "static",
      "resource": "cpu",
      "step_id": "dock",
      "unit_cost": 0.25
    }
  ],
  "per_step": [
    {
      "cost": 0.25,
      "step_id": "dock"
    },
    {
      "cost": 1,
      "step_id": "repredict"
    }
  ],
  "tier": 1,
  "timing_assumptions": [
    {
      "code": "gpu_concurrency_ceiling",
      "effective_fanout": 10,
      "message": "Platform GPU concurrency is capped near 10 containers; large GPU fan-outs may queue (not a live queue depth)."
    }
  ],
  "total": 1.25
}

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`	Spec, graph_layout, or create-body exceeds size caps (Diagnostic[]). Create-body oversize uses `path: /create_body`; spec uses `/`; layout uses `/graph_layout`.
`422`	Spec validation or estimate failure. Never returns a bogus $0 total for a failed estimate.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

List curated workflow templates

GET/api/v1/workflows/templates

API key or token

Curated template outlines (step job types, param names) in gallery order.

Read scope; no database access. Fetch one full WorkflowSpec with GET /workflows/templates/{template_id}.

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.templates()
print(result)

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

Responses

Successful Response · application/json · WorkflowTemplateListResponse

Response fields
Field	Type	Description
`templates[]`required	`WorkflowTemplateSummary[]`
templates.`complexity`required	`string`
templates.`family`required	`string`	Problem family id the template belongs to.
templates.`id`required	`string`
templates.`name`required	`string`	Pipeline summary, e.g. `SMILES → embed → dock`.
templates.`params[]`required	`string[]`
templates.`steps[]`required	`WorkflowTemplateStep[]`
templates.steps.`id`required	`string`
templates.steps.`job_type`	`string \| null`
templates.steps.`op`	`string \| null`
templates.steps.`type`required	`string`
templates.`summary`required	`string`
templates.`title`required	`string`	The problem the template solves.

Example 200 response

{
  "templates": [
    {
      "complexity": "simple",
      "family": "virtual-screening",
      "id": "smiles-embed-dock",
      "name": "SMILES → 3D embed → dock",
      "params": [
        "ligands",
        "target_structure"
      ],
      "steps": [
        {
          "id": "embed3d",
          "job_type": "convert-batch",
          "type": "job"
        },
        {
          "id": "dock",
          "job_type": "autodockvina",
          "type": "job"
        }
      ],
      "summary": "Convert SMILES to 3D structures, detect pockets, then dock with AutoDock Vina.",
      "title": "Screen a compound library against a target"
    }
  ]
}

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 one curated workflow template

GET/api/v1/workflows/templates/{template_id}

API key or token

Return one template with its full WorkflowSpec (no graph_layout).

Parameters

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

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.template("TEMPLATE_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowTemplateResponse

Response fields
Field	Type	Description
`complexity`required	`string`
`family`required	`string`	Problem family id the template belongs to.
`id`required	`string`
`name`required	`string`	Pipeline summary (the spec name).
`spec`required	`object`
`summary`required	`string`
`title`required	`string`	The problem the template solves.

Example 200 response

{
  "complexity": "simple",
  "family": "virtual-screening",
  "id": "vina-boltz-linear",
  "name": "vina-boltz-linear",
  "spec": {
    "limits": {
      "on_step_failure": "fail_fast"
    },
    "name": "vina-boltz-linear",
    "params": {},
    "spec_version": 1,
    "steps": [
      {
        "id": "dock",
        "inputs": {},
        "job_type": "autodockvina",
        "mode": "batch",
        "resource": "cpu",
        "type": "job"
      },
      {
        "id": "repredict",
        "inputs": {
          "ligands": {
            "$from": "dock.poses"
          }
        },
        "job_type": "boltz2",
        "mode": "batch",
        "resource": "a10",
        "type": "job"
      }
    ]
  },
  "summary": "Dock with Vina, then re-predict with Boltz-2.",
  "title": "Re-predict docking hits with Boltz-2 affinities"
}

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`	Unknown `template_id`.
`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 catalog workflow ports for a job type

GET/api/v1/workflows/node-ports

API key or token

Input and output ports so $from edges and $param binds are valid.

Parameters

Query parameters
Name	Type	Description
`job_type`required	`string`	Catalog job type. Limits: `min length 1`

Example request

curl "https://api.cognichem.com/api/v1/workflows/node-ports?job_type=JOB_TYPE" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.node_ports("JOB_TYPE")
print(result)

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

Responses

Successful Response · application/json · WorkflowNodePortsResponse

Response fields
Field	Type	Description
`inputs`required	`object`
`job_type`required	`string`
`outputs`required	`object`

Example 200 response

{
  "inputs": {
    "molecules": {
      "cardinality": "many",
      "formats": [
        "smiles"
      ],
      "kind": "molecule_set",
      "max_items": 10000,
      "payload_field": "input_data",
      "required": true
    }
  },
  "job_type": "padel-descriptor",
  "outputs": {
    "archive": {
      "format": "zip",
      "kind": "archive",
      "resolver": "passthrough"
    },
    "descriptors": {
      "format": "csv",
      "kind": "table",
      "metrics": [],
      "resolver": "padel_descriptor"
    }
  }
}

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`	Unknown `job_type`.
`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 workflow runs

GET/api/v1/workflows/runs

API key or token

Paginated owned runs without spec, params, or steps.

Parameters

Query parameters
Name	Type	Description
`limit`	`integer`	Limits: `≥ 1, ≤ 100`
`offset`	`integer`	Limits: `≥ 0`
`status`	`string`	Optional run status filter (pending\|running\|paused\|…). One of: `"pending", "running", "paused", "completed", "failed", "cancelled"`

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.list()
print(result)

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

Responses

Successful Response · application/json · WorkflowRunListResponse

Response fields
Field	Type	Description
`items[]`required	`WorkflowRunListItem[]`
items.`charged_amount`	`number`	Default: `0`
items.`created_at`	`string \| null`
items.`definition_id`	`string \| null`
items.`estimated_cost`	`number`	Default: `0`
items.`finished_at`	`string \| null`
items.`id`required	`string`
items.`max_run_cost`	`number \| null`
items.`remaining_hold`	`number`	Default: `0`
items.`run_name`required	`string`
items.`status`required	`string`
items.`status_message`	`string`	Default: `""`
items.`step_counts`	`object`
items.`updated_at`	`string \| null`
`limit`required	`integer`
`offset`required	`integer`
`total`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`	Invalid `status` query value (operational string detail).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Create a workflow run

POST/api/v1/workflows/runs

API key or tokenCharges your wallet

Create a workflow run from an inline WorkflowSpec.

The request body is capped at 48 MiB (path: /create_body). The spec is validated against the job catalog, then estimated_cost is held on your wallet until the run settles; if the estimate fails, no run is created.

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

Request fields
Field	Type	Description
`definition_id`	`string \| null`	Optional FK to a saved definition (`wfd-…`). Spec is frozen on the run; later definition edits do not change this run.
`max_run_cost`	`number \| null`	Optional spend cap; run pauses when exceeded.
`params`	`object`
`run_name`required	`string`	Limits: `min length 1`
`spec`required	`object`	Inline WorkflowSpec, frozen when the run is created. Filters are validated at create; scatter steps are rejected.

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/runs" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "run_name": "vina-boltz-demo",
  "spec": {
    "limits": {
      "on_step_failure": "fail_fast"
    },
    "name": "vina-boltz-linear",
    "params": {},
    "spec_version": 1,
    "steps": [
      {
        "id": "dock",
        "inputs": {},
        "job_type": "autodockvina",
        "mode": "batch",
        "resource": "cpu",
        "type": "job"
      },
      {
        "id": "repredict",
        "inputs": {
          "ligands": {
            "$from": "dock.poses"
          }
        },
        "job_type": "boltz2",
        "mode": "batch",
        "resource": "a10",
        "type": "job"
      }
    ]
  }
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.create(
    run_name="vina-boltz-demo",
    spec={
        "limits": {"on_step_failure": "fail_fast"},
        "name": "vina-boltz-linear",
        "params": {},
        "spec_version": 1,
        "steps": [
            {
                "id": "dock",
                "inputs": {},
                "job_type": "autodockvina",
                "mode": "batch",
                "resource": "cpu",
                "type": "job",
            },
            {
                "id": "repredict",
                "inputs": {"ligands": {"$from": "dock.poses"}},
                "job_type": "boltz2",
                "mode": "batch",
                "resource": "a10",
                "type": "job",
            },
        ],
    },
)
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 · WorkflowRunResponse

Response fields
Field	Type	Description
`charged_amount`	`number`	Default: `0`
`created_at`	`string \| null`
`definition_id`	`string \| null`
`estimated_cost`	`number`	Default: `0`
`finished_at`	`string \| null`
`id`required	`string`
`max_run_cost`	`number \| null`
`remaining_hold`	`number`	Default: `0`
`run_name`required	`string`
`spec`	`object \| null`
`status`required	`string`
`status_message`	`string`	Default: `""`
`step_counts`	`object`
`steps[]`	`WorkflowStepSummary[]`
steps.`id`required	`string`
steps.`job_id`	`string \| null`
steps.`job_type`	`string \| null`
steps.`status`required	`string`
steps.`status_message`	`string`	Default: `""`
steps.`step_index`	`integer`	Default: `0`
steps.`step_key`required	`string`
`updated_at`	`string \| null`
`warnings[]`	`object[]`

Error statuses
Status	When
`400`	Operational create failure: `invalid_run_name`, `insufficient_wallet`.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	`definition_not_found` when `definition_id` is set but missing or not owned.
`409`	`duplicate_run_name` — run name already used by this user.
`413`	Spec, graph_layout, or create-body exceeds size caps (Diagnostic[]). Create-body oversize uses `path: /create_body`; spec uses `/`; layout uses `/graph_layout`.
`422`	Spec validation or estimate failure. Create is stricter than pre-Phase-5 and rejects when estimate fails instead of a $0 hold.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

List artifacts for a workflow run

GET/api/v1/workflows/runs/{run_id}/artifacts

API key or token

Artifacts for a run you own, each with the step_key and step_index of the step that produced it.

Parameters

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

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.artifacts("RUN_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowRunArtifactsResponse

Response fields
Field	Type	Description
`items[]`required	`WorkflowRunArtifactItem[]`
items.`artifact_id`required	`string`
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.`port`required	`string`
items.`record_count`	`integer`	Default: `0`
items.`size_bytes`	`integer`	Default: `0`
items.`step_index`	`integer \| null`
items.`step_key`	`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`	Run missing or not owned.
`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 workflow run

GET/api/v1/workflows/runs/{run_id}

API key or token

Return run status, step_counts, and a per-step summary (wfr-…).

Parameters

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

Query parameters
Name	Type	Description
`include_spec`	`integer`	When 1, add frozen `spec` and `definition_id` only. Default response stays Phase-5 field-identical. `params` are never returned. Default: `0`Limits: `≥ 0, ≤ 1`

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.get("RUN_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowRunResponse

Response fields
Field	Type	Description
`charged_amount`	`number`	Default: `0`
`created_at`	`string \| null`
`definition_id`	`string \| null`
`estimated_cost`	`number`	Default: `0`
`finished_at`	`string \| null`
`id`required	`string`
`max_run_cost`	`number \| null`
`remaining_hold`	`number`	Default: `0`
`run_name`required	`string`
`spec`	`object \| null`
`status`required	`string`
`status_message`	`string`	Default: `""`
`step_counts`	`object`
`steps[]`	`WorkflowStepSummary[]`
steps.`id`required	`string`
steps.`job_id`	`string \| null`
steps.`job_type`	`string \| null`
steps.`status`required	`string`
steps.`status_message`	`string`	Default: `""`
steps.`step_index`	`integer`	Default: `0`
steps.`step_key`required	`string`
`updated_at`	`string \| null`
`warnings[]`	`object[]`

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 workflow run

DELETE/api/v1/workflows/runs/{run_id}

API key or token

Delete a workflow run owned by the current user.

Removes run/step history only. Non-terminal runs are cancelled first. Artifacts remain in storage (detached run_id) and stay pickable as $artifact inputs until TTL/GC. Linked jobs are kept with FK nulls.

Parameters

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

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/workflows/runs/RUN_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.delete("RUN_ID")
print(result)

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

Responses

Successful Response

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.

Resume a paused workflow run

POST/api/v1/workflows/runs/{run_id}/resume

API key or token

Resume a paused run (max_run_cost / hold); rejects filter_empty.

Parameters

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

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/runs/RUN_ID/resume" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.resume("RUN_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowRunResponse

Response fields
Field	Type	Description
`charged_amount`	`number`	Default: `0`
`created_at`	`string \| null`
`definition_id`	`string \| null`
`estimated_cost`	`number`	Default: `0`
`finished_at`	`string \| null`
`id`required	`string`
`max_run_cost`	`number \| null`
`remaining_hold`	`number`	Default: `0`
`run_name`required	`string`
`spec`	`object \| null`
`status`required	`string`
`status_message`	`string`	Default: `""`
`step_counts`	`object`
`steps[]`	`WorkflowStepSummary[]`
steps.`id`required	`string`
steps.`job_id`	`string \| null`
steps.`job_type`	`string \| null`
steps.`status`required	`string`
steps.`status_message`	`string`	Default: `""`
steps.`step_index`	`integer`	Default: `0`
steps.`step_key`required	`string`
`updated_at`	`string \| null`
`warnings[]`	`object[]`

Error statuses
Status	When
`400`	Operational resume failure: `run_not_paused`, `resume_rejected_filter_empty` — string `detail`, not Diagnostic[].
`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 workflow run

POST/api/v1/workflows/runs/{run_id}/cancel

API key or token

Cancel a workflow run owned by the current user.

Unfinished steps are cancelled along with their running jobs. Completed steps and their artifacts are kept.

Parameters

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

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/runs/RUN_ID/cancel" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.runs.cancel("RUN_ID")
print(result)

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

Responses

Successful Response · application/json · CancelWorkflowRunResponse

Response fields
Field	Type	Description
`cancelled_job_ids[]`	`string[]`
`message`required	`string`
`run_id`required	`string`
`status`required	`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.

List workflow definitions

GET/api/v1/workflows/definitions

API key or token

Paginated owned definitions without spec bodies.

Parameters

Query parameters
Name	Type	Description
`limit`	`integer`	Limits: `≥ 1`
`offset`	`integer`	Limits: `≥ 0`

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.list()
print(result)

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

Responses

Successful Response · application/json · WorkflowDefinitionListResponse

Response fields
Field	Type	Description
`items[]`required	`WorkflowDefinitionListItem[]`
items.`created_at`	`string \| null`
items.`description`required	`string`
items.`graph_layout`	`object \| null`
items.`id`required	`string`
items.`name`required	`string`
items.`spec_version`required	`integer`
items.`updated_at`	`string \| null`
items.`user_id`required	`string`
items.`visibility`	`string`	Default: `"private"`One of: `"private", "link"`
`limit`required	`integer`
`offset`required	`integer`
`total`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.

Create a workflow definition

POST/api/v1/workflows/definitions

API key or token

Save a WorkflowSpec as a named definition.

Top-level graph_layout is always popped into the DB column; the stored spec jsonb never contains that key. Full catalog validate before insert.

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

Request fields
Field	Type	Description
`description`	`string`	Optional human description. Default: `""`
`graph_layout`	`object \| null`	Optional builder layout; wins over in-spec graph_layout when set.
`name`required	`string`	Unique per-user definition name. Limits: `min length 1`
`spec`required	`object`	WorkflowSpec document. Top-level graph_layout is popped into the DB column; may also be sent as a sibling field.
`spec_version`	`integer`	Default: `1`Limits: `≥ 1`

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/definitions" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Vina then Boltz linear chain",
  "graph_layout": {
    "nodes": {
      "dock": {
        "x": 0,
        "y": 0
      }
    }
  },
  "name": "my-triage",
  "spec": {
    "limits": {
      "on_step_failure": "fail_fast"
    },
    "name": "vina-boltz-linear",
    "params": {},
    "spec_version": 1,
    "steps": [
      {
        "id": "dock",
        "inputs": {},
        "job_type": "autodockvina",
        "mode": "batch",
        "resource": "cpu",
        "type": "job"
      },
      {
        "id": "repredict",
        "inputs": {
          "ligands": {
            "$from": "dock.poses"
          }
        },
        "job_type": "boltz2",
        "mode": "batch",
        "resource": "a10",
        "type": "job"
      }
    ]
  }
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.create(
    name="my-triage",
    spec={
        "limits": {"on_step_failure": "fail_fast"},
        "name": "vina-boltz-linear",
        "params": {},
        "spec_version": 1,
        "steps": [
            {
                "id": "dock",
                "inputs": {},
                "job_type": "autodockvina",
                "mode": "batch",
                "resource": "cpu",
                "type": "job",
            },
            {
                "id": "repredict",
                "inputs": {"ligands": {"$from": "dock.poses"}},
                "job_type": "boltz2",
                "mode": "batch",
                "resource": "a10",
                "type": "job",
            },
        ],
    },
    description="Vina then Boltz linear chain",
)
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 · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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`	`definition_name_taken` or `definition_limit_reached` (string detail / marker; not always Diagnostic[]).
`413`	Spec or graph_layout exceeds size caps (Diagnostic[]).
`422`	Spec validation failure. `ProblemDetail.errors` is a Diagnostic[] ({code, message, step_id?, port?, path?}).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get a shared workflow definition

GET/api/v1/workflows/definitions/shared/{token}

API key or token

A shared definition's export: its spec, plus graph_layout when saved.

Requires sign-in (401 otherwise). An unknown or revoked token is a 404.

Parameters

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

Example request

curl "https://api.cognichem.com/api/v1/workflows/definitions/shared/TOKEN" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.get_shared("TOKEN")
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: object

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.

Fork a shared definition into the caller's library

POST/api/v1/workflows/definitions/shared/{token}/fork

API key or token

Create a new owned wfd- from the shared snapshot; never mutates owner.

Parameters

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

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

Request fields
Field	Type	Description
`description`	`string`	Default: `""`
`name`required	`string`	Limits: `min length 1`

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/definitions/shared/TOKEN/fork" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "NAME"
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.fork_shared("TOKEN", "NAME")
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 · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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`	`definition_name_taken` or `definition_limit_reached`.
`413`	Spec or graph_layout exceeds size caps (Diagnostic[]).
`422`	Spec validation failure. `ProblemDetail.errors` is a Diagnostic[] ({code, message, step_id?, port?, path?}).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

POST/api/v1/workflows/definitions/{definition_id}/share

API key or token

Mint a new share_token and set visibility=link.

Parameters

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

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.

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/share" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.share("DEFINITION_ID")
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 · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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/api/v1/workflows/definitions/{definition_id}/share

API key or token

Null share_token and set visibility=private.

Parameters

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

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/share" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.unshare("DEFINITION_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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 definition version history

GET/api/v1/workflows/definitions/{definition_id}/versions

API key or token

Paginated version metadata (no spec bodies). Cross-user → 404.

Parameters

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

Query parameters
Name	Type	Description
`limit`	`integer`	Limits: `≥ 1`
`offset`	`integer`	Limits: `≥ 0`

Example request

curl "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/versions" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.versions("DEFINITION_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowDefinitionVersionListResponse

Response fields
Field	Type	Description
`items[]`required	`WorkflowDefinitionVersionListItem[]`
items.`created_at`	`string \| null`
items.`created_by_user_id`	`string \| null`
items.`version`required	`integer`
`limit`required	`integer`
`offset`required	`integer`
`total`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.

Get a definition version snapshot

GET/api/v1/workflows/definitions/{definition_id}/versions/{version}

API key or token

Return one owned version snapshot; missing / cross-user → 404.

Parameters

Path parameters
Name	Type	Description
`definition_id`required	`string`
`version`required	`integer`

Example request

curl "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/versions/1" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.get_version("DEFINITION_ID", 1)
print(result)

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

Responses

Successful Response · application/json · WorkflowDefinitionVersionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`created_by_user_id`	`string \| null`
`definition_id`required	`string`
`graph_layout`	`object \| null`
`spec`required	`object`
`version`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.

Restore a definition version

POST/api/v1/workflows/definitions/{definition_id}/versions/{version}/restore

API key or token

Set the live row to version version's snapshot and append exactly one new history version. Does not rewrite the restored row.

Parameters

Path parameters
Name	Type	Description
`definition_id`required	`string`
`version`required	`integer`

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.

Example request

curl -X POST "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/versions/1/restore" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.restore_version("DEFINITION_ID", 1)
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 · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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 WorkflowSpec JSON export

GET/api/v1/workflows/definitions/{definition_id}/download

API key or token

Export a saved definition as pretty-printed WorkflowSpec JSON.

Default body is the spec column only (configuration; no ids, costs, or run param values). ?include_layout=1 merges the DB graph_layout column at the top level.

Import (no upload endpoint): client parses the file → POST /workflows/validate → POST /workflows/definitions. Create always pops top-level graph_layout into the DB column.

Parameters

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

Query parameters
Name	Type	Description
`include_layout`	`integer`	When 1, merge DB graph_layout at top level. Default: `0`Limits: `≥ 0, ≤ 1`

Example request

curl "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID/download" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.download("DEFINITION_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`	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 workflow definition

GET/api/v1/workflows/definitions/{definition_id}

API key or token

Return one owned definition; cross-user / missing → 404.

Parameters

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

Example request

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

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.get("DEFINITION_ID")
print(result)

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

Responses

Successful Response · application/json · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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.

Update a workflow definition

PATCH/api/v1/workflows/definitions/{definition_id}

API key or token

Update the live definition row (latest). Spec/layout changes append a history version; name/description-only updates do not. When spec changes, re-validate and pop layout.

Parameters

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

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

Request fields
Field	Type	Description
`description`	`string \| null`
`graph_layout`	`object \| null`
`name`	`string \| null`	Limits: `min length 1`
`spec`	`object \| null`
`spec_version`	`integer \| null`	Limits: `≥ 1`

Example request

curl -X PATCH "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-triage-v2"
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.update(
    "DEFINITION_ID",
    name="my-triage-v2",
)
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 · WorkflowDefinitionResponse

Response fields
Field	Type	Description
`created_at`	`string \| null`
`description`required	`string`
`graph_layout`	`object \| null`
`id`required	`string`
`name`required	`string`
`share_token`	`string \| null`	Present only for owner responses when visibility=link.
`spec`required	`object`
`spec_version`required	`integer`
`updated_at`	`string \| null`
`user_id`required	`string`
`visibility`	`string`	Default: `"private"`One of: `"private", "link"`

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`	Name conflict or definition limit (operational; string detail).
`413`	Spec or graph_layout exceeds size caps (Diagnostic[]).
`422`	Spec validation failure. `ProblemDetail.errors` is a Diagnostic[] ({code, message, step_id?, port?, path?}).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Delete a workflow definition

DELETE/api/v1/workflows/definitions/{definition_id}

API key or token

Delete an owned definition; runs keep frozen specs.

Parameters

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

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/workflows/definitions/DEFINITION_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.workflows.definitions.delete("DEFINITION_ID")
print(result)

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

Responses

Successful Response

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.