Skip to content

Open interface: quickstart

Wire a regulator check into your workflow

One request asks whether a medicine is authorised in a market, or authorised for an indication, on a date. The answer names the regulator record that settles it, or says plainly that nothing held can. Free, no account needed. The full specification is the reference lookup page.


1. First call

The fastest path: no key, no account, no email, under a minute. Copy the request below and run it. Name the medicine exactly (brand or active substance), the market (an ISO country code or EU) and the proposition: P1, registered or authorised; P2, authorised for an indication from the published list.

curl "https://alphacitation.com/api/v1/reference/lookup?src=quickstart&medicine=Mounjaro&market=US&proposition=P2&indication=weight_management"

The answer, shortened:

{
  "status": "settled",
  "relation": "disagrees",
  "summary": "Mounjaro for weight management in US on ...: settled by the US prescribing information (DailyMed, as submitted to the US FDA). The label does not state the claimed indication. In US, tirzepatide is authorised for weight management as Zepbound (the US prescribing information for Zepbound (DailyMed, as submitted to the US FDA), ...), not as Mounjaro.",
  "records": [ { "role": "regulator_of_record", "issuedBy": { "name": "Eli Lilly and Company" }, "publishedBy": { "name": "US National Library of Medicine (DailyMed)" }, "authority": { "name": "US FDA" }, "application": "...",
                 "pointer": "https://dailymed.nlm.nih.gov/...", "version": "SPL version ...", "sha256": "...",
                 "lastVerifiedAt": "...", "relied": true, "relation": "disagrees", ... }, ... ],
  "notes": [ { "code": "indication_under_other_product", "detail": "..." } ],
  "unresolved": [],
  ...
}

The summary states the answer in words and names the authority that settles it. Cite the pointer and version of the regulator_of_record records; where one is marked relied, the answer rests on that one. In a disagrees answer none is marked relied: the answer rests on every regulator_of_record record together. Where the substance is authorised for the indication under another product, as here, notes names that product with its own pointer. The service returns no label text: the pointer is where a person reads it.

2. Read the answer as a decision

Only settled with agrees clears a claim. Every other answer is a 200 with a body, and none of them is a clearance. An answer that cannot settle the claim is unknown, never false, and should go to a person.

settled, agrees
Clear the claim, citing the relied record's pointer and version.
settled, agrees_narrower
Clear it only for the population or formulations the record names (statedPopulation, formulations); for anything wider, send it for review.
settled, disagrees
Do not clear. The governing record does not state the indication: correct the claim, or send it for review with the record.
settled, insufficient
Not a clearance. Send it to a person, with the records and the unresolved items the answer lists.
supported_attested
Not a clearance. Send it to a person, with the records and the unresolved items the answer lists.
settling_record_identified
Not a clearance. Send it to a person, with the records and the unresolved items the answer lists.
reference_only
Not a clearance. Send it to a person, with the records and the unresolved items the answer lists.
unresolved
Not a clearance. Send it to a person, with the records and the unresolved items the answer lists.

A refusal (400, 401, 413, 429, 503) or a call that fails is no answer at all, and is not a clearance either. Each item in unresolved says what could not be established; where it carries retryAfter, asking again after that many seconds may settle it.

3. In your code

Python
import time, requests

LOOKUP = "https://alphacitation.com/api/v1/reference/lookup?src=quickstart"

def decide(answer):
    """Only a settled answer that agrees clears a claim. Anything that cannot settle it is never a clearance."""
    status, relation = answer["status"], answer["relation"]
    if status != "settled":
        return "cannot_settle"            # route to a person; unknown, never false
    return {"agrees": "clear",
            "agrees_narrower": "clear_narrower_only",
            "disagrees": "contradicted"}.get(relation, "cannot_settle")

def lookup(query, key=None, attempts=3):
    headers = {"Authorization": f"Bearer {key}"} if key else {}
    for _ in range(attempts):
        r = requests.post(LOOKUP, json=query, headers=headers, timeout=60)
        if r.status_code in (429, 503):    # over the limit, or paused: wait, then ask again
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        r.raise_for_status()               # 400 names the field; 401 means the key was not accepted
        return r.json()
    return None                            # no answer is not a clearance

