Akteora for developers
These pages are the source of Akteora's developer documentation. They are written for someone outside the company: an agency building a Shopify section, a developer putting testimonials into a CMS, someone automating a weekly export. They will be published as the developer docs site.
Keep them true. When a route, a field or a guarantee changes, change its page in the same commit. A page that describes last month's API is worse than no page.
The API in one paragraph
Everything the Akteora dashboard does, it does through the public API, with the same requests
and the same responses any integration gets. There are no private endpoints (ADR 0003). The
API is described by an OpenAPI document (packages/contracts/openapi.json), and the typed
TypeScript client @akteora/sdk is generated from it.
Conventions
| Base URL | https://api.akteora.com/v1 |
| Authentication | An API key: Authorization: Bearer rk_live_…, with scopes. rk_test_… keys work on a separate test-mode sandbox. The examples write the key as $AKTEORA_API_KEY. See Authentication. |
| Bodies | JSON, with snake_case fields |
| IDs | Prefixed and opaque: sub_… a testimonial, brd_… a brand, lnk_… a collect link, ast_… a media file. Store them as strings. |
| Times | RFC 3339, UTC: 2026-09-13T10:00:00.000Z. Durations are milliseconds, in fields ending _ms. |
| Lists | { "data": [ … ], "next_cursor": "…" }. Ask for up to 100 with limit, and pass next_cursor back as cursor for the next page. null means there is no next page. |
| Errors | RFC 9457 application/problem+json, with type, title, status, detail and a request_id. Quote the request_id when you contact support. |
| Plan limits | 402 with type ending plan_limit_exceeded, and a limit member naming the limit, the plan's allowance, the plan that raises it, and an upgrade_url one click from the upgrade. See Plans and billing. |
Pages
Start here:
- Quickstart: from an API key to a testimonial read through the API, in about five minutes, in test mode.
- Authentication: API keys, scopes, the routes no key can reach, and test mode.
- Webhooks: events as they happen, signed; verifying the signature in Node.js, Python and PHP; retries, the delivery log and replay.
How the API behaves everywhere:
- Pagination: the list envelope and cursors.
- Idempotency: retrying a
POSTsafely withIdempotency-Key. - Errors: the problem document and every
type. - Rate limits: per key, per organisation, and the headers that say where you stand.
- Versioning and deprecation: what can change, what cannot, and six months'
notice with a
Sunsetheader. - Changelog: every change to the API.
- TypeScript SDK:
@akteora/sdk.
What the API does:
- Media: a testimonial's video, audio and poster. Permanent public links for websites and emails, short-lived links for your own screens, and downloads.
- Exports: testimonials in bulk, as CSV, JSON, MP4, MP3 or a ZIP bundle.
- Widget: one snippet that shows a brand's testimonials on any website, and the public document behind it.
- Public walls: a brand's public page on akteora.com, its address rules, and the unauthenticated routes it is rendered from.
- Reels: several testimonials cut into one captioned video in three sizes, how a span is chosen and checked, rendering, and the public link.
- Plans and billing: what each plan allows, the 402 a limit returns and how to act on it, usage against the plan, and paying through Paddle.
The API reference — every route, with a runnable example — is generated from the
OpenAPI document. These pages are published beside it at docs.akteora.com (apps/docs).
Writing these pages
- One job per page, opening with what the reader is trying to do.
- Examples first, reference after. Every example must work against the API as it is.
- Say what a field guarantees (how long a URL lives, when it changes, when it stops working), not only its type. The guarantees are what an integration is built on.
- Name things as the reader knows them: a testimonial, not a submission row; a public link, not an object key.