API
Terrads API documentation
Everything the app can do with an ad run, over HTTPS with an API key. Base URL https://terrads.com/api/v1. Machine-readable: an OpenAPI 3.1 document at /api/v1/openapi.json, and every page here as plain markdown under /md/docs.
- 01Updated September 10, 2026
Quickstart
Mint an API key, create an ad run, poll it until it finishes, and download the results — the whole loop in five requests from the command line.
Read it →
- 02Updated September 10, 2026
Authentication
How API keys work: bearer tokens, where to create and revoke them, what makes a key stop working, and which plan-level refusals a request can meet.
Read it →
- 03Updated September 10, 2026
Runs and the interactive loop
How a run moves from queued to completed, how to read its events, and how to answer the two points where a run can pause and wait for you: questions and copy review.
Read it →
- 04Updated September 10, 2026
Idempotency
Why every POST /runs needs an Idempotency-Key, what the API answers when a key is seen again, and how to build a retry loop that can never charge you twice.
Read it →
- 05Updated September 10, 2026
Endpoint reference
Every route under /api/v1 with its scope, rate-limit tier, parameters, request body and response fields — runs, the three gates, results, and the five catalog endpoints.
Read it →
- 06Updated September 10, 2026
Errors
The one error envelope every endpoint uses, the full list of error codes with their HTTP status, and what to do about each — which are yours to fix, which to wait on, and which to retry.
Read it →
- 07Updated September 10, 2026
Rate limits
Per-key and per-team request limits by endpoint tier, the headers that report your remaining budget, and the fair-use caps that answer 429 for reasons other than request rate.
Read it →
- 08Updated September 12, 2026
MCP server
Use the API from any MCP client: the endpoint URL, how a key authenticates a session, the twelve tools and what each returns, and how a run's questions are answered.
Read it →