{"openapi":"3.1.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"}],"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"}}}}}}}}},"/.well-known/mcp.json":{"get":{"operationId":"getMcpDiscovery","summary":"MCP server discovery manifest","tags":["Discovery"],"responses":{"200":{"description":"MCP tool list + transport.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-card.json":{"get":{"operationId":"getAgentCard","summary":"A2A agent card","tags":["Discovery"],"responses":{"200":{"description":"Agent capabilities + skills.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agents.json":{"get":{"operationId":"getAgentsManifest","summary":"Agent-Commerce-Kit agents.json","tags":["Discovery"],"responses":{"200":{"description":"Participant + services + capabilities.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"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"]},"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"}}},"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"}}}}},"tags":[{"name":"Agent","description":"LLM-facing HTTP surface."},{"name":"Discovery","description":"Well-known capability manifests."}]}