{ "openapi": "3.1.0", "info": { "title": "Seqhub Public API", "version": "1.0.0", "description": "Public API for protein search and annotation across 130,000+ microbial genomes.\n\nEvery endpoint requires a personal access token, sent as `Authorization: Bearer `." }, "servers": [ { "url": "https://api.seqhub.org" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/protein-contexts/search": { "post": { "tags": [ "Protein Context Search" ], "summary": "Protein Context Search", "description": "Search our database of 130,000+ microbial genomes for protein contexts containing a protein most similar (by embedding distance) to your query sequence. A protein context is the set of proteins encoded on the same contig (genomic neighborhood). Returns taxonomic information and functionally annotated proteins within each matching context.", "operationId": "searchProteinContexts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProteinSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProteinSearchResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/protein-contexts/search/multi-query": { "post": { "tags": [ "Protein Context Search" ], "summary": "Protein Context Search (Multi-Query)", "description": "Search our database of 130,000+ microbial genomes for genomic neighborhoods where a combination of proteins and features occurs together. A query is 1-5 protein sequences, optionally combined with Pfam domains, Rfam families and intergenic SAE features (`featureFilter`) and a taxonomy filter (`taxonomyFilter`). Each protein is matched by embedding similarity, and only neighborhoods that contain a match for every protein and satisfy the filters are returned.\n\nWith a single sequence, this works like single-query search, plus filters and the option to return every SAE feature and Rfam hit in each neighborhood (`includeOtherSaes`, `includeOtherRfams`).\n\nEach entry in `sequences` is either a plain sequence string or an object with an optional `id` and `pfamFilter`. All entries must use the same form, so to add a `pfamFilter` to one query, send every query as an object.", "operationId": "searchProteinContextsMultiQuery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiQuerySearchRequest" }, "examples": { "simple": { "summary": "Two proteins co-occurring", "value": { "sequences": [ "MSIVMQLQDVAESTRLGPLSGEVRAGEILHLVGPNGAGKSTLLARMAGMTSGKGSIQFAGQPLEAWSATKLALHRAYLSQQQTPPFATPVWHYLTLHQHDKTRTELLNDVAGALALDDKLGRSTNQLSGGEWQRVRLAAVVLQITPQANPAGQLLLLDEPMNSLDVAQQSALDKILSALCQQGLAIVMSSHDLNHTLRHAHRAWLLKGGKMLASGRREEVLTPPNLAQAYGMNFRRLDIEGHRMLISTI", "MAKSLFRALVALSFLAPLWLNAAPRVITLSPANTELAFAAGITPVGVSSYSDYPPQAQKIEQVSTWQGMNLERIVALKPDLVIAWRGGNAERQVDQLASLGIKVMWVDATSIEQIANALRQLAPWSPQPDKAEQAAQSLLDQYAQLKAQYADKPKKRVFLQFGINPPFTSGKESIQNQVLEVCGGENIFKDSRVPWPQVSREQVLARSPQAIVITGGPDQIPKIKQYWGEQLKIPVIPLTSDWFERASPRIILAAQQLCNALSQVD" ] } }, "filtered": { "summary": "Narrowed by feature and taxonomy", "description": "Only return neighborhoods that contain a cobalamin riboswitch and come from the genus Escherichia.", "value": { "sequences": [ "MSIVMQLQDVAESTRLGPLSGEVRAGEILHLVGPNGAGKSTLLARMAGMTSGKGSIQFAGQPLEAWSATKLALHRAYLSQQQTPPFATPVWHYLTLHQHDKTRTELLNDVAGALALDDKLGRSTNQLSGGEWQRVRLAAVVLQITPQANPAGQLLLLDEPMNSLDVAQQSALDKILSALCQQGLAIVMSSHDLNHTLRHAHRAWLLKGGKMLASGRREEVLTPPNLAQAYGMNFRRLDIEGHRMLISTI", "MAKSLFRALVALSFLAPLWLNAAPRVITLSPANTELAFAAGITPVGVSSYSDYPPQAQKIEQVSTWQGMNLERIVALKPDLVIAWRGGNAERQVDQLASLGIKVMWVDATSIEQIANALRQLAPWSPQPDKAEQAAQSLLDQYAQLKAQYADKPKKRVFLQFGINPPFTSGKESIQNQVLEVCGGENIFKDSRVPWPQVSREQVLARSPQAIVITGGPDQIPKIKQYWGEQLKIPVIPLTSDWFERASPRIILAAQQLCNALSQVD" ], "featureFilter": { "field": "rfam", "value": "RF00174" }, "taxonomyFilter": { "rank": "genus", "value": "Escherichia" }, "diversityLevel": "medium" } }, "per_protein_pfam": { "summary": "Constrain which protein a query may match", "description": "The protein matched by the first query must have an ABC transporter domain (PF00005); the second query is unconstrained. Each `id` is returned as `queryId` in `matchIndices`.", "value": { "sequences": [ { "id": "transporter", "sequence": "MSIVMQLQDVAESTRLGPLSGEVRAGEILHLVGPNGAGKSTLLARMAGMTSGKGSIQFAGQPLEAWSATKLALHRAYLSQQQTPPFATPVWHYLTLHQHDKTRTELLNDVAGALALDDKLGRSTNQLSGGEWQRVRLAAVVLQITPQANPAGQLLLLDEPMNSLDVAQQSALDKILSALCQQGLAIVMSSHDLNHTLRHAHRAWLLKGGKMLASGRREEVLTPPNLAQAYGMNFRRLDIEGHRMLISTI", "pfamFilter": { "accession": "PF00005" } }, { "id": "neighbor", "sequence": "MAKSLFRALVALSFLAPLWLNAAPRVITLSPANTELAFAAGITPVGVSSYSDYPPQAQKIEQVSTWQGMNLERIVALKPDLVIAWRGGNAERQVDQLASLGIKVMWVDATSIEQIANALRQLAPWSPQPDKAEQAAQSLLDQYAQLKAQYADKPKKRVFLQFGINPPFTSGKESIQNQVLEVCGGENIFKDSRVPWPQVSREQVLARSPQAIVITGGPDQIPKIKQYWGEQLKIPVIPLTSDWFERASPRIILAAQQLCNALSQVD" } ] } }, "other_features": { "summary": "Return all SAE features and Rfam hits", "description": "By default, `saeFeatures` and `rfamFamilies` only list features named in `featureFilter`. `includeOtherSaes` and `includeOtherRfams` return every SAE feature and Rfam hit in the window instead. This does not change which results match, but makes the response much larger.", "value": { "sequences": [ "MSIVMQLQDVAESTRLGPLSGEVRAGEILHLVGPNGAGKSTLLARMAGMTSGKGSIQFAGQPLEAWSATKLALHRAYLSQQQTPPFATPVWHYLTLHQHDKTRTELLNDVAGALALDDKLGRSTNQLSGGEWQRVRLAAVVLQITPQANPAGQLLLLDEPMNSLDVAQQSALDKILSALCQQGLAIVMSSHDLNHTLRHAHRAWLLKGGKMLASGRREEVLTPPNLAQAYGMNFRRLDIEGHRMLISTI", "MAKSLFRALVALSFLAPLWLNAAPRVITLSPANTELAFAAGITPVGVSSYSDYPPQAQKIEQVSTWQGMNLERIVALKPDLVIAWRGGNAERQVDQLASLGIKVMWVDATSIEQIANALRQLAPWSPQPDKAEQAAQSLLDQYAQLKAQYADKPKKRVFLQFGINPPFTSGKESIQNQVLEVCGGENIFKDSRVPWPQVSREQVLARSPQAIVITGGPDQIPKIKQYWGEQLKIPVIPLTSDWFERASPRIILAAQQLCNALSQVD" ], "featureFilter": { "field": "pfam", "value": "PF00005" }, "includeOtherSaes": true, "includeOtherRfams": true } }, "filtered_boolean": { "summary": "Filters as boolean expressions", "description": "Both filters can be nested with `and`, `or` and `not`. Here: an ABC transporter domain and no cobalamin riboswitch in the window, from either Escherichia or Bacillus.", "value": { "sequences": [ "MSIVMQLQDVAESTRLGPLSGEVRAGEILHLVGPNGAGKSTLLARMAGMTSGKGSIQFAGQPLEAWSATKLALHRAYLSQQQTPPFATPVWHYLTLHQHDKTRTELLNDVAGALALDDKLGRSTNQLSGGEWQRVRLAAVVLQITPQANPAGQLLLLDEPMNSLDVAQQSALDKILSALCQQGLAIVMSSHDLNHTLRHAHRAWLLKGGKMLASGRREEVLTPPNLAQAYGMNFRRLDIEGHRMLISTI", "MAKSLFRALVALSFLAPLWLNAAPRVITLSPANTELAFAAGITPVGVSSYSDYPPQAQKIEQVSTWQGMNLERIVALKPDLVIAWRGGNAERQVDQLASLGIKVMWVDATSIEQIANALRQLAPWSPQPDKAEQAAQSLLDQYAQLKAQYADKPKKRVFLQFGINPPFTSGKESIQNQVLEVCGGENIFKDSRVPWPQVSREQVLARSPQAIVITGGPDQIPKIKQYWGEQLKIPVIPLTSDWFERASPRIILAAQQLCNALSQVD" ], "featureFilter": { "and": [ { "field": "pfam", "value": "PF00005" }, { "not": { "field": "rfam", "value": "RF00174" } } ] }, "taxonomyFilter": { "or": [ { "rank": "genus", "value": "Escherichia" }, { "rank": "genus", "value": "Bacillus" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultiQuerySearchResponse" }, "examples": { "per_protein_pfam": { "summary": "Which protein each query matched", "description": "Each `matchIndices` entry links a query to the protein it matched. `queryIndex` is the query's position in `sequences`, and `queryId` is its `id` (null if none was sent). Here the first query matched BtuD's homolog, `contig[2]`, and the second matched BtuF's, `contig[0]`.", "value": { "matches": [ { "sampleId": "2931362734", "contigId": "Ga0501769_01", "taxonomy": { "domain": "Bacteria", "phylum": "Pseudomonadota", "class": "Gammaproteobacteria", "order": "Burkholderiales", "family": "Chitinibacteraceae", "genus": "Deefgea", "species": "Deefgea sp019665765" }, "contig": [ { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363712", "strand": "+", "start": 1000672, "end": 1001553 }, "sequence": "MRLILQLKLTVAAFVLCAGGASAA...", "annotation": { "id": "A7MXP0", "description": "Vitamin B12-binding protein", "score": 0.9892790913581848, "percentIdentity": 33.72549057006836, "queryCoverage": 86.68942260742188 }, "hmmAnnotations": [ { "accession": "PF01497", "name": "Peripla_BP_2", "description": "Periplasmic binding protein", "score": 84.0680923461914, "evalue": 2.6122769155821025e-22, "start": 1000801, "end": 1001478, "residueStart": 44, "residueEnd": 269 } ] }, { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363713", "strand": "+", "start": 1001550, "end": 1002560 }, "sequence": "MTAGQTSARTSARLTPKKAAATLS...", "annotation": { "id": "Q47085", "description": "Achromobactin transport system permease protein CbrB", "score": 0.9924771189689636, "percentIdentity": 34.5345344543457, "queryCoverage": 96.13095092773438 }, "hmmAnnotations": [ { "accession": "PF01032", "name": "FecCD", "description": "FecCD transport family", "score": 277.6910400390625, "evalue": 0.0, "start": 1001631, "end": 1002545, "residueStart": 28, "residueEnd": 332 } ] }, { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363714", "strand": "+", "start": 1002557, "end": 1003324 }, "sequence": "MSLLQTQNLSLKQGERILIAGLNL...", "annotation": { "id": "Q7N3Q4", "description": "Vitamin B12 import ATP-binding protein BtuD", "score": 0.9724332094192505, "percentIdentity": 32.52032470703125, "queryCoverage": 91.37255096435547 }, "hmmAnnotations": [ { "accession": "PF00005", "name": "ABC_tran", "description": "ABC transporter", "score": 97.54109954833984, "evalue": 2.5586268971048064e-26, "start": 1002611, "end": 1003060, "residueStart": 19, "residueEnd": 168 } ] } ], "matchIndices": [ { "contigProteinIndex": 2, "queryIndex": 0, "queryId": "transporter", "percentIdentity": 35.321, "queryCoverage": 84.0 }, { "contigProteinIndex": 0, "queryIndex": 1, "queryId": "neighbor", "percentIdentity": 36.22, "queryCoverage": 91.0 } ], "saeFeatures": [], "rfamFamilies": [] } ] } }, "other_features": { "summary": "All SAE features and Rfam hits", "description": "`saeFeatures` and `rfamFamilies` list every feature found in the returned window. Without the include flags both would be empty here, since the filter only names a Pfam domain. Pfam hits are reported on each protein's `hmmAnnotations`.", "value": { "matches": [ { "sampleId": "2931362734", "contigId": "Ga0501769_01", "taxonomy": { "domain": "Bacteria", "phylum": "Pseudomonadota", "class": "Gammaproteobacteria", "order": "Burkholderiales", "family": "Chitinibacteraceae", "genus": "Deefgea", "species": "Deefgea sp019665765" }, "contig": [ { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363712", "strand": "+", "start": 1000672, "end": 1001553 }, "sequence": "MRLILQLKLTVAAFVLCAGGASAA...", "annotation": { "id": "A7MXP0", "description": "Vitamin B12-binding protein", "score": 0.9892790913581848, "percentIdentity": 33.72549057006836, "queryCoverage": 86.68942260742188 }, "hmmAnnotations": [ { "accession": "PF01497", "name": "Peripla_BP_2", "description": "Periplasmic binding protein", "score": 84.0680923461914, "evalue": 2.6122769155821025e-22, "start": 1000801, "end": 1001478, "residueStart": 44, "residueEnd": 269 } ] }, { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363713", "strand": "+", "start": 1001550, "end": 1002560 }, "sequence": "MTAGQTSARTSARLTPKKAAATLS...", "annotation": { "id": "Q47085", "description": "Achromobactin transport system permease protein CbrB", "score": 0.9924771189689636, "percentIdentity": 34.5345344543457, "queryCoverage": 96.13095092773438 }, "hmmAnnotations": [ { "accession": "PF01032", "name": "FecCD", "description": "FecCD transport family", "score": 277.6910400390625, "evalue": 0.0, "start": 1001631, "end": 1002545, "residueStart": 28, "residueEnd": 332 } ] }, { "cdsId": { "sampleId": "2931362734", "contigId": "Ga0501769_01", "cdsShorthand": "2931363714", "strand": "+", "start": 1002557, "end": 1003324 }, "sequence": "MSLLQTQNLSLKQGERILIAGLNL...", "annotation": { "id": "Q7N3Q4", "description": "Vitamin B12 import ATP-binding protein BtuD", "score": 0.9724332094192505, "percentIdentity": 32.52032470703125, "queryCoverage": 91.37255096435547 }, "hmmAnnotations": [ { "accession": "PF00005", "name": "ABC_tran", "description": "ABC transporter", "score": 97.54109954833984, "evalue": 2.5586268971048064e-26, "start": 1002611, "end": 1003060, "residueStart": 19, "residueEnd": 168 } ] } ], "matchIndices": [ { "contigProteinIndex": 2, "queryIndex": 0, "percentIdentity": 35.321, "queryCoverage": 84.0 }, { "contigProteinIndex": 0, "queryIndex": 1, "percentIdentity": 36.22, "queryCoverage": 91.0 } ], "saeFeatures": [ { "saeFeatureId": 3108, "runs": [ { "start": 1000646, "end": 1000662, "strand": "+", "offsets": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], "maxActivation": 58.48704528808594 } ], "nFiringPositions": 17 } ], "rfamFamilies": [ { "accession": "RF00174", "hits": [ { "start": 993279, "end": 993371, "strand": "+", "family": "Cobalamin", "accession": "RF00174", "evalue": 0.00010916763696491092, "score": 27.9 } ], "bestScore": 27.9 } ] } ] } } } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/protein-annotations": { "post": { "tags": [ "Protein Annotation" ], "summary": "Protein Annotation", "description": "Annotate protein sequences by finding their closest functional match in SwissProt (UniProt's curated database). Returns the best-matching SwissProt entry by embedding distance.", "operationId": "annotateProteins", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotateResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/feature-contexts/search": { "post": { "tags": [ "Feature Context Search" ], "summary": "Feature Context Search", "description": "Search our database of 130,000+ microbial genomes for genomic neighborhoods where a combination of features occurs, without a query sequence. Features are Pfam domains, Rfam families and intergenic SAE features (interpretable features learned from the gLM2 genomic language model), combined with `and`, `or` and `not`. A neighborhood matches when the required features are found within `window` genes of each other. Returns the proteins in each matching window, with taxonomy and functional annotations.", "operationId": "searchFeatureContexts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSearchRequest" }, "examples": { "simple": { "summary": "One Pfam domain", "description": "Every neighborhood containing a protein kinase domain.", "value": { "featureFilter": { "field": "pfam", "value": "PF00069" }, "window": 10 } }, "and_cooccurrence": { "summary": "AND: a domain near an SAE feature", "description": "Kinase domains within 5 genes of an iron-box operator SAE feature.", "value": { "featureFilter": { "and": [ { "field": "pfam", "value": "PF00069" }, { "field": "saeFeature", "value": 8581 } ] }, "window": 5 } }, "or_alternatives": { "summary": "OR: either riboswitch", "description": "Neighborhoods carrying a cobalamin riboswitch or bacterial RNase P.", "value": { "featureFilter": { "or": [ { "field": "rfam", "value": "RF00174" }, { "field": "rfam", "value": "RF00010" } ] } } }, "not_exclusion": { "summary": "NOT: exclude a feature", "description": "Kinase domains with no cobalamin riboswitch in the window. The expression must always require at least one feature to be present, so an expression made only of `not` terms is rejected.", "value": { "featureFilter": { "and": [ { "field": "pfam", "value": "PF00069" }, { "not": { "field": "rfam", "value": "RF00174" } } ] }, "window": 8 } }, "taxonomy_scoped": { "summary": "Nested expression with a taxonomy filter", "description": "A kinase domain near either of two SAE features, restricted to the phylum Pseudomonadota. `includeOtherSaes` also returns every other SAE feature in the window, which makes the response much larger.", "value": { "featureFilter": { "and": [ { "field": "pfam", "value": "PF00069" }, { "or": [ { "field": "saeFeature", "value": 8581 }, { "field": "saeFeature", "value": 5834 } ] } ] }, "taxonomyFilter": { "rank": "phylum", "value": "Pseudomonadota" }, "window": 5, "includeOtherSaes": true } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSearchResponse" }, "examples": { "and_cooccurrence": { "summary": "AND: a domain near an SAE feature", "description": "The kinase domain is on the protein at 1381-2877, and SAE feature 8581 fires at 6622-6632, four genes downstream and within the requested window of 5. All positions are base-pair coordinates on the contig.", "value": { "matches": [ { "contigSegmentId": "5d7d61dd-6d0f-5689-a85d-eee8598def31", "taxonomy": { "domain": "Bacteria", "phylum": "Bacillota_A", "class": "Clostridia", "order": "Lachnospirales", "family": "Lachnospiraceae", "genus": "Wujia", "species": "Wujia chipingensis" }, "contig": [ { "cdsId": { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "cdsShorthand": "2800059173", "strand": "+", "start": 1381, "end": 2877 }, "sequence": "MNYPLTLEQYIAQMPMQEAELARM...", "annotation": { "id": "P54735", "description": "Serine/threonine-protein kinase D", "score": 0.729790210723877, "percentIdentity": 24.13793182373047, "queryCoverage": 27.710844039916992 }, "hmmAnnotations": [ { "name": "Pkinase", "residueStart": 2, "residueEnd": 142, "accession": "PF00069", "description": "Protein kinase domain", "score": 53.072513580322266, "evalue": 8.173563822294616e-13, "start": 1384, "end": 1806 }, { "name": "PK_Tyr_Ser-Thr", "residueStart": 5, "residueEnd": 111, "accession": "PF07714", "description": "Protein tyrosine and serine/threonine kinase", "score": 26.082927703857422, "evalue": 0.00013060917262919247, "start": 1393, "end": 1713 } ] }, { "cdsId": { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "cdsShorthand": "2800059174", "strand": "+", "start": 2887, "end": 3735 }, "sequence": "MKNLRMLFCMLMGLLIGSVLGIVI...", "annotation": { "id": "C0SP99", "description": "Putative L,D-transpeptidase YciB", "score": 0.8224581480026245, "percentIdentity": 22.85714340209961, "queryCoverage": 12.411347389221191 }, "hmmAnnotations": [ { "name": "YkuD", "residueStart": 106, "residueEnd": 277, "accession": "PF03734", "description": "L,D-transpeptidase catalytic domain", "score": 26.354814529418945, "evalue": 0.00023604501620866358, "start": 3202, "end": 3717 } ] } ], "rfamFamilies": [], "saeFeatures": [ { "saeFeatureId": 8581, "runs": [ { "start": 6622, "end": 6632, "strand": "+", "offsets": [ 0, 1, 5, 6, 10 ], "maxActivation": 280.92337 } ], "nFiringPositions": 5 } ] } ] } }, "or_alternatives": { "summary": "OR: either riboswitch", "description": "Only RF00010 was found in this window, so only RF00010 appears in `rfamFamilies`.", "value": { "matches": [ { "contigSegmentId": "647d37f6-6632-5ac4-865d-b99cd50f1def", "taxonomy": { "domain": "Bacteria", "phylum": "Pseudomonadota", "class": "Gammaproteobacteria", "order": "Enterobacterales", "family": "Enterobacteriaceae", "genus": "Serratia", "species": "Serratia marcescens_K" }, "contig": [ { "cdsId": { "sampleId": "2961237444", "contigId": "Ga0149631_02", "cdsShorthand": "2961239400", "strand": "+", "start": 545047, "end": 545727 }, "sequence": "MDIIKELIHALWQQDFETLANPSL...", "annotation": { "id": "P0AA63", "description": "Inner membrane protein YqjA", "score": 0.9962493777275085, "percentIdentity": 82.79069519042969, "queryCoverage": 95.13274383544922 }, "hmmAnnotations": [ { "name": "VTT_dom", "residueStart": 48, "residueEnd": 174, "accession": "PF09335", "description": "VTT domain", "score": 72.08621215820312, "evalue": 1.5310045041390583e-18, "start": 545188, "end": 545568 } ] } ], "rfamFamilies": [ { "accession": "RF00010", "hits": [ { "start": 551430, "end": 551807, "strand": "-", "family": "RNaseP_bact_a", "accession": "RF00010", "evalue": 2.135211936250319e-84, "score": 289.63 } ], "bestScore": 289.63 } ], "saeFeatures": [] } ] } } } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/contig-dna": { "post": { "tags": [ "Contig DNA" ], "summary": "Fetch Contig DNA", "description": "Fetch DNA for up to 100 ranges on contigs returned by a search. Identify the contig with a match's `sampleId` and `contigId`, and give 1-based inclusive `start`/`end` coordinates. Any `start`/`end` in a search response works: a gene's `cdsId`, a Pfam domain, an Rfam hit or an SAE run.\n\nSequences are always returned on the plus strand, so reverse-complement minus-strand features yourself. If any range is invalid, for example past the end of its contig, the whole request fails.", "operationId": "fetchContigDna", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContigDnaRequest" }, "examples": { "from_a_search": { "summary": "An SAE feature's run and its surrounding window", "description": "Both ranges come from the feature context search example: the SAE feature's run (6622-6632), and the whole window from the first protein's start to the last protein's end (1381-3735).", "value": { "ranges": [ { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "start": 6622, "end": 6632 }, { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "start": 1381, "end": 3735 } ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContigDnaResponse" }, "examples": { "from_a_search": { "summary": "One sequence per range, in request order", "description": "The first sequence is 11 bases (6622-6632, inclusive). The second is 2,355 bases and is truncated here.", "value": { "sequences": [ { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "start": 6622, "end": 6632, "sequence": "ATGCGTTACGA" }, { "sampleId": "2799112551", "contigId": "Ga0313777_1080", "start": 1381, "end": 3735, "sequence": "ATGAATTATCCGCTGACGCTGGAACAGTAT..." } ] } } } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/pfam-families": { "get": { "tags": [ "Vocabularies" ], "summary": "List Pfam Families", "description": "List every Pfam family, including families with no hits in SeqHub. Use an accession as the `value` of a `pfam` literal in a feature filter.", "operationId": "listPfamFamilies", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PfamFamilyListResponse" }, "examples": { "excerpt": { "summary": "Excerpt: 3 of 25,545 families", "description": "Ordered by family name. Use `accession` as the `value` of a `pfam` literal.", "value": { "families": [ { "accession": "PF00005", "family": "ABC_tran" }, { "accession": "PF00069", "family": "Pkinase" }, { "accession": "PF13561", "family": "adh_short_C2" } ] } } } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/rfam-families": { "get": { "tags": [ "Vocabularies" ], "summary": "List Rfam Families", "description": "List every Rfam family, including families with no hits in SeqHub. Use an accession as the `value` of an `rfam` literal in a feature filter.", "operationId": "listRfamFamilies", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfamFamilyListResponse" }, "examples": { "excerpt": { "summary": "Excerpt: 3 of 4,227 families", "description": "Ordered by family name. Use `accession` as the `value` of an `rfam` literal.", "value": { "families": [ { "accession": "RF00010", "family": "RNaseP_bact_a" }, { "accession": "RF00050", "family": "FMN" }, { "accession": "RF00174", "family": "Cobalamin" } ] } } } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/sae-features": { "get": { "tags": [ "Vocabularies" ], "summary": "List SAE Features", "description": "List the SAE features that can be searched for. `nSegments` is the number of contig segments each feature occurs on.", "operationId": "listSaeFeatures", "parameters": [ { "name": "includeNames", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return each feature's name and whether it is interpretable. Set to false to return only ids, which makes the response about a third of the size.", "default": true, "title": "Includenames" }, "description": "Return each feature's name and whether it is interpretable. Set to false to return only ids, which makes the response about a third of the size." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaeFeatureListResponse" }, "examples": { "excerpt": { "summary": "Excerpt: 3 of 4,862 SAE features", "description": "Ordered by `nSegments`, most common first. `name` and `interpretable` are omitted with `includeNames=false`.", "value": { "features": [ { "saeFeatureId": 3108, "nSegments": 5569486, "name": "Shine-Dalgarno translation initiation region", "interpretable": true }, { "saeFeatureId": 2698, "nSegments": 5444279, "name": "Region just past a reverse gene's 5' end", "interpretable": false }, { "saeFeatureId": 7147, "nSegments": 5420791, "name": "Region just past a reverse gene's stop codon", "interpretable": false } ] } } } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Unprocessable Content" }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } }, "/api/v1/taxa": { "get": { "tags": [ "Vocabularies" ], "summary": "List Taxa", "description": "List every taxon in SeqHub across the seven ranks, ordered by name. Each entry is a `{rank, value}` pair that can be used directly in `taxonomyFilter`.", "operationId": "listTaxa", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonListResponse" }, "examples": { "excerpt": { "summary": "Excerpt: 3 of 43,949 taxa", "description": "Ordered by name. Each entry can be used directly in `taxonomyFilter`.", "value": { "taxa": [ { "rank": "genus", "value": "Bacillus" }, { "rank": "genus", "value": "Escherichia" }, { "rank": "phylum", "value": "Pseudomonadota" } ] } } } } } }, "401": { "description": "Missing or invalid personal access token, or the account has no active subscription." } } } } }, "components": { "schemas": { "FeatureAndGroup": { "properties": { "and": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FeatureLiteral" }, { "$ref": "#/components/schemas/FeatureAndGroup" }, { "$ref": "#/components/schemas/FeatureOrGroup" }, { "$ref": "#/components/schemas/FeatureNot" } ] }, "type": "array", "minItems": 2, "title": "And", "description": "Every sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "and" ], "title": "FeatureAndGroup" }, "FeatureLiteral": { "properties": { "field": { "type": "string", "enum": [ "rfam", "saeFeature", "pfam" ], "title": "Field", "description": "Which vocabulary `value` comes from." }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "title": "Value", "description": "A Pfam accession (e.g. 'PF00069') or Rfam accession (e.g. 'RF00174') as a string, or an SAE feature id (e.g. 8581) as an integer. Valid values are listed by /api/v1/pfam-families, /api/v1/rfam-families and /api/v1/sae-features." } }, "additionalProperties": false, "type": "object", "required": [ "field", "value" ], "title": "FeatureLiteral" }, "FeatureNot": { "properties": { "not": { "oneOf": [ { "$ref": "#/components/schemas/FeatureLiteral" }, { "$ref": "#/components/schemas/FeatureAndGroup" }, { "$ref": "#/components/schemas/FeatureOrGroup" }, { "$ref": "#/components/schemas/FeatureNot" } ], "title": "Not", "description": "The sub-expression to negate." } }, "additionalProperties": false, "type": "object", "required": [ "not" ], "title": "FeatureNot" }, "FeatureOrGroup": { "properties": { "or": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FeatureLiteral" }, { "$ref": "#/components/schemas/FeatureAndGroup" }, { "$ref": "#/components/schemas/FeatureOrGroup" }, { "$ref": "#/components/schemas/FeatureNot" } ] }, "type": "array", "minItems": 2, "title": "Or", "description": "At least one sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "or" ], "title": "FeatureOrGroup" }, "PfamAndGroup": { "properties": { "and": { "items": { "oneOf": [ { "$ref": "#/components/schemas/PfamLiteral" }, { "$ref": "#/components/schemas/PfamAndGroup" }, { "$ref": "#/components/schemas/PfamOrGroup" }, { "$ref": "#/components/schemas/PfamNot" } ] }, "type": "array", "minItems": 2, "title": "And", "description": "Every sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "and" ], "title": "PfamAndGroup" }, "PfamFamily": { "properties": { "accession": { "type": "string", "title": "Accession" }, "family": { "type": "string", "title": "Family" } }, "type": "object", "required": [ "accession", "family" ], "title": "PfamFamily", "examples": [ { "accession": "PF00069", "family": "Pkinase" } ] }, "PfamFamilyListResponse": { "properties": { "families": { "items": { "$ref": "#/components/schemas/PfamFamily" }, "type": "array", "title": "Families" } }, "type": "object", "required": [ "families" ], "title": "PfamFamilyListResponse" }, "PfamLiteral": { "properties": { "accession": { "type": "string", "title": "Accession", "description": "A Pfam accession, e.g. 'PF00005'. See /api/v1/pfam-families." } }, "additionalProperties": false, "type": "object", "required": [ "accession" ], "title": "PfamLiteral" }, "PfamNot": { "properties": { "not": { "oneOf": [ { "$ref": "#/components/schemas/PfamLiteral" }, { "$ref": "#/components/schemas/PfamAndGroup" }, { "$ref": "#/components/schemas/PfamOrGroup" }, { "$ref": "#/components/schemas/PfamNot" } ], "title": "Not", "description": "The sub-expression to negate." } }, "additionalProperties": false, "type": "object", "required": [ "not" ], "title": "PfamNot" }, "PfamOrGroup": { "properties": { "or": { "items": { "oneOf": [ { "$ref": "#/components/schemas/PfamLiteral" }, { "$ref": "#/components/schemas/PfamAndGroup" }, { "$ref": "#/components/schemas/PfamOrGroup" }, { "$ref": "#/components/schemas/PfamNot" } ] }, "type": "array", "minItems": 2, "title": "Or", "description": "At least one sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "or" ], "title": "PfamOrGroup" }, "ProblemDetail": { "properties": { "title": { "type": "string", "title": "Title", "description": "Short summary of the problem type, e.g. 'Unprocessable Entity'." }, "status": { "type": "integer", "title": "Status", "description": "Repeats the HTTP status code." }, "detail": { "type": "string", "title": "Detail", "description": "Explanation specific to this occurrence." }, "instance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance", "description": "Identifier for this error. Include it when reporting a problem." }, "errors": { "items": { "$ref": "#/components/schemas/ProblemDetailError" }, "type": "array", "title": "Errors", "description": "Field-level failures. Present on validation errors (422)." } }, "type": "object", "required": [ "title", "status", "detail" ], "title": "ProblemDetail" }, "ProblemDetailError": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "What was wrong, e.g. 'Input should be a valid integer'." }, "location": { "type": "string", "title": "Location", "description": "Dotted path to the offending field, e.g. 'body.sequences.0'." }, "type": { "type": "string", "title": "Type", "description": "Machine-readable error code, e.g. 'string_type' or 'missing'." }, "input": { "title": "Input", "description": "The value that was rejected, echoed back." } }, "type": "object", "required": [ "detail", "location", "type" ], "title": "ProblemDetailError" }, "ProteinQuery": { "properties": { "sequence": { "type": "string", "title": "Sequence" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Optional label for this query, returned as `queryId` in `matchIndices`. Must be unique within the request." }, "pfamFilter": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/PfamLiteral" }, { "$ref": "#/components/schemas/PfamAndGroup" }, { "$ref": "#/components/schemas/PfamOrGroup" }, { "$ref": "#/components/schemas/PfamNot" } ] }, { "type": "null" } ], "title": "Pfamfilter", "description": "Pfam domains that the protein matched by this query must have, as a single accession or combined with `and`, `or` and `not`. See /api/v1/pfam-families." } }, "additionalProperties": false, "type": "object", "required": [ "sequence" ], "title": "ProteinQuery" }, "ProteinTaxonomy": { "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "phylum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phylum" }, "class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Class" }, "order": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order" }, "family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family" }, "genus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Genus" }, "species": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Species" } }, "type": "object", "title": "ProteinTaxonomy" }, "AnnotateResponse": { "properties": { "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array", "title": "Annotations", "description": "The closest SwissProt match for each input sequence, in the order the sequences were sent." } }, "type": "object", "required": [ "annotations" ], "title": "AnnotateResponse" }, "Annotation": { "properties": { "id": { "type": "string", "title": "Id" }, "description": { "type": "string", "title": "Description" }, "score": { "type": "number", "title": "Score" }, "percentIdentity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percentidentity", "description": "Percent identity between this protein and its SwissProt match (`id`). This describes the annotation, not the search match. Null if not available." }, "queryCoverage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Querycoverage", "description": "Percent of this protein covered by the alignment to its SwissProt match. Null if not available." } }, "type": "object", "required": [ "id", "description", "score" ], "title": "Annotation" }, "CdsIdentifier": { "properties": { "sampleId": { "type": "string", "title": "Sampleid", "description": "Sample (genome) the gene is in." }, "contigId": { "type": "string", "title": "Contigid", "description": "Contig the gene is on." }, "cdsShorthand": { "type": "string", "title": "Cdsshorthand", "description": "Gene identifier, unique within its contig. The same identifier appears in gene IDs exported from the SeqHub website." }, "strand": { "type": "string", "enum": [ "+", "-" ], "title": "Strand", "description": "Strand the gene is on, \"+\" or \"-\"." }, "start": { "type": "integer", "title": "Start", "description": "Gene start position (bp) on the contig, inclusive." }, "end": { "type": "integer", "title": "End", "description": "Gene end position (bp) on the contig, inclusive." } }, "type": "object", "required": [ "sampleId", "contigId", "cdsShorthand", "strand", "start", "end" ], "title": "CdsIdentifier" }, "AnnotateRequest": { "properties": { "sequences": { "items": { "type": "string" }, "type": "array", "maxItems": 128, "minItems": 1, "title": "Sequences", "description": "Protein sequences to annotate (each max length 15000). Maximum 128 sequences." } }, "additionalProperties": false, "type": "object", "required": [ "sequences" ], "title": "AnnotateRequest" }, "ContigDnaRequest": { "properties": { "ranges": { "items": { "$ref": "#/components/schemas/ContigDnaRange" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Ranges" } }, "additionalProperties": false, "type": "object", "required": [ "ranges" ], "title": "ContigDnaRequest" }, "ContigDnaResponse": { "properties": { "sequences": { "items": { "$ref": "#/components/schemas/ContigDnaSequence" }, "type": "array", "title": "Sequences" } }, "type": "object", "required": [ "sequences" ], "title": "ContigDnaResponse" }, "ContigDnaRange": { "properties": { "sampleId": { "type": "string", "title": "Sampleid", "description": "The match's `sampleId`." }, "contigId": { "type": "string", "title": "Contigid", "description": "The match's `contigId`." }, "start": { "type": "integer", "minimum": 1.0, "title": "Start", "description": "Position on the contig, 1-based and inclusive." }, "end": { "type": "integer", "minimum": 1.0, "title": "End", "description": "Position on the contig, 1-based and inclusive." } }, "type": "object", "required": [ "sampleId", "contigId", "start", "end" ], "title": "ContigDnaRange" }, "ContigDnaSequence": { "properties": { "sampleId": { "type": "string", "title": "Sampleid" }, "contigId": { "type": "string", "title": "Contigid" }, "start": { "type": "integer", "title": "Start" }, "end": { "type": "integer", "title": "End" }, "sequence": { "type": "string", "title": "Sequence", "description": "DNA for the range, always on the plus strand." } }, "type": "object", "required": [ "sampleId", "contigId", "start", "end", "sequence" ], "title": "ContigDnaSequence" }, "HMMAnnotation": { "properties": { "accession": { "type": "string", "title": "Accession", "description": "Pfam accession, e.g. 'PF00069'." }, "name": { "type": "string", "title": "Name", "description": "Pfam family name, e.g. 'Pkinase'." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Pfam family description, e.g. 'Protein kinase domain'." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score", "description": "hmmsearch bitscore for this domain hit." }, "evalue": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Evalue", "description": "hmmsearch E-value for this domain hit." }, "start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start", "description": "Domain start position (bp) on the contig, inclusive." }, "end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End", "description": "Domain end position (bp) on the contig, inclusive." }, "residueStart": { "type": "integer", "title": "Residuestart", "description": "Domain start position within the protein sequence (1-based)." }, "residueEnd": { "type": "integer", "title": "Residueend", "description": "Domain end position within the protein sequence (1-based, inclusive)." } }, "type": "object", "required": [ "accession", "name", "residueStart", "residueEnd" ], "title": "HMMAnnotation" }, "MatchIndex": { "properties": { "contigProteinIndex": { "type": "integer", "title": "Contigproteinindex", "description": "Index into this match's `contig` array." }, "queryIndex": { "type": "integer", "title": "Queryindex", "description": "Which entry of the request's `sequences` this protein matched, 0-indexed." }, "queryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Queryid", "description": "The query's `id`, or null if none was given." }, "percentIdentity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percentidentity", "description": "Percent identity of the blastp alignment between the query and the matched protein. Null if blastp found no alignment." }, "queryCoverage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Querycoverage", "description": "Percent of the query sequence covered by the blastp alignment. Null if blastp found no alignment." } }, "type": "object", "required": [ "contigProteinIndex", "queryIndex" ], "title": "MatchIndex" }, "MultiQuerySearchMatch": { "properties": { "contig": { "items": { "$ref": "#/components/schemas/Protein" }, "type": "array", "title": "Contig" }, "taxonomy": { "anyOf": [ { "$ref": "#/components/schemas/ProteinTaxonomy" }, { "type": "null" } ] }, "matchIndices": { "items": { "$ref": "#/components/schemas/MatchIndex" }, "type": "array", "title": "Matchindices", "description": "One entry per query: `sequences[queryIndex]` matched `contig[contigProteinIndex]`." }, "saeFeatures": { "items": { "$ref": "#/components/schemas/Sae" }, "type": "array", "title": "Saefeatures", "description": "SAE features in the window. By default, only those named in `featureFilter`; set `includeOtherSaes` to return all of them." }, "rfamFamilies": { "items": { "$ref": "#/components/schemas/Rfam" }, "type": "array", "title": "Rfamfamilies", "description": "Rfam families found in the window, each with its hits. By default, only families named in `featureFilter`; set `includeOtherRfams` to return all of them." }, "sampleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sample Id", "description": "Sample of the contig this match is on. Use with `contigId` to fetch DNA from /api/v1/contig-dna.", "readOnly": true }, "contigId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contig Id", "description": "Contig this match is on. See `sampleId`.", "readOnly": true } }, "type": "object", "required": [ "contig", "sampleId", "contigId" ], "title": "MultiQuerySearchMatch" }, "MultiQuerySearchRequest": { "properties": { "sequences": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/ProteinQuery" }, "type": "array" } ], "title": "Sequences", "description": "1-5 protein sequences to search for (each max 15000 characters). Standard 20 and ambiguous B, X, Z, U residues are allowed.\n\nEither all plain sequence strings, or all ProteinQuery objects. A ProteinQuery adds an optional `id` and an optional `pfamFilter` on the protein that query matches." }, "featureFilter": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FeatureLiteral" }, { "$ref": "#/components/schemas/FeatureAndGroup" }, { "$ref": "#/components/schemas/FeatureOrGroup" }, { "$ref": "#/components/schemas/FeatureNot" } ] }, { "type": "null" } ], "title": "Featurefilter", "description": "Only return matches whose window satisfies this expression of Pfam, Rfam and SAE features, combined with `and`, `or` and `not`. At most 25 features. Valid identifiers are listed by /api/v1/pfam-families, /api/v1/rfam-families and /api/v1/sae-features." }, "taxonomyFilter": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ] }, { "type": "null" } ], "title": "Taxonomyfilter", "description": "Only return matches from genomes matching this taxonomy expression: a single `{rank, value}`, or several combined with `and`, `or` and `not`. At most 10 taxa. See /api/v1/taxa." }, "diversityLevel": { "type": "string", "enum": [ "low", "medium", "high", "max" ], "title": "Diversitylevel", "description": "How diverse the results are. Higher levels search only one representative protein per cluster of similar sequences, so near-identical proteins don't crowd out the results. `low` (default): clusters at 90% identity, returning the most similar results. `medium`: 70% identity. `high`: 50% identity. `max`: 30% identity, the most diverse results. For distant homologs, use `high` or `max`: at `low`, results can fill up with near-identical close matches.", "default": "low" }, "maxResults": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Maxresults", "description": "Maximum number of results to return, up to 100.", "default": 10 }, "includeOtherSaes": { "type": "boolean", "title": "Includeothersaes", "description": "Also return every SAE feature in each match's window, not just those named in `featureFilter`. Makes the response much larger.", "default": false }, "includeOtherRfams": { "type": "boolean", "title": "Includeotherrfams", "description": "Also return every Rfam hit in each match's window, not just those named in `featureFilter`.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "sequences" ], "title": "MultiQuerySearchRequest" }, "MultiQuerySearchResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/MultiQuerySearchMatch" }, "type": "array", "title": "Matches", "description": "Genomic neighborhoods where every query sequence found a match, best first." } }, "type": "object", "required": [ "matches" ], "title": "MultiQuerySearchResponse" }, "Protein": { "properties": { "cdsId": { "$ref": "#/components/schemas/CdsIdentifier" }, "sequence": { "type": "string", "title": "Sequence" }, "annotation": { "anyOf": [ { "$ref": "#/components/schemas/Annotation" }, { "type": "null" } ] }, "hmmAnnotations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HMMAnnotation" }, "type": "array" }, { "type": "null" } ], "title": "Hmmannotations" } }, "type": "object", "required": [ "cdsId", "sequence" ], "title": "Protein" }, "ProteinSearchRequest": { "properties": { "sequence": { "type": "string", "maxLength": 15000, "title": "Sequence", "description": "The protein sequence to search for (max length 15000). Standard 20 and ambiguous B, X, Z, U residues are allowed." }, "taxonomyFilter": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ] }, { "type": "null" } ], "title": "Taxonomyfilter", "description": "Only return matches from genomes matching this taxonomy expression: a single `{rank, value}`, or several combined with `and`, `or` and `not`. At most 10 taxa. See /api/v1/taxa." }, "diversityLevel": { "type": "string", "enum": [ "low", "medium", "high", "max" ], "title": "Diversitylevel", "description": "How diverse the results are. Higher levels search only one representative protein per cluster of similar sequences, so near-identical proteins don't crowd out the results. `low` (default): clusters at 90% identity, returning the most similar results. `medium`: 70% identity. `high`: 50% identity. `max`: 30% identity, the most diverse results. For distant homologs, use `high` or `max`: at `low`, results can fill up with near-identical close matches.", "default": "low" }, "maxResults": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Maxresults", "description": "Maximum number of results to return, up to 100.", "default": 10 } }, "additionalProperties": false, "type": "object", "required": [ "sequence" ], "title": "ProteinSearchRequest" }, "ProteinSearchResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/SearchMatch" }, "type": "array", "title": "Matches", "description": "Genomic neighborhoods around the closest matches to the query sequence, most similar first." } }, "type": "object", "required": [ "matches" ], "title": "ProteinSearchResponse" }, "Rfam": { "properties": { "accession": { "type": "string", "title": "Accession", "description": "Rfam accession, e.g. \"RF00174\". See /api/v1/rfam-families." }, "hits": { "items": { "$ref": "#/components/schemas/RfamHit" }, "type": "array", "title": "Hits", "description": "Hits within the returned window." }, "bestScore": { "type": "number", "title": "Bestscore", "description": "Highest nhmmer score among this accession's hits in the window." } }, "type": "object", "required": [ "accession", "hits", "bestScore" ], "title": "Rfam" }, "RfamHit": { "properties": { "start": { "type": "integer", "title": "Start", "description": "Start position (bp) of the hit on the contig, inclusive." }, "end": { "type": "integer", "title": "End", "description": "End position (bp) of the hit on the contig, inclusive." }, "strand": { "type": "string", "enum": [ "+", "-" ], "title": "Strand", "description": "Strand the hit is on, \"+\" or \"-\"." }, "family": { "type": "string", "title": "Family", "description": "Rfam family name, e.g. \"Cobalamin\"." }, "accession": { "type": "string", "title": "Accession", "description": "Rfam accession, e.g. \"RF00174\"." }, "evalue": { "type": "number", "title": "Evalue", "description": "nhmmer E-value for this hit." }, "score": { "type": "number", "title": "Score", "description": "nhmmer bit score for this hit." } }, "type": "object", "required": [ "start", "end", "strand", "family", "accession", "evalue", "score" ], "title": "RfamHit" }, "Sae": { "properties": { "saeFeatureId": { "type": "integer", "title": "Saefeatureid", "description": "SAE feature id. See /api/v1/sae-features." }, "runs": { "items": { "$ref": "#/components/schemas/SaeRun" }, "type": "array", "title": "Runs", "description": "Where the feature fires within the returned window." }, "nFiringPositions": { "type": "integer", "title": "Nfiringpositions", "description": "Number of positions in the window where the feature fires. Can be less than the total length of `runs`, since a run may include short gaps." } }, "type": "object", "required": [ "saeFeatureId", "runs", "nFiringPositions" ], "title": "Sae" }, "SaeRun": { "properties": { "start": { "type": "integer", "title": "Start", "description": "Start position (bp) of the run on the contig, inclusive." }, "end": { "type": "integer", "title": "End", "description": "End position (bp) of the run on the contig, inclusive." }, "strand": { "type": "string", "title": "Strand", "description": "Strand the run is on, \"+\" or \"-\"." }, "offsets": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Offsets", "description": "Positions within the run where the feature fires, as bp offsets from `start`. A run may include short gaps, so use these for exact positions. May be absent." }, "maxActivation": { "type": "number", "title": "Maxactivation", "description": "Peak activation among the run's firing positions." } }, "type": "object", "required": [ "start", "end", "strand", "maxActivation" ], "title": "SaeRun" }, "SearchMatch": { "properties": { "contig": { "items": { "$ref": "#/components/schemas/Protein" }, "type": "array", "title": "Contig" }, "taxonomy": { "anyOf": [ { "$ref": "#/components/schemas/ProteinTaxonomy" }, { "type": "null" } ] }, "matchIndex": { "type": "integer", "title": "Matchindex", "description": "Index into `contig` of the protein that matched the query sequence." }, "percentIdentity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percentidentity", "description": "Percent identity of the blastp alignment between the query and the matched protein. Null if blastp found no alignment." }, "queryCoverage": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Querycoverage", "description": "Percent of the query sequence covered by the blastp alignment. Null if blastp found no alignment." }, "sampleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sample Id", "description": "Sample of the contig this match is on. Use with `contigId` to fetch DNA from /api/v1/contig-dna.", "readOnly": true }, "contigId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contig Id", "description": "Contig this match is on. See `sampleId`.", "readOnly": true } }, "type": "object", "required": [ "contig", "matchIndex", "sampleId", "contigId" ], "title": "SearchMatch" }, "FeatureSearchMatch": { "properties": { "contigSegmentId": { "type": "string", "format": "uuid", "title": "Contigsegmentid", "description": "Stable identifier of the contig segment this match is on." }, "taxonomy": { "anyOf": [ { "$ref": "#/components/schemas/ProteinTaxonomy" }, { "type": "null" } ] }, "contig": { "items": { "$ref": "#/components/schemas/Protein" }, "type": "array", "title": "Contig", "description": "The proteins in the matched window." }, "rfamFamilies": { "items": { "$ref": "#/components/schemas/Rfam" }, "type": "array", "title": "Rfamfamilies", "description": "Rfam families found in the window, each with its hits. By default, only families named in `featureFilter`; set `includeOtherRfams` to return all of them." }, "saeFeatures": { "items": { "$ref": "#/components/schemas/Sae" }, "type": "array", "title": "Saefeatures", "description": "SAE features in the window. By default, only those named in `featureFilter`; set `includeOtherSaes` to return all of them." }, "sampleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sampleid", "description": "Sample of the contig this match is on. Use with `contigId` to fetch DNA from /api/v1/contig-dna." }, "contigId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contigid", "description": "Contig this match is on. See `sampleId`." } }, "type": "object", "required": [ "contigSegmentId" ], "title": "FeatureSearchMatch" }, "FeatureSearchRequest": { "properties": { "featureFilter": { "oneOf": [ { "$ref": "#/components/schemas/FeatureLiteral" }, { "$ref": "#/components/schemas/FeatureAndGroup" }, { "$ref": "#/components/schemas/FeatureOrGroup" }, { "$ref": "#/components/schemas/FeatureNot" } ], "title": "Featurefilter", "description": "The features that must occur together: Pfam, Rfam and SAE feature literals combined with `and`, `or` and `not`. At most 10 literals. The expression must always require at least one feature to be present, so an expression that can be satisfied by `not` terms alone is rejected. Valid identifiers are listed by /api/v1/pfam-families, /api/v1/rfam-families and /api/v1/sae-features." }, "taxonomyFilter": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ] }, { "type": "null" } ], "title": "Taxonomyfilter", "description": "Only return matches from genomes matching this taxonomy expression. See /api/v1/taxa." }, "window": { "type": "integer", "maximum": 20.0, "minimum": 0.0, "title": "Window", "description": "Window radius in genes (not base pairs) around each feature hit. Required features must fall within this window, and the proteins in it are returned. At most 20.", "default": 10 }, "taxonomicDiversityRank": { "anyOf": [ { "type": "string", "enum": [ "domain", "phylum", "class", "order", "family", "genus", "species" ] }, { "type": "null" } ], "title": "Taxonomicdiversityrank", "description": "Return at most one match per taxon at this rank, so results are not dominated by over-represented lineages. Set to null to return every match.", "default": "genus" }, "maxResults": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Maxresults", "description": "Maximum number of results to return, up to 100.", "default": 10 }, "includeOtherSaes": { "type": "boolean", "title": "Includeothersaes", "description": "Also return SAE features in the window that are not named in `featureFilter`. Makes the response much larger.", "default": false }, "includeOtherRfams": { "type": "boolean", "title": "Includeotherrfams", "description": "Also return Rfam hits in the window for families not named in `featureFilter`.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "featureFilter" ], "title": "FeatureSearchRequest", "examples": [ { "featureFilter": { "and": [ { "field": "pfam", "value": "PF00069" }, { "field": "saeFeature", "value": 8581 } ] }, "taxonomyFilter": { "rank": "phylum", "value": "Pseudomonadota" }, "window": 5 } ] }, "FeatureSearchResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/FeatureSearchMatch" }, "type": "array", "title": "Matches", "description": "Genomic neighborhoods where the feature expression is satisfied." } }, "type": "object", "required": [ "matches" ], "title": "FeatureSearchResponse" }, "RfamFamily": { "properties": { "accession": { "type": "string", "title": "Accession" }, "family": { "type": "string", "title": "Family" } }, "type": "object", "required": [ "accession", "family" ], "title": "RfamFamily", "examples": [ { "accession": "RF00174", "family": "Cobalamin" } ] }, "RfamFamilyListResponse": { "properties": { "families": { "items": { "$ref": "#/components/schemas/RfamFamily" }, "type": "array", "title": "Families" } }, "type": "object", "required": [ "families" ], "title": "RfamFamilyListResponse" }, "SaeFeatureListEntry": { "properties": { "saeFeatureId": { "type": "integer", "title": "Saefeatureid" }, "nSegments": { "type": "integer", "title": "Nsegments" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "interpretable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Interpretable" } }, "type": "object", "required": [ "saeFeatureId", "nSegments" ], "title": "SaeFeatureListEntry", "examples": [ { "interpretable": true, "nSegments": 999, "name": "Iron-box operator upstream of iron transport operons", "saeFeatureId": 8581 } ] }, "SaeFeatureListResponse": { "properties": { "features": { "items": { "$ref": "#/components/schemas/SaeFeatureListEntry" }, "type": "array", "title": "Features" } }, "type": "object", "required": [ "features" ], "title": "SaeFeatureListResponse" }, "TaxonListResponse": { "properties": { "taxa": { "items": { "$ref": "#/components/schemas/TaxonSuggestion" }, "type": "array", "title": "Taxa" } }, "type": "object", "required": [ "taxa" ], "title": "TaxonListResponse" }, "TaxonSuggestion": { "properties": { "rank": { "type": "string", "enum": [ "domain", "phylum", "class", "order", "family", "genus", "species" ], "title": "Rank" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "rank", "value" ], "title": "TaxonSuggestion", "examples": [ { "rank": "genus", "value": "Escherichia" } ] }, "TaxonomyAndGroup": { "properties": { "and": { "items": { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ] }, "type": "array", "minItems": 2, "title": "And", "description": "Every sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "and" ], "title": "TaxonomyAndGroup" }, "TaxonomyLiteral": { "properties": { "rank": { "type": "string", "enum": [ "domain", "phylum", "class", "order", "family", "genus", "species" ], "title": "Rank", "description": "One of the seven ranks, e.g. 'genus'." }, "value": { "type": "string", "title": "Value", "description": "A taxon name at that rank, e.g. 'Escherichia'. See /api/v1/taxa." } }, "additionalProperties": false, "type": "object", "required": [ "rank", "value" ], "title": "TaxonomyLiteral" }, "TaxonomyNot": { "properties": { "not": { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ], "title": "Not", "description": "The sub-expression to negate." } }, "additionalProperties": false, "type": "object", "required": [ "not" ], "title": "TaxonomyNot" }, "TaxonomyOrGroup": { "properties": { "or": { "items": { "oneOf": [ { "$ref": "#/components/schemas/TaxonomyLiteral" }, { "$ref": "#/components/schemas/TaxonomyAndGroup" }, { "$ref": "#/components/schemas/TaxonomyOrGroup" }, { "$ref": "#/components/schemas/TaxonomyNot" } ] }, "type": "array", "minItems": 2, "title": "Or", "description": "At least one sub-expression must hold." } }, "additionalProperties": false, "type": "object", "required": [ "or" ], "title": "TaxonomyOrGroup" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A personal access token, sent as `Authorization: Bearer `. Create one in the API Tokens section of your SeqHub profile.\n\nA 401 means the token is missing, malformed or unknown, or the account has no active subscription." } } } }