{"openapi":"3.1.0","info":{"title":"IDC API","summary":"LLM-first REST API for NCI Imaging Data Commons, backed by idc-index + DuckDB.","version":"3.0.0b3+0640860"},"paths":{"/v3":{"get":{"tags":["meta"],"summary":"API root","description":"Entry point for the API: returns the server and build version, and links to the\ninteractive docs, the OpenAPI schema, and the version endpoint.","operationId":"root_v3_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v3/health":{"get":{"tags":["meta"],"summary":"Health check","description":"Liveness probe for the load balancer and uptime checks. Returns `{\"status\": \"ok\"}`\nonce the service is up.","operationId":"health_v3_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v3/version":{"get":{"tags":["discovery"],"summary":"IDC and server version","description":"Report the IDC data release served (e.g. `v24`) and the pinned idc-index-data\nversion, plus this server's own software `api_version` (and `build` stamp, if the deploy\nset one). Use it to confirm which IDC version — and which build of this server —\nproduced a given result.","operationId":"version_v3_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionInfo"},"examples":{"illustrative":{"summary":"Illustrative — not live values","value":{"idc_version":"v24","idc_index_data_version":"24.0.0","api_version":"3.0.0","build":"a1b2c3d"}}}}}}}}},"/v3/stats":{"get":{"tags":["discovery"],"summary":"Headline totals","description":"Headline totals for all of IDC: the number of collections, analysis results,\npatients, studies, series, and instances, plus the total size in TB.","operationId":"stats_v3_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"},"examples":{"illustrative":{"summary":"Illustrative — not live values","value":{"idc_version":"v24","collections":187,"analysis_results":42,"patients":68000,"studies":130000,"series":1500000,"instances":55000000,"size_TB":112.5}}}}}}}}},"/v3/collections":{"get":{"tags":["discovery"],"summary":"List collections","description":"List all IDC collections (original imaging datasets) with cancer types, tumor\nlocations, species, and subject counts. Use it to find a `collection_id` to filter\non.","operationId":"collections_v3_collections_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/CollectionSummary"},"type":"array","title":"Response Collections V3 Collections Get"}}}}}}},"/v3/collections/{collection_id}":{"get":{"tags":["discovery"],"summary":"Collection detail","description":"Detailed metadata for one collection: description, subject/series/instance counts,\ntotal size, the modalities present, and the license breakdown.","operationId":"collection_v3_collections__collection_id__get","parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","examples":["nlst"],"title":"Collection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/analysis_results":{"get":{"tags":["discovery"],"summary":"List analysis results","description":"List IDC analysis results — derived datasets (AI or expert segmentations,\nannotations, radiomics) layered on the original collections. Use it to find an\n`analysis_result_id`.","operationId":"analysis_results_v3_analysis_results_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AnalysisResult"},"type":"array","title":"Response Analysis Results V3 Analysis Results Get"}}}}}}},"/v3/attributes":{"get":{"tags":["discovery"],"summary":"List filter attributes","description":"List the attributes a cohort can be filtered by (name, type, whether categorical).\nUse it to learn valid filter attribute names before building a cohort. These are a\ncurated subset of the `index` table chosen for cohort filtering — `/sql` can query or\nfilter on any column in any table listed by `/tables`, including `index` columns that\naren't filter attributes.","operationId":"attributes_v3_attributes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/AttributeInfo"},"type":"array","title":"Response Attributes V3 Attributes Get"}}}}}}},"/v3/attributes/{attribute}/values":{"get":{"tags":["discovery"],"summary":"Distinct attribute values","description":"Return the distinct values (with counts) of a categorical attribute on the `index`\ntable, e.g. `Modality` or `BodyPartExamined`. Query this before filtering by an attribute\nso you use real values with the correct casing rather than guessing. The response carries\na `truncated` flag: when `false` the list is complete; when `true`, raise `limit` (capped\nserver-side) and re-check.","operationId":"attribute_values_v3_attributes__attribute__values_get","parameters":[{"name":"attribute","in":"path","required":true,"schema":{"type":"string","examples":["Modality"],"title":"Attribute"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"examples":[10],"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributeValues"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/tables":{"get":{"tags":["query"],"summary":"List queryable tables","description":"List the tables available to the SQL endpoint: the main `index`, the collection,\nanalysis, and version metadata tables, and the specialized indices — each named\n`<modality>_index` after the DICOM Modality it describes (`seg_index`: segmented anatomy\nof SEG series; `ct_index`, `mr_index`, `pt_index`: acquisition parameters; `sm_index`,\n`ann_index`: microscopy), plus `contrast_index`, `volume_geometry_index`, and\n`clinical_index`. Consult it before writing SQL, and whenever a property you need (e.g.\nwhat a segmentation contains) is not a filterable attribute — it may live in a\nspecialized index. Per-collection clinical tables are listed separately by\n`/clinical/tables`.","operationId":"tables_v3_tables_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableList"}}}}}}},"/v3/tables/{table}":{"get":{"tags":["query"],"summary":"Table schema","description":"Return the columns (name, type, description) of a table. Use it to get correct column\nnames before querying `/sql`. Pass `index` for the main series-level table.","operationId":"table_schema_v3_tables__table__get","parameters":[{"name":"table","in":"path","required":true,"schema":{"type":"string","examples":["index"],"title":"Table"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableSchema"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/clinical/tables":{"get":{"tags":["clinical"],"summary":"List clinical tables","description":"Discover the per-collection clinical (non-imaging) data tables — demographics,\ndiagnoses, cancer staging, therapies, labs, outcomes. Clinical data is not a filterable\nattribute and is not harmonized across collections, so table and column names vary per\ncollection. Pass `collection_id` to narrow to one collection. Each table is queryable via\n`/sql` as `clinical.<table_name>` and joins to `index` on\n`dicom_patient_id = index.PatientID`.","operationId":"clinical_tables_v3_clinical_tables_get","parameters":[{"name":"collection_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["nlst"],"title":"Collection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClinicalTableList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/clinical/tables/{table}":{"get":{"tags":["clinical"],"summary":"Clinical table schema","description":"Return the columns of a clinical table (name, DuckDB type, and a human-readable label\nfrom `clinical_index`, since clinical column names are often cryptic). Get the table name\nfrom `/clinical/tables`.","operationId":"clinical_table_schema_v3_clinical_tables__table__get","parameters":[{"name":"table","in":"path","required":true,"schema":{"type":"string","examples":["nlst_canc"],"title":"Table"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableSchema"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/clinical/tables/{table}/rows":{"get":{"tags":["clinical"],"summary":"Read clinical table rows","description":"Return the rows of a clinical table (capped at `max_rows`). Use it to inspect a small\nclinical table directly; for filtering by clinical attributes or joining to imaging,\nquery `/sql` against `clinical.<table>` instead. Get the table name from\n`/clinical/tables`.","operationId":"clinical_table_rows_v3_clinical_tables__table__rows_get","parameters":[{"name":"table","in":"path","required":true,"schema":{"type":"string","examples":["nlst_canc"],"title":"Table"}},{"name":"max_rows","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100000,"minimum":1},{"type":"null"}],"examples":[100],"title":"Max Rows"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/cohort/counts":{"post":{"tags":["cohort"],"summary":"Cohort counts","description":"Return distinct counts for a filtered cohort — patients, studies, series, instances,\nand total `size_TB` — without the sample rows or download payload. Use it as a fast size\ncheck before building a full manifest or downloading. `filters.terms` is\n`{attribute: [values]}` for equality/IN; `filters.ranges` is\n`{attribute: {\"gte\": x, \"lte\": y}}` for numeric or date ranges.\n\nThe response echoes `filters_applied` (the predicates actually used) and `warnings`.\n**Check them rather than assuming your filter landed**: an empty `filters_applied` means\nnothing was filtered and these counts describe all of IDC. An empty filter is allowed\nhere — it is how you ask how big the archive is — and reported in `warnings`.","operationId":"cohort_counts_v3_cohort_counts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortCounts"}}}},"400":{"description":"Filter could not be applied as given.","content":{"application/json":{"examples":{"unknown attribute":{"summary":"Attribute is not filterable (check GET /v3/attributes)","value":{"error":{"code":"invalid_query","message":"Unknown or non-term filter attribute: 'Modaliti'. Use list_attributes to see valid attributes."}}}}}}},"422":{"description":"Malformed body. Unrecognized keys are rejected rather than ignored, because an ignored key is a dropped predicate — which would silently widen the selection to all of IDC.","content":{"application/json":{"examples":{"filter not under `filters`":{"summary":"The filter object goes under `filters`","value":{"detail":[{"type":"value_error","loc":["body"],"msg":"Value error, the filter object goes under `filters`, e.g. {\"filters\": {\"terms\": {\"collection_id\": [\"nlst\"]}}} — got top-level 'terms'"}]}},"misspelled key":{"summary":"`min` is not a range bound (`gte` / `lte` are)","value":{"detail":[{"type":"extra_forbidden","loc":["body","filters","ranges","instanceCount","min"],"msg":"Extra inputs are not permitted"}]}}}}}}}}},"/v3/cohort/manifest":{"post":{"tags":["cohort"],"summary":"Build cohort manifest","description":"Build a cohort from structured filters and get back distinct counts (patients,\nstudies, series, instances, size_TB), a page of matching series, and a download payload\n(idc commands plus a manifest preview). `filters.terms` is `{attribute: [values]}` for\nequality/IN (e.g. `{\"Modality\": [\"MR\"]}`); `filters.ranges` is\n`{attribute: {\"gte\": x, \"lte\": y}}` for numeric or date ranges. Discover valid attributes\nvia `/attributes` and valid values via `/attributes/{attribute}/values`. For anything\nthese structured filters can't express, use `/sql`.\n\n**At least one filter predicate is required** — unfiltered, this is a download payload for\nthe entire archive; use `/stats` for archive-wide totals. `counts.filters_applied` echoes\nthe predicates actually used.","operationId":"cohort_manifest_v3_cohort_manifest_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestResponse"}}}},"400":{"description":"Filter could not be applied as given. Includes an unfiltered request, which is refused.","content":{"application/json":{"examples":{"unknown attribute":{"summary":"Attribute is not filterable (check GET /v3/attributes)","value":{"error":{"code":"invalid_query","message":"Unknown or non-term filter attribute: 'Modaliti'. Use list_attributes to see valid attributes."}}},"no filter predicate":{"summary":"Refused: unfiltered, this would enumerate every series in IDC","value":{"error":{"code":"invalid_query","message":"At least one filter predicate is required to build a manifest: unfiltered, that is every series in IDC (100+ TB). Use the stats surface for archive-wide totals, or cohort counts to size a filter first."}}}}}}},"422":{"description":"Malformed body. Unrecognized keys are rejected rather than ignored, because an ignored key is a dropped predicate — which would silently widen the selection to all of IDC.","content":{"application/json":{"examples":{"filter not under `filters`":{"summary":"The filter object goes under `filters`","value":{"detail":[{"type":"value_error","loc":["body"],"msg":"Value error, the filter object goes under `filters`, e.g. {\"filters\": {\"terms\": {\"collection_id\": [\"nlst\"]}}} — got top-level 'terms'"}]}},"misspelled key":{"summary":"`min` is not a range bound (`gte` / `lte` are)","value":{"detail":[{"type":"extra_forbidden","loc":["body","filters","ranges","instanceCount","min"],"msg":"Extra inputs are not permitted"}]}}}}}}}}},"/v3/cohort/manifest.txt":{"post":{"tags":["cohort"],"summary":"Cohort manifest (plain text)","description":"Return a plain-text manifest of public download URLs (one `s3://` per series,\ncompatible with `idc download-from-manifest`) for a filtered cohort, up to `limit`\nlines. `source` is `aws` (default) or `gcs` — both use the `s3://` scheme (GCS is\nreached via its S3-compatible endpoint, matching idc-index). These are anonymous public\nURLs — feed the file to the `idc` CLI, or `s5cmd --no-sign-request` directly for\n`source=aws` (add `--endpoint-url https://storage.googleapis.com` for `source=gcs`). The\nresponse is `text/plain`, one URL per line.\n\n**At least one filter predicate is required**: unfiltered, this enumerates every series in\nIDC. Being plain text, this response carries no `filters_applied` echo — use\n`/cohort/counts` first to confirm the filter and the size.","operationId":"cohort_manifest_text_v3_cohort_manifest_txt_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestTextRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"description":"Filter could not be applied as given. Includes an unfiltered request, which is refused.","content":{"application/json":{"examples":{"unknown attribute":{"summary":"Attribute is not filterable (check GET /v3/attributes)","value":{"error":{"code":"invalid_query","message":"Unknown or non-term filter attribute: 'Modaliti'. Use list_attributes to see valid attributes."}}},"no filter predicate":{"summary":"Refused: unfiltered, this would enumerate every series in IDC","value":{"error":{"code":"invalid_query","message":"At least one filter predicate is required to build a manifest: unfiltered, that is every series in IDC (100+ TB). Use the stats surface for archive-wide totals, or cohort counts to size a filter first."}}}}}}},"422":{"description":"Malformed body. Unrecognized keys are rejected rather than ignored, because an ignored key is a dropped predicate — which would silently widen the selection to all of IDC.","content":{"application/json":{"examples":{"filter not under `filters`":{"summary":"The filter object goes under `filters`","value":{"detail":[{"type":"value_error","loc":["body"],"msg":"Value error, the filter object goes under `filters`, e.g. {\"filters\": {\"terms\": {\"collection_id\": [\"nlst\"]}}} — got top-level 'terms'"}]}},"misspelled key":{"summary":"`min` is not a range bound (`gte` / `lte` are)","value":{"detail":[{"type":"extra_forbidden","loc":["body","filters","ranges","instanceCount","min"],"msg":"Extra inputs are not permitted"}]}}}}}}}}},"/v3/sql":{"post":{"tags":["query"],"summary":"Run read-only SQL","description":"Run a single read-only SQL `SELECT`/`WITH` against the IDC index (DuckDB) and return\nthe rows. Use it for anything the cohort filters can't express — GROUP BY, joins across\ntables, custom aggregations, or filtering on columns that aren't filter attributes. The\nattributes from `/attributes` are a curated subset of `index`, so `/sql` is how you reach\nthe rest: other `index` columns (e.g. `SeriesDescription`, `PatientAge`) and columns that\nlive only in a specialized index (e.g. segmented anatomy in `seg_index`). The connection\nis sandboxed: no writes, no file or network access, one statement only. Get correct table\nand column names from `/tables` and `/tables/{table}` first; the main table is `index`,\nand per-collection clinical tables are in the `clinical` schema. The result carries a\n`truncated` flag — when `true` you did not get every row, so narrow or aggregate the\nquery, or raise `max_rows` (clamped to a server ceiling) and re-check.","operationId":"sql_v3_sql_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/viewer-url":{"get":{"tags":["tools"],"summary":"Viewer URL","description":"Return a browser viewer URL (OHIF for radiology, Slim for slide microscopy) for a\nseries or study, so images can be viewed without downloading. Provide a\n`series_instance_uid` or `study_instance_uid` (obtain one from a cohort manifest or\n`/sql`).","operationId":"viewer_url_v3_viewer_url_get","parameters":[{"name":"series_instance_uid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["1.2.840.113654.2.55.136638632728533399820524570150364784952"],"title":"Series Instance Uid"}},{"name":"study_instance_uid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["1.2.840.113654.2.55.100004988183996567551011427980805457777"],"title":"Study Instance Uid"}},{"name":"viewer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["ohif_v3"],"title":"Viewer"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViewerURL"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v3/citations":{"post":{"tags":["tools"],"summary":"Cohort citations","description":"Return the publications to cite for a cohort: per-dataset citations (from the cohort's\nsource DOIs) in `citations`, plus the IDC paper in `idc_acknowledgment`.\n`citation_format` is one of `apa`, `bibtex`, `csl-json`, `turtle`. When publishing\nresults that use IDC data, include the per-dataset citations and acknowledge IDC itself\n(see the `recommendation` field). `filters_applied` echoes the cohort these citations are\nfor. Broad cohorts span many DOIs and take proportionally longer to resolve, so filter to\nthe data you actually used.","operationId":"citations_v3_citations_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationsResult"}}}},"400":{"description":"Filter could not be applied as given.","content":{"application/json":{"examples":{"unknown attribute":{"summary":"Attribute is not filterable (check GET /v3/attributes)","value":{"error":{"code":"invalid_query","message":"Unknown or non-term filter attribute: 'Modaliti'. Use list_attributes to see valid attributes."}}}}}}},"422":{"description":"Malformed body. Unrecognized keys are rejected rather than ignored, because an ignored key is a dropped predicate — which would silently widen the selection to all of IDC.","content":{"application/json":{"examples":{"filter not under `filters`":{"summary":"The filter object goes under `filters`","value":{"detail":[{"type":"value_error","loc":["body"],"msg":"Value error, the filter object goes under `filters`, e.g. {\"filters\": {\"terms\": {\"collection_id\": [\"nlst\"]}}} — got top-level 'terms'"}]}},"misspelled key":{"summary":"`min` is not a range bound (`gte` / `lte` are)","value":{"detail":[{"type":"extra_forbidden","loc":["body","filters","ranges","instanceCount","min"],"msg":"Extra inputs are not permitted"}]}}}}}}}}},"/v3/licenses":{"post":{"tags":["tools"],"summary":"Cohort license breakdown","description":"Return the license breakdown (series count and size per license) for a cohort. Use it\nto check whether the data is commercial-friendly (CC BY) or non-commercial only\n(CC BY-NC) before reuse. `filters_applied` echoes the predicates actually used — an empty\none means this is the license breakdown of all of IDC, not of your cohort.","operationId":"licenses_v3_licenses_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicensesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicensesResult"}}}},"400":{"description":"Filter could not be applied as given.","content":{"application/json":{"examples":{"unknown attribute":{"summary":"Attribute is not filterable (check GET /v3/attributes)","value":{"error":{"code":"invalid_query","message":"Unknown or non-term filter attribute: 'Modaliti'. Use list_attributes to see valid attributes."}}}}}}},"422":{"description":"Malformed body. Unrecognized keys are rejected rather than ignored, because an ignored key is a dropped predicate — which would silently widen the selection to all of IDC.","content":{"application/json":{"examples":{"filter not under `filters`":{"summary":"The filter object goes under `filters`","value":{"detail":[{"type":"value_error","loc":["body"],"msg":"Value error, the filter object goes under `filters`, e.g. {\"filters\": {\"terms\": {\"collection_id\": [\"nlst\"]}}} — got top-level 'terms'"}]}},"misspelled key":{"summary":"`min` is not a range bound (`gte` / `lte` are)","value":{"detail":[{"type":"extra_forbidden","loc":["body","filters","ranges","instanceCount","min"],"msg":"Extra inputs are not permitted"}]}}}}}}}}}},"components":{"schemas":{"AnalysisResult":{"properties":{"analysis_result_id":{"type":"string","title":"Analysis Result Id"},"analysis_result_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Analysis Result Title"},"source_DOI":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Doi"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"subjects":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subjects"},"collections":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collections"},"modalities":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modalities"},"license_short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Short Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["analysis_result_id"],"title":"AnalysisResult"},"AttributeInfo":{"properties":{"name":{"type":"string","title":"Name"},"table":{"type":"string","title":"Table"},"data_type":{"type":"string","title":"Data Type"},"kind":{"type":"string","title":"Kind","description":"'term' (equality/IN) or 'range' (gte/lte)."},"categorical":{"type":"boolean","title":"Categorical","description":"If true, get_attribute_values can enumerate its distinct values."},"description":{"type":"string","title":"Description"}},"type":"object","required":["name","table","data_type","kind","categorical","description"],"title":"AttributeInfo"},"AttributeValue":{"properties":{"value":{"title":"Value"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["value","count"],"title":"AttributeValue"},"AttributeValues":{"properties":{"attribute":{"type":"string","title":"Attribute"},"values":{"items":{"$ref":"#/components/schemas/AttributeValue"},"type":"array","title":"Values"},"truncated":{"type":"boolean","title":"Truncated","default":false},"note":{"type":"string","title":"Note","description":"Semantic caveat about this attribute, when one applies.","default":""}},"type":"object","required":["attribute","values"],"title":"AttributeValues"},"CitationsRequest":{"properties":{"filters":{"$ref":"#/components/schemas/CohortFilters"},"citation_format":{"type":"string","title":"Citation Format","default":"apa"}},"additionalProperties":false,"type":"object","title":"CitationsRequest","examples":[{"citation_format":"apa","filters":{"terms":{"collection_id":["nlst"]}}}]},"CitationsResult":{"properties":{"format":{"type":"string","title":"Format"},"citations":{"items":{},"type":"array","title":"Citations"},"idc_acknowledgment":{"anyOf":[{},{"type":"null"}],"title":"Idc Acknowledgment"},"recommendation":{"type":"string","title":"Recommendation","default":"In addition to the per-dataset citations, always acknowledge IDC itself by citing Fedorov et al., https://doi.org/10.1148/rg.230180 (see idc_acknowledgment)."},"filters_applied":{"$ref":"#/components/schemas/CohortFilters","description":"The filter predicates the server actually applied. Compare it with what you sent: if it is empty, nothing was filtered and these numbers cover all of IDC."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal problems with the request — above all, filter predicates that were dropped. Empty when the request was honored in full."}},"type":"object","required":["format","citations"],"title":"CitationsResult"},"ClinicalTableInfo":{"properties":{"table_name":{"type":"string","title":"Table Name","description":"Short table name; query as clinical.<table_name>."},"sql_path":{"type":"string","title":"Sql Path","description":"Ready-to-use FROM target for run_sql, e.g. clinical.nlst_canc — use this verbatim rather than reconstructing it from table_name."},"collection_id":{"type":"string","title":"Collection Id","description":"Collection this clinical table belongs to."},"column_count":{"type":"integer","title":"Column Count","description":"Number of documented columns (from clinical_index)."},"description":{"type":"string","title":"Description","default":""}},"type":"object","required":["table_name","sql_path","collection_id","column_count"],"title":"ClinicalTableInfo","description":"A per-collection clinical data table (e.g. ``nlst_canc``), queryable in SQL as\n``clinical.<table_name>`` and joinable to ``index`` on ``dicom_patient_id = PatientID``."},"ClinicalTableList":{"properties":{"tables":{"items":{"$ref":"#/components/schemas/ClinicalTableInfo"},"type":"array","title":"Tables"}},"type":"object","required":["tables"],"title":"ClinicalTableList"},"CohortCounts":{"properties":{"patients":{"type":"integer","title":"Patients"},"studies":{"type":"integer","title":"Studies"},"series":{"type":"integer","title":"Series"},"instances":{"type":"integer","title":"Instances"},"size_TB":{"type":"number","title":"Size Tb"},"filters_applied":{"$ref":"#/components/schemas/CohortFilters","description":"The filter predicates the server actually applied. Compare it with what you sent: if it is empty, nothing was filtered and these numbers cover all of IDC."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal problems with the request — above all, filter predicates that were dropped. Empty when the request was honored in full."}},"type":"object","required":["patients","studies","series","instances","size_TB"],"title":"CohortCounts"},"CohortFilters":{"properties":{"terms":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Terms","examples":[{"Modality":["CT"],"collection_id":["nlst"]}]},"ranges":{"additionalProperties":{"$ref":"#/components/schemas/NumericRange"},"type":"object","title":"Ranges"}},"additionalProperties":false,"type":"object","title":"CohortFilters","description":"Structured filters over the main `index` table. ``terms`` does equality/IN (OR within\nan attribute, AND across attributes); ``ranges`` does gte/lte. Discover valid attribute\nnames with ``list_attributes`` and valid values with ``get_attribute_values``.","examples":[{"ranges":{},"terms":{"Modality":["CT"],"collection_id":["nlst"]}}]},"CollectionDetail":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name"},"cancer_types":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancer Types"},"tumor_locations":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Locations"},"species":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Species"},"subjects":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subjects"},"supporting_data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Supporting Data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"patients":{"type":"integer","title":"Patients"},"studies":{"type":"integer","title":"Studies"},"series":{"type":"integer","title":"Series"},"instances":{"type":"integer","title":"Instances"},"size_TB":{"type":"number","title":"Size Tb"},"modalities":{"items":{"type":"string"},"type":"array","title":"Modalities","default":[]},"licenses":{"items":{"$ref":"#/components/schemas/LicenseItem"},"type":"array","title":"Licenses","default":[]}},"type":"object","required":["collection_id","patients","studies","series","instances","size_TB"],"title":"CollectionDetail"},"CollectionSummary":{"properties":{"collection_id":{"type":"string","title":"Collection Id"},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name"},"cancer_types":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancer Types"},"tumor_locations":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Locations"},"species":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Species"},"subjects":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subjects"},"supporting_data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Supporting Data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["collection_id"],"title":"CollectionSummary"},"ColumnSchema":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"description":{"type":"string","title":"Description","default":""}},"type":"object","required":["name","type"],"title":"ColumnSchema"},"CountsRequest":{"properties":{"filters":{"$ref":"#/components/schemas/CohortFilters"}},"additionalProperties":false,"type":"object","title":"CountsRequest","examples":[{"filters":{"terms":{"Modality":["CT"],"collection_id":["nlst"]}}}]},"DownloadInfo":{"properties":{"total_series":{"type":"integer","title":"Total Series"},"size_TB":{"type":"number","title":"Size Tb"},"idc_commands":{"items":{"type":"string"},"type":"array","title":"Idc Commands","description":"Ready-to-run commands using the `idc` CLI (from `pip install idc-index`)."},"manifest_preview":{"items":{"type":"string"},"type":"array","title":"Manifest Preview","description":"First few s3:// series URLs (sample)."},"manifest_truncated":{"type":"boolean","title":"Manifest Truncated","description":"True if the selection exceeds the manifest enumeration cap.","default":false},"note":{"type":"string","title":"Note","default":""}},"type":"object","required":["total_series","size_TB"],"title":"DownloadInfo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LicenseItem":{"properties":{"license_short_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Short Name"},"series":{"type":"integer","title":"Series"},"size_TB":{"type":"number","title":"Size Tb"}},"type":"object","required":["series","size_TB"],"title":"LicenseItem"},"LicensesRequest":{"properties":{"filters":{"$ref":"#/components/schemas/CohortFilters"}},"additionalProperties":false,"type":"object","title":"LicensesRequest","examples":[{"filters":{"terms":{"collection_id":["nlst"]}}}]},"LicensesResult":{"properties":{"licenses":{"items":{"$ref":"#/components/schemas/LicenseItem"},"type":"array","title":"Licenses"},"filters_applied":{"$ref":"#/components/schemas/CohortFilters","description":"The filter predicates the server actually applied. Compare it with what you sent: if it is empty, nothing was filtered and these numbers cover all of IDC."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal problems with the request — above all, filter predicates that were dropped. Empty when the request was honored in full."}},"type":"object","required":["licenses"],"title":"LicensesResult"},"ManifestRequest":{"properties":{"filters":{"$ref":"#/components/schemas/CohortFilters"},"page":{"type":"integer","title":"Page","default":0},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Size"},"include_rows":{"type":"boolean","title":"Include Rows","default":true}},"additionalProperties":false,"type":"object","title":"ManifestRequest","examples":[{"filters":{"terms":{"Modality":["CT"],"collection_id":["nlst"]}},"include_rows":true,"page":0,"page_size":50}]},"ManifestResponse":{"properties":{"counts":{"$ref":"#/components/schemas/CohortCounts"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"returned":{"type":"integer","title":"Returned"},"total_series":{"type":"integer","title":"Total Series"},"series":{"items":{"$ref":"#/components/schemas/SeriesManifestRow"},"type":"array","title":"Series"},"download":{"$ref":"#/components/schemas/DownloadInfo"}},"type":"object","required":["counts","page","page_size","returned","total_series","series","download"],"title":"ManifestResponse"},"ManifestTextRequest":{"properties":{"filters":{"$ref":"#/components/schemas/CohortFilters"},"source":{"type":"string","title":"Source","default":"aws"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"}},"additionalProperties":false,"type":"object","title":"ManifestTextRequest","examples":[{"filters":{"terms":{"collection_id":["nlst"]}},"limit":1000,"source":"gcs"}]},"NumericRange":{"properties":{"gte":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Gte"},"lte":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Lte"}},"additionalProperties":false,"type":"object","title":"NumericRange"},"SeriesManifestRow":{"properties":{"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"},"PatientID":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Patientid"},"StudyInstanceUID":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Studyinstanceuid"},"SeriesInstanceUID":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seriesinstanceuid"},"Modality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modality"},"SeriesDescription":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seriesdescription"},"instanceCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Instancecount"},"series_size_MB":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Series Size Mb"},"aws_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aws Bucket"},"crdc_series_uuid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Crdc Series Uuid"},"series_aws_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Series Aws Url"}},"type":"object","title":"SeriesManifestRow"},"SqlRequest":{"properties":{"sql":{"type":"string","title":"Sql"},"max_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Rows"}},"type":"object","required":["sql"],"title":"SqlRequest","examples":[{"max_rows":20,"sql":"SELECT Modality, count(*) AS n FROM index GROUP BY 1 ORDER BY n DESC"}]},"SqlResult":{"properties":{"columns":{"items":{"type":"string"},"type":"array","title":"Columns"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows"},"row_count":{"type":"integer","title":"Row Count"},"truncated":{"type":"boolean","title":"Truncated"},"max_rows":{"type":"integer","title":"Max Rows"}},"type":"object","required":["columns","rows","row_count","truncated","max_rows"],"title":"SqlResult"},"Stats":{"properties":{"idc_version":{"type":"string","title":"Idc Version"},"collections":{"type":"integer","title":"Collections"},"analysis_results":{"type":"integer","title":"Analysis Results"},"patients":{"type":"integer","title":"Patients"},"studies":{"type":"integer","title":"Studies"},"series":{"type":"integer","title":"Series"},"instances":{"type":"integer","title":"Instances"},"size_TB":{"type":"number","title":"Size Tb"}},"type":"object","required":["idc_version","collections","analysis_results","patients","studies","series","instances","size_TB"],"title":"Stats"},"TableInfo":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"column_count":{"type":"integer","title":"Column Count"}},"type":"object","required":["name","column_count"],"title":"TableInfo"},"TableList":{"properties":{"tables":{"items":{"$ref":"#/components/schemas/TableInfo"},"type":"array","title":"Tables"}},"type":"object","required":["tables"],"title":"TableList"},"TableSchema":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"columns":{"items":{"$ref":"#/components/schemas/ColumnSchema"},"type":"array","title":"Columns"}},"type":"object","required":["name","columns"],"title":"TableSchema"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VersionInfo":{"properties":{"idc_version":{"type":"string","title":"Idc Version","description":"IDC data release served, e.g. 'v24'."},"idc_index_data_version":{"type":"string","title":"Idc Index Data Version","description":"Pinned idc-index-data package version."},"api_version":{"type":"string","title":"Api Version","description":"This server's own software version (the idc-api package), e.g. '3.0.0.dev0' — distinct from the IDC *data* version above."},"build":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Build","description":"Deploy-time build stamp (IDC_API_BUILD, e.g. a short git SHA), or null if unset. Confirms which build a hosted instance is running; the MCP initialize handshake reports the same as serverInfo.version = api_version[+build]."}},"type":"object","required":["idc_version","idc_index_data_version","api_version"],"title":"VersionInfo"},"ViewerURL":{"properties":{"viewer_url":{"type":"string","title":"Viewer Url"},"viewer":{"type":"string","title":"Viewer"},"study_instance_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Study Instance Uid"},"series_instance_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Series Instance Uid"}},"type":"object","required":["viewer_url","viewer"],"title":"ViewerURL"}}}}