API reference

Assistant

CogniChem Assistant sessions, turn estimates, SSE streams, and stop. JWT only. Wallet-billed at caller-tier token rates.

On this page

List Assistant threads

GET/api/v1/chat/sessions

Access token only

List the caller's Assistant threads.

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.list()
print(result)

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

Responses

Successful Response · application/json · ChatSessionListResponse

Response fields
Field	Type	Description
`items[]`required	`ChatSessionResponse[]`
items.`allow_structure_search`	`boolean`	Default: `false`
items.`created_at`required	`string`
items.`id`required	`string`
items.`title`	`string \| null`
items.`updated_at`required	`string`

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.

Create an Assistant thread

POST/api/v1/chat/sessions

Access token only

Create an Assistant thread.

Request body

application/json · ChatSessionCreateRequest

Request fields
Field	Type	Description
`title`	`string \| null`	Limits: `max length 200`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "TITLE"
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.create(title="TITLE")
print(result)

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

Responses

Successful Response · application/json · ChatSessionResponse

Response fields
Field	Type	Description
`allow_structure_search`	`boolean`	Default: `false`
`created_at`required	`string`
`id`required	`string`
`title`	`string \| null`
`updated_at`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.

Get an Assistant thread

GET/api/v1/chat/sessions/{session_id}

Access token only

Fetch one Assistant thread.

Parameters

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

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.get("SESSION_ID")
print(result)

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

Responses

Successful Response · application/json · ChatSessionResponse

Response fields
Field	Type	Description
`allow_structure_search`	`boolean`	Default: `false`
`created_at`required	`string`
`id`required	`string`
`title`	`string \| null`
`updated_at`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.

Update an Assistant thread

PATCH/api/v1/chat/sessions/{session_id}

Access token only

Rename an Assistant thread or turn structure search on / off (E1).

Parameters

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

Request body

application/json · ChatSessionRenameRequest

Request fields
Field	Type	Description
`allow_structure_search`	`boolean \| null`	Allow the Assistant to send structures (SMILES) to external databases for similarity / substructure search in this thread. Off by default; only the user sets it.
`title`	`string \| null`	Limits: `max length 200`

Example request

curl -X PATCH "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "allow_structure_search": false,
  "title": "TITLE"
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.update(
    "SESSION_ID",
    title="TITLE",
    allow_structure_search=False,
)
print(result)

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

Responses

Successful Response · application/json · ChatSessionResponse

Response fields
Field	Type	Description
`allow_structure_search`	`boolean`	Default: `false`
`created_at`required	`string`
`id`required	`string`
`title`	`string \| null`
`updated_at`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.

Delete an Assistant thread

DELETE/api/v1/chat/sessions/{session_id}

Access token only

Delete a thread owned by the current JWT user.

Messages and wallet holds cascade. Additive v1; no request body.

Parameters

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

Example request

curl -X DELETE "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.delete("SESSION_ID")
print(result)

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

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.

List messages in a thread

GET/api/v1/chat/sessions/{session_id}/messages

Access token only

Return thread history (no secrets).

Parameters

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

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/messages" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.sessions.messages("SESSION_ID")
print(result)

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

Responses

Successful Response · application/json · ChatMessageListResponse

Response fields
Field	Type	Description
`items[]`required	`ChatMessageResponse[]`
items.`artifact_ids[]`	`string[] \| null`
items.`billed_usd`	`number \| null`
items.`cached_tokens`	`integer \| null`
items.`citations[]`	`object[] \| null`
items.`completion_tokens`	`integer \| null`
items.`content`	`string \| null`
items.`created_at`required	`string`
items.`embedding_tokens`	`integer \| null`
items.`id`required	`string`
items.`job_ids[]`	`string[] \| null`
items.`model_id`	`string \| null`
items.`prompt_tokens`	`integer \| null`
items.`reasoning_effort`	`string \| null`	One of: `"low", "medium", "high"`
items.`role`required	`string`	One of: `"user", "assistant", "tool", "system"`
items.`session_id`required	`string`
items.`tool_calls[]`	`object[] \| null`
items.`turn_id`	`string \| null`
items.`workflow_run_ids[]`	`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.

Estimate Assistant turn hold

POST/api/v1/chat/sessions/{session_id}/estimate

Access token only

Quote max-turn hold USD at the caller subscription tier (no side effects).

Parameters

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

Request body

application/json · ChatEstimateRequest

Request fields
Field	Type	Description
`artifact_ids[]`	`string[]`
`message`required	`string`	User message (at most 16000 characters; attach files as artifacts instead of pasting them). Limits: `min length 1, max length 16000`
`model_id`	`string`	Default: `"cognichem-assistant"`
`reasoning_effort`	`string \| null`	Assistant reasoning level. Higher levels run a stronger model at a higher per-token rate, which raises the turn hold and the bill. Omit for the catalog default (low). One of: `"low", "medium", "high"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/estimate" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "MESSAGE"
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.estimate("SESSION_ID", "MESSAGE")
print(result)

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

