Cactal Feedback API

openapi: 3.2.0
info:
  title: Cactal Ai Feedback API
  version: 1.0.0
  description: 'Operations tagged Feedback across 2 of this provider''s published API definitions: openapi.json, cactal-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cactal.ai/v1
security:
- apiKey: []
tags:
- name: Feedback
  description: Submit free-form product feedback from users and agents to the Cactal feedback inbox.
paths:
  /feedback:
    post:
      operationId: feedback.submit
      summary: Submit product feedback
      description: Adds user-requested free-form feedback to the Cactal product-feedback inbox. Describe what happened and what would have made the experience better. Agents must set `authorKind` to `agent` even when acting through a user OAuth connection. Never include credentials, secrets, raw sensitive user content, or unnecessary personal or customer data.
      tags:
      - Feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                authorKind:
                  type: string
                  enum:
                  - user
                  - agent
                  description: Who wrote the feedback. An AI agent must pass "agent" even when connected through a user OAuth token.
                feedback:
                  type: string
                  minLength: 1
                  maxLength: 12000
                  description: Concise free-form feedback describing the Cactal problem or limitation and what would have made the experience better.
              required:
              - authorKind
              - feedback
      responses:
        '200':
          description: The id and receipt time of the accepted feedback.
          content:
            application/json:
              schema:
                type: object
                properties:
                  feedbackId:
                    type: string
                    description: Generated id of the accepted feedback.
                  receivedAt:
                    description: When Cactal accepted the feedback.
                    type: string
                    format: date-time
                required:
                - feedbackId
                - receivedAt
                additionalProperties: false
        '400':
          description: Validation failed. The response `message` names the first invalid field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '403':
          description: The authenticated principal lacks the required capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '404':
          description: The resource does not exist or is outside the principal’s access scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '429':
          description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      x-cactal-required-capability: null
      x-cactal-read-only: false
      x-cactal-destructive: false
      x-cactal-idempotent: false
    servers:
    - url: https://api.cactal.ai/v1
components:
  schemas:
    ServiceError:
      type: object
      required:
      - kind
      - message
      description: Canonical error body returned by every non-2xx response. Extra fields carry error-specific details.
      properties:
        kind:
          type: string
          enum:
          - validation
          - unauthorized
          - forbidden
          - not_found
          - conflict
          - rate_limited
          - internal
          description: Stable, machine-readable error category.
        message:
          type: string
          description: Human-readable explanation of the failure.
        suggestion:
          type: string
          description: What to do next when the failure has a known fix; may name the exact operation to call.
        validValues:
          type: array
          items:
            type: string
          description: The acceptable values for the failing field, when the set is closed.
      additionalProperties: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation.
x-refined-from:
- openapi.json
- cactal-ai-openapi.json