{"openapi":"3.1.0","info":{"title":"OncoKB reader microservice (research use)","description":"Research-use microservice that reads oncokb.org with logged-in web accounts and returns structured\nOncoKB evidence. **Read the guide first: [`/`](/)**: which endpoint to call for which assay (Thermo Oncomine myeloid /\nCGP panels, Illumina WGS / WES germline, somatic VCF, single variants), what each one does, and what it does not do.\n\nFull reference with every field and error code: [`/reference`](/reference).\n\nEvery `/api/v1/*` and `/admin/*` call needs the `X-API-Key` header (press **Authorize** to try calls here). `/health`,\n`/ready` and the documentation pages are open.","version":"4.0.0"},"paths":{"/health":{"get":{"tags":["Operations"],"summary":"Liveness and full status","description":"200 while the process runs, whatever oncokb.org's state: read the fields, or use /ready to decide on traffic.\nAccount names, tokens and proxy credentials never appear here; per-account detail is at /admin/accounts.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"tags":["Operations"],"summary":"Can this instance read oncokb.org right now?","description":"200 when at least one account can carry a request; otherwise 503. For load balancers and deploys.","operationId":"ready_ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"503":{"description":"Not ready; `reasons` says why"}}}},"/api/v1/annotate":{"post":{"tags":["Annotate"],"summary":"Annotate one variant","operationId":"annotate_post_api_v1_annotate_post","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Input rejected, or OncoKB rejected the alteration; see errors[].code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"oncokb.org could not be read; see errors[].retryable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Annotate"],"summary":"Annotate one variant (query string)","operationId":"annotate_get_api_v1_annotate_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"gene","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gene"}},{"name":"alteration","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alteration"}},{"name":"tumor_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Type"}},{"name":"fusion_partner","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fusion Partner"}},{"name":"copy_number_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Copy Number Type"}},{"name":"variant_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Type"}},{"name":"reference_genome","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Genome"}},{"name":"germline","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Germline"}},{"name":"detail","in":"query","required":false,"schema":{"type":"string","default":"standard","title":"Detail"}},{"name":"generate_pdf","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Generate Pdf"}},{"name":"force_refresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force Refresh"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Input rejected, or OncoKB rejected the alteration; see errors[].code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"oncokb.org could not be read; see errors[].retryable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/annotate/batch":{"post":{"tags":["Annotate"],"summary":"Annotate up to 100 variants","description":"Up to 100 items; each item gets its own status. One bad item never fails the batch.","operationId":"annotate_batch_api_v1_annotate_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/sample":{"post":{"tags":["Annotate"],"summary":"Annotate one whole sample","description":"Every finding of one tumour sample in one call (targeted panel, CGP panel, or a filtered exome / genome list):\nSNVs and indels by protein change or genomic coordinates, fusions, copy-number calls, TMB-High and MSI-High. The\nanswer leads with a summary for the report (actionable findings by level, therapies in this tumour type, resistance,\nresistance, therapies and resistance known in other tumour types) and keeps each finding's full answer in `results`, in the order sent\n(variants first, then biomarkers). One bad finding never fails the sample. Up to 500 findings; use\n/api/v1/jobs or /api/v1/vcf for more.","operationId":"sample_api_v1_sample_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/info":{"get":{"tags":["Reference"],"summary":"OncoKB data version in use","description":"The OncoKB data version stored answers belong to, the gene list in use, and this service's versions.","operationId":"info_api_v1_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/genes":{"get":{"tags":["Reference"],"summary":"Genes OncoKB annotates","description":"OncoKB's Cancer Gene List: symbol, type, transcripts and panel membership. No download per call.","operationId":"gene_list_api_v1_genes_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"annotated_only","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Annotated Only"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/genes/{symbol}":{"get":{"tags":["Reference"],"summary":"One gene, optionally with its curated alterations","description":"Gene type, transcripts and panel membership; with `variants=true` also every alteration OncoKB has curated for\nthe gene (oncogenicity, effect) and every levelled association (drugs, cancer types, FDA level). The tables are\nread once per gene and OncoKB data version.","operationId":"gene_detail_api_v1_genes__symbol__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"variants","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Variants"}},{"name":"force_refresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force Refresh"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not in OncoKB's Cancer Gene List","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"oncokb.org could not be read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs":{"post":{"tags":["Jobs"],"summary":"Submit a list of up to 20,000 variants","description":"WES/WGS-size lists (up to 20,000 items). Returns at once; poll GET /api/v1/jobs/{id}.","operationId":"job_submit_api_v1_jobs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Job progress and paged results","description":"Progress and counts; pass limit>0 to page through results (in submission order).","operationId":"job_status_api_v1_jobs__job_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Jobs"],"summary":"Delete a finished job","description":"Delete a finished job and its results (file reports hold patient-derived variants).","operationId":"job_delete_api_v1_jobs__job_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/oncomine":{"post":{"tags":["Lab files"],"summary":"Upload Ion Reporter TSV exports","description":"Thermo Fisher Ion Reporter exports: Oncomine Myeloid, Oncomine Comprehensive Plus (CGP 500), Oncomine Precision.\nFull (unselected) exports are filtered like Ion Reporter (thermo_like_v1); lab-selected exports are taken as they are.\nReturns a job; poll GET /api/v1/jobs/{id}, then GET /api/v1/jobs/{id}/report (JSON) or /report.tsv.","operationId":"oncomine_submit_api_v1_oncomine_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_oncomine_submit_api_v1_oncomine_post"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"File over ONCOKB_MAX_UPLOAD_MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not a usable file, or bad form field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/vcf":{"post":{"tags":["Lab files"],"summary":"Upload a GRCh38 VCF","description":"Illumina NovaSeq X / DRAGEN WGS or WES VCF (GRCh38). Calls in OncoKB-gene coding sequence get a local MANE\nconsequence, common gnomAD v4.1 polymorphisms are removed, the rest go to OncoKB.\nReturns a job; poll GET /api/v1/jobs/{id}, then GET /api/v1/jobs/{id}/report (JSON) or /report.tsv.","operationId":"vcf_submit_api_v1_vcf_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_vcf_submit_api_v1_vcf_post"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"File over ONCOKB_MAX_UPLOAD_MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not a usable file, or bad form field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/api/v1/jobs/{job_id}/report":{"get":{"tags":["Jobs"],"summary":"File job report as JSON","description":"Finished file analysis as JSON. `full=true` keeps each call's complete OncoKB response (`oncokb_full`).","operationId":"job_report_api_v1_jobs__job_id__report_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"full","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Full"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The job has not finished, or it failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/report.tsv":{"get":{"tags":["Jobs"],"summary":"File job report as TSV","description":"One row per variant (Oncomine: every kept variant of every sample; VCF: every coding call).","operationId":"job_report_tsv_api_v1_jobs__job_id__report_tsv_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The job has not finished, or it failed","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/artifacts/pdf/{name}":{"get":{"tags":["Artifacts"],"summary":"Download a generated PDF","operationId":"pdf_api_v1_artifacts_pdf__name__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}}],"responses":{"200":{"description":"Successful Response"},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/cache/purge":{"post":{"tags":["Operations"],"summary":"Empty the store of oncokb.org answers","description":"Every later lookup is downloaded again. Not needed after an OncoKB data release: the service notices the new\ndata version and drops the old answers itself.","operationId":"purge_admin_cache_purge_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/admin/accounts":{"get":{"tags":["Accounts"],"summary":"Accounts and their state","description":"One row per account: state, token expiry, pacing, today's requests, bytes. No password, token or proxy credential.","operationId":"accounts_list_admin_accounts_get","security":[{"APIKeyHeader":[]}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Accounts"],"summary":"Add or change an account","description":"Adds the account, or changes the one with this id (without an id: the one with this login). Fields left out keep\ntheir stored value. The accounts file is rewritten. With `login=true` (default) a new account, or one whose\npassword changed, is logged in at once, so a wrong password shows in the answer.","operationId":"accounts_upsert_admin_accounts_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"login","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Login"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not a usable account, or the accounts file cannot be written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/admin/accounts/reload":{"post":{"tags":["Accounts"],"summary":"Re-read the accounts file","description":"After editing the accounts file by hand. Known accounts keep their token and counters; new ones log in on first use.","operationId":"accounts_reload_admin_accounts_reload_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The file does not parse; nothing changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/admin/accounts/{account_id}/login":{"post":{"tags":["Accounts"],"summary":"Log an account in now","description":"Logs in whatever the account's state and ends a cooldown: use after fixing a password or a proxy.","operationId":"accounts_login_admin_accounts__account_id__login_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/accounts/{account_id}":{"delete":{"tags":["Accounts"],"summary":"Remove an account","operationId":"accounts_delete_admin_accounts__account_id__delete","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin/usage":{"get":{"tags":["Accounts"],"summary":"Requests and bytes per day and account","description":"What went to oncokb.org: requests, failures and bytes per UTC day and account (bytes include an estimate for\nheaders and TLS handshakes, which is what a per-GB proxy bills).","operationId":"usage_admin_usage_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or wrong X-API-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AccountIn":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Short name for logs and /health; derived from the e-mail when omitted"},"username":{"type":"string","title":"Username","description":"The oncokb.org login e-mail"},"password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password","description":"Needed to log in and to renew the token; omit to keep the stored one"},"proxy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Proxy","description":"http://user:pass@host:port or socks5://...; this account's only way out"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token","description":"A token copied from oncokb.org/account, to skip the first login"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"false takes the account out of use; left out keeps the stored value (new accounts: true)"},"max_concurrency":{"anyOf":[{"type":"integer","maximum":32.0,"minimum":1.0},{"type":"null"}],"title":"Max Concurrency"},"min_interval_s":{"anyOf":[{"type":"number","maximum":60.0,"minimum":0.0},{"type":"null"}],"title":"Min Interval S"},"daily_limit":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Daily Limit"},"note":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Note"}},"additionalProperties":false,"type":"object","required":["username"],"title":"AccountIn","description":"One oncokb.org web account. Secrets are write-only: no endpoint returns them."},"AnnotateOptions":{"properties":{"generate_pdf":{"type":"boolean","title":"Generate Pdf","description":"Browser backend only: print the OncoKB page to an A4 PDF. The default (wire) backend has no browser and answers with a warning instead.","default":false},"force_refresh":{"type":"boolean","title":"Force Refresh","description":"Ignore the stored answer and ask oncokb.org again","default":false},"detail":{"type":"string","enum":["summary","standard","full"],"title":"Detail","description":"summary: levels, drugs and citations without long texts; standard: everything except the article list; full: adds titles and journals of every cited article","default":"standard"}},"additionalProperties":false,"type":"object","title":"AnnotateOptions"},"AnnotateRequest":{"properties":{"gene":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gene","description":"HGNC symbol, 'Other Biomarkers', or 'A::B' for a fusion"},"alteration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alteration","description":"Protein change (R132S, p.Arg132Ser, c.394C>A:p.Arg132Ser), named alteration (Exon 19 in-frame deletions, ITD), TMB-High, MSI-High"},"tumor_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Type","description":"OncoTree code or name (AML, CLLSLL, MDS/MPN...). Omit for pan-cancer."},"variant_type":{"anyOf":[{"type":"string","enum":["snv_indel","fusion","cnv","biomarker","special"]},{"type":"null"}],"title":"Variant Type"},"fusion_partner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fusion Partner","description":"3' partner when gene is the 5' partner"},"copy_number_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Copy Number Type","description":"Amplification or Deletion"},"genomic_coordinates":{"anyOf":[{"$ref":"#/components/schemas/GenomicCoordinates"},{"type":"null"}],"description":"Use instead of alteration for VCF input (WES/WGS); OncoKB maps it on its canonical transcript. gene, if also given, is only a hint."},"reference_genome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Genome","description":"GRCh37 (default, as on oncokb.org) or GRCh38: the transcript set a protein change is read on. Send GRCh38 with protein changes called on MANE Select. Ignored with genomic_coordinates."},"germline":{"type":"boolean","title":"Germline","description":"Ask OncoKB's germline annotation (pathogenicity, penetrance, inheritance) instead of the somatic one","default":false},"client_ref":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Ref","description":"Echoed back unchanged"},"options":{"$ref":"#/components/schemas/AnnotateOptions"}},"additionalProperties":false,"type":"object","title":"AnnotateRequest","example":{"alteration":"p.Arg132Ser","gene":"IDH1","options":{"generate_pdf":false},"tumor_type":"AML"}},"BatchRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AnnotateRequest"},"type":"array","maxItems":100,"minItems":1,"title":"Items"}},"additionalProperties":false,"type":"object","required":["items"],"title":"BatchRequest"},"Body_oncomine_submit_api_v1_oncomine_post":{"properties":{"files":{"items":{"type":"string","format":"binary"},"type":"array","title":"Files","description":"Ion Reporter variant TSV exports (selected or full)"},"tumor_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Type","description":"OncoTree code/name; omit for pan-cancer"}},"type":"object","required":["files"],"title":"Body_oncomine_submit_api_v1_oncomine_post"},"Body_vcf_submit_api_v1_vcf_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"VCF or VCF.gz, GRCh38 (Illumina DRAGEN or similar)"},"mode":{"type":"string","title":"Mode","description":"germline (WGS/WES constitutional) or somatic (tumour VCF)","default":"germline"},"tumor_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Type","description":"OncoTree code/name; omit for pan-cancer"},"sample":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sample","description":"sample column, required for multi-sample VCFs"},"max_pop_af":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Max Pop Af","description":"gnomAD filtering AF at or above which a call is dropped","default":0.01},"include_synonymous":{"type":"boolean","title":"Include Synonymous","default":false},"min_vaf":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Vaf","description":"drop calls below this allele fraction (somatic reporting threshold, e.g. 0.05)","default":0.0},"min_depth":{"type":"integer","minimum":0.0,"title":"Min Depth","description":"drop calls below this read depth","default":0},"germline_annotation":{"type":"boolean","title":"Germline Annotation","description":"mode=germline: also ask OncoKB's germline annotation for constitutional calls","default":true}},"type":"object","required":["file"],"title":"Body_vcf_submit_api_v1_vcf_post"},"ErrorItem":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine-readable code; see docs/API.md"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","description":"Request field at fault, when there is one"},"retryable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retryable","description":"True when the same request can succeed later"},"suggestions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Suggestions","description":"Close matches, e.g. for a misspelt tumour type"}},"additionalProperties":true,"type":"object","required":["code"],"title":"ErrorItem","description":"One problem. `code` is stable and meant for programs; `message` is for people."},"ErrorResponse":{"properties":{"status":{"type":"string","enum":["invalid","error"],"title":"Status"},"errors":{"items":{"$ref":"#/components/schemas/ErrorItem"},"type":"array","title":"Errors"},"client_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Ref"}},"additionalProperties":true,"type":"object","required":["status","errors"],"title":"ErrorResponse","description":"Body of every 4xx / 5xx answer."},"GenomicCoordinates":{"properties":{"chromosome":{"type":"string","title":"Chromosome","description":"1-22, X, Y, MT (chr prefix accepted)"},"position":{"type":"integer","minimum":1.0,"title":"Position","description":"VCF POS (1-based)"},"reference":{"type":"string","title":"Reference","description":"VCF REF"},"alternate":{"type":"string","title":"Alternate","description":"VCF ALT (one allele)"},"genome_build":{"type":"string","title":"Genome Build","description":"GRCh37 or GRCh38"}},"additionalProperties":false,"type":"object","required":["chromosome","position","reference","alternate","genome_build"],"title":"GenomicCoordinates"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"JobRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AnnotateRequest"},"type":"array","maxItems":20000,"minItems":1,"title":"Items"}},"additionalProperties":false,"type":"object","required":["items"],"title":"JobRequest"},"SampleBiomarkers":{"properties":{"tmb_high":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tmb High","description":"true: annotate TMB-High"},"msi_high":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Msi High","description":"true: annotate MSI-High"}},"additionalProperties":false,"type":"object","title":"SampleBiomarkers"},"SampleRequest":{"properties":{"sample_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Sample Id","description":"Echoed back; never sent to oncokb.org"},"tumor_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tumor Type","description":"OncoTree code or name for every finding. Omit for pan-cancer."},"assay":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Assay","description":"Free label echoed back (targeted, CGP, WES, WGS...)"},"variants":{"items":{"$ref":"#/components/schemas/SampleVariant"},"type":"array","maxItems":5000,"title":"Variants"},"biomarkers":{"$ref":"#/components/schemas/SampleBiomarkers"},"options":{"$ref":"#/components/schemas/AnnotateOptions"}},"additionalProperties":false,"type":"object","title":"SampleRequest","description":"Everything found in one tumour sample: a targeted panel, a CGP panel, an exome or a genome.","example":{"assay":"CGP","biomarkers":{"tmb_high":true},"sample_id":"S-001","tumor_type":"NSCLC","variants":[{"alteration":"L858R","gene":"EGFR","vaf":0.31},{"alteration":"R273H","gene":"TP53"},{"copy_number_type":"Amplification","gene":"MET"},{"fusion_partner":"ALK","gene":"EML4"}]}},"SampleVariant":{"properties":{"gene":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gene","description":"HGNC symbol; 'A::B' for a fusion"},"alteration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alteration"},"genomic_coordinates":{"anyOf":[{"$ref":"#/components/schemas/GenomicCoordinates"},{"type":"null"}]},"fusion_partner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fusion Partner"},"copy_number_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Copy Number Type"},"reference_genome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Genome"},"germline":{"type":"boolean","title":"Germline","default":false},"vaf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vaf","description":"Carried into the report unchanged"},"client_ref":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Client Ref"}},"additionalProperties":false,"type":"object","title":"SampleVariant","description":"One finding of a sample: gene with one of alteration, fusion_partner or copy_number_type, or genomic_coordinates.\nSend two findings for two events (a fusion and a resistance mutation in the same gene are two entries)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"Service key; ask the service owner","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Annotate","description":"Variants answered in the response: one at a time, up to 100, or one whole sample."},{"name":"Reference","description":"What OncoKB lists: genes, their curated alterations, the data version."},{"name":"Lab files","description":"Upload Ion Reporter TSVs or a DRAGEN VCF; the answer is a job."},{"name":"Jobs","description":"Progress, results and deletion of background work."},{"name":"Artifacts","description":"Files the service produced."},{"name":"Operations","description":"Probes for monitoring, and cache control."},{"name":"Accounts","description":"The oncokb.org web accounts the service reads with, and what each has used."}]}