agent-api-spec.yaml

openapi: "3.1.0"

info:
  title: Protocol Guide Agent API
  version: "1.0.0"
  description: |
    Agent-native API for Protocol Guide — EMS protocol search and retrieval.

    Designed for AI agent consumption: structured JSON responses, sub-50ms edge
    latency, edge caching, and a batch/multiplexer endpoint for parallel fan-out.

    ## Authentication
    All endpoints require an `X-Agent-Key` header with a valid API key.
    Keys are provisioned by the Protocol Guide team. Rate limit: 1000 req/day per key.

    ## Response Format
    All endpoints return a consistent envelope:
    ```json
    {
      "latency_ms": 23,
      "cache_hit": true,
      "result_count": 5,
      "data": { ... }
    }
    ```

    ## Batch / Multiplexer
    Use `POST /agent/batch` to fan out multiple queries in parallel. This is the
    recommended pattern for AI agents that need multiple lookups — all operations
    execute simultaneously with Promise.allSettled, returning in a single response.

    ## Caching
    - Search results: 1 hour TTL
    - Protocol content: 24 hours TTL
    - Drug info: 24 hours TTL
    - Batch responses: not cached (individual ops within batch are cached)

    ## Rate Limits
    - Default: 1000 requests/day per API key
    - Rate limit resets at 00:00 UTC daily
    - On limit exceeded: HTTP 429 with error message

  contact:
    name: The Fire Dev LLC
    url: https://thefiredev.com
  license:
    name: Proprietary
    url: https://protocolguide.app/terms

servers:
  - url: https://protocolguide-search.workers.dev
    description: Production (Cloudflare Workers)
  - url: http://localhost:8787
    description: Local dev (wrangler dev)

# ── Security ──────────────────────────────────────────────────────────────────

security:
  - AgentKeyAuth: []

components:
  securitySchemes:
    AgentKeyAuth:
      type: apiKey
      in: header
      name: X-Agent-Key
      description: |
        API key for agent access. Prefix: `pg_`.
        Example: `X-Agent-Key: pg_a3f7b2c1d4e5f6...`

  # ── Shared schemas ──────────────────────────────────────────────────────────

  schemas:

    # Envelope wrapping all responses
    AgentEnvelope:
      type: object
      required: [latency_ms, cache_hit, result_count, data]
      properties:
        latency_ms:
          type: integer
          description: Wall-clock latency for this request in milliseconds
          example: 23
        cache_hit:
          type: boolean
          description: Whether the response was served from edge cache
          example: true
        result_count:
          type: integer
          description: Number of results in the data payload
          example: 5
        data:
          description: Response payload (type varies by endpoint)

    # A single protocol result
    ProtocolResult:
      type: object
      properties:
        id:
          type: integer
          description: Internal chunk ID
        protocol_number:
          type: string
          nullable: true
          example: "12.1"
        protocol_title:
          type: string
          nullable: true
          example: "Cardiac Arrest — Adult"
        section:
          type: string
          nullable: true
          example: "3"
        agency_name:
          type: string
          nullable: true
          example: "Los Angeles County EMS"
        state_code:
          type: string
          nullable: true
          example: "CA"
        protocol_year:
          type: integer
          nullable: true
          example: 2024
        similarity_score:
          type: number
          format: float
          description: Cosine similarity score (0–1)
          example: 0.87
        has_images:
          type: boolean
          example: false
        source_pdf_url:
          type: string
          nullable: true
          format: uri
        content:
          type: string
          description: Full section content as plain text (agent-optimized, no truncation)

    # Full protocol detail
    ProtocolDetail:
      type: object
      properties:
        protocol_number:
          type: string
          nullable: true
        protocol_title:
          type: string
          nullable: true
        agency_name:
          type: string
          nullable: true
        state_code:
          type: string
          nullable: true
        protocol_year:
          type: integer
          nullable: true
        has_images:
          type: boolean
        source_pdf_url:
          type: string
          nullable: true
          format: uri
        section_count:
          type: integer
        sections:
          type: array
          items:
            type: object
            properties:
              section:
                type: string
              content:
                type: string
        content_markdown:
          type: string
          description: |
            All sections concatenated as structured markdown.
            Each section is wrapped in `### Section N\n\n<content>` blocks.
            Use this field for direct LLM context injection.

    # Drug search result
    DrugProtocol:
      type: object
      properties:
        protocol_number:
          type: string
          nullable: true
        protocol_title:
          type: string
          nullable: true
        agency_name:
          type: string
          nullable: true
        state_code:
          type: string
          nullable: true
        protocol_year:
          type: integer
          nullable: true
        similarity_score:
          type: number
          format: float
        source_pdf_url:
          type: string
          nullable: true
          format: uri
        drug_mentions:
          type: array
          items:
            type: string
          description: Sentences from the protocol that directly mention the drug
        section_content:
          type: string
          description: Full section content for context

    # Batch operation (input)
    BatchOperation:
      type: object
      required: [type, params]
      properties:
        type:
          type: string
          enum: [search, protocol, drug]
          description: Operation type — routes to the corresponding single endpoint
        params:
          type: object
          description: |
            Parameters for the operation. Must match the corresponding
            single-endpoint request body (minus the envelope).
          oneOf:
            - $ref: '#/components/schemas/SearchParams'
            - $ref: '#/components/schemas/ProtocolParams'
            - $ref: '#/components/schemas/DrugParams'

    SearchParams:
      type: object
      required: [query]
      properties:
        query:
          type: string
          maxLength: 500
        agencyId:
          type: integer
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 20
          default: 10

    ProtocolParams:
      type: object
      required: [protocolNumber]
      properties:
        protocolNumber:
          type: string
        agencyId:
          type: integer
          nullable: true

    DrugParams:
      type: object
      required: [drugName]
      properties:
        drugName:
          type: string
          maxLength: 200
        agencyId:
          type: integer
          nullable: true

    # Batch operation result (output)
    BatchOperationResult:
      type: object
      required: [index, success, latency_ms]
      properties:
        index:
          type: integer
          description: 0-based index matching the input queries array position
        success:
          type: boolean
        data:
          description: Operation result data (present on success)
        error:
          type: string
          description: Error message (present on failure)
        cache_hit:
          type: boolean
          description: Whether this individual operation was served from cache
        latency_ms:
          type: integer
          description: Time taken for this specific operation (parallel, not sequential)

    # Error response
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: "Invalid API key"

  # ── Response headers ─────────────────────────────────────────────────────────

  headers:
    X-Cache:
      description: Cache status for this response
      schema:
        type: string
        enum: [HIT, MISS]
    X-Cache-Key:
      description: SHA-256 hash of the cache key used
      schema:
        type: string
    X-Latency-Ms:
      description: Server-side processing time in milliseconds
      schema:
        type: integer
    X-Result-Count:
      description: Number of results returned
      schema:
        type: integer

