Skip to main content

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/autogenerations \
  -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" } }

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/autogenerations \
  -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-conversions 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.

MechanismBest for
Poll a status endpointSimple scripts; no public endpoint required.
Stream (SSE)Real-time progress inside an app, agent, or UI.
WebhooksPush 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/autogenerations/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.

Prefer the v2 status endpoint for Template Converter​

For the Template Converter family, prefer the v2 status endpoint, which maps workflow state onto the HTTP status so you can branch on status code alone:

GET /api/v2/template-converter/status/{callback_id}
  • 200 only when the conversion has completed successfully.
  • 202 while the pipeline is still in progress.
  • 4xx / 5xx on workflow failure, with the standard error envelope.

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", an HTTP 4xx/5xx from a v2 status endpoint, 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/autogenerations
                  (Authorization: Bearer ..., Idempotency-Key: <uuid>)
callback_id = job.data.callback_id

loop:
    resp = GET /api/v1/autogenerations/{callback_id}
    if resp is HTTP 429:
        sleep((Retry-After if present else backoff) + jitter); continue
    switch resp.data.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​