CogniChem REST API

Base URL

Every endpoint lives under https://api.cognichem.com/api/v1. Requests and responses are JSON unless an endpoint says otherwise.

Authentication

Send an API key in the X-Api-Key header. Create keys in your CogniChem account and keep them out of source code: the examples read one from COGNICHEM_API_KEY.

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

Endpoints marked Access token only (API key management and the Assistant) need a signed-in access token instead, sent as Authorization: Bearer …. Get one from Log in with email and password.

Errors

Failed requests return an RFC 7807 problem detail (application/problem+json) with the HTTP status, a title and detail, the request_id to quote to support, and a retryability hint: retry upstream and timeout errors with backoff, fix the request for validation, and wait or top up for quota. Validation errors (422) list each problem in errors.

Safe retries

14 endpoints that start or save something take an Idempotency-Key header, and calls made with an API key must send one. Use a new unique key (a UUID) for each request and the same key when you retry it: a repeat returns the first result instead of doing the work twice, and the same key with a different body is a 409. Idempotency has the details.

Charges

5 endpoints are marked Charges your wallet. Submitting a job or workflow run (or approving one the Assistant proposed) reserves its estimated cost, and the charge settles at the actual runtime when the work finishes. An Assistant turn holds funds for the tokens it may use and debits what it uses.

Utility and inference calls are marked Counts toward monthly limits: they are not charged to your wallet but use your plan's monthly allowance. Check it with Get usage and limits.

Price a job first with Estimate job reservation cost or a workflow with Estimate a workflow run's cost; neither charges anything.

Endpoints

• Auth and API keys11 endpoints

  Email login, token refresh, API keys, and session check.

• Jobs10 endpoints

  Submit, track, and download long-running compute jobs.

• Artifacts6 endpoints

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

• Workflows25 endpoints

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

• Inference7 endpoints

  Molecule inference jobs (e.g. MPNN) and batch submit.

• Utilities6 endpoints

  Lightweight utility jobs (e.g. structure conversion).

• Usage limits1 endpoint

  Monthly and total usage counters vs subscription tier limits.

• Public models1 endpoint

  Catalog of organization-wide public models.

• Your models2 endpoints

  Per-user trained models (e.g. MPNN).

• Assistant15 endpoints

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

• Science lookups6 endpoints

  Live science lookups (PubChem, ChEMBL, Open Targets, UniProt, RCSB PDB) with source attribution on every result. Structures (SMILES, InChI) are sent to these sources only for API keys created with allow_structure_search.

• Reference papers3 endpoints

  Method papers and papers that used CogniChem tools: search them, get one paper, or list the papers linked to a job type or to another paper. Titles, venues, and licensed abstracts; no full text.

• Wallet1 endpoint

  Read-only wallet balance and active reserved USD.

• Events1 endpoint

  Job and workflow run completion events: gap-free cursor feed with optional long-poll. Thin events; re-read status.

• Health2 endpoints

  Unauthenticated liveness and readiness probes.

The raw OpenAPI document is at https://api.cognichem.com/openapi.json.