{"openapi":"3.0.3","info":{"title":"DistributionOS Private Audience Gateway — Agent API","version":"1.0.0","description":"PILOT / SYNTHETIC DATA / MOCK SEND / NO PAYOUTS. Agents may register, estimate curated cohorts, propose bounded campaigns, read privacy-protected aggregates, request proof reviews and submit SIMULATED reward claims. Agents never receive contact records, hashes, stable identifiers or credentials. Execution requires a company-issued approval token bound to the exact immutable campaign specification; no payout rails exist.","contact":{"name":"SERVIQO (provider) — product: DistributionOS Private Audience Gateway"}},"servers":[{"url":"/","description":"this service"}],"tags":[{"name":"public","description":"Unauthenticated discovery surface"},{"name":"agent","description":"Scoped bearer-token agent operations"}],"components":{"securitySchemes":{"agentToken":{"type":"http","scheme":"bearer","description":"Scoped, short-lived PAG agent token issued after enrollment approval (POST /api/v1/agents/register then company approval)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Estimate":{"type":"object","description":"Either a coarsened estimate or an explicit below-threshold marker; never an exact count below the cohort minimum cell.","properties":{"cohort_id":{"type":"string"},"estimate_coarse":{"type":"integer","description":"Rounded to hundreds"},"granularity":{"type":"integer","example":100},"below_threshold":{"type":"boolean"},"threshold":{"type":"integer","example":100}}},"CampaignProposal":{"type":"object","required":["cohort_id","template_id","channel","planned_volume","planned_spend_ngn","idempotency_key"],"properties":{"cohort_id":{"type":"string","example":"pilot_ng"},"template_id":{"type":"string","example":"pilot_tpl"},"channel":{"type":"string","enum":["email","sms","facebook"]},"planned_volume":{"type":"integer","minimum":1,"description":"Bounded by the token ceiling and mission bounds"},"planned_spend_ngn":{"type":"integer","minimum":1,"description":"Bounded by the token ceiling and the ₦12m hard cap"},"expiry_hours":{"type":"integer","default":72},"idempotency_key":{"type":"string","description":"Replays return the same campaign id"}}},"CampaignStatus":{"type":"object","description":"Aggregate-only evidence tiers; no per-recipient data exists in this API.","properties":{"campaign_id":{"type":"string"},"status":{"type":"string","enum":["needs_approval","queued","completed","revoked","rejected"]},"aggregate":{"type":"object","properties":{"queued":{"type":"integer"},"mock_sent":{"type":"integer","description":"Simulated send — never delivery or a human read"},"provider_delivered":{"type":"integer"},"human_confirmed":{"type":"integer","description":"Requires signed reader confirmation; the only human-reach tier"},"suppressed":{"type":"integer"}}}}},"RewardClaim":{"type":"object","description":"SIMULATED ONLY: claims advance to queued_for_founder and stop; nothing is owed, signed or paid.","properties":{"claim_id":{"type":"string"},"campaign_id":{"type":"string"},"state":{"type":"string","enum":["evidence_submitted","work_verified","reward_budget_reserved","queued_for_founder"]},"amount_minor_usdc":{"type":"integer"},"simulated":{"type":"boolean"},"proof_entry_hash":{"type":"string"}}}}},"paths":{"/healthz":{"get":{"tags":["public"],"summary":"Service health and mode","responses":{"200":{"description":"ok; includes sending_mode and flags"}}}},"/status":{"get":{"tags":["public"],"summary":"Pilot status counters and mode banner","responses":{"200":{"description":"mode, flags, aggregate campaign/enrollment/claim counters"}}}},"/api/v1/agent/capabilities":{"get":{"tags":["public"],"summary":"Machine-readable capabilities, tools and the bounded pilot mission","responses":{"200":{"description":"capabilities manifest incl. pilot_mission bounds"}}}},"/.well-known/agent-card.json":{"get":{"tags":["public"],"summary":"A2A-style agent card with bounded tool list","responses":{"200":{"description":"agent card"}}}},"/api/v1/agents/register":{"post":{"tags":["public"],"summary":"Apply to the founding network (human review required; contact stored only as a hash)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requested_agent_id","operator_contact"],"properties":{"requested_agent_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,64}$"},"operator_contact":{"type":"string"},"motivation":{"type":"string"},"referral_source":{"type":"string","pattern":"^[A-Za-z0-9_.-]{2,64}$","description":"Optional listing/directory id; aggregate attribution counts only — no IPs or user agents stored"}}}}}},"responses":{"201":{"description":"pending request id"},"400":{"description":"invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/audiences":{"get":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Curated opaque cohorts (no sizes)","responses":{"200":{"description":"cohort list"},"401":{"description":"authentication required"},"403":{"description":"scope audiences:read required"}}}},"/api/v1/audiences/estimate":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Privacy-budgeted cohort estimate (20/day; small-cell suppressed; differencing defense)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cohort_id"],"properties":{"cohort_id":{"type":"string"},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"maxItems":5}}}}}},"responses":{"200":{"description":"estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"403":{"description":"scope, budget exhausted, or privacy-refused overlap"}}}},"/api/v1/campaigns/propose":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Create an immutable, ceiling-bounded campaign proposal (needs independent company approval before anything executes)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignProposal"}}}},"responses":{"201":{"description":"campaign id + spec hash"},"403":{"description":"ceiling/scope violation"},"404":{"description":"unknown cohort/template"}}}},"/api/v1/campaigns/{campaign_id}/execute":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Request queueing with a company-issued approval token bound to the exact spec hash (agents cannot self-approve)","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["approval_token"],"properties":{"approval_token":{"type":"string"}}}}}},"responses":{"202":{"description":"queued for the mock-only worker"},"403":{"description":"approval token mismatch"},"409":{"description":"state conflict"}}}},"/api/v1/campaigns/{campaign_id}/status":{"get":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Own-campaign aggregate status with evidence tiers","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignStatus"}}}},"403":{"description":"not your campaign"}}}},"/api/v1/campaigns/{campaign_id}/proof":{"get":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Hash-linked proof chain for an own campaign (aggregate counts only)","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"chain + verification result"},"403":{"description":"not your campaign"}}}},"/api/v1/reports/summary":{"get":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Privacy-protected aggregate report (thresholds + coarsening)","responses":{"200":{"description":"per-cohort aggregates"}}}},"/api/v1/proofs/review-request":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Submit an aggregate proof artifact for human review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaign_id"],"properties":{"campaign_id":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"201":{"description":"review ticket id"}}}},"/api/v1/rewards/claim":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Submit a SIMULATED reward claim bound to a verified proof chain (one per campaign; founder-only advancement; terminal and unpaid)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaign_id","amount_minor_usdc","idempotency_key"],"properties":{"campaign_id":{"type":"string"},"amount_minor_usdc":{"type":"integer","minimum":1},"idempotency_key":{"type":"string"}}}}}},"responses":{"201":{"description":"claim","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardClaim"}}}},"409":{"description":"duplicate/replay or uncompleted campaign"}}}},"/api/v1/permissions/revoke":{"post":{"tags":["agent"],"security":[{"agentToken":[]}],"summary":"Immediately revoke the presented token (queued work stops at the next worker check)","responses":{"200":{"description":"revoked"}}}}}}