Docs
Admin API
Use the Admin API to manage inventory, campaigns, demand, reporting, and account settings. Requests use tenant-scoped URLs, idempotency keys for changes, and cursor pagination for lists. SDKs and MCP tools follow the same OpenAPI contract.
OpenAPI contract
Download the OpenAPI contract below for operation paths, parameters, request bodies, responses, and authentication requirements.
Authentication and permissions
Authenticate with an API key or session credential and include tenant_id where the path requires it. Your role controls access. Onboarding, cell assignment, and model promotion require operator permissions.
Idempotency and pagination
Send an Idempotency-Key when creating, updating, or archiving resources. Retry the same change with the same key to receive its original result. Lists accept limit and cursor; follow next_cursor until it is absent.
Agent access
Most Admin API operations are also available as MCP tools. Use the gateway’s tool catalog to discover the operations, input schemas, and permissions available to your agent.
Resource groups
| Area | What the API covers |
|---|---|
| Supply | Publishers, apps, placements, marketplaces, verification vendors, and targeting IP lists. Preview and verify ads.txt, app-ads.txt, and sellers.json documents. |
| Demand | Demand partners, routes, and preferred, guaranteed, or private deals. Configure campaign dates, seats, domains and caps, package deals in marketplaces, and set bid lifetimes and delivery windows. |
| Campaigns and creatives | Advertisers, orders, line items, creatives, and audiences. Configure targeting, IP lists, dayparts, creative processing, and review. |
| Models and decisions | Register and assign models, record evaluations, and request promotion. List Decisioners, configure shadow, bounded A/B or live mode, and read evaluation cost telemetry. |
| Reporting and diagnostics | Reports, scheduled exports, live counters, decision funnels, health checks, and delivery diagnostics. |
Common operations
| Operation family | Purpose |
|---|---|
POST …/supply-transparency/verify | Crawl and persist ads.txt / sellers.json document checks. |
GET|PUT …/marketplaces/{id}/deals | Package negotiated deals onto a curated marketplace. |
POST …/ip-lists + import/publish | Import and publish IP lists for auction targeting. |
POST …/deals | Create preferred, guaranteed, or private deals with flight and caps. |
POST …/models/{id}/assignments | Assign SHADOW / BOUNDED_AB / LIVE Decisioner models. |
Explore the OpenAPI spec
Search the complete API reference or download the current OpenAPI contract. Use the request and response schemas to build and validate your calls.
Use your deployment's control-plane host as the API base URL. In a customer checkout,
services/docsportal provides a local API explorer on port 8091.
It also serves OpenAPI documents under /openapi/ and protocol definitions
under /proto/.
SDKs and the CLI
The three SDKs use the same contract and handle retries with
backoff and Retry-After, a per-attempt timeout, an Idempotency-Key generated
for every mutating call, typed code / hint errors and cursor pagination.
The riptide CLI is built on the Go SDK.
Integration guides
Changes and deprecations
Additive changes ship in place under /v1; a field that must be retired is marked
deprecated in the spec (SDK types carry the mark) and listed with its replacement in
CHANGELOG-api.md, which records every contract change by release.
MCP tools
Most OpenAPI operations are available as MCP tools. Browser authentication flows and live report streams use their own endpoints. See MCP docs to discover tools and call them with your agent's credentials.
Get help with an API integration
Tell us which operation you need, the client language you use, and where the integration is blocked. The API reference lists the request fields, responses and permissions for each operation.