answer = lookup({"medicine": "Wegovy", "market": "EU", "proposition": "P2", "indication": "weight_management"})
decision = decide(answer) if answer else "cannot_settle"
records = [x for x in (answer or {}).get("records", []) if x["role"] == "regulator_of_record"]
print(decision, answer and answer["summary"], [(x["pointer"], x["version"]) for x in records])
TypeScript
const LOOKUP = "https://alphacitation.com/api/v1/reference/lookup?src=quickstart";

type Decision = "clear" | "clear_narrower_only" | "contradicted" | "cannot_settle";

/** Only a settled answer that agrees clears a claim. Anything that cannot settle it is never a clearance. */
function decide(a: { status: string; relation: string }): Decision {
  if (a.status !== "settled") return "cannot_settle";
  if (a.relation === "agrees") return "clear";
  if (a.relation === "agrees_narrower") return "clear_narrower_only";
  if (a.relation === "disagrees") return "contradicted";
  return "cannot_settle";
}

async function lookup(query: Record<string, string | number>, key?: string, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(LOOKUP, {
      method: "POST",
      headers: { "Content-Type": "application/json", ...(key ? { Authorization: `Bearer ${key}` } : {}) },
      body: JSON.stringify(query),
      signal: AbortSignal.timeout(60_000),
    });
    if (res.status === 429 || res.status === 503) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 60) * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`lookup refused: ${res.status} ${await res.text()}`);
    return res.json();
  }
  return null; // no answer is not a clearance
}

POST keeps the query out of URLs and logs; GET with the same fields as query parameters works too. The full interface is described in OpenAPI 3.1.

4. As an MCP server

For an agent, the same lookup is a Model Context Protocol server at https://alphacitation.com/api/v1/reference/mcp (Streamable HTTP) with one tool, lookup_medicine_evidence. No key or sign-in is needed to connect.

Claude (claude.ai or the desktop app): Customize, Connectors, Add, Add custom connector; give it a name, paste this address, choose No sign in, then Add. On Team and Enterprise plans an Owner adds it under Organization settings, Connectors, and members then connect it.

ChatGPT (on the web): Plugins, the plus button, Add custom MCP server; give it a name, paste this address as the Server URL, choose No authentication, confirm the warning, Create as a plugin, then install it. Your workspace's own permissions apply.

Then ask, for example, whether Mounjaro is authorised for weight management in the US. In Claude Code:

claude mcp add --transport http alphacitation "https://alphacitation.com/api/v1/reference/mcp?src=quickstart"

Or in a project's .mcp.json; other clients take the same address, in the file format their own documentation gives:

{
  "mcpServers": {
    "alphacitation": { "type": "http", "url": "https://alphacitation.com/api/v1/reference/mcp?src=quickstart" }
  }
}

From the Claude API, with the MCP connector:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "mcp_servers": [{ "type": "url", "url": "https://alphacitation.com/api/v1/reference/mcp?src=quickstart", "name": "alphacitation" }],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "alphacitation" }],
    "messages": [{ "role": "user", "content": "Is Mounjaro authorised for weight management in the US today? Cite the record." }]
  }'

From the OpenAI Responses API, as a remote MCP tool:

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{ "type": "mcp", "server_label": "alphacitation", "server_url": "https://alphacitation.com/api/v1/reference/mcp?src=quickstart", "require_approval": "never" }],
    "input": "Is Mounjaro authorised for weight management in the US today? Cite the record."
  }'

To check the server from a terminal, call the tool directly:

curl -X POST "https://alphacitation.com/api/v1/reference/mcp?src=quickstart" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"lookup_medicine_evidence","arguments":{"medicine":"Mounjaro","market":"DE","proposition":"P1"}}}'

The tool's result is the same answer as the lookup's, and the decision rule above applies to it unchanged. The server tells the model never to present an answer other than settled as settled; your workflow should hold to that rule in its own code, not rely on the model.

5. Test every answer in the sandbox

