Prezent Webhooks API

openapi: 3.1.0
info:
  title: Prezent Platform Audiences Webhooks API
  version: 1.0.0
  summary: Agent-ready REST API for Prezent's content-generation and template-conversion services.
  description: "The Prezent Platform API exposes Prezent's AutoGenerator, Template Converter,\nAudiences, Themes, and File-upload services as a uniform JSON HTTP API.\n\nThis contract describes the **target agent-ready shape** of the API: every\ndocumented endpoint returns a uniform success envelope `{ \"success\": true,\n\"data\": { ... } }` or a uniform error envelope `{ \"success\": false,\n\"data\": null, \"error\": { \"code\": \"...\", \"message\": \"...\", \"details\": { ... } } }`.\nError codes are drawn from a stable catalog (see `ErrorCode`). The contract\nis additive: handlers may continue to emit legacy keys alongside the\ndocumented ones for backwards compatibility, so schemas explicitly allow\nadditional properties at the envelope and data levels.\n\nSeveral endpoints kick off long-running background work and return a\n`callback_id` that the client polls against a corresponding status\nendpoint. The canonical async polling endpoint for the Template Converter\nfamily is **`GET /api/v2/template-converter/status/{callback_id}`** which\nuses strict HTTP-status mapping (200 only on workflow success, 4xx/5xx on\nworkflow failure). The v1 polling endpoint at\n`/api/v1/template-converter/status/{callbackId}` (and its REST alias\n`GET /api/v1/template-conversions/{callback_id}`) continues to be served\nwith legacy semantics (HTTP 200 with `status` field) and is intentionally\nomitted from this documentation.\n\n**REST resource aliases (v1.1).** AutoGenerator and Template Converter\nendpoints are documented here under their REST-resource path names\n(`/api/v1/autogenerations`, `/api/v1/template-conversions`). The legacy\nRPC-style paths under `/api/v1/autogenerator/*` and\n`/api/v1/template-converter/*` continue to be served indefinitely; they\nreturn a `Deprecation: true` header pointing to the successor alias.\n\n**Conventions that apply to every endpoint** (full reference in the\ncompanion guides on this documentation site):\n\n- **Auth:** API key as a Bearer token — `Authorization: Bearer <key>`.\n  Each key is scoped to an allow-list of endpoint paths; an out-of-scope\n  call returns `404 ENDPOINT_NOT_FOUND`.\n- **Rate limits:** gateway throttle 10 req/s sustained, 5 burst,\n  1,000 req/day per key; per-company per-category 60-second sliding\n  windows; annual quotas (50,000 slide generations/yr, 1,000,000\n  downloads/yr). Limit breaches return `429` with `error.code`\n  `TOO_MANY_REQUESTS` (gateway), `RATE_LIMIT_EXCEEDED` (per-category),\n  or `USAGE_LIMIT_EXCEEDED` (annual).\n- **Errors:** every error uses the `{ success:false, data:null, error:{\n  code, message, details } }` envelope with stable, documented `code`\n  values.\n- **Idempotency & pagination:** mutating requests accept an\n  `Idempotency-Key`; list endpoints accept opt-in `limit`/`cursor`\n  paging.\n\n**Building with an AI agent?** Prezent ships a first-class Model Context\nProtocol (MCP) server. The hosted endpoint is\n`https://mcp.myprezent.com/mcp` (OAuth 2.1, works with Claude.ai Custom\nConnectors); a local stdio server is published on PyPI as\n`prezent-mcp-server` and plugs into Claude Desktop, Cursor, Cline,\nContinue, and Zed. The MCP tools wrap the same REST endpoints\ndescribed here.\n\n**Official SDKs.** Typed REST clients are published for Python and\nTypeScript (`prezent-sdk`) — generated from and versioned against this\nspec. For other languages, generate a client from this document.\n\n**Out of scope of this document:** SCIM endpoints under `/api/v1/scim/*`.\nThose endpoints conform to RFC 7644 (SCIM 2.0) and follow a different\nenvelope (`schemas`, `Resources`, `totalResults`, etc.). They are\ndocumented separately at /docs/scim-user-management.\n"
  x-out-of-scope-note: 'SCIM endpoints (`/api/v1/scim/*`) are NOT included in this spec. They

    follow RFC 7644 (SCIM 2.0) and are documented in a separate document at

    /docs/scim-user-management.

    '
  contact:
    name: Prezent API Support
    email: support@prezent.ai
    url: https://prezent.ai
  license:
    name: Proprietary - Prezent, Inc.
    url: https://prezent.ai/terms