Responses

Successful Response · application/json · ChatEstimateResponse

Response fields
Field	Type	Description
`hold_usd`required	`number`
`max_completion_tokens`required	`integer`
`model_id`required	`string`
`prompt_tokens`required	`integer`
`reasoning_effort`required	`string`	One of: `"low", "medium", "high"`
`tier`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.

Start an Assistant turn

POST/api/v1/chat/sessions/{session_id}/turns

Access token onlyCharges your wallet

Open a wallet hold and stream Assistant tokens as SSE.

Parameters

Path parameters
Name	Type	Description
`session_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 · ChatTurnRequest

Request fields
Field	Type	Description
`artifact_ids[]`	`string[]`
`message`required	`string`	User message (at most 16000 characters; attach files as artifacts instead of pasting them). Limits: `min length 1, max length 16000`
`model_id`	`string`	Default: `"cognichem-assistant"`
`reasoning_effort`	`string \| null`	Assistant reasoning level. Higher levels run a stronger model at a higher per-token rate, which raises the turn hold and the bill. Omit for the catalog default (low). One of: `"low", "medium", "high"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/turns" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "MESSAGE"
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.send("SESSION_ID", "MESSAGE")
print(result)

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

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 turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Resource not found or not owned by the user.
`409`	`session-spend-cap`: the hold would take the thread past its spend cap; no hold opened. Carries `spent_usd`, `held_usd`, `hold_usd`, `cap_usd`, `step_usd`.
`413`	Request body or workflow spec exceeds size caps.
`422`	Invalid body (e.g. message over 16,000 characters).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Get a thread's spend and cap

GET/api/v1/chat/sessions/{session_id}/spend-cap

Access token only

Server-side spend and cap of one owned thread (never client-computed).

Parameters

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

Query parameters
Name	Type	Description
`model_id`	`string`	Default: `"cognichem-assistant"`

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/spend-cap" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.spend_cap("SESSION_ID")
print(result)

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

Responses

Successful Response · application/json · ChatSpendCapResponse

Response fields
Field	Type	Description
`cap_usd`required	`number`	Current thread spend cap.
`held_usd`required	`number`	Holds of turns still in flight.
`raised`	`boolean`	Continue only: whether this request raised the cap. Default: `false`
`spent_usd`required	`number`	Debited Assistant turns in this thread.
`step_usd`required	`number`	How much one Continue raises the cap.

Example 200 response

{
  "cap_usd": 1,
  "held_usd": 0,
  "raised": false,
  "spent_usd": 0.97,
  "step_usd": 1
}

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.

Continue past the thread spend cap

POST/api/v1/chat/sessions/{session_id}/spend-cap/continue

Access token only

User Continue: raise this thread's cap by one catalog step.

current_cap_usd is the cap the prompt showed; a repeat after the cap moved returns the current state with raised: false. JWT only; no hosted Assistant tool can call this.

Parameters

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

Request body

application/json · ChatSpendCapContinueRequest

Request fields
Field	Type	Description
`current_cap_usd`required	`number`	The cap the Continue prompt showed. If the cap has already moved (double click, second tab), nothing changes. Limits: `> 0`
`model_id`	`string`	Default: `"cognichem-assistant"`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/spend-cap/continue" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "current_cap_usd": 1
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.continue_spend_cap("SESSION_ID", 1)
print(result)

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

Responses

Successful Response · application/json · ChatSpendCapResponse

Response fields
Field	Type	Description
`cap_usd`required	`number`	Current thread spend cap.
`held_usd`required	`number`	Holds of turns still in flight.
`raised`	`boolean`	Continue only: whether this request raised the cap. Default: `false`
`spent_usd`required	`number`	Debited Assistant turns in this thread.
`step_usd`required	`number`	How much one Continue raises the cap.

Example 200 response

{
  "cap_usd": 1,
  "held_usd": 0,
  "raised": false,
  "spent_usd": 0.97,
  "step_usd": 1
}

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.

Stop an Assistant turn

POST/api/v1/chat/sessions/{session_id}/turns/{turn_id}/stop

