supp.ai
SUPP.AI
API Documentation
SUPP.AI's API is free to use, provided you comply with theSemantic 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).
Help us improve supp.ai, we'd love to hear your feedback: Submit Feedback
© The Allen Institute for Artificial Intelligence (AI2) - All Rights Reserved | Privacy Policy | Terms of Use