API Documentation

SUPP.AI's API is free to use, provided you comply with the Semantic Scholar Dataset License Agreement.

Endpoints

Search
Agent
AgentInteraction
InteractionEvidence

Data Types

SearchResponse
Query
Agent
AgentInteractionResponse
Interaction
Evidence
Paper
Author
Sentence
Span

Search

The search endpoint executes a search query and returns agents (supplements and drugs) that best match the provided query. Results are paginated, with a maximum of 10 results being returned with each request.

GET https://supp.ai/api/agent/search?q=$query[&p=$page]

Parameters

Name	Type	Required	Default Value	Description
`q`	`string`	`Yes`	`-`	Text to search for. The agent name, description and synonyms are searched.
`p`	`number`	`No`	`0`	The result page number, beginning from zero.

Return Type

Returns a single SearchResponse.

Example

~ curl "https://supp.ai/api/agent/search?q=ginkgo"
{
    "results": [ ... ],
    "query": { "q": "ginkgo", "p": 0 },
    "total_pages": 1,
    "total_results": 8,
    "num_per_page": 10
}

Agent

The agent endpoint returns metadata associated with a particular CUI.

GET https://supp.ai/api/agent/<string:CUI>

Parameters

Name	Type	Required	Default Value	Description

Return Type

Returns a single Agent.

Example

~ curl "https://supp.ai/api/agent/C3531686"
{
    "cui": "C3531686",
    "preferred_name": "Ginkgo Biloba Whole",
    "synonyms": [
        "Ginkgo biloba",
        "ginkgo",
        "maidenhair tree",
        "Salisburia ginkgo"
    ],
    "tradenames": [ ],
    "definition": "A tree native to China. Substances taken from the leaves and seeds have been used in some cultures to treat certain medical problems...",
    "ent_type": "supplement",
    "slug": "ginkgo-biloba-whole",
    "interacts_with_count": 140,
    "matches": { }
}

AgentInteraction

The agent interactions endpoint returns all interaction IDs associated with a particular CUI.

GET https://supp.ai/api/agent/<string:CUI>/interactions?[p=$page]

Parameters

Name	Type	Required	Default Value	Description
`p`	`number`	`No`	`1`	The result page number, beginning from one.

Return Type

Returns a single AgentInteractionResponse.

Example

~ curl "https://supp.ai/api/agent/C3531686/interactions?p=1"
{
    "page": 1,
    "interactions": [ ... ],
    "interactions_per_page": 50,
    "total": 140
}

InteractionEvidence

The interaction-evidence endpoint returns the interaction evidence sentences between a pair of CUIs.

GET https://supp.ai/api/interaction/<string:IID>

Parameters

Name	Type	Required	Default Value	Description

Return Type

Returns a single Interaction.

Example

~ curl "https://supp.ai/api/interaction/C0043031-C3531686"
{
    "interaction_id": "C0043031-C3531686",
    "slug": "warfarin-ginkgo-biloba-whole",
    "agents": [ ... ],
    "evidence": [ ... ]
}

`SearchResponse`

The result of a search request.

Name	Type	Description
`results`	`List[Agent]`	The supplement and drug entities matching the search query, in descending order by the likelihood of the match.
`query`	`Query`	The original search query.
`total_pages`	`number`	The total number of result pages.
`total_results`	`number`	The total number of results.
`num_per_page`	`number`	The number of results per results page.

`Query`

A search query

Name	Type	Description
`q`	`string`	The query text.
`p`	`number`	The requested page number of results, zero indexed.

`Agent`

A drug or supplement.

Name	Type	Description
`cui`	`string`	A unique identifier, derived from <a href="https://www.nlm.nih.gov/research/umls/index.html">UMLS</a>
`preferred_name`	`string`	The agent's canonical name.
`synonyms`	`List[string]`	A list of alternative names for the agent.
`tradenames`	`List[string]`	A list of tradenames (brand names) for the agent (only available for drugs).
`definition`	`string`	A description of the agent.
`slug`	`string`	A url safe version of the agent's name.
`ent_type`	`string`	The type of agent. One of "supplement", "drug", or "other."
`interacts_with_count`	`number`	The number of interactions we found between the agent and others in our corpus.
`matches`	`Map[string,string]`	If the agent is being returned in response to a search query, this map contains the name of each field and the text from that field that matched the query. This is typically used to highlight the matching items.

`AgentInteractionResponse`

The result of a agent interactions request.

Name	Type	Description
`page`	`number`	The page number of the results.
`interactions`	`Interaction`	The original search query.
`interactions_per_page`	`number`	The number of results per results page.
`total`	`number`	The total number of results.

`Interaction`

One interaction between two agents supported by evidence.

Name	Type	Description
`interaction_id`	`string`	The interaction id between two agents, takes the form [CUI1-CUI2].
`slug`	`string`	A url safe version of the interaction name.
`agent`	`Agent`	The agent interacting with the queried agent.
`evidence`	`List[Evidence]`	A list of evidence sentences supporting the interaction.

`Evidence`

Evidence sentences supporting an interaction

Name	Type	Description
`paper`	`Paper`	The paper from which the evidence was derived.
`sentences`	`List[Sentence]`	List of sentences from the paper with labeled supplement and drug spans.

`Paper`

Metadata about a scientific paper

Name	Type	Description
`pid`	`string`	Semantic Scholar corpus identifier for a paper.
`title`	`string`	Title of paper.
`authors`	`List[Author]`	Authors of paper (currently an empty list).
`year`	`number`	Publication year of paper.
`venue`	`string`	Publication venue of paper.
`doi`	`string`	DOI of paper.
`pmid`	`number`	PubMed identifier of paper.
`fields_of_study`	`List[string]`	Fields of study of paper.
`animal_study`	`boolean`	Whether the paper documents an animal study.
`human_study`	`boolean`	Whether the paper documents a human study.
`clinical_study`	`boolean`	Whether the paper documents a clinical study.
`retraction`	`boolean`	Whether the paper has been retracted.

`Author`

Author metadata

Name	Type	Description
`first`	`string`	Author first name.
`middle`	`string`	Author middle names.
`last`	`string`	Author last name.
`suffix`	`string`	Author name suffixes.

`Sentence`

Evidence sentence

Name	Type	Description
`uid`	`number`	Sentence unique identifier.
`confidence`	`number`	Confidence of prediction (currently NULL).
`paper_id`	`string`	Unique ID of paper from which evidence was derived.
`sentence_id`	`number`	Sentence number in abstract of source paper.
`spans`	`List[Span]`	Sentence containing interaction evidence.

`Span`

Sentence span

Name	Type	Description
`text`	`string`	Span text.
`cui`	`string`	Associated agent CUI (Null if none associated).

Help us improve supp.ai, we'd love to hear your feedback: Submit Feedback