# The Peptides API

> Intelligence layer for peptide research: structured peptide data, research
> studies, dosing protocols, vendor intel, semantic search, and AI Q&A.

## Base URL
https://www.thepeptidesapi.com/api/v1

## Authentication
All endpoints require an API key. Send it as a Bearer token:
  Authorization: Bearer pk_live_xxxxxxxx
(The X-Api-Key header is also accepted.)
Create and manage keys in your dashboard under API Keys.

## Conventions
- JSON request and response bodies.
- List endpoints are paginated via ?page= and ?limit= and return { data, meta }.
- Errors return { error: { code, message } } with an appropriate HTTP status.
- Rate limits and a monthly quota apply per plan; see response headers
  X-RateLimit-* and X-Quota-*. Some endpoints require Builder plan or higher.

## Endpoints

### Health
- GET /api/health — API Health Check
    Liveness probe. Returns 200 when the API and database are reachable, 503 otherwise. No API key required.

### Peptides
- GET https://www.thepeptidesapi.com/api/v1/peptides — List Peptides
    Paginated list of peptides with filtering, sorting, and sparse fieldsets.
    Query params: q, category, research_status, tag, featured, fields, page, limit, sort_by, sort_dir
- GET https://www.thepeptidesapi.com/api/v1/peptides/{id} — Get Peptide Details
    Retrieve a single peptide by slug, id, or alias.
    Path params: id
- GET https://www.thepeptidesapi.com/api/v1/peptides/{id}/studies — Get Peptide Studies
    Studies referencing this peptide, newest first.
    Path params: id
    Query params: limit
- GET https://www.thepeptidesapi.com/api/v1/peptides/{id}/protocols — Get Peptide Protocols
    Community and literature dosing protocols for this peptide.
    Path params: id
- GET https://www.thepeptidesapi.com/api/v1/peptides/{id}/similar — Get Similar Peptides [Builder+]
    Vector-similarity neighbors of this peptide.
    Path params: id
    Query params: limit
- GET https://www.thepeptidesapi.com/api/v1/peptides/{id}/sources — Get Peptide Sources
    Provenance and citations behind this peptide record.
    Path params: id
- POST https://www.thepeptidesapi.com/api/v1/peptides/batch — Batch Get Peptides
    Fetch up to 100 peptides by id and/or slug in one call.
    Body example: {"slugs":["bpc-157","tb-500"],"fields":["id","name","researchStatus"]}

### Search
- GET https://www.thepeptidesapi.com/api/v1/search/autocomplete — Autocomplete Search
    Fast prefix/typeahead suggestions across peptide names and aliases.
    Query params: q*, limit
- POST https://www.thepeptidesapi.com/api/v1/search/semantic — Semantic Search [Builder+]
    Natural-language search using embeddings + pgvector cosine similarity.
    Body example: {"query":"healing peptides for tendon recovery","limit":10}
- POST https://www.thepeptidesapi.com/api/v1/similarity — Text Similarity [Builder+]
    Score the semantic similarity between an input text and peptides.
    Body example: {"text":"stimulates collagen synthesis and angiogenesis","limit":5}

### Studies
- GET https://www.thepeptidesapi.com/api/v1/studies — List Studies
    Paginated research studies across all peptides.
    Query params: q, peptide, year, page, limit
- GET https://www.thepeptidesapi.com/api/v1/studies/{id} — Get Study Details
    Full record for a single study, including abstract and key findings.
    Path params: id

### Protocols
- GET https://www.thepeptidesapi.com/api/v1/protocols — List Protocols
    Dosing protocols across peptides.
    Query params: peptide, page, limit
- GET https://www.thepeptidesapi.com/api/v1/protocols/{id} — Get Protocol Details
    Full protocol record including schedule and citations.
    Path params: id

### Vendors
- GET https://www.thepeptidesapi.com/api/v1/vendors — List Vendors
    Tracked vendors with trust tiers and testing data.
    Query params: q, tier, hplc_tested
- GET https://www.thepeptidesapi.com/api/v1/vendors/{id} — Get Vendor Details
    Full vendor record including lots and test results.
    Path params: id

### AI
- POST https://www.thepeptidesapi.com/api/v1/ai/ask — AI Ask (RAG Q&A)
    Grounded question answering over the peptide corpus with citations.
    Body example: {"question":"What is BPC-157 used for in research?","context_limit":5}
- POST https://www.thepeptidesapi.com/api/v1/ai/compare — AI Compare Peptides [Builder+]
    Side-by-side AI comparison of two or more peptides.
    Body example: {"peptides":["bpc-157","tb-500"]}
- POST https://www.thepeptidesapi.com/api/v1/ai/summarize — AI Summarize
    Summarize a peptide or a block of research text.
    Body example: {"peptide_id":"bpc-157"}
- POST https://www.thepeptidesapi.com/api/v1/ai/query — AI Natural-Language Query [Builder+]
    Convert a plain-English query into a structured filter and return matches.
    Body example: {"query":"approved peptides for weight loss","limit":20}
- POST https://www.thepeptidesapi.com/api/v1/ai/stack — AI Stack Analysis [Builder+]
    Analyze a peptide stack for synergies and conflicts.
    Body example: {"peptides":["bpc-157","tb-500","ghk-cu"]}
- POST https://www.thepeptidesapi.com/api/v1/ai/parse-coa — AI Parse COA [Builder+]
    Extract structured fields from a Certificate of Analysis.
    Body example: {"text":"Product: BPC-157\nPurity (HPLC): 99.2%\nMass (MS): 1419.5 Da"}
- POST https://www.thepeptidesapi.com/api/v1/embeddings — Create Embeddings [Builder+]
    Generate vector embeddings for one or more text inputs.
    Body example: {"input":"tendon healing peptide"}

### Discovery
- GET https://www.thepeptidesapi.com/api/v1/digest — Research Digest
    Recent studies across all peptides, optionally AI-summarized.
    Query params: days, limit, summarize
- GET https://www.thepeptidesapi.com/api/v1/trends — Emerging Trends
    Peptides ranked by recent publication velocity.
    Query params: years, limit
- GET https://www.thepeptidesapi.com/api/v1/graph — Interaction Graph
    Nodes and edges of the peptide interaction graph.
    Query params: peptide, depth
- GET https://www.thepeptidesapi.com/api/v1/changelog — Data Changelog
    Recent changes to the dataset (new peptides, updated records).
    Query params: limit

### Account
- GET https://www.thepeptidesapi.com/api/v1/account — Get Account
    Your plan, scopes, rate limit, and current monthly quota status.
- GET https://www.thepeptidesapi.com/api/v1/analytics/usage — Usage Analytics
    Your API usage over time, grouped by endpoint and status.
    Query params: days
- GET https://www.thepeptidesapi.com/api/v1/openapi — OpenAPI Spec
    The machine-readable OpenAPI 3.1 specification for this API.