API reference

Reference papers

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.

On this page

Search reference papers

GET/api/v1/reference/papers

API key or token

Ranked search over method papers, papers that used CogniChem tools, and general papers (title, venue, licensed abstract). No full text.

Parameters

Query parameters
Name	Type	Description
`q`required	`string`	Limits: `min length 1, max length 200`
`paper_set`	`string`	One of: `"method", "used_cognichem", "general"`
`limit`	`integer`	Default: `10`Limits: `≥ 1, ≤ 50`

Example request

curl "https://api.cognichem.com/api/v1/reference/papers?q=pKa%20protonation" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.reference.search("pKa protonation")
print(result)

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

Responses

Successful Response · application/json · ReferenceSearchResponse

Response fields
Field	Type	Description
`mode`	`string`	`hybrid` when the query embedding was used. Default: `"lexical"`One of: `"hybrid", "lexical"`
`papers[]`required	`ReferencePaper[]`
papers.`abstract`	`string \| null`	Only on get, and only when stored under CC0 / CC BY (Europe PMC). Show it with the title, authors, `url`, `abstract_license` (linked to `abstract_license_url`) and `abstract_notice`.
papers.`abstract_license`	`string \| null`	One of: `"CC0", "CC BY"`
papers.`abstract_license_url`	`string \| null`	Creative Commons page for `abstract_license`; the article at `url` states the licence version.
papers.`abstract_notice`	`string \| null`	How the stored abstract differs from the original (only on get).
papers.`abstract_source`	`string \| null`	"Europe PMC" when an abstract is stored.
papers.`authors[]`	`string[]`	First authors (capped).
papers.`authors_total`	`integer`	Default: `0`
papers.`doi`	`string \| null`
papers.`id`required	`string`
papers.`oa_url`	`string \| null`
papers.`paper_set`required	`string`	One of: `"method", "used_cognichem", "general"`
papers.`retrieved_at`	`string \| null`
papers.`source`required	`string`
papers.`title`required	`string`
papers.`url`	`string \| null`	Public landing link (DOI, else open-access or OpenAlex).
papers.`venue`	`string \| null`
papers.`year`	`integer \| null`
`provenance`required	`ReferenceProvenance`	Where an answer came from.
provenance.`entity_ids[]`	`string[]`
provenance.`outbound[]`	`map<string, string>[]`
provenance.`source`	`"cognichem_reference_kg"`	Default: `"cognichem_reference_kg"`
`query`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`	Empty query.
`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 reference paper

GET/api/v1/reference/papers/{paper_id}

API key or token

Paper metadata, its links (method_of / uses_tool Product KG ids, cites papers) and how many KG papers cite it. The abstract is present only when stored under CC0 / CC BY / CC BY-SA, with its licence.

Parameters

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

Example request

curl "https://api.cognichem.com/api/v1/reference/papers/PAPER_ID" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.reference.get("PAPER_ID")
print(result)

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

Responses

Successful Response · application/json · ReferencePaperResponse

Response fields
Field	Type	Description
`cited_by_count`	`integer`	Papers in the reference KG that cite this one. Default: `0`
`edges[]`required	`ReferenceEdge[]`
edges.`dst_id`required	`string`
edges.`dst_kind`required	`string`	One of: `"paper", "product_node"`
edges.`kind`required	`string`	One of: `"cites", "method_of", "uses_tool", "compares", "describes"`
edges.`src_paper_id`required	`string`
`paper`required	`ReferencePaper`	One paper: public metadata and links. No full text in v1.
paper.`abstract`	`string \| null`	Only on get, and only when stored under CC0 / CC BY (Europe PMC). Show it with the title, authors, `url`, `abstract_license` (linked to `abstract_license_url`) and `abstract_notice`.
paper.`abstract_license`	`string \| null`	One of: `"CC0", "CC BY"`
paper.`abstract_license_url`	`string \| null`	Creative Commons page for `abstract_license`; the article at `url` states the licence version.
paper.`abstract_notice`	`string \| null`	How the stored abstract differs from the original (only on get).
paper.`abstract_source`	`string \| null`	"Europe PMC" when an abstract is stored.
paper.`authors[]`	`string[]`	First authors (capped).
paper.`authors_total`	`integer`	Default: `0`
paper.`doi`	`string \| null`
paper.`id`required	`string`
paper.`oa_url`	`string \| null`
paper.`paper_set`required	`string`	One of: `"method", "used_cognichem", "general"`
paper.`retrieved_at`	`string \| null`
paper.`source`required	`string`
paper.`title`required	`string`
paper.`url`	`string \| null`	Public landing link (DOI, else open-access or OpenAlex).
paper.`venue`	`string \| null`
paper.`year`	`integer \| null`
`provenance`required	`ReferenceProvenance`	Where an answer came from.
provenance.`entity_ids[]`	`string[]`
provenance.`outbound[]`	`map<string, string>[]`
provenance.`source`	`"cognichem_reference_kg"`	Default: `"cognichem_reference_kg"`

