nexbid-dev Agent API

openapi: 3.2.0
info:
  title: Nexbid Agent API
  version: 1.0.0
  description: HTTP surface for LLM agents that do not speak MCP. Complements the MCP server at mcp.nexbid.dev.
  contact:
    name: Nexbid
    url: https://nexbid.dev/support
    email: welcome@digital-opua.ch
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://nexbid.dev
  description: Production
tags:
- name: Agent
  description: LLM-facing HTTP surface.
paths:
  /agent/snippet/{id}:
    get:
      operationId: getAgentSnippet
      summary: Fetch an enriched snippet (billable)
      description: Returns Schema.org-shaped JSON for a brand_content item. Writes a billable enriched_snippet_impressions row. Unverified agents are capped at tier=basic; verified agents get the full tier ladder based on the content declaration.
      tags:
      - Agent
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: brand_content.id
      - name: x-nexbid-agent
        in: header
        required: false
        schema:
          type: string
        description: Explicit agent slug hint, overrides UA detection. Must match a catalog entry.
      - name: x-nexbid-session-hint
        in: header
        required: false
        schema:
          type: string
        description: Opaque per-conversation token the agent controls. Used in frequency-cap bucketing so the same cap applies across all turns of one conversation.
      responses:
        '200':
          description: Snippet returned; impression billed.
          headers:
            x-nexbid-agent-detected:
              schema:
                type: string
              description: Catalog slug or "unknown".
            x-nexbid-agent-verified:
              schema:
                type: string
                enum:
                - 'true'
                - 'false'
              description: DNS-verified (reverse + forward) or not.
            x-nexbid-snippet-tier:
              schema:
                type: string
                enum:
                - basic
                - standard
                - rich
                - premium
            x-nexbid-snippet-fee-cents:
              schema:
                type: integer
                minimum: 2
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSnippet'
        '204':
          description: Frequency cap reached for this agent/session — no billing write. See x-nexbid-frequency-cap header for current/max.
        '404':
          description: Content not found.
        '410':
          description: Content not publicly available (draft/rejected).
  /agent/match:
    get:
      operationId: matchAgent
      summary: Natural-language intent match (free)
      description: Returns a ranked list of snippet_url + projected_tier + projected_fee_cents so the agent can decide whether to fetch. Matches themselves are free; billing happens when the agent follows up with /agent/snippet/:id.
      tags:
      - Agent
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          maxLength: 500
        description: Natural-language search query.
      - name: geo
        in: query
        required: false
        schema:
          type: string
          default: CH
        description: ISO-3166-1 alpha-2 country code.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 5
          minimum: 1
          maximum: 20
      responses:
        '200':
          description: Ranked matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResponse'
        '400':
          description: Missing or overlong q.
        '429':
          description: Rate limit exceeded (60 req/min per slug or IP).
  /agent/track:
    post:
      operationId: trackBeacon
      summary: Impression beacon (P1 stub)
      description: Placeholder for CDN-cached snippet responses. Returns {ok:true, mode:"stub"} in P0 — no billing write. Wire up now so the contract is stable when CDN caching lands.
      tags:
      - Agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                snippet_id:
                  type: string
                  format: uuid
                agent_slug:
                  type: string
              required:
              - snippet_id
      responses:
        '200':
          description: Beacon acknowledged.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  mode:
                    type: string
components:
  schemas:
    MatchResult:
      type: object
      properties:
        content_id:
          type: string
          format: uuid
        content_type:
          type: string
        snippet_url:
          type: string
          format: uri
        canonical_url:
          type: string
          format: uri
        cite_as:
          type: string
        title:
          type: string
        brand:
          type: string
          nullable: true
        projected_tier:
          type: string
        projected_fee_cents:
          type: integer
    MatchResponse:
      type: object
      properties:
        query:
          type: string
        geo:
          type: string
        agent:
          type: object
          properties:
            slug:
              type: string
              nullable: true
            provider:
              type: string
              nullable: true
            verified:
              type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/MatchResult'
        disclosure:
          type: string
    AgentSnippet:
      type: object
      properties:
        '@context':
          type: string
        '@type':
          type: string
          enum:
          - Product
        '@id':
          type: string
          format: uri
        name:
          type: string
        description:
          type: string
        brand:
          type: object
          properties:
            '@type':
              type: string
            name:
              type: string
        url:
          type: string
          format: uri
        image:
          type: string
          format: uri
        offers:
          type: object
          properties:
            '@type':
              type: string
            price:
              type: string
            priceCurrency:
              type: string
            availability:
              type: string
        citation:
          type: object
          properties:
            cite_as:
              type: string
            canonical_url:
              type: string
              format: uri
          required:
          - cite_as
          - canonical_url
        nexbid:
          type: object
          properties:
            snippet_id:
              type: string
              format: uuid
            tier:
              type: string
            content_type:
              type: string
      required:
      - '@context'
      - '@type'
      - '@id'
      - name
      - nexbid