Allen Institute for Artificial Intelligence
supp.ai logo
supp.ai

API Documentation

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

Endpoints

Data Types

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

NameTypeRequiredDefault ValueDescription
qstringYes-Text to search for. The agent name, description and synonyms are searched.
pnumberNo0The 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

NameTypeRequiredDefault ValueDescription

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

NameTypeRequiredDefault ValueDescription
pnumberNo1The 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

NameTypeRequiredDefault ValueDescription

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.

NameTypeDescription
resultsList[Agent]The supplement and drug entities matching the search query, in descending order by the likelihood of the match.
queryQueryThe original search query.
total_pagesnumberThe total number of result pages.
total_resultsnumberThe total number of results.
num_per_pagenumberThe number of results per results page.

Query

A search query

NameTypeDescription
qstringThe query text.
pnumberThe requested page number of results, zero indexed.

Agent

A drug or supplement.

NameTypeDescription
cuistringA unique identifier, derived from <a href="https://www.nlm.nih.gov/research/umls/index.html">UMLS</a>
preferred_namestringThe agent's canonical name.
synonymsList[string]A list of alternative names for the agent.
tradenamesList[string]A list of tradenames (brand names) for the agent (only available for drugs).
definitionstringA description of the agent.
slugstringA url safe version of the agent's name.
ent_typestringThe type of agent. One of "supplement", "drug", or "other."
interacts_with_countnumberThe number of interactions we found between the agent and others in our corpus.
matchesMap[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.

NameTypeDescription
pagenumberThe page number of the results.
interactionsInteractionThe original search query.
interactions_per_pagenumberThe number of results per results page.
totalnumberThe total number of results.

Interaction

One interaction between two agents supported by evidence.

NameTypeDescription
interaction_idstringThe interaction id between two agents, takes the form [CUI1-CUI2].
slugstringA url safe version of the interaction name.
agentAgentThe agent interacting with the queried agent.
evidenceList[Evidence]A list of evidence sentences supporting the interaction.

Evidence

Evidence sentences supporting an interaction

NameTypeDescription
paperPaperThe paper from which the evidence was derived.
sentencesList[Sentence]List of sentences from the paper with labeled supplement and drug spans.

Paper

Metadata about a scientific paper

NameTypeDescription
pidstringSemantic Scholar corpus identifier for a paper.
titlestringTitle of paper.
authorsList[Author]Authors of paper (currently an empty list).
yearnumberPublication year of paper.
venuestringPublication venue of paper.
doistringDOI of paper.
pmidnumberPubMed identifier of paper.
fields_of_studyList[string]Fields of study of paper.
animal_studybooleanWhether the paper documents an animal study.
human_studybooleanWhether the paper documents a human study.
clinical_studybooleanWhether the paper documents a clinical study.
retractionbooleanWhether the paper has been retracted.

Author

Author metadata

NameTypeDescription
firststringAuthor first name.
middlestringAuthor middle names.
laststringAuthor last name.
suffixstringAuthor name suffixes.

Sentence

Evidence sentence

NameTypeDescription
uidnumberSentence unique identifier.
confidencenumberConfidence of prediction (currently NULL).
paper_idstringUnique ID of paper from which evidence was derived.
sentence_idnumberSentence number in abstract of source paper.
spansList[Span]Sentence containing interaction evidence.

Span

Sentence span

NameTypeDescription
textstringSpan text.
cuistringAssociated agent CUI (Null if none associated).