servers:
- url: https://api.prezent.ai
  description: Production (canonical)
- url: https://uatstage-api.myprezent.com
  description: UAT (user acceptance testing)
- url: https://devstage-api.myprezent.com
  description: Development
security:
- BearerAuth: []
tags:
- name: Webhooks
  description: Receive signed HTTPS callbacks when Prezent jobs complete or fail. Subscriptions are scoped per API key, retried over a 21h window, and auto-disabled after 50 consecutive failures. See the [Webhooks guide](/docs/webhooks) for the signature format and verification examples.
paths:
  /api/v1/webhook-subscriptions:
    post:
      tags:
      - Webhooks
      summary: Create a webhook subscription
      description: 'Registers a new HTTPS endpoint to receive signed delivery

        callbacks for the listed event types. Returns the HMAC `secret`

        ONCE — store it securely. Subsequent reads only expose the

        `secret_prefix`.

        '
      operationId: createWebhookSubscription
      x-rate-limit-category: general
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionCreateRequest'
      responses:
        '201':
          description: Subscription created. Body contains the `secret` — the only response that ever exposes it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
    get:
      tags:
      - Webhooks
      summary: List webhook subscriptions
      description: 'Returns the subscriptions owned by the calling API key. Excludes

        soft-deleted rows. Use the standard cursor-pagination parameters

        — see [Developer Guide → Pagination](/docs/developer-guide#pagination).

        '
      operationId: listWebhookSubscriptions
      x-rate-limit-category: general
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 25
      - in: query
        name: cursor
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Paginated subscription list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /api/v1/webhook-subscriptions/{id}:
    get:
      tags:
      - Webhooks
      summary: Read a webhook subscription
      description: 'Returns one subscription. `secret_prefix` (the first 6 chars of

        the HMAC secret) is exposed for human disambiguation; the full

        secret is never returned by a read.

        '
      operationId: getWebhookSubscription
      x-rate-limit-category: general
      parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionIdPath'
      responses:
        '200':
          description: Subscription found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionReadResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
    patch:
      tags:
      - Webhooks
      summary: Update a webhook subscription
      description: 'Partial update. Any combination of `url`, `events`, `description`,

        or `status` may be supplied. Changes to `url` are re-validated

        against the SSRF / scheme / port rules. Setting `status` to

        `"active"` re-enables an auto-disabled subscription.

        '
      operationId: updateWebhookSubscription
      x-rate-limit-category: general
      parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionUpdateRequest'
      responses:
        '200':
          description: Subscription updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionReadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook subscription
      description: 'Soft-deletes the subscription. The `id` is permanently retired

        — no future deliveries will be attempted, and the row is

        excluded from list responses.

        '
      operationId: deleteWebhookSubscription
      x-rate-limit-category: general
      parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionIdPath'
      responses:
        '200':
          description: Subscription deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionDeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /api/v1/webhook-subscriptions/{id}/rotate-secret:
    post:
      tags:
      - Webhooks
      summary: Rotate the HMAC secret for a subscription
      description: 'Generates a new HMAC `secret` and invalidates the old one

        immediately. Returns the new secret ONCE — store it before

        responding to the caller. There is no grace window during which

        both secrets verify; if you need an overlap, stand up a second

        subscription on a distinct path, switch over, then delete the

        old one.

        '
      operationId: rotateWebhookSubscriptionSecret
      x-rate-limit-category: general
      parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionIdPath'
      responses:
        '200':
          description: Secret rotated. Body contains the new `secret` — the only place it is ever returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionRotateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
  /api/v1/webhook-subscriptions/{id}/test:
    post:
      tags:
      - Webhooks
      summary: Send a test delivery to a subscription
      description: 'Immediately POSTs a synthetic `webhook.test` event to the

        subscription''s URL (signed with the current secret, 5s timeout,

        no retries) and returns the response status + body verbatim.

        Use this to verify the receiver''s signature-verification path

        before real traffic flows.

        '
      operationId: testWebhookSubscription
      x-rate-limit-category: general
      parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionIdPath'
      responses:
        '200':
          description: Test delivery attempted. The `delivery.ok` field indicates whether the receiver returned a 2xx.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionTestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