Access token only

Interrupt an owned in-flight Assistant turn and release leftover hold.

Parameters

Path parameters
Name	Type	Description
`session_id`required	`string`
`turn_id`required	`string`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/turns/TURN_ID/stop" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.stop("SESSION_ID", "TURN_ID")
print(result)

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

Responses

Successful Response · application/json

Response fields: map<string, 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 Assistant run proposals for a thread

GET/api/v1/chat/sessions/{session_id}/proposals

Access token only

Plan cards for the thread (payload bodies are previewed, never returned).

Parameters

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

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/proposals" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.proposals.list("SESSION_ID")
print(result)

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

Responses

Successful Response · application/json · ChatRunProposalListResponse

Response fields
Field	Type	Description
`items[]`required	`ChatRunProposal[]`
items.`accepted_estimate_usd`	`number \| null`
items.`citations[]`	`ChatCitation[]`
items.citations.`title`	`string \| null`
items.citations.`url`required	`string`
items.`created_at`required	`string`
items.`display_name`	`string \| null`
items.`estimate_breakdown`	`object \| null`
items.`estimate_usd`required	`number`
items.`expires_at`required	`string`
items.`failure_code`	`string \| null`
items.`id`required	`string`
items.`job_id`	`string \| null`
items.`job_type`	`string \| null`
items.`kind`required	`string`	One of: `"job", "workflow"`
items.`last_failure_code`	`string \| null`
items.`max_run_cost_usd`	`number \| null`
items.`message_id`	`string \| null`
items.`params_preview`	`object \| null`
items.`payload_preview`	`object \| null`
items.`resource`	`string \| null`
items.`session_id`required	`string`
items.`spec_outline`	`object \| null`
items.`status`required	`string`	One of: `"pending", "approving", "submitted", "rejected", "expired", "failed"`
items.`summary`	`string \| null`
items.`tier`	`integer \| null`
items.`turn_id`	`string \| null`
items.`workflow_run_id`	`string \| null`
items.`workflow_spec`	`object \| null`	Frozen WorkflowSpec (GET one proposal with include_spec=1).

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 Assistant run proposal

GET/api/v1/chat/sessions/{session_id}/proposals/{proposal_id}

Access token only

One plan card; include_spec=1 adds the WorkflowSpec for the builder.

Parameters

Path parameters
Name	Type	Description
`session_id`required	`string`
`proposal_id`required	`string`

Query parameters
Name	Type	Description
`include_spec`	`boolean`	Include the frozen workflow spec (Open in builder). Default: `false`

Example request

curl "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/proposals/PROPOSAL_ID" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.proposals.get("SESSION_ID", "PROPOSAL_ID")
print(result)

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

Responses

Successful Response · application/json · ChatRunProposal

Response fields
Field	Type	Description
`accepted_estimate_usd`	`number \| null`
`citations[]`	`ChatCitation[]`
citations.`title`	`string \| null`
citations.`url`required	`string`
`created_at`required	`string`
`display_name`	`string \| null`
`estimate_breakdown`	`object \| null`
`estimate_usd`required	`number`
`expires_at`required	`string`
`failure_code`	`string \| null`
`id`required	`string`
`job_id`	`string \| null`
`job_type`	`string \| null`
`kind`required	`string`	One of: `"job", "workflow"`
`last_failure_code`	`string \| null`
`max_run_cost_usd`	`number \| null`
`message_id`	`string \| null`
`params_preview`	`object \| null`
`payload_preview`	`object \| null`
`resource`	`string \| null`
`session_id`required	`string`
`spec_outline`	`object \| null`
`status`required	`string`	One of: `"pending", "approving", "submitted", "rejected", "expired", "failed"`
`summary`	`string \| null`
`tier`	`integer \| null`
`turn_id`	`string \| null`
`workflow_run_id`	`string \| null`
`workflow_spec`	`object \| null`	Frozen WorkflowSpec (GET one proposal with include_spec=1).

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 proposal or not the caller's (`proposal-not-found`).
`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.

Approve an Assistant run proposal

POST/api/v1/chat/sessions/{session_id}/proposals/{proposal_id}/approve

Access token onlyCharges your wallet

User Approve: re-validate, re-estimate at the current tier, then enqueue.

Idempotency-Key is required (JWT too): this is a spend mutation from a clickable card. Nothing here opens an LLM turn.

Parameters

Path parameters
Name	Type	Description
`session_id`required	`string`
`proposal_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 · ChatProposalApproveRequest

