Docs
Publisher API
Use the Publisher API to view your placements, run and schedule reports, and download payout statements. Your credential is limited to your publisher. Calls use /v1/tenants/{tenant_id}/publishers/{publisher_id}/… paths, with a few shared lookup endpoints listed below.
Publisher API key
Your tenant admin creates a key with role publisher bound to your publisher_id (POST …/api-keys). Send it as X-Riptide-Api-Key. The secret is shown once; the tenant can revoke it at any time.
Console session
An invite with role publisher binds your console user to one publisher. The portal's dashboard, reports, scheduled reports and finance pages show that publisher's records.
Publisher scope
Reports automatically filter to your publisher. A filter naming another publisher returns BAD_INPUT. Requests for another publisher or restricted tenant resources return FORBIDDEN.
Administrative changes
Ask your tenant's trafficking or finance team to edit placements or close payout periods. Publisher credentials cannot access other publishers or tenant-wide resource lists.
Operations
| Operation | Purpose |
|---|---|
GET …/publishers/{id}/placements | Placements owned by your publisher (Placement.publisher_id). |
GET …/publishers/{id}/report-summary?days=7 | Requests, impressions, fills, net revenue, and payout for the trailing period. When executed=false, reporting storage is unavailable; zero counts do not represent measured activity. |
POST …/publishers/{id}/reports/run | Same ReportRunRequest shape as the tenant endpoint; the publisher filter is injected server-side. Use dimensions such as placement, country, hour_of_day. |
GET|POST …/publishers/{id}/report-configs | Save report definitions scoped to your publisher. |
GET|POST …/publishers/{id}/scheduled-reports | Hourly / daily / weekly HMAC-signed deliveries of a saved report to your HTTPS endpoint; the signing secret is returned once. |
GET …/publishers/{id}/payout-statements[/{sid}[/csv]] | Per-period statements: impressions, gross revenue, publisher share, adjustments, total due, status (DRAFT / ISSUED / PAID), provider reference; CSV download. |
GET /v1/tenants/{id}/reports/catalog · GET /v1/platforms | Shared reporting definitions and platform information available to publisher credentials. |
Worked example
Use a placement report to compare which ad positions delivered impressions and contributed
to your payout. This example runs a report for a fixed week, saves the report definition,
then schedules daily delivery to an HTTPS endpoint. Replace the sample dates, destination,
TENANT and PUB with your reporting period and account details.
curl -sS -X POST https://console.example/v1/tenants/TENANT/publishers/PUB/reports/run \
-H "X-Riptide-Api-Key: rt_key_…" -H "Content-Type: application/json" \
-d '{"metrics":["impressions","publisher_payout"],"dimensions":["placement"],
"from":"2026-08-25T00:00:00Z","to":"2026-09-01T00:00:00Z","grain":"day"}'
curl -sS -X POST https://console.example/v1/tenants/TENANT/publishers/PUB/report-configs \
-H "X-Riptide-Api-Key: rt_key_…" -H "Idempotency-Key: rc-weekly-1" -H "Content-Type: application/json" \
-d '{"name":"weekly payout","metrics":["impressions","publisher_payout"],"dimensions":["placement"],"grain":"day"}'
curl -sS -X POST https://console.example/v1/tenants/TENANT/publishers/PUB/scheduled-reports \
-H "X-Riptide-Api-Key: rt_key_…" -H "Idempotency-Key: sr-weekly-1" -H "Content-Type: application/json" \
-d '{"report_config_id":"…","cadence":"daily","destination_url":"https://hooks.example/riptide"}'
Represent money as decimal strings with four decimal places. Every mutation
needs an Idempotency-Key; replays return the original result. Pagination is
limit + opaque cursor. The full contract, including the
PublisherReportSummary and PublisherPayoutStatement schemas, is in
the API reference; see the Admin API docs for
auth, errors and SDKs.
Get a publisher credential
Ask your tenant administrator for a publisher API key bound to your publisher ID, or an invitation to the publisher portal. Use the API guide to authenticate requests and the access guide to understand roles and key management.