Skip to main content
Docs

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

    SDKs

    Python SDK

    Install cognichem-client, authenticate, and call every part of the API from Python.

    Updated October 1, 2026

    On this page

    cognichem-client is the official Python client for the CogniChem API: jobs, workflows, artifacts, events, the wallet, science lookups, reference papers, utilities, inference, and the Assistant. It needs Python 3.10 or later. Source and examples: cognichem-client-python (Apache 2.0).

    pip install cognichem-client

    Version 1.1 or later covers the whole current API; the samples in these docs assume it.

    Authenticate

    from cognichem_client import CogniChem
 
client = CogniChem.from_env()            # reads COGNICHEM_API_KEY (and COGNICHEM_ACCESS_TOKEN, COGNICHEM_BASE_URL)
client = CogniChem(api_key="...")        # or pass a key directly

    API key management and the Assistant need an access token instead of a key (Authentication):

    client = CogniChem()
client.auth.login_email("[email protected]", "your-password")   # stores the token on the client

    What's in it

    ResourceMethods
    client.jobsestimate, submit, submit_many, status, info, list, wait, run, result, result_many, cancel, delete
    client.workflowsvalidate, estimate, templates, template, node_ports
    client.workflows.runscreate, list, get, artifacts, resume, cancel, delete, wait, run
    client.workflows.definitionscreate, list, get, update, delete, download, share, unshare, get_shared, fork_shared, versions, get_version, restore_version
    client.artifactslist, usage, upload, get, download, delete
    client.eventslist, listen
    client.walletbalance
    client.lookuppubchem, chembl, targets, uniprot, pdb, properties
    client.referencesearch, get, neighborhood
    client.utilssubmit, status, result, wait, run, list, cancel, delete
    client.inferencesubmit, submit_batch, status, result, wait, run, list, cancel, delete
    client.inference.models.mpnnpublic, user, delete
    client.usagelimits
    client.chat (access token)estimate, send, stream, stop, spend_cap, continue_spend_cap, sessions.*, proposals.*
    client.auth, client.api_keyslogin, check, refresh, logout; list, create, get, update, rotate, delete keys

    AsyncCogniChem has the same methods for asyncio. Every operation in the API reference shows its SDK call in the Python tab.

    Helpers

    • run (jobs, utilities, inference, workflow runs) submits and waits in one call; wait polls with backoff until the work stops.
    • artifact_ref(id, port) builds an {"$artifact": …} reference for job payloads and workflow params.
    • events.listen() long-polls completion events and drops repeats.
    • Idempotency: writes send a fresh Idempotency-Key automatically. Pass idempotency_key= to reuse one across your own retries (Retry safely).

    Errors

    Failed calls raise subclasses of CogniChemError (BadRequestError, AuthenticationError, PaymentRequiredError, ForbiddenError, NotFoundError, ConflictError, GoneError, PayloadTooLargeError, ValidationError, RateLimitError, ServerError) carrying the problem detail's fields, including code (the problem type, such as insufficient-scope) and retryability. wait and run raise PollTimeoutError, ProcessFailedError, or ProcessCancelledError. See Handle errors.

    Notes

    • client.auth.refresh uses the deprecated GET /auth/refresh, which may be removed after 2027-01-01 (Versioning).
    • Workflow template objects don't include the newer title and family fields yet; use id, name, and summary.