REST API
A smaller, deliberately chosen surface.
Not everything the app can do — create a job, read its state, fetch assets, schedule a post, read usage. Every published endpoint is a promise (docs/23 §1).
Authentication
API keys, scoped to one workspace — never a session cookie, never a password. A key is shown once at creation and stored hashed; a leaked key is identifiable by its tonta_sk_live_/tonta_sk_test_ prefix and last-four suffix in the dashboard. Two active keys are allowed per workspace so you can rotate without downtime.
Idempotency
An Idempotency-Key header is required on every POST that spends money. The first response is replayed for 24 hours — retry safely, never double-charged.
Webhooks
Polling a job for twenty minutes is a bad integration, so Tonta pushes. Events include job.completed, job.failed, job.needs_review, job.awaiting_input, piece.ready, post.published, post.failed, connection.reauth_required, credit.low, credit.exhausted and subscription.updated.
- · Signed: Tonta-Signature: t=<unix>,v1=<hmac-sha256 of "t.body"> with a 5-minute tolerance.
- · At least once — deliveries can repeat or arrive out of order; the event id is the dedupe key.
- · Retried on any non-2xx: 8 attempts with backoff over roughly 24 hours, then the endpoint is marked failing.
- · Every attempt is visible in the dashboard for 30 days, with a manual replay button.
Rate limits
Per plan: Pro gets 60 requests/minute and 10 jobs/hour; Studio gets 300 requests/minute and 60 jobs/hour. Lower tiers have no API access. A 429 carries Retry-After and X-RateLimit-* headers.
The published surface (v1)
| POST | /api/v1/jobs | Create a job | jobs:write |
| GET | /api/v1/jobs/:id | State, cost, progress | jobs:read |
| GET | /api/v1/jobs | List, filterable | jobs:read |
| POST | /api/v1/jobs/:id/cancel | Cancel | jobs:write |
| POST | /api/v1/jobs/estimate | Price without committing | — |
| GET | /api/v1/capabilities | Presets this plan may use | — |
| GET | /api/v1/content/:id | A finished piece and its variants | assets:read |
| GET | /api/v1/assets/:id/url | Short-lived signed URL | assets:read |
| POST | /api/v1/schedule | Schedule a piece | schedule:write |
| GET | /api/v1/schedule | Upcoming and past posts | schedule:read |
| DELETE | /api/v1/schedule/:id | Cancel | schedule:write |
| GET | /api/v1/usage | Credits by day, job and service | usage:read |
| GET | /api/v1/balance | Balance, held, next expiry | usage:read |
| POST | /api/v1/webhooks | Register an endpoint | — |
| GET | /api/v1/webhooks | List | — |
| DELETE | /api/v1/webhooks/:id | Remove | — |
| POST | /api/v1/webhooks/:id/test | Send a test delivery | — |
An OpenAPI document generated from the same schemas the handlers use is planned but not yet served publicly — check the changelog for when it lands.
Get an API key
Available on Pro and Studio. Create and rotate keys from Settings → API keys once you're signed in.
Manage API keys