BioMCP

openapi: "3.0.3" info: title: "ClinicalTrials.gov REST API" description: "This API is made available to provide users meta data, statistics,\ \ and the most recent version of the clinical trials available on ClinicalTrials.gov." version: "2.0.3" tags: - name: "Studies" description: "Related to clinical trial studies" - name: "Stats" description: "Data statistics" - name: "Version" description: "Version info" servers: - url: "https://clinicaltrials.gov/api/v2" description: "This server" paths: /studies: get: summary: "Studies" description: "Returns data of studies matching query and filter parameters.\ \ The studies are returned page by page.\nIf response contains `nextPageToken`,\ \ use its value in `pageToken` to get next page.\nThe last page will not contain\ \ `nextPageToken`. A page may have empty `studies` array.\nRequest for each\ \ subsequent page **must** have the same parameters as for the first page,\ \ except\n`countTotal`, `pageSize`, and `pageToken` parameters.\n\nIf neither\ \ queries nor filters are set, all studies will be returned.\nIf any query\ \ parameter contains only NCT IDs (comma- and/or space-separated), filters\ \ are ignored.\n\n`query.*` parameters are in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\n\ Those parameters affect ranking of studies, if sorted by relevance. See `sort`\ \ parameter for details.\n\n`filter.*` and `postFilter.*` parameters have\ \ same effect as there is no aggregation calculation. \nBoth are available\ \ just to simplify applying parameters from search request.\nBoth do not affect\ \ ranking of studies.\n\nNote: When trying JSON format in your browser, do\ \ not set too large `pageSize` parameter, if `fields` is\nunlimited. That\ \ may return too much data for the browser to parse and render." tags: - "Studies" operationId: "listStudies" parameters: - name: "format" in: "query" description: "Must be one of the following:\n* `csv`- return CSV table with\ \ one page of study data; first page will contain header with column names;\ \ available fields are listed on [CSV Download](/data-api/about-api/csv-download)\ \ page\n* `json`- return JSON with one page of study data; every study object\ \ is placed in a separate line; `markup` type fields format depends on `markupFormat`\ \ parameter" required: false schema: type: "string" enum: - "csv" - "json" default: "json" - name: "markupFormat" in: "query" description: "Format of `markup` type fields:\n* `markdown`- [markdown](https://spec.commonmark.org/0.28/)\ \ format\n* `legacy`- compatible with classic PRS\n\nApplicable only to\ \ `json` format." required: false schema: type: "string" enum: - "markdown" - "legacy" default: "markdown" - name: "query.cond" in: "query" description: "\"Conditions or disease\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"ConditionSearch Area\" on [Search Areas](/data-api/about-api/search-areas#ConditionSearch)\ \ for more details." required: false schema: type: "string" examples: example1: value: "lung cancer" example2: value: "(head OR neck) AND pain" - name: "query.term" in: "query" description: "\"Other terms\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"BasicSearch Area\" on [Search Areas](/data-api/about-api/search-areas#BasicSearch)\ \ for more details." required: false schema: type: "string" examples: example1: value: "AREA[LastUpdatePostDate]RANGE[2023-01-15,MAX]" - name: "query.locn" in: "query" description: "\"Location terms\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"LocationSearch Area\" on [Search Areas](/data-api/about-api/search-areas#LocationSearch)\ \ for more details." required: false schema: type: "string" - name: "query.titles" in: "query" description: "\"Title / acronym\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"TitleSearch Area\" on [Search Areas](/data-api/about-api/search-areas#TitleSearch)\ \ for more details." required: false schema: type: "string" - name: "query.intr" in: "query" description: "\"Intervention / treatment\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"InterventionSearch Area\" on [Search Areas](/data-api/about-api/search-areas#InterventionSearch)\ \ for more details." required: false schema: type: "string" - name: "query.outc" in: "query" description: "\"Outcome measure\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"OutcomeSearch Area\" on [Search Areas](/data-api/about-api/search-areas#OutcomeSearch)\ \ for more details." required: false schema: type: "string" - name: "query.spons" in: "query" description: "\"Sponsor / collaborator\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"SponsorSearch Area\" on [Search Areas](/data-api/about-api/search-areas#SponsorSearch)\ \ for more details." required: false schema: type: "string" - name: "query.lead" in: "query" description: "Searches in \"LeadSponsorName\" field. See [Study Data Structure](/data-api/about-api/study-data-structure#LeadSponsorName)\ \ for more details. The query is in [Essie expression syntax](/find-studies/constructing-complex-search-queries)." required: false schema: type: "string" - name: "query.id" in: "query" description: "\"Study IDs\" query in [Essie expression syntax](/find-studies/constructing-complex-search-queries).\ \ See \"IdSearch Area\" on [Search Areas](/data-api/about-api/search-areas#IdSearch)\ \ for more details." required: false schema: type: "string" - name: "query.patient" in: "query" description: "See \"PatientSearch Area\" on [Search Areas](/data-api/about-api/search-areas#PatientSearch)\ \ for more details." required: false schema: type: "string" - name: "filter.overallStatus" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of statuses" required: false schema: type: "array" items: $ref: "#/components/schemas/Status" examples: example1: value: - "NOT_YET_RECRUITING" - "RECRUITING" example2: value: - "COMPLETED" - name: "filter.geo" in: "query" description: "Filter by geo-function. Currently only distance function is\ \ supported.\nFormat: `distance(latitude,longitude,distance)`" required: false schema: type: "string" pattern: "^distance\\(-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,\\d+(\\.\\d+)?(km|mi)?\\\ )$" examples: example1: value: "distance(39.0035707,-77.1013313,50mi)" - name: "filter.ids" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of NCT IDs (a.k.a. ClinicalTrials.gov\ \ identifiers).\nThe provided IDs will be searched in [NCTId](data-api/about-api/study-data-structure#NCTId)\ \ and\n[NCTIdAlias](data-api/about-api/study-data-structure#NCTIdAlias)\ \ fields." required: false schema: type: "array" items: type: "string" pattern: "^[Nn][Cc][Tt]0*[1-9]\\d{0,7}$" examples: example1: value: - "NCT04852770" - "NCT01728545" - "NCT02109302" - name: "filter.advanced" in: "query" description: "Filter by query in [Essie expression syntax](/find-studies/constructing-complex-search-queries)" required: false schema: type: "string" examples: example1: value: "AREA[StartDate]2022" example2: value: "AREA[MinimumAge]RANGE[MIN, 16 years] AND AREA[MaximumAge]RANGE[16\ \ years, MAX]" - name: "filter.synonyms" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of `area`:`synonym_id`\ \ pairs" required: false schema: type: "array" items: type: "string" examples: example1: value: - "ConditionSearch:1651367" - "BasicSearch:2013558" - name: "postFilter.overallStatus" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of statuses" required: false schema: type: "array" items: $ref: "#/components/schemas/Status" examples: example1: value: - "NOT_YET_RECRUITING" - "RECRUITING" example2: value: - "COMPLETED" - name: "postFilter.geo" in: "query" description: "Filter by geo-function. Currently only distance function is\ \ supported.\nFormat: `distance(latitude,longitude,distance)`" required: false schema: type: "string" pattern: "^distance\\(-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?,\\d+(\\.\\d+)?(km|mi)?\\\ )$" examples: example1: value: "distance(39.0035707,-77.1013313,50mi)" - name: "postFilter.ids" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of NCT IDs (a.k.a. ClinicalTrials.gov\ \ identifiers).\nThe provided IDs will be searched in [NCTId](data-api/about-api/study-data-structure#NCTId)\ \ and\n[NCTIdAlias](data-api/about-api/study-data-structure#NCTIdAlias)\ \ fields." required: false schema: type: "array" items: type: "string" pattern: "^[Nn][Cc][Tt]0*[1-9]\\d{0,7}$" examples: example1: value: - "NCT04852770" - "NCT01728545" - "NCT02109302" - name: "postFilter.advanced" in: "query" description: "Filter by query in [Essie expression syntax](/find-studies/constructing-complex-search-queries)" required: false schema: type: "string" examples: example1: value: "AREA[StartDate]2022" example2: value: "AREA[MinimumAge]RANGE[MIN, 16 years] AND AREA[MaximumAge]RANGE[16\ \ years, MAX]" - name: "postFilter.synonyms" in: "query" style: "pipeDelimited" explode: false description: "Filter by comma- or pipe-separated list of `area`:`synonym_id`\ \ pairs" required: false schema: type: "array" items: type: "string" examples: example1: value: - "ConditionSearch:1651367" - "BasicSearch:2013558" - name: "aggFilters" in: "query" description: "Apply aggregation filters, aggregation counts will not be provided.\n\ The value is comma- or pipe-separated list of pairs `filter_id`:`space-separated\ \ list of option keys` for the checked options." required: false schema: type: "string" examples: example1: value: "results:with,status:com" example2: value: "status:not rec,sex:f,healthy:y" - name: "geoDecay" in: "query" description: "Set proximity factor by distance from `filter.geo` location\ \ to the closest [LocationGeoPoint](/data-api/about-api/study-data-structure#LocationGeoPoint)\ \ of a study.\nIgnored, if `filter.geo` parameter is not set or response\ \ contains more than 10,000 studies." required: false schema: type: "string" pattern: "^func:(gauss|exp|linear),scale:(\\d+(\\.\\d+)?(km|mi)),offset:(\\\ d+(\\.\\d+)?(km|mi)),decay:(\\d+(\\.\\d+)?)$" default: "func:exp,scale:300mi,offset:0mi,decay:0.5" examples: example1: value: "func:linear,scale:100km,offset:10km,decay:0.1" example2: value: "func:gauss,scale:500mi,offset:0mi,decay:0.3" - name: "fields" in: "query" style: "pipeDelimited" explode: false description: "If specified, must be non-empty comma- or pipe-separated list\ \ of fields to return. If unspecified, all fields will be returned.\nOrder\ \ of the fields does not matter.\n\nFor `csv` format, specify list of columns.\ \ The column names are available on [CSV Download](/data-api/about-api/csv-download).\n\ \nFor `json` format, every list item is either area name, piece name, field\ \ name, or special name.\nIf a piece or a field is a branch node, all descendant\ \ fields will be included.\nAll area names are available on [Search Areas](/data-api/about-api/search-areas),\n\ the piece and field names — on [Data Structure](/data-api/about-api/study-data-structure)\ \ and also can be retrieved at `/studies/metadata` endpoint.\nThere is a\ \ special name, `@query`, which expands to all fields queried by search." required: false schema: type: "array" minItems: 1 items: type: "string" pattern: "^([a-zA-Z][a-zA-Z0-9\\-. ]*)|(@query)$" examples: example1: value: - "NCTId" - "BriefTitle" - "OverallStatus" - "HasResults" example2: value: "ProtocolSection" - name: "sort" in: "query" style: "pipeDelimited" explode: false description: "Comma- or pipe-separated list of sorting options of the studies.\ \ The returning studies are not sorted by default for a performance reason.\n\ Every list item contains a field/piece name and an optional sort direction\ \ (`asc` for ascending or `desc` for descending)\nafter colon character.\n\ \nAll piece and field names can be found on [Data Structure](/data-api/about-api/study-data-structure)\ \ and also can be retrieved\nat `/studies/metadata` endpoint. Currently,\ \ only date and numeric fields are allowed for sorting.\nThere is a special\ \ \"field\" `@relevance` to sort by relevance to a search query.\n\nStudies\ \ missing sort field are always last. Default sort direction:\n* Date field\ \ - `desc`\n* Numeric field - `asc`\n* `@relevance` - `desc`" required: false schema: type: "array" maxItems: 2 default: [] items: type: "string" pattern: "^(([a-zA-Z][a-zA-Z0-9\\-. ]*)|(@relevance))(:(asc|desc))?$" examples: example1: value: - "@relevance" example2: value: - "LastUpdatePostDate" example3: value: - "EnrollmentCount:desc" - "NumArmGroups" - name: "countTotal" in: "query" description: "Count total number of studies in all pages and return `totalCount`\ \ field with first page, if `true`.\nFor CSV, the result can be found in\ \ `x-total-count` response header.\nThe parameter is ignored for the subsequent\ \ pages." required: false schema: type: "boolean" default: false - name: "pageSize" in: "query" description: "Page size is maximum number of studies to return in response.\ \ It does not have to be the same for every page.\nIf not specified or set\ \ to 0, the default value will be used. It will be coerced down to 1,000,\ \ if greater than that." required: false schema: type: "integer" format: "int32" minimum: 0 default: 10 examples: example1: value: 2 example2: value: 100 - name: "pageToken" in: "query" description: "Token to get next page. Set it to a `nextPageToken` value returned\ \ with the previous page in JSON format.\nFor CSV, it can be found in `x-next-page-token`\ \ response header.\nDo not specify it for first page." required: false schema: type: "string" responses: "200": description: "OK" content: application/json: schema: $ref: "#/components/schemas/PagedStudies" example: totalCount: 438897 studies: - protocolSection: identificationModule: nctId: "NCT03540771" briefTitle: "Introducing Palliative Care (PC) Within the Treatment\ \ of End Stage Liver Disease (ESLD)" statusModule: overallStatus: "RECRUITING" hasResults: false - protocolSection: identificationModule: nctId: "NCT03630471" briefTitle: "Effectiveness of a Problem-solving Intervention\ \ for Common Adolescent Mental Health Problems in India" statusModule: overallStatus: "COMPLETED" hasResults: false - protocolSection: identificationModule: nctId: "NCT00587795" briefTitle: "Orthopedic Study of the Aircast StabilAir Wrist\ \ Fracture Brace" statusModule: overallStatus: "TERMINATED" hasResults: true nextPageToken: "abracadabra" "400": description: "Bad Request" content: text/plain: schema: $ref: "#/components/schemas/errorMessage" /studies/{nctId}: get: summary: "Single Study" description: "Returns data of a single study." tags: - "Studies" operationId: "fetchStudy" parameters: - name: "nctId" in: "path" description: "NCT Number of a study. If found in [NCTIdAlias](data-api/about-api/study-data-structure#NCTIdAlias)\ \ field,\n301 HTTP redirect to the actual study will be returned." required: true schema: type: "string" pattern: "^[Nn][Cc][Tt]0*[1-9]\\d{0,7}$" examples: example1: value: "NCT00841061" example2: value: "NCT04000165" - name: "format" in: "query" description: "Must be one of the following:\n* `csv`- return CSV table; available\ \ fields are listed on [CSV Download](/data-api/about-api/csv-download)\n\ * `json`- return JSON object; format of `markup` fields depends on `markupFormat`\ \ parameter\n* `json.zip`- put JSON object into a .json file and download\ \ it as zip archive; field values of type `markup` are in [markdown](https://spec.commonmark.org/0.28/)\ \ format\n* `fhir.json` - return FHIR JSON; fields are not customizable;\ \ see [Access Data in FHIR](/data-api/fhir)\n* `ris`- return RIS record;\ \ available tags are listed on [RIS Download](/data-api/about-api/ris-download)" required: false schema: type: "string" enum: - "csv" - "json" - "json.zip" - "fhir.json" - "ris" default: "json" - name: "markupFormat" in: "query" description: "Format of `markup` type fields:\n* `markdown`- [markdown](https://spec.commonmark.org/0.28/)\ \ format\n* `legacy`- compatible with classic PRS\n\nApplicable only to\ \ `json` format." required: false schema: type: "string" enum: - "markdown" - "legacy" default: "markdown" - name: "fields" in: "query" style: "pipeDelimited" explode: false description: "If specified, must be non-empty comma- or pipe-separated list\ \ of fields to return. If unspecified, all fields will be returned.\nOrder\ \ of the fields does not matter.\n\nFor `csv` format, specify list of columns.\ \ The column names are available on [CSV Download](/data-api/about-api/csv-download).\n\ \nFor `json` and `json.zip` formats, every list item is either area name,\ \ piece name, or field name.\nIf a piece or a field is a branch node, all\ \ descendant fields will be included.\nAll area names are available on [Search\ \ Areas](/data-api/about-api/search-areas),\nthe piece and field names -\ \ on [Data Structure](/data-api/about-api/study-data-structure) and also\ \ can be retrieved at `/studies/metadata` endpoint.\n\nFor `fhir.json` format,\ \ all available fields are returned and this parameter must be unspecified.\n\ \nFor `ris` format, specify list of tags. The tag names are available on\ \ [RIS Download](/data-api/about-api/ris-download)." required: false schema: type: "array" minItems: 1 items: type: "string" pattern: "^[a-zA-Z][a-zA-Z0-9\\-. ]*$" examples: example1: value: - "NCTId" - "BriefTitle" - "Reference" example2: value: - "ConditionsModule" - "EligibilityModule" responses: "200": description: "OK" content: text/csv: schema: $ref: "#/components/schemas/StudiesCsv" application/json: schema: $ref: "#/components/schemas/Study" application/zip: schema: $ref: "#/components/schemas/StudiesZip" application/fhir+json: schema: $ref: "#/components/schemas/StudyFhir" "301": description: "Moved Permanently" content: {} "400": description: "Bad Request" content: text/plain: schema: $ref: "#/components/schemas/errorMessage" "404": description: "Not Found" content: text/plain: schema: $ref: "#/components/schemas/errorMessage" /studies/metadata: get: summary: "Data Model Fields" description: "Returns study data model fields." tags: - "Studies" operationId: "studiesMetadata" parameters: - name: "includeIndexedOnly" in: "query" description: "Include indexed-only fields, if `true`" required: false schema: type: "boolean" default: false - name: "includeHistoricOnly" in: "query" description: "Include fields available only in historic data, if `true`" required: false schema: type: "boolean" default: false responses: "200": description: "OK" content: application/json: schema: $ref: "#/components/schemas/FieldNodeList" "400": description: "Bad Request" content: text/plain: schema: $ref: "#/components/schemas/errorMessage"