Error statuses
Status	When
`400`	Malformed paper id.
`401`	Missing or invalid credentials.
`402`	Wallet cannot cover the Assistant turn hold.
`403`	Authenticated but not allowed to access the resource.
`404`	Unknown paper 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.

List papers linked to a job type or paper

GET/api/v1/reference/neighborhood

API key or token

One hop: for node_id the papers that are its method or that used it; for paper_id the papers it cites and that cite it.

Parameters

Query parameters
Name	Type	Description
`node_id`	`string`	Limits: `max length 220`
`paper_id`	`string`	Limits: `max length 130`
`kind`	`string`	One of: `"cites", "method_of", "uses_tool", "compares", "describes"`
`limit`	`integer`	Default: `25`Limits: `≥ 1, ≤ 50`

Example request

curl "https://api.cognichem.com/api/v1/reference/neighborhood?node_id=job_type%3Aprotein-prepare" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

from cognichem_client import CogniChem

client = CogniChem.from_env()
result = client.reference.neighborhood(node_id="job_type:protein-prepare")
print(result)

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

Responses

Successful Response · application/json · ReferenceNeighborhoodResponse

Response fields
Field	Type	Description
`center`required	`string`
`edges[]`required	`ReferenceEdge[]`
edges.`dst_id`required	`string`
edges.`dst_kind`required	`string`	One of: `"paper", "product_node"`
edges.`kind`required	`string`	One of: `"cites", "method_of", "uses_tool", "compares", "describes"`
edges.`src_paper_id`required	`string`
`papers[]`required	`ReferencePaper[]`
papers.`abstract`	`string \| null`	Only on get, and only when stored under CC0 / CC BY (Europe PMC). Show it with the title, authors, `url`, `abstract_license` (linked to `abstract_license_url`) and `abstract_notice`.
papers.`abstract_license`	`string \| null`	One of: `"CC0", "CC BY"`
papers.`abstract_license_url`	`string \| null`	Creative Commons page for `abstract_license`; the article at `url` states the licence version.
papers.`abstract_notice`	`string \| null`	How the stored abstract differs from the original (only on get).
papers.`abstract_source`	`string \| null`	"Europe PMC" when an abstract is stored.
papers.`authors[]`	`string[]`	First authors (capped).
papers.`authors_total`	`integer`	Default: `0`
papers.`doi`	`string \| null`
papers.`id`required	`string`
papers.`oa_url`	`string \| null`
papers.`paper_set`required	`string`	One of: `"method", "used_cognichem", "general"`
papers.`retrieved_at`	`string \| null`
papers.`source`required	`string`
papers.`title`required	`string`
papers.`url`	`string \| null`	Public landing link (DOI, else open-access or OpenAlex).
papers.`venue`	`string \| null`
papers.`year`	`integer \| null`
`provenance`required	`ReferenceProvenance`	Where an answer came from.
provenance.`entity_ids[]`	`string[]`
provenance.`outbound[]`	`map<string, string>[]`
provenance.`source`	`"cognichem_reference_kg"`	Default: `"cognichem_reference_kg"`

Error statuses
Status	When
`400`	Pass exactly one well-formed id.
`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.