prezent-sdk 0.1.0

Prezent Platform API

The Prezent Platform API exposes Prezent's AutoGenerator, Template Converter, Audiences, Themes, and File-upload services as a uniform JSON HTTP API.  This contract describes the **target agent-ready shape** of the API: every documented endpoint returns a uniform success envelope `{ \"success\": true, \"data\": { ... } }` or a uniform error envelope `{ \"success\": false, \"data\": null, \"error\": { \"code\": \"...\", \"message\": \"...\", \"details\": { ... } } }`. Error codes are drawn from a stable catalog (see `ErrorCode`). The contract is additive: handlers may continue to emit legacy keys alongside the documented ones for backwards compatibility, so schemas explicitly allow additional properties at the envelope and data levels.  Several endpoints kick off long-running background work and return a `callback_id` that the client polls against a corresponding status endpoint. The canonical async polling endpoint for the Template Converter family is **`GET /api/v2/template-converter/status/{callback_id}`** which uses strict HTTP-status mapping (200 only on workflow success, 4xx/5xx on workflow failure). The v1 polling endpoint at `/api/v1/template-converter/status/{callbackId}` (and its REST alias `GET /api/v1/template-conversions/{callback_id}`) continues to be served with legacy semantics (HTTP 200 with `status` field) and is intentionally omitted from this documentation.  **REST resource aliases (v1.1).** AutoGenerator and Template Converter endpoints are documented here under their REST-resource path names (`/api/v1/autogenerations`, `/api/v1/template-conversions`). The legacy RPC-style paths under `/api/v1/autogenerator/*` and `/api/v1/template-converter/*` continue to be served indefinitely; they return a `Deprecation: true` header pointing to the successor alias.  **Conventions that apply to every endpoint** (full reference in the companion guides on this documentation site):  - **Auth:** API key as a Bearer token — `Authorization: Bearer <key>`.   Each key is scoped to an allow-list of endpoint paths; an out-of-scope   call returns `404 ENDPOINT_NOT_FOUND`. - **Rate limits:** gateway throttle 10 req/s sustained, 5 burst,   1,000 req/day per key; per-company per-category 60-second sliding   windows; annual quotas (50,000 slide generations/yr, 1,000,000   downloads/yr). Limit breaches return `429` with `error.code`   `TOO_MANY_REQUESTS` (gateway), `RATE_LIMIT_EXCEEDED` (per-category),   or `USAGE_LIMIT_EXCEEDED` (annual). - **Errors:** every error uses the `{ success:false, data:null, error:{   code, message, details } }` envelope with stable, documented `code`   values. - **Idempotency & pagination:** mutating requests accept an   `Idempotency-Key`; list endpoints accept opt-in `limit`/`cursor`   paging.  **Building with an AI agent?** Prezent ships a first-class Model Context Protocol (MCP) server. The hosted endpoint is `https://mcp.myprezent.com/mcp` (OAuth 2.1, works with Claude.ai Custom Connectors); a local stdio server is published on PyPI as `prezent-mcp-server` and plugs into Claude Desktop, Cursor, Cline, Continue, and Zed. The MCP tools wrap the same REST endpoints described here.  **Official SDKs.** Typed REST clients are published for Python, TypeScript, Go, Java, Ruby, C#, and PHP — generated from and versioned against this spec. See the SDKs guide for per-language install commands.  **Out of scope of this document:** SCIM endpoints under `/api/v1/scim/*`. Those endpoints conform to RFC 7644 (SCIM 2.0) and follow a different envelope (`schemas`, `Resources`, `totalResults`, etc.). They are documented separately at /docs/scim-user-management.