{"openapi":"3.1.0","info":{"title":"The Peptides API","version":"1.5.0","description":"Intelligence layer for peptide research. Structured data, semantic search, AI summaries, vendor intel, and more.","contact":{"email":"api@peptides.dev","url":"https://peptides.dev"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.peptides.dev/api/v1","description":"Production"},{"url":"http://localhost:3000/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key from your dashboard. Format: Bearer pk_live_..."}},"schemas":{"Peptide":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"sequence":{"type":"string","nullable":true},"molecularWeight":{"type":"number","nullable":true},"halfLife":{"type":"string","nullable":true},"researchStatus":{"type":"string","enum":["PRECLINICAL","CLINICAL_TRIALS","APPROVED","EXPERIMENTAL","DISCONTINUED"]},"mechanism":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"references":{"type":"integer"},"coverageScore":{"type":"number","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"PaginatedResponse":{"type":"object","properties":{"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}},"paths":{"/peptides/batch":{"post":{"summary":"Bulk fetch peptides by id and/or slug (max 100)","tags":["Peptides"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"slugs":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string"},"description":"Sparse fieldset"}}}}}},"responses":{"200":{"description":"Peptides"},"400":{"description":"Invalid request"}}}},"/ai/query":{"post":{"summary":"Natural-language search → structured filter → results (Builder+)","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Parsed filter + matching peptides"},"403":{"description":"Plan required"}}}},"/ai/stack":{"post":{"summary":"Analyze a peptide stack for synergies/conflicts (Builder+)","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["peptides"],"properties":{"peptides":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":6}}}}}},"responses":{"200":{"description":"Known interactions + AI analysis"},"403":{"description":"Plan required"}}}},"/ai/parse-coa":{"post":{"summary":"Extract structured fields from a Certificate of Analysis (Builder+)","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"vendor_id":{"type":"string","description":"Persist a VendorLot when provided"}}}}}},"responses":{"200":{"description":"Parsed COA fields"},"422":{"description":"Could not parse"}}}},"/digest":{"get":{"summary":"Recent studies across all peptides, optionally AI-summarized","tags":["Discovery"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"summarize","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Digest of recent studies"}}}},"/trends":{"get":{"summary":"Emerging peptides by publication velocity","tags":["Discovery"],"parameters":[{"name":"years","in":"query","schema":{"type":"integer","default":2}},{"name":"limit","in":"query","schema":{"type":"integer","default":15}}],"responses":{"200":{"description":"Ranked peptides with momentum score"}}}},"/peptides":{"get":{"operationId":"listPeptides","summary":"List peptides","description":"Returns a paginated list of peptides with optional filters.","tags":["Peptides"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query (fuzzy)"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"research_status","in":"query","schema":{"type":"string"},"description":"Filter by research status"},{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string"}},"description":"Filter by tags (repeatable)"},{"name":"featured","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["name","molecularWeight","references","createdAt","coverageScore"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limited"}}}},"/peptides/{id}":{"get":{"operationId":"getPeptide","summary":"Get peptide by ID","description":"Retrieve a peptide by its slug, ID, or alias.","tags":["Peptides"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Peptide slug, id, or alias"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Peptide"}}}}}},"404":{"description":"Not found"}}}},"/search/semantic":{"post":{"operationId":"semanticSearch","summary":"Semantic peptide search","description":"Natural language search using OpenAI embeddings + pgvector cosine similarity.","tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","example":"healing peptides for tendon recovery"},"limit":{"type":"integer","default":10,"maximum":50},"filters":{"type":"object","properties":{"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"researchStatus":{"type":"string"}}}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Plan upgrade required"}}}},"/ai/ask":{"post":{"operationId":"aiAsk","summary":"Ask a question about peptides","description":"Grounded Q&A using RAG over the peptide corpus.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string"},"peptide_id":{"type":"string","description":"Focus on a specific peptide"},"context_limit":{"type":"integer","default":5}}}}}},"responses":{"200":{"description":"OK"}}}},"/vendors":{"get":{"operationId":"listVendors","summary":"List vendors","description":"Returns tracked vendors with trust scores and testing data.","tags":["Vendors"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tier","in":"query","schema":{"type":"string","enum":["VERIFIED","TRUSTED","UNVERIFIED"]}},{"name":"hplc_tested","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"}}}},"/analytics/usage":{"get":{"operationId":"getUsageAnalytics","summary":"Get API usage analytics","description":"Returns the authenticated user's API usage statistics.","tags":["Analytics"],"responses":{"200":{"description":"OK"}}}},"/embeddings":{"post":{"operationId":"createEmbeddings","summary":"Generate embeddings","description":"Generate 1536-d embeddings for text inputs. Requires Builder plan or higher.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":100}]}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Plan upgrade required"}}}}},"tags":[{"name":"Peptides","description":"Peptide database endpoints"},{"name":"Search","description":"Semantic and keyword search"},{"name":"AI","description":"AI-powered Q&A and summarization"},{"name":"Vendors","description":"Vendor intelligence data"},{"name":"Analytics","description":"Usage analytics"}]}