{
  "openapi": "3.1.0",
  "info": {
    "title": "Trial0 API",
    "version": "1.0.0",
    "summary": "Frontier treatment eligibility matching and site-level availability, live from ClinicalTrials.gov.",
    "description": "Trial0 helps people worldwide find relevant clinical trials from public registries. Free members get live matches and alerts; Pro members can ask Trial0 to research contacts and prepare outreach, with approval required before each trial is contacted. Informational matching only, never medical advice.\n\n**Authentication.** Every endpoint takes `Authorization: Bearer <key>`. The public sandbox key `fc_test_sandbox` requires no signup and is throttled to roughly 25 requests per 24 hours per IP. That counter lives in each server instance's memory, so the effective ceiling scales with concurrency and resets on redeploy — treat it as a courtesy limit, not a quota you can rely on.\n\n**Disclaimer.** Trial0 is a navigation service, not a medical provider. Nothing here is medical advice or a recommendation to pursue any treatment; eligibility matching is informational, based on published registry criteria, and only the trial site or treating clinician can determine actual eligibility. Decisions belong with the patient and their own doctors.",
    "contact": {
      "name": "Trial0 support",
      "email": "hello@trial0.com",
      "url": "https://trial0.com/docs/api"
    },
    "license": {
      "name": "Registry data: ClinicalTrials.gov, US Government work",
      "url": "https://clinicaltrials.gov/about-site/terms-conditions"
    }
  },
  "servers": [
    {
      "url": "https://trial0.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Matching",
      "description": "Match a patient profile to open frontier options."
    },
    {
      "name": "Availability",
      "description": "Site-level recruiting status for one study."
    },
    {
      "name": "Reference",
      "description": "Launch areas and intake vocabulary."
    }
  ],
  "paths": {
    "/match": {
      "post": {
        "operationId": "matchFrontierOptions",
        "tags": [
          "Matching"
        ],
        "summary": "Match a patient profile against every open frontier option",
        "description": "Queries ClinicalTrials.gov live (interventional trials + expanded-access programs, open statuses only) and returns each option with per-criterion match states. Structured registry fields (age, sex, status, phase) give firm matched/not_matched; free-text criteria give mentioned/unknown signposts to verify with the site. Pro-plan keys also receive the verified site-intelligence overlay under `sites[].verified`; other keys get `verified_site_counts` instead. Informational matching only — never medical advice.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "condition": {
                    "type": "string",
                    "description": "Launch-area slug (alzheimers, glioblastoma, pancreatic-cancer) or free-text condition name."
                  },
                  "stage": {
                    "type": "string"
                  },
                  "biomarkers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 16
                  },
                  "prior_lines": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "age": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 130
                  },
                  "sex": {
                    "type": "string",
                    "enum": [
                      "male",
                      "female"
                    ]
                  },
                  "location": {
                    "type": "object",
                    "properties": {
                      "lat": {
                        "type": "number"
                      },
                      "lng": {
                        "type": "number"
                      },
                      "radius_miles": {
                        "type": "number",
                        "default": 100
                      },
                      "query": {
                        "type": "string"
                      }
                    },
                    "description": "Either {lat, lng, radius_miles?} or {query}."
                  },
                  "include": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "interventional",
                        "expanded_access"
                      ]
                    }
                  },
                  "phases": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "EARLY_PHASE1",
                        "PHASE1",
                        "PHASE2",
                        "PHASE3",
                        "PHASE4"
                      ]
                    }
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 20
                  }
                },
                "required": [
                  "condition"
                ],
                "additionalProperties": false
              },
              "examples": {
                "glioblastoma_recurrent": {
                  "summary": "Recurrent glioblastoma near Boston",
                  "value": {
                    "condition": "glioblastoma",
                    "stage": "Recurrent",
                    "biomarkers": [
                      "MGMT methylated",
                      "IDH wild-type"
                    ],
                    "age": 54,
                    "location": {
                      "lat": 42.3601,
                      "lng": -71.0589,
                      "radius_miles": 200
                    },
                    "limit": 10
                  }
                },
                "rare_free_text": {
                  "summary": "Rare disease via free text",
                  "value": {
                    "condition": "Fibrodysplasia Ossificans Progressiva",
                    "limit": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matched options, ranked; empty `options` is a real answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RegistryUnavailable"
          }
        }
      }
    },
    "/availability/{nctId}": {
      "get": {
        "operationId": "getSiteAvailability",
        "tags": [
          "Availability"
        ],
        "summary": "Site-level availability for one study",
        "description": "The study's sites with registry-published status. Pro-plan keys receive the verified overlay (observed status, freshness, investigator referral acceptance); other keys receive `verified_site_count`.",
        "parameters": [
          {
            "name": "nctId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^NCT\\d{8}$"
            },
            "example": "NCT04575922"
          }
        ],
        "responses": {
          "200": {
            "description": "The study with its sites.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailabilityResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RegistryUnavailable"
          }
        }
      }
    },
    "/conditions": {
      "get": {
        "operationId": "listLaunchConditions",
        "tags": [
          "Reference"
        ],
        "summary": "Launch disease areas and intake vocabulary",
        "description": "The condition areas with structured intake, their registry expressions and suggested stage/biomarker vocabulary, plus the rare-disease free-text path. Free text is always accepted by /match.",
        "responses": {
          "200": {
            "description": "The launch areas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConditionsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/RegistryUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key. The public sandbox key `fc_test_sandbox` needs no signup and is limited to ~25 requests/24h per IP. Issued keys (`fc_sk_…`, Pro plan) carry a 5,000 call/month quota and unlock the verified site-intelligence fields."
      }
    },
    "schemas": {
      "CriterionCheck": {
        "type": "object",
        "description": "How the profile relates to one published criterion. `matched`/`not_matched` come only from structured registry fields; `mentioned_*` means the term appears in free-text criteria (verify with the site); `unknown` means the registry does not publish enough to decide. A mention is a signpost, never a verdict.",
        "properties": {
          "criterion": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "matched",
              "not_matched",
              "mentioned_inclusion",
              "mentioned_exclusion",
              "unknown"
            ]
          },
          "evidence": {
            "type": "string",
            "description": "What in the registry record produced this state."
          }
        },
        "required": [
          "criterion",
          "state",
          "evidence"
        ]
      },
      "VerifiedSiteIntel": {
        "type": "object",
        "description": "The private-graph overlay: what Trial0 has OBSERVED first-hand about this (trial, site) pair. Present only on Pro-plan responses.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "recruiting",
              "not_recruiting",
              "waitlist",
              "unknown"
            ],
            "description": "Observed recruiting status — not the registry's published one."
          },
          "last_verified_at": {
            "type": "string",
            "format": "date-time"
          },
          "investigator_accepts_referrals": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "status",
          "last_verified_at"
        ]
      },
      "TrialSite": {
        "type": "object",
        "properties": {
          "facility": {
            "type": "string"
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "registry_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registry-published per-site status, when the registry lists one."
          },
          "distance_miles": {
            "type": [
              "number",
              "null"
            ],
            "description": "Present when the request carried a geo point."
          },
          "verified": {
            "type": "object",
            "description": "The private-graph overlay: what Trial0 has OBSERVED first-hand about this (trial, site) pair. Present only on Pro-plan responses.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "recruiting",
                  "not_recruiting",
                  "waitlist",
                  "unknown"
                ],
                "description": "Observed recruiting status — not the registry's published one."
              },
              "last_verified_at": {
                "type": "string",
                "format": "date-time"
              },
              "investigator_accepts_referrals": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "notes": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "last_verified_at"
            ]
          }
        },
        "required": [
          "facility"
        ]
      },
      "MatchedOption": {
        "type": "object",
        "properties": {
          "nct_id": {
            "type": "string",
            "pattern": "^NCT\\d{8}$"
          },
          "title": {
            "type": "string"
          },
          "study_type": {
            "type": "string",
            "enum": [
              "interventional",
              "expanded_access"
            ]
          },
          "overall_status": {
            "type": "string"
          },
          "phases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "interventions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "sponsor": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "criteria_checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CriterionCheck"
            }
          },
          "unknown_count": {
            "type": "integer",
            "description": "How many profile fields the published record could not decide on."
          },
          "sites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrialSite"
            }
          },
          "eligibility_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "registry_url": {
            "type": "string",
            "format": "uri"
          },
          "last_update_posted": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "nct_id",
          "title",
          "study_type",
          "overall_status",
          "criteria_checks",
          "sites"
        ]
      },
      "Source": {
        "type": "object",
        "description": "Provenance: the registry actually queried, with the exact URL.",
        "properties": {
          "registry": {
            "type": "string",
            "const": "ClinicalTrials.gov"
          },
          "query_url": {
            "type": "string",
            "format": "uri"
          },
          "retrieved_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "registry",
          "query_url",
          "retrieved_at"
        ]
      },
      "MatchResponse": {
        "type": "object",
        "properties": {
          "input_echo": {
            "type": "object"
          },
          "total_found": {
            "type": "integer"
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatchedOption"
            }
          },
          "verified_fields_included": {
            "type": "boolean"
          },
          "verified_site_counts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Non-Pro keys only: per-NCT count of sites carrying verified observations, without their contents."
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "registry": {
            "type": "string"
          },
          "registry_api": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string",
            "description": "Ships on every payload: informational matching, never medical advice."
          }
        },
        "required": [
          "total_found",
          "options",
          "verified_fields_included",
          "source"
        ]
      },
      "AvailabilityResponse": {
        "type": "object",
        "properties": {
          "study": {
            "$ref": "#/components/schemas/MatchedOption"
          },
          "verified_fields_included": {
            "type": "boolean"
          },
          "verified_site_count": {
            "type": "integer"
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          },
          "registry": {
            "type": "string"
          },
          "registry_api": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string",
            "description": "Ships on every payload: informational matching, never medical advice."
          }
        },
        "required": [
          "study",
          "verified_fields_included",
          "source"
        ]
      },
      "ConditionsResponse": {
        "type": "object",
        "properties": {
          "launch_areas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "registry_query": {
                  "type": "string"
                },
                "stages": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "biomarkers": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "rare_disease_path": {
            "type": "object"
          },
          "note": {
            "type": "string"
          },
          "registry": {
            "type": "string"
          },
          "registry_api": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string",
            "description": "Ships on every payload: informational matching, never medical advice."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "unauthorized",
                  "rate_limited",
                  "not_found",
                  "method_not_allowed",
                  "idempotency_key_reuse",
                  "internal_error"
                ]
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              },
              "known_keys": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is malformed. `error.field` names the offending field and `error.known_keys` lists valid values for enums.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or unrecognised API key. The body includes the public sandbox key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such study exists on ClinicalTrials.gov.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit reached. `Retry-After` and `error.detail.retry_after_seconds` say when to retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RegistryUnavailable": {
        "description": "ClinicalTrials.gov could not be reached or errored. Nothing is cached or invented in its place — retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Full documentation",
    "url": "https://trial0.com/docs/api"
  }
}