Cavuno Agent feedback API

openapi: 3.2.0
info:
  title: Cavuno v1 REST Agent feedback API
  version: 1.0.0
  description: 'The Cavuno API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Base URL


    Production: `https://api.cavuno.com/v1`


    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. ## Authentication


    The Cavuno API uses API keys to authenticate requests. You can view and manage your API keys in the Cavuno dashboard, under Settings → Developer → API keys. Cavuno API keys have the prefix `cavuno_live_`. Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via Bearer auth. Provide your API key as the bearer token in the `Authorization` header:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -H "Authorization: Bearer YOUR_SECRET_API_KEY"

    ```


    API requests without authentication will fail. ## Rate limits


    The Cavuno API has rate limits in place to ensure stability and reliability. By default, API keys are limited to 100 requests per minute. If you exceed your limit, requests return an HTTP 429 response with a `Retry-After` header indicating when you can try again. If you have a use case that needs a higher limit, contact support. ## Idempotency


    The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a job fails due to a network connection error, you can safely retry the request with the same idempotency key, and we''ll guarantee that only one job is created. To perform an idempotent request, provide an additional `Idempotency-Key` header on any `POST`, `PATCH`, or `DELETE` request:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -X POST \

    -H "Authorization: Bearer cavuno_live_..." \

    -H "Idempotency-Key: $(uuidgen)" \

    -H "Content-Type: application/json" \

    -d ''{ "title": "Senior Engineer" }''

    ```


    ## Errors


    Cavuno uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with Cavuno''s servers (these are rare). Error responses include a JSON body with details:


    ```json

    {

    "error": {

    "code": "validation_bad_request",

    "message": "Field ''title'' is required.",

    "requestId": "req_..."

    }

    }

    ```


    Some errors carry an additional `details` field with structured context, such as per-field validation issues. ### Plan upgrade hints


    When an Operator API request is refused because of the board''s Cavuno plan, the error also carries an `upgrade` object. It names the capability that blocked the request, the cheapest self-serve plan that unlocks it (when that can be told), and the hosted billing endpoints that start the upgrade:


    ```json

    {

    "error": {

    "code": "settings_plan_required_for_branding_removal",

    "message": "Removing Cavuno branding requires a plan that includes branding removal.",

    "requestId": "req_...",

    "upgrade": {

    "capability": "canRemoveBranding",

    "requiredPlan": "basic",

    "checkout": { "method": "POST", "path": "/v1/billing/checkout" },

    "changePlan": { "method": "POST", "path": "/v1/billing/upgrade" }

    }

    }

    }

    ```


    Call `GET /v1/billing/subscription` first. With no active subscription, use `checkout`; with one, use `changePlan`. Send `{ "planKey": "" }` and give the returned `url` to a person: both endpoints return a hosted page where a person confirms the purchase. Nothing is charged until they do. Each `path` is relative to the API origin (`https://api.cavuno.com`), like `Location` headers and list `url` fields, so do not join it to a base URL that already ends in `/v1`.'
  contact:
    name: Cavuno
    url: https://cavuno.com
servers:
- url: https://api.cavuno.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Agent feedback
  description: Report a problem an AI agent hit with the API, CLI, MCP server or SDK (Agent Feedback Protocol v0.1).
paths:
  /feedback:
    post:
      security:
      - {}
      - bearerAuth: []
      summary: Report a problem as an AI agent
      description: 'Agent Feedback Protocol v0.1 (https://trybackloop.com/spec/). Report anything that prevented or complicated a task on Cavuno''s API, CLI, MCP server or SDK. Responses use the protocol''s own shapes, not the usual error envelope. Bodies over 16384 bytes and unknown fields are rejected. 20 reports per account or visitor every 5 minutes. Never include credentials or personal data; send the report, then continue with your task. Discovery: `/.well-known/agent-feedback`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentFeedbackReport'
      responses:
        '202':
          description: Accepted. A retry with the same `session_id` and content returns the original report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackAccepted'
        '400':
          description: '`invalid_json` or `invalid_feedback`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackError'
        '413':
          description: '`payload_too_large`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackError'
        '415':
          description: '`unsupported_media_type`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackError'
        '429':
          description: '`rate_limited`. Wait for `Retry-After` seconds.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackError'
        '503':
          description: '`rate_limit_unavailable`. Continue with your task.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFeedbackError'
      x-audience: operator
      tags:
      - Agent feedback
      operationId: submitAgentFeedback
