Your agent can call this
and get real availability back.

Every endpoint takes Authorization: Bearer <key>. An unrecognised key is rejected with a structured 401 rather than silently downgraded to the sandbox tier — a caller with a stale key must be told, not quietly served under different limits.

# Base URL
https://trial0.com/api/v1

# Every request
-H 'authorization: Bearer fc_test_sandbox'

CORS is open for GET and POST from any origin, so browser-side agents can call it directly.

Every command below is complete and runnable as written. Responses are trimmed for readability but the field names are exact; each one also carries source (the exact registry query URL) and disclaimer.

curl -s https://trial0.com/api/v1/match \
  -H 'authorization: Bearer fc_test_sandbox' \
  -H 'content-type: application/json' \
  -d '{
    "condition": "glioblastoma",
    "stage": "Recurrent",
    "biomarkers": ["MGMT methylated", "IDH wild-type"],
    "age": 54,
    "location": {"lat": 42.3601, "lng": -71.0589, "radius_miles": 200},
    "limit": 5
  }'

{
  "total_found": 87,
  "options": [
    {
      "nct_id": "NCT0XXXXXXX",
      "title": "A Phase 2 Study of ... in Recurrent Glioblastoma",
      "study_type": "interventional",
      "overall_status": "RECRUITING",
      "phases": ["PHASE2"],
      "criteria_checks": [
        { "criterion": "Study open to new participants", "state": "matched",
          "evidence": "Registry overall status: RECRUITING" },
        { "criterion": "Age within published bounds", "state": "matched",
          "evidence": "Published bounds: 18 Years – none; patient age 54." },
        { "criterion": "Biomarker: MGMT methylated", "state": "mentioned_inclusion",
          "evidence": "This biomarker appears in the published inclusion criteria text. A promising signpost — the site must confirm it applies." }
      ],
      "unknown_count": 1,
      "sites": [
        { "facility": "Massachusetts General Hospital", "city": "Boston",
          "registry_status": "RECRUITING", "distance_miles": 0.8 }
      ],
      "registry_url": "https://clinicaltrials.gov/study/NCT0XXXXXXX"
    }
  ],
  "verified_fields_included": false,
  "verified_site_counts": { "NCT0XXXXXXX": 2 },
  "source": {
    "registry": "ClinicalTrials.gov",
    "query_url": "https://clinicaltrials.gov/api/v2/studies?query.cond=...",
    "retrieved_at": "2026-08-24T12:00:00.000Z"
  },
  "disclaimer": "Trial0 is a navigation service, not a medical provider. ..."
}

curl -s https://trial0.com/api/v1/availability/NCT04575922 \
  -H 'authorization: Bearer fc_test_sandbox'

{
  "study": {
    "nct_id": "NCT04575922",
    "title": "...",
    "overall_status": "RECRUITING",
    "sites": [
      { "facility": "...", "city": "...", "registry_status": "RECRUITING" }
    ]
  },
  "verified_fields_included": false,
  "verified_site_count": 1,
  "source": { "registry": "ClinicalTrials.gov", "query_url": "...", "retrieved_at": "..." }
}

curl -s https://trial0.com/api/v1/conditions \
  -H 'authorization: Bearer fc_test_sandbox'

{
  "launch_areas": [
    { "slug": "alzheimers", "name": "Alzheimer's disease & early-stage dementia",
      "stages": ["Mild cognitive impairment (MCI)", "..."],
      "biomarkers": ["Amyloid PET positive", "..."] },
    { "slug": "glioblastoma", "name": "Glioblastoma", "stages": ["..."], "biomarkers": ["..."] },
    { "slug": "pancreatic-cancer", "name": "Pancreatic cancer", "stages": ["..."], "biomarkers": ["..."] }
  ],
  "rare_disease_path": { "slug": "rare-disease", "name": "Rare disease (any condition)" }
}

JSON-RPC 2.0 over HTTP (Streamable HTTP transport) at https://trial0.com/api/mcp. Stateless — no session to resume, so a dropped connection is a non-event. Implements initialize, tools/list, tools/call and ping.

{
  "mcpServers": {
    "trial0": {
      "type": "http",
      "url": "https://trial0.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fc_test_sandbox"
      }
    }
  }
}

• match_frontier_options

  The /match endpoint as a tool: patient profile in, ranked frontier options with per-criterion match states out.

• get_site_availability

  Site-level availability for one NCT id — registry status for everyone, the verified overlay on Pro keys.

• list_launch_conditions

  The launch disease areas and intake vocabulary. Call it when unsure what `condition` accepts.

Every tool returns a readable text summary plus the full payload as structuredContent. The text keeps the match-state caveats attached, so a model relaying results to a human carries the “verify with the site” framing with it.

curl -s https://trial0.com/api/mcp \
  -H 'authorization: Bearer fc_test_sandbox' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://trial0.com/api/mcp \
  -H 'authorization: Bearer fc_test_sandbox' \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "match_frontier_options",
      "arguments": {
        "condition": "pancreatic-cancer",
        "stage": "Metastatic",
        "biomarkers": ["KRAS G12C"],
        "limit": 5
      }
    }
  }'

Protocol errors follow JSON-RPC: -32601 for an unknown method, -32602 for bad params — and a -32602 carries the same known_keys the REST API would return.

Errors are always {"error": {"code", "message", "docs_url", ...}}. When the offending field is an enum, the body carries known_keys — the complete list of accepted values — so a failed call can be fixed on the next attempt without a human reading these docs.

$ curl -s https://trial0.com/api/v1/match \
    -H 'authorization: Bearer fc_test_sandbox' \
    -H 'content-type: application/json' \
    -d '{"condition": "glioblastoma", "sex": "F"}'

{
  "error": {
    "code": "invalid_request",
    "message": "`sex` must be one of the known values.",
    "field": "sex",
    "known_keys": ["male", "female"],
    "docs": "https://trial0.vercel.app/docs/api#errors"
  }
}

Send an Idempotency-Key header on any POST. A replay with the same key and the same body returns the byte-identical original response, plus Idempotency-Replayed: true — so a caller that lost the first reply can tell a repeat from a fresh result. Reusing a key with a different body is a 409 rather than a silent wrong answer. Keys are held for 24 hours in memory, per instance.

curl -s https://trial0.com/api/v1/match \
  -H 'authorization: Bearer fc_test_sandbox' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: case-7f3a-attempt-1' \
  -d '{"condition": "alzheimers", "stage": "Mild / early-stage", "limit": 10}'

The sandbox key allows 25 requests per rolling 24 hours per IP. Every response — success or error — carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds). A 429 adds Retry-After. The counter is in-memory and per-instance, so it resets on deploy; account keys will use a durable store. See pricing for production volumes.

Trial0 is a navigation service, not a medical provider. Nothing returned by this API is medical advice; eligibility is always decided by the trial site, and treatment decisions belong with the patient and their own doctors.