# ── Paths ─────────────────────────────────────────────────────────────────────

paths:

  /agent/search:
    post:
      operationId: agentSearch
      summary: Semantic search over EMS protocols
      description: |
        Performs semantic vector search over EMS protocols using Gemini embeddings
        and Vectorize. Returns structured protocol results optimized for agent
        consumption — full content, no truncation, no HTML.

        Internally uses: query normalization → embedding → Vectorize → D1 → rerank.

        **Caching:** Results cached at edge for 1 hour per query+agencyId combination.
      tags: [Agent API]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchParams'
            examples:
              basic:
                summary: Simple query
                value:
                  query: "epinephrine cardiac arrest adult"
              with_agency:
                summary: Agency-scoped search
                value:
                  query: "SVT adenosine dose"
                  agencyId: 42
                  limit: 5
      responses:
        "200":
          description: Search results
          headers:
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Cache-Key:
              $ref: '#/components/headers/X-Cache-Key'
            X-Latency-Ms:
              $ref: '#/components/headers/X-Latency-Ms'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AgentEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          query:
                            type: string
                          normalized_query:
                            type: string
                            description: Query after EMS abbreviation expansion
                          total_found:
                            type: integer
                          results:
                            type: array
                            items:
                              $ref: '#/components/schemas/ProtocolResult'
              example:
                latency_ms: 45
                cache_hit: false
                result_count: 3
                data:
                  query: "epi cardiac arrest"
                  normalized_query: "epinephrine cardiac arrest"
                  total_found: 3
                  results:
                    - protocol_number: "12.1"
                      protocol_title: "Cardiac Arrest — Adult"
                      agency_name: "Los Angeles County EMS"
                      state_code: "CA"
                      similarity_score: 0.91
                      content: "Epinephrine 1mg IV/IO every 3-5 minutes..."
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "429":
          description: Rate limit exceeded (1000 req/day default)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agent/protocol:
    post:
      operationId: agentProtocol
      summary: Fetch full protocol content by protocol number
      description: |
        Returns the complete content of an EMS protocol as structured markdown.
        All sections are merged in order. Use `content_markdown` for direct LLM
        context injection.

        **Caching:** Cached at edge for 24 hours per protocolNumber+agencyId.
      tags: [Agent API]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtocolParams'
            examples:
              basic:
                value:
                  protocolNumber: "12.1"
              with_agency:
                value:
                  protocolNumber: "12.1"
                  agencyId: 42
      responses:
        "200":
          description: Full protocol content
          headers:
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Latency-Ms:
              $ref: '#/components/headers/X-Latency-Ms'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AgentEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ProtocolDetail'
        "400":
          description: Protocol not found or bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agent/drug:
    post:
      operationId: agentDrug
      summary: Fetch drug protocol info by drug name
      description: |
        Searches EMS protocols for mentions of a specific drug. Returns protocols
        that reference the drug, with the relevant sentences extracted for quick
        context injection.

        Useful for: "What dose of adenosine does [agency] use for SVT?"

        **Caching:** Cached at edge for 24 hours per drugName+agencyId.
      tags: [Agent API]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DrugParams'
            examples:
              epinephrine:
                value:
                  drugName: "epinephrine"
              adenosine_agency:
                value:
                  drugName: "adenosine"
                  agencyId: 42
      responses:
        "200":
          description: Drug protocol info
          headers:
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Latency-Ms:
              $ref: '#/components/headers/X-Latency-Ms'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AgentEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          drug_name:
                            type: string
                          protocols_found:
                            type: integer
                          protocols:
                            type: array
                            items:
                              $ref: '#/components/schemas/DrugProtocol'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agent/batch:
    post:
      operationId: agentBatch
      summary: Execute multiple queries in parallel (multiplexer)
      description: |
        The agent-native multiplexer endpoint. Accepts up to 50 operations and
        executes ALL of them simultaneously using Promise.allSettled.

        **This is the recommended pattern for AI agents** that need multiple
        lookups in one agent step. Instead of:
        ```
        result1 = await search(query1)   # 45ms
        result2 = await protocol(num1)   # 38ms
        result3 = await drug(drug1)      # 52ms
        # Total: 135ms sequential
        ```

        Use batch:
        ```
        results = await batch([search(q1), protocol(n1), drug(d1)])
        # Total: ~52ms (slowest op, parallel)
        ```

        **Timeouts:**
        - Per-operation: 5 seconds
        - Total batch: 10 seconds
        - Partial results returned if some operations fail or timeout

        **Caching:** Individual operations within the batch respect their own
        cache TTLs. The batch response itself is not cached.
      tags: [Agent API]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [queries]
              properties:
                queries:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    $ref: '#/components/schemas/BatchOperation'
            examples:
              parallel_lookup:
                summary: Search + protocol + drug in parallel
                value:
                  queries:
                    - type: search
                      params:
                        query: "cardiac arrest adult epinephrine"
                        agencyId: 42
                    - type: protocol
                      params:
                        protocolNumber: "12.1"
                        agencyId: 42
                    - type: drug
                      params:
                        drugName: "adenosine"
                        agencyId: 42
              bulk_search:
                summary: Multiple searches in parallel
                value:
                  queries:
                    - type: search
                      params:
                        query: "SVT treatment"
                    - type: search
                      params:
                        query: "ventricular fibrillation"
                    - type: search
                      params:
                        query: "stroke protocol"
                    - type: search
                      params:
                        query: "trauma hemorrhage control"
      responses:
        "200":
          description: Batch results — all operations, including partial failures
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AgentEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        required: [total, succeeded, failed, results, latency_ms]
                        properties:
                          latency_ms:
                            type: integer
                            description: Wall-clock batch latency (parallel, not sum of ops)
                          total:
                            type: integer
                          succeeded:
                            type: integer
                          failed:
                            type: integer
                          results:
                            type: array
                            items:
                              $ref: '#/components/schemas/BatchOperationResult'
              example:
                latency_ms: 52
                cache_hit: false
                result_count: 3
                data:
                  latency_ms: 52
                  total: 3
                  succeeded: 3
                  failed: 0
                  results:
                    - index: 0
                      success: true
                      cache_hit: false
                      latency_ms: 45
                      data:
                        query: "cardiac arrest adult epinephrine"
                        total_found: 4
                        results: []
                    - index: 1
                      success: true
                      cache_hit: true
                      latency_ms: 3
                      data:
                        protocol_number: "12.1"
                        protocol_title: "Cardiac Arrest — Adult"
                        content_markdown: "### Section 1\n\n..."
                    - index: 2
                      success: true
                      cache_hit: false
                      latency_ms: 52
                      data:
                        drug_name: "adenosine"
                        protocols_found: 2
                        protocols: []
        "400":
          description: Invalid batch payload or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

# ── Tags ──────────────────────────────────────────────────────────────────────

tags:
  - name: Agent API
    description: |
      Agent-native endpoints for AI agent consumption.
      Optimized for structured data access, sub-50ms edge latency,
      and parallel batch execution.

      **Key design decisions:**
      - No HTML, no pagination UI, no cursor tokens — agents prefer flat arrays
      - `content_markdown` fields are formatted for direct LLM context injection
      - Consistent envelope wraps all responses for predictable parsing
      - Batch endpoint eliminates sequential round-trips (the Amdahl's Law fix)

# ── External docs ─────────────────────────────────────────────────────────────

externalDocs:
  description: Protocol Guide Developer Docs
  url: https://protocolguide.app/docs/agent-api