components:
  schemas:
    WebhookSubscriptionDeleteResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: object
            required:
            - id
            - deleted
            properties:
              id:
                type: string
                example: whsub_3f7a9b1c8d2e4f5a6b7c8d9e0f1a2b3c
              deleted:
                type: boolean
                const: true
    WebhookSubscription:
      type: object
      description: 'Core read-shape for a webhook subscription. Returned by GET +

        PATCH endpoints. Never includes the raw HMAC secret — only

        `secret_prefix` (the first 6 chars, for human disambiguation).

        '
      required:
      - id
      - url
      - secret_prefix
      - events
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
          pattern: ^whsub_[a-f0-9]{32}$
          example: whsub_3f7a9b1c8d2e4f5a6b7c8d9e0f1a2b3c
        url:
          type: string
          format: uri
          description: HTTPS endpoint receiving signed deliveries.
          example: https://hooks.example.com/prezent
        secret_prefix:
          type: string
          description: First 6 characters of the HMAC secret, for human disambiguation. Always `whsec_` for current implementations.
          example: whsec_
        events:
          type: array
          description: 'Event types this subscription receives. Use `["*"]` to

            subscribe to everything, including future event types.

            '
          items:
            $ref: '#/components/schemas/WebhookEventType'
          minItems: 1
          example:
          - autogeneration.completed
          - autogeneration.failed
        description:
          type: string
          nullable: true
          description: Free-form human label for the subscription.
          example: Push completions into our deal-room worker.
        status:
          $ref: '#/components/schemas/WebhookSubscriptionStatus'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_delivery_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the most recent successful delivery.
        last_failure_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of the most recent failed delivery.
        consecutive_failure_count:
          type: integer
          format: int32
          minimum: 0
          description: 'Failures since the last successful delivery. At 50 the

            subscription is auto-disabled.

            '
      additionalProperties: true
    WebhookSubscriptionCreateResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            allOf:
            - $ref: '#/components/schemas/WebhookSubscription'
            - type: object
              required:
              - secret
              properties:
                secret:
                  type: string
                  description: 'The raw HMAC secret. Returned ONCE on this

                    endpoint and on `/rotate-secret`. Store it

                    immediately — subsequent reads expose only

                    `secret_prefix`.

                    '
                  example: whsec_4mZkV8t9oFp1qR3sT7uW9xY2zA5bCdEfGhI
    ErrorCode:
      type: string
      description: 'Stable identifier for an error condition. Codes never change

        meaning or HTTP status once published.

        '
      enum:
      - INVALID_API_KEY
      - EXPIRED_API_KEY
      - UNAUTHORIZED
      - FORBIDDEN
      - ENDPOINT_NOT_FOUND
      - RESOURCE_NOT_FOUND
      - NOT_FOUND
      - METHOD_NOT_ALLOWED
      - UNSUPPORTED_FILE_TYPE
      - INVALID_INPUT
      - UNPROCESSABLE_ENTITY
      - RATE_LIMIT_EXCEEDED
      - USAGE_LIMIT_EXCEEDED
      - TOO_MANY_REQUESTS
      - THROTTLED
      - BAD_REQUEST
      - INVALID_JSON
      - MISSING_REQUIRED_FIELD
      - MISSING_QUERY_PARAM
      - MISSING_CALLBACK_ID
      - MISSING_SLIDES_ARRAY
      - MISSING_PROMPT
      - MISSING_TEMPLATE_ID
      - MISSING_FILE_CONTENT
      - MISSING_SHARE_DETAILS
      - INVALID_TYPE
      - INVALID_DATA
      - INVALID_DATA_TYPE
      - INVALID_PAYLOAD
      - INVALID_REQUEST
      - API_REQUEST_FAILED
      - FILE_UPLOAD_FAILED
      - MAX_RETRIES_EXCEEDED
      - EXTERNAL_SERVICE_ERROR
      - INTERNAL_SERVER_ERROR
      - SERVICE_UNAVAILABLE
      - GATEWAY_TIMEOUT
    WebhookSubscriptionReadResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/WebhookSubscription'
    WebhookSubscriptionUpdateRequest:
      type: object
      description: Partial update. Any combination of fields may be supplied.
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
          minItems: 1
        description:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/WebhookSubscriptionStatus'
      additionalProperties: false
    ErrorEnvelope:
      type: object
      description: 'Standard error envelope returned by every documented endpoint

        (both in-Lambda and gateway-level errors). Additional legacy

        keys may appear alongside `success`/`data`/`error` for

        backwards compatibility.

        '
      required:
      - success
      - data
      - error
      properties:
        success:
          type: boolean
          const: false
          description: Always `false` on error.
        data:
          type:
          - object
          - 'null'
          description: Always `null` on error.
        error:
          type: object
          required:
          - code
          - message
          description: Error description.
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable error description (English).
            details:
              type: object
              description: Optional structured details (validation failures, downstream-service info, etc.).
              additionalProperties: true
      additionalProperties: true
    WebhookSubscriptionRotateResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: object
            required:
            - id
            - secret
            - secret_prefix
            - rotated_at
            properties:
              id:
                type: string
                example: whsub_3f7a9b1c8d2e4f5a6b7c8d9e0f1a2b3c
              secret:
                type: string
                description: The freshly-issued HMAC secret. Stored nowhere by Prezent after this response — capture it before forwarding.
                example: whsec_NewlyGeneratedSecretMaterial
              secret_prefix:
                type: string
                example: whsec_
              rotated_at:
                type: string
                format: date-time
    WebhookSubscriptionListResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: object
            required:
            - items
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookSubscription'
              next_cursor:
                type: string
                nullable: true
                description: Pass to the next call's `cursor` query param. `null` when no more pages.
    SuccessEnvelope:
      type: object
      description: 'Standard success envelope. Endpoint-specific schemas extend this

        and constrain the `data` property to their concrete shape.

        Additional legacy keys (`status`, `log`, …) may appear alongside

        `success`/`data` for backwards compatibility, and some legacy

        handlers omit `success`, so it is not marked required.

        '
      required:
      - data
      properties:
        success:
          type: boolean
          description: '`true` on success (omitted by some legacy handlers).'
        data:
          type: object
          description: Endpoint-specific payload.
      additionalProperties: true
    WebhookSubscriptionCreateRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: 'HTTPS endpoint to receive deliveries. Must use `https://`,

            resolve to a public IP, and not use a disallowed port. See

            the [Webhooks guide](/docs/webhooks#url-requirements).

            '
          example: https://hooks.example.com/prezent
        events:
          type: array
          description: Event types to subscribe to. Defaults to `["*"]`.
          items:
            $ref: '#/components/schemas/WebhookEventType'
          default:
          - '*'
          example:
          - autogeneration.completed
          - autogeneration.failed
        description:
          type: string
          nullable: true
          example: Push completions into our deal-room worker.
        status:
          $ref: '#/components/schemas/WebhookSubscriptionStatus'
      additionalProperties: false
    WebhookEvent:
      type: object
      description: 'Payload **POSTed to your subscription URL**. This is NOT the

        body of any management endpoint — it is what your receiver

        parses. Verify the signature first; see the [Webhooks

        guide](/docs/webhooks#4-verify-the-signature).

        '
      required:
      - id
      - type
      - api_version
      - created_at
      - data
      properties:
        id:
          type: string
          pattern: ^evt_[a-zA-Z0-9_]+$
          description: Globally unique event identifier. Also sent in the `X-Prezent-Event` header. Dedupe on this if you receive the same event twice (at-least-once delivery).
          example: evt_8c2a1f7e6d3b4a5c9e0f8d7b6a5c4d3e
        type:
          $ref: '#/components/schemas/WebhookEventType'
        api_version:
          type: string
          description: Schema version for the `data` field. Increments only on breaking changes; legacy versions remain available.
          example: '1.0'
        created_at:
          type: string
          format: date-time
        data:
          type: object
          description: 'Event-specific payload. For `autogeneration.*` events,

            contains `callback_id`, `report_id`, `status`, plus

            `outputs` (on success) or `error_log` (on failure). For

            `template_conversion.*` events, contains the conversion

            `callback_id`, `status`, and output URLs.

            '
          additionalProperties: true
    WebhookSubscriptionTestResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - type: object
        properties:
          data:
            type: object
            required:
            - subscription_id
            - event
            - delivery
            properties:
              subscription_id:
                type: string
                example: whsub_3f7a9b1c8d2e4f5a6b7c8d9e0f1a2b3c
              event:
                $ref: '#/components/schemas/WebhookEvent'
              delivery:
                type: object
                required:
                - ok
                - status
                - delivery_id
                properties:
                  ok:
                    type: boolean
                    description: True if the receiver returned a 2xx.
                  status:
                    type: integer
                    description: HTTP status code from the receiver (0 on network error / timeout).
                    example: 200
                  error:
                    type: string
                    nullable: true
                    description: Network error code (`timeout`, `ECONNREFUSED`, etc.). `null` on success.
                  response_body_preview:
                    type: string
                    description: First 8 KiB of the receiver's response body, for debugging.
                  delivery_id:
                    type: string
                    pattern: ^whdl_[a-f0-9]{24}$
                    description: Internal delivery id. Also sent to the receiver in the `X-Prezent-Delivery` header.
    WebhookEventType:
      type: string
      description: 'Catalog of event types emitted by Prezent. New types may be

        added without notice; clients should ignore unknown values.

        '
      enum:
      - autogeneration.completed
      - autogeneration.failed
      - template_conversion.completed
      - template_conversion.failed
      - webhook.test
    WebhookSubscriptionStatus:
      type: string
      enum:
      - active
      - disabled
      description: '`active` subscriptions receive deliveries. `disabled`

        subscriptions are skipped at dispatch time — either explicitly

        set by the customer or set by Prezent''s auto-disable rule after

        50 consecutive delivery failures. PATCH `status: active` to

        re-enable.

        '
  responses:
    Forbidden:
      description: Caller is authenticated but not allowed to perform this operation. `error.code` is `FORBIDDEN`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: FORBIDDEN
              message: Access to the resource is forbidden.
              details: {}
    RateLimited:
      description: "Rate limit, usage limit, or gateway-level throttle exceeded.\n`error.code` is `TOO_MANY_REQUESTS` (gateway throttle),\n`RATE_LIMIT_EXCEEDED` (per-category), or `USAGE_LIMIT_EXCEEDED`\n(annual quota).\n\nDefault limits (all configurable per company/key):\n- Gateway throttle (per API key) → `TOO_MANY_REQUESTS`: 10 requests/second\n  sustained, 5 burst, 1,000 requests/day.\n- Per-company, per-category sliding 60-second window →\n  `RATE_LIMIT_EXCEEDED`. The applicable category is given by each\n  operation's `x-rate-limit-category`.\n- Annual usage quota → `USAGE_LIMIT_EXCEEDED`: 50,000 slide\n  generations/year and 1,000,000 presentation downloads/year.\n\n`X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` are\nreturned on successful (2xx) responses from rate-limited endpoints\nand, with `Retry-After`, on the per-category `RATE_LIMIT_EXCEEDED`\n429 (the headers declared below). The gateway `TOO_MANY_REQUESTS`\nand annual `USAGE_LIMIT_EXCEEDED` responses do not carry them. Read\n`X-RateLimit-Remaining` to self-throttle and honour `Retry-After` on\na 429.\n"
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: RATE_LIMIT_EXCEEDED
              message: Rate limit exceeded for this category. Try again later.
              details:
                category: auto_generator
                retry_after_seconds: 12
    ServiceUnavailable:
      description: Service is temporarily unavailable (downstream dependency unhealthy). `error.code` is `SERVICE_UNAVAILABLE` or `EXTERNAL_SERVICE_ERROR`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: SERVICE_UNAVAILABLE
              message: Service is temporarily unavailable.
              details: {}
    Unauthorized:
      description: 'Caller did not present a valid Bearer token, or the token has

        expired. `error.code` is one of `UNAUTHORIZED`, `INVALID_API_KEY`,

        `EXPIRED_API_KEY`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: INVALID_API_KEY
              message: API key not found or not authorized.
              details: {}
    NotFound:
      description: 'Requested endpoint or resource does not exist. `error.code` is

        one of `ENDPOINT_NOT_FOUND`, `RESOURCE_NOT_FOUND`, `NOT_FOUND`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              details: {}
    GatewayTimeout:
      description: A downstream call timed out. `error.code` is `GATEWAY_TIMEOUT`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            data: null
            error:
              code: GATEWAY_TIMEOUT
              messag

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prezent/refs/heads/main/openapi/prezent-webhooks-api-openapi.yml