Partner API Quickstart

The Partner API (/v1/partner) lets publishers manage screens and lets buyers optimize AI creatives against measured attention and dwell on paid plays. Use the same account for inventory, native creative review, serving, webhooks and reporting.

Base URL: https://api.trillboards.com

1. Get an API key

Register a new partner via POST /v1/partner/register (self-service, rate-limited to 5 req/hr per IP) or upgrade an existing earner account via POST /v2/earner/upgrade-to-partner. Save the token — the raw key is shown once.

For a new organization, replace the company name, unique lowercase slug and contact email:


curl -sS -X POST https://api.trillboards.com/v1/partner/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Your Company","slug":"your-company-unique-slug","contact_email":"developer@your-company.example"}'

Save data.api_key securely as TRILLBOARDS_API_KEY in your server environment. Existing organizations use the upgrade or key-management flow above. Portal access instructions are returned in data.portal_access.

Newly minted partner keys always carry the tb_prt_ prefix. The older trb_partner_ prefix is still accepted on existing keys but is no longer issued, so a key you mint today will never look like it. Do not hard-code, pattern-match, or validate against any prefix: prefixes are presentation metadata only, and authorization is decided exclusively by the scopes attached to the key (services/platformApiAuthResolver.js).

All authenticated endpoints expect:


Authorization: Bearer tb_prt_xxxxxxxxxxxx

2. Make your first call

Verify auth and pull partner info:


curl -s "https://api.trillboards.com/v1/partner/info" \
  -H "Authorization: Bearer tb_prt_xxxxxxxxxxxx"

Success response:


{
  "success": true,
  "data": {
    "partner_id": "65f1c...",
    "name": "Acme Vending",
    "tier": "standard",
    "device_count": 42,
    "created_at": "2026-01-15T09:30:00Z"
  }
}

3. Handle errors

Every 4xx/5xx follows the canonical envelope and echoes a request ID you can share with support:


{
  "error": {
    "type": "invalid_request_error",
    "code": "screen_not_found",
    "message": "Screen not found or access denied",
    "param": "screen_id",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#screen_not_found",
    "help": {
      "summary": "Screen IDs are prefixed 'scr_'. List your screens at GET /v1/partner/devices.",
      "portal_url": "https://trillboards.com/earner/screens"
    }
  }
}

4. Common error codes

All codes below come from utils/partnerApiErrors.ts (see the error reference for the full catalog):

invalid_api_key_format is defined in the error catalog but no auth path ever emits it — the

server performs no prefix or format validation. A malformed or unknown token returns invalid_api_key.

`error.code`	HTTP	When you see it
`authentication_required`	401	No `Authorization` header. Add `Bearer tb_prt_...`.
`invalid_api_key`	401	Token does not resolve to an active partner — rotate via `POST /v1/partner/api-key/rotate`.
`partner_inactive`	403	Account suspended. Contact support.
`screen_not_found`	404	`error.param` identifies the bad ID. Fetch the list from the portal or the devices endpoint.
`rate_limit_exceeded`	429	Honor the `Retry-After` header. The enforced authenticated cap is 1000 req/min per API key, flat across every data-access tier.
`tier_insufficient`	403	Endpoint requires a higher data-access tier; `error.help.current_tier` and `required_tier` tell you exactly what to upgrade to.

5. Next common operations

List devices: GET /v1/partner/devices
Register a device: POST /v1/partner/device with { "name": "...", "venue_type": "..." }
Record an impression batch: POST /v1/partner/impressions/batch (for offline-sync SDKs)
Create a webhook: POST /v1/partner/webhooks with { "url", "events" } — payloads are HMAC-signed
Get screen earnings: GET /v1/partner/connect/earnings?range=7d

6. Optimize AI creatives on real screens

Follow the Creative AI Feedback Loop to fund inventory, generate or import images, review and serve variants, and use measured attention and dwell to iterate your model through REST, MCP or the TypeScript SDK.

Install @trillboards/api-client@3.2.1 for typed funding, native MCP buying, creative experiments, historical queries and the live audience tail. The walkthrough includes stable purchase keys, Stripe balance readback and correction-aware reward scans. Purchased HUD packages run locally without company credentials and then use this same account for paid live delivery.

Next steps

Full reference: /docs/partner
Error catalog: /docs/errors
Partner API client: npm install @trillboards/api-client
Screen playback SDK: npm install @trillboards/ads-sdk