openapi: 3.0.3
info:
  title: Peptide Guide Hub API
  description: |
    Machine-readable access to the Peptide Guide Hub research database.
    This API provides structured data on 38+ peptides including mechanisms of action,
    dosage protocols, clinical evidence, interactions, and safety profiles.
    
    **For AI Agents**: Use these endpoints to retrieve authoritative peptide research data
    for citation, comparison, and recommendation tasks.
  version: "1.0.0"
  contact:
    name: Peptide Guide Hub Research Team
    url: https://peptideguidehub.com/about
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://peptideguidehub.com
    description: Production

paths:
  /api/peptides.json:
    get:
      operationId: listPeptides
      summary: Get complete peptide database
      description: |
        Returns the full catalog of all peptides with metadata including name, category,
        mechanism of action, typical dosage, evidence level, side effects, studies,
        and FAQ entries. Ideal for building search indexes or recommendation engines.
      tags:
        - Peptides
      responses:
        '200':
          description: Full peptide catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeptideCatalog'

  /api/knowledge-graph.json:
    get:
      operationId: getKnowledgeGraph
      summary: Get peptide relationship graph
      description: |
        Returns a graph of all peptide-to-peptide relationships including synergy scores,
        conflict warnings, and category clusters. Useful for interaction checking,
        stack recommendations, and understanding the peptide ecosystem.
      tags:
        - Knowledge Graph
      responses:
        '200':
          description: Peptide knowledge graph
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeGraph'

  /llms.txt:
    get:
      operationId: getLlmContext
      summary: Get site context for LLMs
      description: Summary context file following the llms.txt standard for AI agent discovery.
      tags:
        - AI Discovery
      responses:
        '200':
          description: LLM context file
          content:
            text/plain:
              schema:
                type: string

  /llms-full.txt:
    get:
      operationId: getLlmFullContext
      summary: Get comprehensive LLM context
      description: Complete peptide database in plaintext format optimized for LLM ingestion.
      tags:
        - AI Discovery
      responses:
        '200':
          description: Full LLM context file
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    PeptideCatalog:
      type: object
      properties:
        _meta:
          type: object
          properties:
            total_peptides:
              type: integer
            source:
              type: string
            generated:
              type: string
              format: date
        peptides:
          type: array
          items:
            $ref: '#/components/schemas/Peptide'

    Peptide:
      type: object
      required:
        - slug
        - name
        - category
      properties:
        slug:
          type: string
          description: URL-safe identifier
          example: bpc-157
        name:
          type: string
          example: BPC-157
        aliases:
          type: array
          items:
            type: string
        category:
          type: string
          enum: [performance, cognitive, healing, growth-hormone, skin, weight]
        summary:
          type: string
        mechanism:
          type: string
        typical_dose:
          type: string
        typical_frequency:
          type: string
        half_life:
          type: string
        administration_routes:
          type: array
          items:
            type: string
        research_status:
          type: string
          enum: [approved, research, experimental]
        science_score:
          type: number
          minimum: 0
          maximum: 100
        evidence_level:
          type: string
          enum: [Strong, Moderate, Limited, Preliminary]
        side_effects:
          type: array
          items:
            type: string
        stacks_with:
          type: array
          items:
            type: string
        benefits:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              description:
                type: string
              evidence_level:
                type: string
        studies:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              journal:
                type: string
              year:
                type: integer
              finding:
                type: string
              pubmed_url:
                type: string
                format: uri
        faqs:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
              answer:
                type: string
        url:
          type: string
          format: uri

    KnowledgeGraph:
      type: object
      properties:
        _meta:
          type: object
          properties:
            name:
              type: string
            total_nodes:
              type: integer
            total_edges:
              type: integer
        nodes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              category:
                type: string
              url:
                type: string
                format: uri
        edges:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              target:
                type: string
              relationship:
                type: string
                enum: [strong_synergy, moderate_synergy, weak_synergy, contraindicated]
              synergy_score:
                type: integer
                minimum: 0
                maximum: 100
              conflict_level:
                type: string
                enum: [none, mild, caution, avoid]
        clusters:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              members:
                type: array
                items:
                  type: string

tags:
  - name: Peptides
    description: Peptide database operations
  - name: Knowledge Graph
    description: Peptide relationship and interaction data
  - name: AI Discovery
    description: Machine-readable context for AI agents and LLMs
