API reference

Science lookups

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.

On this page

Resolve compound names with PubChem

POST/api/v1/lookup/pubchem

API key or token

SMILES, CID and title for up to 20 compound names. Only the names are sent; a SMILES or InChI given as a name returns structure_egress_not_allowed and is not sent.

Request body

application/json · PubchemLookupRequest

Request fields
Field	Type	Description
`names[]`required	`string[]`	Up to 20 compound names (each 1-100 characters). Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/pubchem" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "aspirin"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.pubchem(["aspirin"])
print(result)

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

Responses

Successful Response · application/json · PubchemLookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`compounds[]`required	`CompoundItem[]`
compounds.`cid`	`integer \| null`
compounds.`license`required	`string`
compounds.`name`required	`string`
compounds.`other_cids[]`	`integer[] \| null`
compounds.`smiles`	`string \| null`
compounds.`source`	`string`	Default: `"PubChem"`
compounds.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
compounds.`title`	`string \| null`
compounds.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from PubChem (NCBI), ...",
  "compounds": [
    {
      "cid": 2244,
      "license": "Public domain (NCBI); ...",
      "name": "aspirin",
      "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
      "source": "PubChem",
      "status": "found",
      "title": "Aspirin",
      "url": "https://pubchem.ncbi.nlm.nih.gov/compound/2244"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).

Look up ChEMBL molecules, targets and activities

POST/api/v1/lookup/chembl

API key or token

molecule / target / *_activities send only IDs and names. similarity / substructure send SMILES only for an API key with allow_structure_search on; otherwise every item returns structure_egress_not_allowed and nothing is sent.

Request body

application/json · ChemblLookupRequest

Request fields
Field	Type	Description
`limit`	`integer \| null`	Rows per query (default 10). Limits: `≥ 1, ≤ 25`
`operation`required	`string`	One of: `"molecule", "target", "molecule_activities", "target_activities", "similarity", "substructure"`
`queries[]`required	`string[]`	IDs or names (<= 100 characters); SMILES (<= 500) for similarity / substructure, which run only for keys with allow_structure_search. Limits: `min items 1, max items 20`
`threshold`	`integer \| null`	similarity only: percent (70). Limits: `≥ 40, ≤ 100`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/chembl" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 5,
  "operation": "molecule",
  "queries": [
    "CHEMBL25"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.chembl("molecule", ["CHEMBL25"])
print(result)

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

Responses

Successful Response · application/json · LookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`results[]`required	`LookupItem[]`
results.`data`	`any`
results.`license`required	`string`
results.`operation`required	`string`
results.`query`	`string \| null`
results.`record_id`	`string \| null`
results.`release`	`string \| null`
results.`source`required	`string`
results.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
results.`title`	`string \| null`
results.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from ChEMBL (EMBL-EBI), CC BY-SA 3.0 Unported. ...",
  "results": [
    {
      "data": {
        "smiles": "CC(=O)Oc1ccccc1C(=O)O"
      },
      "license": "CC BY-SA 3.0",
      "operation": "molecule",
      "query": "CHEMBL25",
      "record_id": "CHEMBL25",
      "release": "ChEMBL_35",
      "source": "ChEMBL",
      "status": "found",
      "title": "ASPIRIN",
      "url": "https://www.ebi.ac.uk/chembl/explore/compound/CHEMBL25"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).

Look up Open Targets associations and drugs

POST/api/v1/lookup/targets

API key or token

Target-disease associations and drugs by gene symbol, Ensembl or EFO ID.

Request body

application/json · TargetsLookupRequest

Request fields
Field	Type	Description
`limit`	`integer \| null`	Rows per query (default 10). Limits: `≥ 1, ≤ 25`
`operation`required	`string`	One of: `"target_diseases", "disease_targets", "target_drugs", "disease_drugs"`
`queries[]`required	`string[]`	Up to 20 IDs or names (each 1-100 characters). Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/targets" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "target_diseases",
  "queries": [
    "EGFR"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.targets("target_diseases", ["EGFR"])
print(result)

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

Responses

Successful Response · application/json · LookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`results[]`required	`LookupItem[]`
results.`data`	`any`
results.`license`required	`string`
results.`operation`required	`string`
results.`query`	`string \| null`
results.`record_id`	`string \| null`
results.`release`	`string \| null`
results.`source`required	`string`
results.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
results.`title`	`string \| null`
results.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from ChEMBL (EMBL-EBI), CC BY-SA 3.0 Unported. ...",
  "results": [
    {
      "data": {
        "smiles": "CC(=O)Oc1ccccc1C(=O)O"
      },
      "license": "CC BY-SA 3.0",
      "operation": "molecule",
      "query": "CHEMBL25",
      "record_id": "CHEMBL25",
      "release": "ChEMBL_35",
      "source": "ChEMBL",
      "status": "found",
      "title": "ASPIRIN",
      "url": "https://www.ebi.ac.uk/chembl/explore/compound/CHEMBL25"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).

Look up UniProtKB entries

POST/api/v1/lookup/uniprot

API key or token

UniProtKB entries by accession, or search by gene / protein name.

Request body

application/json · UniprotLookupRequest

Request fields
Field	Type	Description
`operation`required	`string`	One of: `"entry", "search"`
`organism`	`string \| null`	search only: organism name or NCBI taxon ID (9606 = human). Limits: `max length 100`
`queries[]`required	`string[]`	Up to 20 IDs or names (each 1-100 characters). Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/uniprot" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "search",
  "organism": "9606",
  "queries": [
    "EGFR"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.uniprot("search", ["EGFR"])
print(result)

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

Responses

Successful Response · application/json · LookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`results[]`required	`LookupItem[]`
results.`data`	`any`
results.`license`required	`string`
results.`operation`required	`string`
results.`query`	`string \| null`
results.`record_id`	`string \| null`
results.`release`	`string \| null`
results.`source`required	`string`
results.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
results.`title`	`string \| null`
results.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from ChEMBL (EMBL-EBI), CC BY-SA 3.0 Unported. ...",
  "results": [
    {
      "data": {
        "smiles": "CC(=O)Oc1ccccc1C(=O)O"
      },
      "license": "CC BY-SA 3.0",
      "operation": "molecule",
      "query": "CHEMBL25",
      "record_id": "CHEMBL25",
      "release": "ChEMBL_35",
      "source": "ChEMBL",
      "status": "found",
      "title": "ASPIRIN",
      "url": "https://www.ebi.ac.uk/chembl/explore/compound/CHEMBL25"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).

Look up RCSB PDB entries

POST/api/v1/lookup/pdb

API key or token

PDB entries by ID, or search by UniProt accession or free text.

Request body

application/json · PdbLookupRequest

Request fields
Field	Type	Description
`limit`	`integer \| null`	Rows per query (default 10). Limits: `≥ 1, ≤ 25`
`operation`required	`string`	One of: `"entry", "search"`
`queries[]`required	`string[]`	Up to 20 IDs or names (each 1-100 characters). Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/pdb" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "entry",
  "queries": [
    "1M17"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.pdb("entry", ["1M17"])
print(result)

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

Responses

Successful Response · application/json · LookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`results[]`required	`LookupItem[]`
results.`data`	`any`
results.`license`required	`string`
results.`operation`required	`string`
results.`query`	`string \| null`
results.`record_id`	`string \| null`
results.`release`	`string \| null`
results.`source`required	`string`
results.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
results.`title`	`string \| null`
results.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from ChEMBL (EMBL-EBI), CC BY-SA 3.0 Unported. ...",
  "results": [
    {
      "data": {
        "smiles": "CC(=O)Oc1ccccc1C(=O)O"
      },
      "license": "CC BY-SA 3.0",
      "operation": "molecule",
      "query": "CHEMBL25",
      "record_id": "CHEMBL25",
      "release": "ChEMBL_35",
      "source": "ChEMBL",
      "status": "found",
      "title": "ASPIRIN",
      "url": "https://www.ebi.ac.uk/chembl/explore/compound/CHEMBL25"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).

Look up PubChem experimental properties

POST/api/v1/lookup/properties

API key or token

Measured boiling point, vapor pressure, density and similar values by CID or compound name. Each value carries its supplier and licence; values from suppliers without an allowed licence are dropped and counted in data.excluded.

Request body

application/json · PropertiesLookupRequest

Request fields
Field	Type	Description
`limit`	`integer \| null`	Values per property (default 3). Limits: `≥ 1, ≤ 10`
`operation`required	`"experimental"`
`properties[]`	`string[] \| null`	Properties to return (default: boiling / melting point, density, vapor pressure, heat of vaporization, viscosity, surface tension). 'other' holds critical constants and other measured values. One of: `"boiling_point", "melting_point", "density", "vapor_pressure", "vapor_density", "heat_of_vaporization", "heat_of_combustion", "viscosity", "surface_tension", "solubility", "logp", "henrys_law_constant", "flash_point", "autoignition_temperature", "refractive_index", "dissociation_constants", "other"`Limits: `min items 1, max items 17`
`queries[]`required	`string[]`	Up to 20 PubChem CIDs or compound names. Limits: `min items 1, max items 20`

Example request

curl -X POST "https://api.cognichem.com/api/v1/lookup/properties" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "experimental",
  "properties": [
    "boiling_point",
    "vapor_pressure"
  ],
  "queries": [
    "methanol"
  ]
}'

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.lookup.properties(
    ["methanol"],
    properties=["boiling_point", "vapor_pressure"],
)
print(result)

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

Responses

Successful Response · application/json · LookupResponse

Response fields
Field	Type	Description
`attribution`required	`string`
`results[]`required	`LookupItem[]`
results.`data`	`any`
results.`license`required	`string`
results.`operation`required	`string`
results.`query`	`string \| null`
results.`record_id`	`string \| null`
results.`release`	`string \| null`
results.`source`required	`string`
results.`status`required	`string`	One of: `"found", "ambiguous", "not_found", "error", "structure_egress_not_allowed"`
results.`title`	`string \| null`
results.`url`	`string \| null`

Example 200 response

{
  "attribution": "Data from ChEMBL (EMBL-EBI), CC BY-SA 3.0 Unported. ...",
  "results": [
    {
      "data": {
        "smiles": "CC(=O)Oc1ccccc1C(=O)O"
      },
      "license": "CC BY-SA 3.0",
      "operation": "molecule",
      "query": "CHEMBL25",
      "record_id": "CHEMBL25",
      "release": "ChEMBL_35",
      "source": "ChEMBL",
      "status": "found",
      "title": "ASPIRIN",
      "url": "https://www.ebi.ac.uk/chembl/explore/compound/CHEMBL25"
    }
  ]
}

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`	This source is disabled on the server (base URL unset).