{"openapi": "3.1.0", "info": {"title": "MGnify Proteins API", "version": "1.0", "description": "Look up MGnify proteins by MGYP accession or search them by biome or Pfam. Bulk downloads are available from the [protein database release FTP](https://ftp.ebi.ac.uk/pub/databases/metagenomics/peptide_database/current_release/)."}, "paths": {"/metagenomics/proteins/api/v1/protein/search": {"get": {"operationId": "search_proteins", "summary": "Search proteins by biome or Pfam", "parameters": [{"in": "query", "name": "biome_id", "schema": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Biome Id"}, "required": false}, {"in": "query", "name": "biome_lineage", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "example": "root:Engineered:Wastewater", "title": "Biome Lineage"}, "required": false, "example": "root:Engineered:Wastewater"}, {"in": "query", "name": "pfam_accession", "schema": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Pfam Accession"}, "required": false}, {"in": "query", "name": "limit", "schema": {"default": 50, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"items": {"$ref": "#/components/schemas/ProteinSearchResultOut"}, "title": "Response", "type": "array"}}}, "links": {"ProteinDetail": {"operationId": "get_protein_detail", "parameters": {"mgyp": "$response.body#/0/mgyp"}, "description": "The `mgyp` of a search hit fetches its full record from the protein detail endpoint."}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorSchema"}}}}}, "description": "Filter proteins by exactly one of `biome_id`, `biome_lineage`, or `pfam_accession`. `biome_lineage` is descendant-inclusive: `root:Engineered:Wastewater` also matches its sub-biomes. Returns 422 when a `biome_lineage` resolves to no biome (e.g. a partial name like `Wastewater` rather than a full lineage). Results are a single page, capped by `limit`.", "tags": ["Proteins"]}}, "/metagenomics/proteins/api/v1/protein/{mgyp}": {"get": {"operationId": "get_protein_detail", "summary": "Get protein detail by MGYP accession", "parameters": [{"in": "path", "name": "mgyp", "schema": {"example": "MGYP000000302531", "title": "Mgyp", "type": "string"}, "required": true, "example": "MGYP000000302531"}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProteinDetailSchema"}}}}, "302": {"description": "Found"}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorSchema"}}}}}, "tags": ["Proteins"]}}}, "components": {"schemas": {"ProteinSearchParams": {"properties": {"biome_id": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Biome Id"}, "biome_lineage": {"anyOf": [{"type": "string"}, {"type": "null"}], "example": "root:Engineered:Wastewater", "title": "Biome Lineage"}, "pfam_accession": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Pfam Accession"}, "limit": {"default": 50, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer"}}, "title": "ProteinSearchParams", "type": "object"}, "ProteinSearchResultOut": {"properties": {"mgyp": {"title": "Mgyp", "type": "string"}, "full_length": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "title": "Full Length"}, "cluster_size": {"title": "Cluster Size", "type": "integer"}}, "required": ["mgyp", "full_length", "cluster_size"], "title": "ProteinSearchResultOut", "type": "object"}, "ErrorSchema": {"properties": {"detail": {"title": "Detail", "type": "string"}}, "required": ["detail"], "title": "ErrorSchema", "type": "object"}, "BiomeSchema": {"properties": {"count": {"title": "Count", "type": "integer"}, "id": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Id"}, "name": {"title": "Name", "type": "string"}}, "required": ["count", "name"], "title": "BiomeSchema", "type": "object"}, "PfamAnnotationSchema": {"properties": {"accession": {"title": "Accession", "type": "string"}, "name": {"title": "Name", "type": "string"}, "clan": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Clan"}, "evalue": {"title": "Evalue", "type": "number"}, "bit_score": {"title": "Bit Score", "type": "number"}, "hmm_start": {"title": "Hmm Start", "type": "integer"}, "hmm_end": {"title": "Hmm End", "type": "integer"}, "env_start": {"title": "Env Start", "type": "integer"}, "env_end": {"title": "Env End", "type": "integer"}}, "required": ["accession", "name", "clan", "evalue", "bit_score", "hmm_start", "hmm_end", "env_start", "env_end"], "title": "PfamAnnotationSchema", "type": "object"}, "ProteinDetailSchema": {"properties": {"mgyp": {"title": "Mgyp", "type": "string"}, "sequence": {"title": "Sequence", "type": "string"}, "full_length": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "title": "Full Length"}, "cluster_size": {"title": "Cluster Size", "type": "integer"}, "biomes": {"items": {"$ref": "#/components/schemas/BiomeSchema"}, "title": "Biomes", "type": "array"}, "pfam_annotations": {"items": {"$ref": "#/components/schemas/PfamAnnotationSchema"}, "title": "Pfam Annotations", "type": "array"}, "study_assembly_contigs": {"items": {"$ref": "#/components/schemas/StudyAssemblyContigSchema"}, "title": "Study Assembly Contigs", "type": "array"}}, "required": ["mgyp", "sequence", "full_length", "cluster_size", "biomes", "pfam_annotations", "study_assembly_contigs"], "title": "ProteinDetailSchema", "type": "object"}, "StudyAssemblyContigSchema": {"properties": {"study_accession": {"title": "Study Accession", "type": "string"}, "assembly_accession": {"title": "Assembly Accession", "type": "string"}, "contig_accession": {"title": "Contig Accession", "type": "string"}, "contig_name": {"title": "Contig Name", "type": "string"}, "start": {"title": "Start", "type": "integer"}, "end": {"title": "End", "type": "integer"}, "strand": {"title": "Strand", "type": "string"}}, "required": ["study_accession", "assembly_accession", "contig_accession", "contig_name", "start", "end", "strand"], "title": "StudyAssemblyContigSchema", "type": "object"}}}, "servers": [], "externalDocs": {"description": "MGnify documentation", "url": "https://docs.mgnify.org/"}, "tags": [{"name": "Proteins", "description": "Look up and search MGnify proteins (MGYP accessions)."}]}