Which status a real medicine returns depends on the records held that day, so a test suite cannot rely on one. The sandbox at /api/v1/reference/sandbox/lookup takes the same request and returns a fixed, fictional answer for the scenario the medicine names. Every sandbox answer carries sandbox with the decision your code should reach, so a test can assert against it. It is never evidence about any medicine.

curl "https://alphacitation.com/api/v1/reference/sandbox/lookup?src=quickstart&medicine=sandbox-reference-only&market=AE&proposition=P1"
sandbox-settled-agrees
settled, agrees. Clear the claim, citing the record's pointer and version.
sandbox-settled-narrower
settled, agrees_narrower (P2 only). Clear the claim only for the population or formulations the record names; otherwise send it for review.
sandbox-settled-disagrees
settled, disagrees (P2 only). Do not clear. The governing record does not state the indication; correct the claim or send it for review.
sandbox-record-identified
settling_record_identified, insufficient. Do not clear. Send for review, with the record's pointer for the reviewer to read.
sandbox-attested
supported_attested, agrees. Do not treat as settled. Supported by the authorisation holder's own label; route by your own policy for holder evidence.
sandbox-reference-only
reference_only, insufficient. Do not clear. Other markets' labels do not decide this market; send for review.
sandbox-unresolved
unresolved, insufficient. Do not clear. Unknown, never false; where an item carries retryAfter, ask again after it.
sandbox-rate-limited
HTTP 429 with Retry-After. Wait for Retry-After seconds, then ask again. Never read a refusal as an answer.
sandbox-paused
HTTP 503 with Retry-After. Wait for Retry-After seconds, then ask again. Never read a refusal as an answer.

Requests are read exactly as the live lookup reads them, so a malformed one is refused with the same 400, and a key is checked the same way. Refusals ask you to wait 30 or 120 seconds. The sandbox has its own hourly allowance and never uses the live one.

6. An optional key

A key is free and changes no answer. It raises the limit 5 times, counted for the key wherever you call from, so a workflow behind shared or changing addresses keeps its allowance. Sign in with your work address at Open API keys (a code is emailed; no password), name your organisation and make a key; it is shown once. Send it as Authorization: Bearer or X-API-Key. A key that is revoked or mistyped is refused with 401, never silently ignored.

7. Limits, errors and status

  • 240 requests an hour from one address, shared by the lookup and the MCP server, or 1200 an hour for one key. One medicine, one market and one proposition a request; no listing or bulk access.
  • A medicine nobody has asked about that day needs fresh reads of the regulators' registers. One address may start about 30 of those an hour, and a new medicine takes two to four. Beyond that, the answer is unresolved with the code upstream_caller_limit and a retryAfter; asking again then is answered. A medicine already asked about that day is not counted.
  • 400 names the field that could not be read. 401: the key was not accepted. 413: the body is over 4 KiB.
  • 429 (over the limit) and 503 (paused) carry Retry-After: wait that long, then ask again.
  • An answer usually arrives within a few seconds; one that has to read a regulator's register afresh takes longer. Allow 60 seconds before treating a call as failed.

GET https://alphacitation.com/api/v1/reference/status says whether the lookup is answering: operating, degraded (answering, but likely to abstain more than usual) or paused. Check it before a batch, or point a monitor at it. No uptime figure is published yet, and no service level is offered on the open interface; for an agreed one, write to analyst@alphacitation.com.

What it covers today

  • Registration (P1) is settled from US labels of approved applications (an unapproved, OTC monograph or homeopathic label settles nothing), and, for products authorised through the EU's centralised procedure whose record is held, from the EU product information, for the EU and each EU and EEA member state. A product authorised only nationally, or a central record not yet held, is answered as unresolved or reference only, never as not authorised.
  • Indications (P2) are asked only by an identifier on the published list, which today covers cardiometabolic indications. An indication is decided only where the label's indications section has been read; where it has not, the answer says so and decides nothing.
  • Dates. A date is decided only where the version held was in force on it. An earlier date is answered with no_version_in_force_on_date in unresolved.
  • Other markets, the Gulf states and the UK among them, are answered as reference_only unless the authorisation holder publishes its own label: the US and EU labels are listed as references and never decide the claim there.

What an answer does and does not establish is stated in every answer's scope and on the specification.