Using the Tap API

Overview#

The Tap API is the public REST gateway to every supplier, platform, and plan on Tap. Use it to search inventory, generate plans, and manage campaigns programmatically — from your own backend, an internal tool, or the Tap CLI.

If your use case is AI-assistant-driven (an LLM that reasons over Tap data and calls tools), use the Tap MCP server instead — same auth, same data, MCP transport.

Base URL#

Related endpoints under the same auth:

• https://mcp.tap.co — MCP server (for Claude Desktop and other MCP clients)
• https://adcp.tap.co — ADCP gateway (Prebid.org Ad Context Protocol)

Authentication#

Every request requires Bearer authentication:

Get an API key from Profile → API Keys in the Tap dashboard, or request access if you don't have an account yet. Requests without a valid key get 401 Unauthorized.

Core endpoints#

Discovery#

Planning#

Campaigns#

Example request#

Search for TV inventory in a specific market:

curl -X POST "https://sdk.tap.co/v1/platforms/search" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "market": "Phoenix",
    "format": "tv",
    "audience": "adults_25_54",
    "budget": 30000
  }'

Response:

{
  "platforms": [
    {
      "id": "plat_kpho",
      "name": "KPHO Phoenix",
      "type": "tv",
      "market": "Phoenix",
      "reach": 850000,
      "cpm": 18.50
    }
  ],
  "total": 12
}

Generating a plan#

curl -X POST "https://sdk.tap.co/v1/plans/generate" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "brand awareness for a new product launch",
    "budget": 50000,
    "audience": "women_25_54",
    "markets": ["Los Angeles", "San Francisco"]
  }'

Response includes the generated plan with platforms, allocation, and projected reach.

Tap CLI#

If you'd rather not write code, the Tap CLI wraps the API:

npm install -g @tap/cli
tap auth login
tap platforms search --market "Phoenix" --format tv
tap plans generate --budget 50000 --audience "women_25_54" --markets "Los Angeles,San Francisco"

By default the CLI talks to https://sdk.tap.co/v1. Override with TAP_API_URL if you need to point at a different environment.

Error handling#

Standard HTTP status codes:

Error response shape:

{
  "error": "Unauthorized",
  "message": "Invalid API key. Please provide a valid API key using Bearer authentication.",
  "code": "INVALID_API_KEY"
}

Best practices#

1. Always check the status code before parsing the response body
2. Log full error responses for debugging
3. Retry on 5xx with exponential backoff (max ~3 attempts)
4. Don't retry on 4xx — fix the request and resend
5. Use environment variables for API keys — never hardcode
6. Cache discovery results — platform/inventory data changes infrequently; 15–30 minute TTLs are reasonable

Rate limiting#

The API is rate-limited per API key. If you hit the limit you'll get 429 Too Many Requests. Slow your request rate or contact support about higher limits for your use case.

Documentation#

The full reference and request/response schemas live at docs.tap.co.