components:
  schemas:
    AgentFeedbackReport:
      type: object
      properties:
        type:
          type: string
          enum:
          - missing_capability
          - bug
          - unclear_documentation
          - unexpected_response
          - unhelpful_error
          - performance
          - other
          description: The kind of problem.
        goal:
          type: string
          maxLength: 1000
          description: What you or your user were trying to accomplish, in plain language.
        message:
          type: string
          maxLength: 4000
          description: What prevented or complicated the task.
        endpoint:
          type: string
          maxLength: 512
          description: API path, CLI command or MCP tool involved, e.g. `/jobs`.
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          - HEAD
          - OPTIONS
          description: HTTP method, when `endpoint` is a path.
        outcome:
          type: string
          enum:
          - blocked
          - degraded
          - completed
          description: '`blocked`: the task failed. `degraded`: it finished worse or slower. `completed`: a suggestion only.'
        workaround:
          type: boolean
          description: Whether you found a workaround.
        workaround_description:
          type: string
          maxLength: 2000
          description: The workaround, if any.
        expected:
          type: string
          maxLength: 2000
          description: What you expected to find or happen.
        suggestion:
          type: string
          maxLength: 2000
          description: A concrete change that would have let you succeed.
        request_id:
          type: string
          maxLength: 256
          description: The `X-Request-Id` of the failing call, if you have it.
        session_id:
          type: string
          maxLength: 256
          description: Reuse one value for every report in a task; a retry with the same content returns the original report.
        agent:
          type: object
          properties:
            name:
              type: string
              maxLength: 256
            version:
              type: string
              maxLength: 256
            model:
              type: string
              maxLength: 256
            framework:
              type: string
              maxLength: 256
          additionalProperties: false
          description: 'Who is reporting: name (agent or product) and model.'
        evidence:
          type: object
          properties:
            status_code:
              type: integer
            request:
              type: object
              additionalProperties: {}
            response_excerpt:
              type: string
              maxLength: 4000
          additionalProperties: false
          description: Sanitized details of the failing call, with no credentials or personal data.
        metadata:
          type: object
          additionalProperties: {}
          description: Any other context, as a JSON object.
        spec_version:
          type: string
          enum:
          - '0.1'
          description: Protocol version. Only `0.1` is accepted.
      required:
      - type
      - goal
      - message
      additionalProperties: false
    AgentFeedbackAccepted:
      type: object
      properties:
        id:
          type: string
          description: The report id, e.g. `fb_…`.
        status:
          type: string
          enum:
          - accepted
        received_at:
          type: string
          description: When Cavuno first received this report (ISO 8601). A retry returns the original time.
      required:
      - id
      - status
      - received_at
    AgentFeedbackError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: '`invalid_json`, `invalid_feedback`, `payload_too_large`, `unsupported_media_type`, `rate_limited`, `rate_limit_unavailable` or `internal_error`.'
            message:
              type: string
              description: Human-readable explanation.
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                - path
                - message
              description: Every problem with the report, for `invalid_feedback`.
          required:
          - code
          - message
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cavuno_live_<keyId>_<secret>
      description: Use your secret API key to authenticate. Pass it as a Bearer token in the `Authorization` header. You can view and manage your API keys in the Cavuno dashboard.
externalDocs:
  description: Cavuno API reference
  url: https://cavuno.com/docs/api