Request fields
Field	Type	Description
`accepted_estimate_usd`required	`number`	Server estimate displayed on the plan card when clicked. Limits: `≥ 0`
`max_run_cost_usd`	`number \| null`	Workflow max_run_cost (defaults to the estimate total). Limits: `> 0`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/proposals/PROPOSAL_ID/approve" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "accepted_estimate_usd": 0.0421
}'

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.proposals.approve("SESSION_ID", "PROPOSAL_ID", 0.0421)
print(result)

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

Responses

Successful Response · application/json · ChatRunProposal

Response fields
Field	Type	Description
`accepted_estimate_usd`	`number \| null`
`citations[]`	`ChatCitation[]`
citations.`title`	`string \| null`
citations.`url`required	`string`
`created_at`required	`string`
`display_name`	`string \| null`
`estimate_breakdown`	`object \| null`
`estimate_usd`required	`number`
`expires_at`required	`string`
`failure_code`	`string \| null`
`id`required	`string`
`job_id`	`string \| null`
`job_type`	`string \| null`
`kind`required	`string`	One of: `"job", "workflow"`
`last_failure_code`	`string \| null`
`max_run_cost_usd`	`number \| null`
`message_id`	`string \| null`
`params_preview`	`object \| null`
`payload_preview`	`object \| null`
`resource`	`string \| null`
`session_id`required	`string`
`spec_outline`	`object \| null`
`status`required	`string`	One of: `"pending", "approving", "submitted", "rejected", "expired", "failed"`
`summary`	`string \| null`
`tier`	`integer \| null`
`turn_id`	`string \| null`
`workflow_run_id`	`string \| null`
`workflow_spec`	`object \| null`	Frozen WorkflowSpec (GET one proposal with include_spec=1).

Error statuses
Status	When
`400`	Invalid input or business rule violation.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the run (`insufficient-wallet`).
`403`	Authenticated but not allowed to access the resource.
`404`	Unknown proposal or not the caller's (`proposal-not-found`).
`409`	`proposal-not-pending` (already approved/dismissed; carries `proposal`) or `estimate-changed` (carries the new server `proposal`); nothing was enqueued.
`410`	Proposal TTL elapsed (`proposal-expired`).
`413`	Request body or workflow spec exceeds size caps.
`422`	Payload/spec no longer valid (`proposal-invalid`).
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	Dependency temporarily unavailable.

Dismiss an Assistant run proposal

POST/api/v1/chat/sessions/{session_id}/proposals/{proposal_id}/reject

Access token only

Dismiss a pending proposal. No spend.

Parameters

Path parameters
Name	Type	Description
`session_id`required	`string`
`proposal_id`required	`string`

Example request

curl -X POST "https://api.cognichem.com/api/v1/chat/sessions/SESSION_ID/proposals/PROPOSAL_ID/reject" \
  -H "Authorization: Bearer $COGNICHEM_ACCESS_TOKEN"

import os

from cognichem_client import CogniChem

client = CogniChem(access_token=os.environ["COGNICHEM_ACCESS_TOKEN"])
result = client.chat.proposals.reject("SESSION_ID", "PROPOSAL_ID")
print(result)

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

Responses

Successful Response · application/json · ChatRunProposal

Response fields
Field	Type	Description
`accepted_estimate_usd`	`number \| null`
`citations[]`	`ChatCitation[]`
citations.`title`	`string \| null`
citations.`url`required	`string`
`created_at`required	`string`
`display_name`	`string \| null`
`estimate_breakdown`	`object \| null`
`estimate_usd`required	`number`
`expires_at`required	`string`
`failure_code`	`string \| null`
`id`required	`string`
`job_id`	`string \| null`
`job_type`	`string \| null`
`kind`required	`string`	One of: `"job", "workflow"`
`last_failure_code`	`string \| null`
`max_run_cost_usd`	`number \| null`
`message_id`	`string \| null`
`params_preview`	`object \| null`
`payload_preview`	`object \| null`
`resource`	`string \| null`
`session_id`required	`string`
`spec_outline`	`object \| null`
`status`required	`string`	One of: `"pending", "approving", "submitted", "rejected", "expired", "failed"`
`summary`	`string \| null`
`tier`	`integer \| null`
`turn_id`	`string \| null`
`workflow_run_id`	`string \| null`
`workflow_spec`	`object \| null`	Frozen WorkflowSpec (GET one proposal with include_spec=1).

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 proposal or not the caller's (`proposal-not-found`).
`409`	`proposal-not-pending`.
`410`	Proposal TTL elapsed (`proposal-expired`).
`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.