Agent Quickstart

This page is a single, linear runbook for an autonomous agent (or the code orchestrating one) to drive the Prezent Platform API end to end:

1. Discover the surface area.
2. Authenticate with a Bearer token.
3. Start an async job.
4. Track it to a terminal state (poll, stream, or webhook).
5. Handle success and failure.
6. Back off when rate-limited.

Everything here links back to the page that documents it in full. If you are wiring Prezent into an MCP-aware client (Claude, Cursor, Cline, Continue, Zed), you can skip the HTTP plumbing entirely — see Agents & MCP.

1. Discover

Two machine-readable entry points on the Prezent docs site describe the whole API (paths are relative to this documentation site's origin):

• /llms.txt — an llms.txt index: a short summary plus links to every documentation page and the OpenAPI spec. Start here to enumerate what exists.
• /openapi/openapi.yaml — the OpenAPI 3.1 contract. Every path, request body, response schema, and error code is defined here. Load it to generate a client or to validate requests before sending them.

A fuller, self-contained digest of the whole contract lives at /llms-full.txt.

The same contract is browsable interactively at the API Reference.

2. Authenticate

Every endpoint uses API key (Bearer) authentication. Send your key on every request:

Authorization: Bearer YOUR_API_KEY

API keys are issued by your Customer Success Manager (self-service key generation is not currently supported). See Getting Started → Authentication for key scoping, expiry, and the 401 codes you may see.

The canonical production host is https://api.prezent.ai.

3. Start an async job

Most useful operations are asynchronous. You POST to an entry endpoint and receive a callback_id in the success envelope:

curl -s -X POST https://api.prezent.ai/api/v1/autogenerator \
  -H "Authorization: Bearer $PREZENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A 5-slide deck on renewable energy" }'

{ "success": true, "data": { "callback_id": "cb_123" } }

Make the start idempotent (recommended)

Resource-creating writes (POST/PUT/PATCH) accept an optional Idempotency-Key request header so a retry after a network error does not create a duplicate job. Send a unique key (a UUID is ideal) per logical operation:

curl -s -X POST https://api.prezent.ai/api/v1/autogenerator \
  -H "Authorization: Bearer $PREZENT_API_KEY" \
  -H "Idempotency-Key: 8e6df756-18f6-4f16-8e12-7d7a5c5cb181" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A 5-slide deck on renewable energy" }'

A retry with the same key and an identical body returns the cached response verbatim with an Idempotency-Replayed: true header, so the job is never created twice. See Developer Guide → Idempotency for the cache window and the behaviour on body mismatch.

The Template Converter family follows the same shape: POST /api/v1/template-converter/start returns a callback_id. See the Template Converter API.

4. Track completion

Pick one of three mechanisms to learn when the job reaches a terminal state. They are interchangeable — choose by your environment.

Mechanism	Best for
Poll a status endpoint	Simple scripts; no public endpoint required.
Stream (SSE)	Real-time progress inside an app, agent, or UI.
Webhooks	Push completion into your own backend.

Option A — Poll the status endpoint

Poll the job's status endpoint until it reaches a terminal state:

curl -s https://api.prezent.ai/api/v1/autogenerator/status?callback_id=cb_123 \
  -H "Authorization: Bearer $PREZENT_API_KEY"

The response data.status is one of in_progress, success, or failed. Once status is success, the same cached payload is returned for subsequent polls of the same callback_id.

Polling cadence: start at 2–5 seconds and apply jittered exponential backoff up to ~30 seconds. Do not poll faster than every 2 seconds.

Polling Template Converter

The Template Converter family has its own status endpoint, which takes the callbackId in the path:

GET /api/v1/template-converter/status/{callbackId}

It returns 200 whenever the job is found — branch on data.status, as with AutoGenerator, rather than on the HTTP status code.

See Developer Guide → Async operations.

Option B — Stream progress (SSE)

For live milestones, mint a streaming session for the callback_id and open it with any SSE client:

curl -s -X POST https://api.prezent.ai/api/v1/streams/sessions \
  -H "Authorization: Bearer $PREZENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callback_id": "cb_123" }'

You receive a short-lived stream_url. Opening it yields workflow.started, each task.completed, and finally workflow.completed or workflow.failed (the stream closes after the terminal event). Full details, reconnection, and code samples are in Streaming (SSE).

Option C — Subscribe to webhooks

To avoid polling entirely, subscribe an HTTPS URL once and Prezent delivers a signed POST on completion. The relevant event types are autogeneration.completed / autogeneration.failed and template_conversion.completed / template_conversion.failed. Verify the X-Prezent-Signature (HMAC-SHA256) before acting, and deduplicate on the event id. See Webhooks.

5. Handle terminal states

Whichever mechanism you chose, branch on the terminal state:

• Success — for AutoGenerator, data.status == "success" (or the workflow.completed SSE event / autogeneration.completed webhook). The completed payload carries the generated slides and metadata; use the relevant download sub-endpoint to fetch the final file (see the AutoGenerator API / Template Converter API).
• Failure — data.status == "failed", the workflow.failed SSE event, or the *.failed webhook. Failures arrive in the standard error envelope; read error.code against the error catalog to decide whether to retry, fix the input, or surface the error.

6. Back off on rate limits

When you exceed a limit the API returns HTTP 429 with the standard error envelope. Use both the headers and the body:

• X-RateLimit-Remaining is returned on successful responses from rate-limited endpoints — read it to self-throttle before you hit the wall (X-RateLimit-Limit and X-RateLimit-Reset accompany it).
• On a per-category RATE_LIMIT_EXCEEDED 429, honour Retry-After (seconds to wait) — it ships with the same X-RateLimit-* headers.
• error.code on a 429 is TOO_MANY_REQUESTS (gateway), RATE_LIMIT_EXCEEDED (per-category), or USAGE_LIMIT_EXCEEDED (annual) — the source of truth for why you were limited. The gateway throttle and the annual quota do not carry X-RateLimit-*/Retry-After, so fall back to backoff there.

Always layer your own jittered exponential backoff (start ~1–2 s, cap ~30 s) on top of Retry-After so a fleet of agents does not retry in lockstep. The full limit model (gateway throttle, per-minute limits, annual quotas) is in Developer Guide → Usage quotas and rate limits.

Putting it together

A robust agent loop, in pseudocode:

spec        = GET /openapi/openapi.yaml          # on the Prezent docs site
job         = POST /api/v1/autogenerator
                  (Authorization: Bearer ..., Idempotency-Key: <uuid>)
callback_id = job.resData.callback_id

loop:
    resp = GET /api/v1/autogenerator/status
    if resp is HTTP 429:
        sleep((Retry-After if present else backoff) + jitter); continue
    switch resp.status:
        case "success":     fetch outputs; break
        case "failed":      inspect error.code; stop or remediate
        case "in_progress": sleep(backoff up to ~30s); continue

Where to go next

• Getting Started — first call, response envelopes, status codes.
• Developer Guide — rate limits, error codes, idempotency, pagination, async patterns.
• Agents & MCP — drive all of this as MCP tool calls with no HTTP code.
• Webhooks and Streaming (SSE) — push and real-time completion tracking.
• API Reference — every endpoint, interactively.