{
  "openapi": "3.0.3",
  "info": {
    "title": "Peptide List API",
    "version": "1.0.0",
    "description": "Read-only JSON API exposing the Peptide List catalog. All data is sourced from the public site at peptidelist.org. Access is free of charge and requires an API key (request one at https://peptidelist.org/developers).",
    "contact": {
      "name": "Peptide List",
      "url": "https://peptidelist.org/developers",
      "email": "hello@peptidelist.org"
    }
  },
  "servers": [
    { "url": "https://peptidelist.org", "description": "Production" }
  ],
  "security": [{ "BearerAuth": [] }, { "ApiKeyHeader": [] }],
  "paths": {
    "/api/peptides": {
      "get": {
        "summary": "List peptides",
        "description": "Returns slim metadata for every peptide in the catalog. Use this to discover slugs, then call /api/peptides/{slug} for full details.",
        "operationId": "listPeptides",
        "responses": {
          "200": {
            "description": "Catalog of peptide metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["count", "peptides"],
                  "properties": {
                    "count": { "type": "integer", "example": 216 },
                    "peptides": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/PeptideMeta" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" }
        }
      }
    },
    "/api/peptides/{slug}": {
      "get": {
        "summary": "Get peptide details",
        "description": "Returns the full Peptide object for the given slug, including all optional extended-content fields when present.",
        "operationId": "getPeptideBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "URL-safe peptide identifier (e.g. \"bpc-157\").",
            "schema": { "type": "string" },
            "example": "bpc-157"
          }
        ],
        "responses": {
          "200": {
            "description": "Full peptide record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Peptide" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your key as `Authorization: Bearer <key>`."
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative to Bearer auth: send your key as `X-API-Key: <key>`."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "NotFound": {
        "description": "Peptide not found for the given slug.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "MethodNotAllowed": {
        "description": "Only GET is supported.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      }
    },
    "schemas": {
      "EvidenceLevel": {
        "type": "string",
        "enum": ["strong", "moderate", "emerging", "preliminary", "limited"]
      },
      "SafetyLevel": {
        "type": "string",
        "enum": ["well-studied", "moderate-data", "limited-data", "use-caution"]
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      },
      "PeptideMeta": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "altNames",
          "shortDescription",
          "tags",
          "evidenceLevel",
          "safetyLevel",
          "goalSlugs",
          "peptideClass",
          "popularity",
          "updatedDate",
          "attributionUrl"
        ],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "altNames": { "type": "array", "items": { "type": "string" } },
          "shortDescription": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "evidenceLevel": { "$ref": "#/components/schemas/EvidenceLevel" },
          "safetyLevel": { "$ref": "#/components/schemas/SafetyLevel" },
          "goalSlugs": { "type": "array", "items": { "type": "string" } },
          "peptideClass": { "type": "string" },
          "popularity": { "type": "integer", "minimum": 1, "maximum": 10 },
          "updatedDate": { "type": "string" },
          "attributionUrl": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL on peptidelist.org for this peptide. Use this as the link target when republishing data sourced from the API.",
            "example": "https://peptidelist.org/peptides/bpc-157"
          }
        }
      },
      "Reference": {
        "type": "object",
        "required": ["title", "url", "type"],
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "type": { "type": "string" },
          "summary": { "type": "string" }
        }
      },
      "Peptide": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "altNames",
          "shortDescription",
          "tags",
          "evidenceLevel",
          "safetyLevel",
          "goalSlugs",
          "updatedDate",
          "popularity",
          "peptideClass",
          "whatItIs",
          "whyPeopleTalkAboutIt",
          "commonQuestions",
          "safetyNotes",
          "mechanismSimple",
          "mechanismDetailed",
          "evidenceSnapshot",
          "formsAndAdministration",
          "references",
          "relatedPeptideSlugs",
          "compareSlugs",
          "attributionUrl"
        ],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "altNames": { "type": "array", "items": { "type": "string" } },
          "shortDescription": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "evidenceLevel": { "$ref": "#/components/schemas/EvidenceLevel" },
          "safetyLevel": { "$ref": "#/components/schemas/SafetyLevel" },
          "goalSlugs": { "type": "array", "items": { "type": "string" } },
          "updatedDate": { "type": "string" },
          "popularity": { "type": "integer", "minimum": 1, "maximum": 10 },
          "peptideClass": { "type": "string" },
          "whatItIs": { "type": "string" },
          "whyPeopleTalkAboutIt": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["useCase", "evidenceLevel"],
              "properties": {
                "useCase": { "type": "string" },
                "evidenceLevel": { "$ref": "#/components/schemas/EvidenceLevel" }
              }
            }
          },
          "useCasesSummary": { "type": "string" },
          "commonQuestions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["q", "a"],
              "properties": {
                "q": { "type": "string" },
                "a": { "type": "string" }
              }
            }
          },
          "safetyNotes": {
            "type": "object",
            "required": ["commonSideEffects", "cautions", "unknowns"],
            "properties": {
              "commonSideEffects": { "type": "array", "items": { "type": "string" } },
              "cautions": { "type": "array", "items": { "type": "string" } },
              "unknowns": { "type": "string" }
            }
          },
          "mechanismSimple": { "type": "string" },
          "mechanismDetailed": { "type": "string" },
          "evidenceSnapshot": {
            "type": "object",
            "required": [
              "humanClinical",
              "animalPreclinical",
              "mechanisticRationale",
              "overallConfidence"
            ],
            "properties": {
              "humanClinical": { "type": "string" },
              "animalPreclinical": { "type": "string" },
              "mechanisticRationale": { "type": "string" },
              "overallConfidence": { "type": "integer", "minimum": 0, "maximum": 100 }
            }
          },
          "formsAndAdministration": { "type": "string" },
          "references": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Reference" }
          },
          "relatedPeptideSlugs": { "type": "array", "items": { "type": "string" } },
          "compareSlugs": { "type": "array", "items": { "type": "string" } },
          "attributionUrl": {
            "type": "string",
            "format": "uri",
            "description": "Canonical URL on peptidelist.org for this peptide. Use this as the link target when republishing data sourced from the API.",
            "example": "https://peptidelist.org/peptides/bpc-157"
          },
          "historyAndDiscovery": { "type": "string" },
          "dosing": {
            "type": "object",
            "required": ["typicalRange", "frequency", "notes"],
            "properties": {
              "typicalRange": { "type": "string" },
              "frequency": { "type": "string" },
              "cycleLength": { "type": "string" },
              "notes": { "type": "string" },
              "disclaimer": { "type": "string" },
              "timing": {
                "type": "object",
                "properties": {
                  "timeOfDay": { "type": "string" },
                  "relativeToMeals": { "type": "string" },
                  "relativeToExercise": { "type": "string" },
                  "notes": { "type": "string" }
                }
              }
            }
          },
          "timelineOfEffects": {
            "type": "object",
            "required": ["onset", "peak", "afterDiscontinuation"],
            "properties": {
              "onset": { "type": "string" },
              "peak": { "type": "string" },
              "afterDiscontinuation": { "type": "string" }
            }
          },
          "legalStatus": {
            "type": "object",
            "required": ["us"],
            "properties": {
              "us": { "type": "string" },
              "international": { "type": "string" },
              "sports": { "type": "string" }
            }
          },
          "contraindications": { "type": "array", "items": { "type": "string" } },
          "drugInteractions": { "type": "string" },
          "researchGaps": { "type": "array", "items": { "type": "string" } },
          "myths": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["myth", "reality"],
              "properties": {
                "myth": { "type": "string" },
                "reality": { "type": "string" }
              }
            }
          },
          "monitoring": {
            "type": "object",
            "required": ["timing", "notes"],
            "properties": {
              "biomarkers": { "type": "array", "items": { "type": "string" } },
              "functionalTests": { "type": "array", "items": { "type": "string" } },
              "timing": { "type": "string" },
              "notes": { "type": "string" }
            }
          }
        }
      }
    }
  }
}