generated: '2026-07-20'
method: derived
source: openapi/moonbounce-openapi-original.json
# Cross-cutting request/response semantics for the Clavata Public API v1
# (Moonbounce Realtime AI Control / content-moderation platform). Derived from the
# published OpenAPI + docs (docs.clavata.ai). Where the provider does not document a
# convention (e.g. idempotency), it is recorded as unsupported rather than invented.
authentication:
  style: bearer-token
  header: Authorization
  format: "Bearer <API_KEY>"
  notes: >-
    API keys are created/managed in the app (Account Settings -> API Keys, Admin role only),
    support 30/90/180/365-day or no expiration, and can be disabled or revoked. The OpenAPI
    declares bearerFormat JWT.
  ref: authentication/moonbounce-authentication.yml
pagination:
  style: cursor
  request_params:
    page_size: pageSize
    page_token: pageToken
  applies_to:
    - GatewayService_ListJobs   # GET /v1/jobs
  notes: Google AIP-style cursor pagination; list endpoints return a nextPageToken to fetch subsequent pages.
filtering:
  list_jobs:
    - createdTimeRange (start/end/inclusive)
    - updatedTimeRange (start/end/inclusive)
    - completedTimeRange (start/end/inclusive)
    - status
    - policyId
  list_batch_jobs:
    - batchJobIds
    - states
idempotency:
  supported: false
  notes: No idempotency-key header or parameter is documented in the OpenAPI or developer docs.
versioning:
  scheme: uri-path
  current: v1
  base_path: /v1
error_envelope:
  format: grpc-status
  content_type: application/json
  fields: [code, message, details]
  ref: errors/moonbounce-problem-types.yml
rate_limiting:
  signal: http-status
  status_code: 429
  notes: >-
    Rate limits are enforced per account/plan (free plan caps at 1,000 evaluations/day);
    exceeding limits returns HTTP 429 with the v1GRPCErrorResponse envelope. No documented
    rate-limit response headers.
async_and_webhooks:
  webhooks:
    supported: true
    mechanism: >-
      CreateJob requests accept an optional webhook object (url + extraHeaders) that
      Moonbounce calls when the job completes.
    ref: asyncapi/moonbounce-webhooks.yml
  batch:
    pattern: presigned-url-upload
    notes: >-
      Batch jobs return a presigned upload URL (valid 4h); results are retrieved via a
      presigned output_url once the job reaches BATCH_JOB_STATE_COMPLETED.
  streaming:
    supported: true
    endpoint: POST /v1/jobs/stream
    notes: Streams evaluation results in real time as content is processed.