> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycaesar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Record feedback

> Persist an agent or evaluation feedback event.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/feedback
openapi: 3.1.0
info:
  description: >-
    Local implementation of the v1 search, document, feedback, and internal
    operational APIs.
  title: Agent Search API (Public)
  version: 0.1.0
servers:
  - description: Staging
    url: https://alpha.api.trycaesar.com
  - description: Local development
    url: http://localhost:8080
security: []
tags:
  - description: Public search APIs.
    name: Search
  - description: Public document inspection APIs.
    name: Documents
  - description: Public feedback ingestion APIs.
    name: Feedback
  - description: Asynchronous deep-research APIs.
    name: Research
  - description: Internal health, readiness, and metrics APIs.
    name: Operations
paths:
  /v1/feedback:
    post:
      tags:
        - Feedback
      summary: Record feedback
      description: Persist an agent or evaluation feedback event.
      operationId: record-feedback
      parameters:
        - description: Optional client session identifier.
          in: header
          name: X-Session-ID
          schema:
            description: Optional client session identifier.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackResponse'
          description: Feedback accepted.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Validation error.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Missing or invalid API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: API key does not have the required scope.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Search or document target not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Rate limited.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Internal error.
      security:
        - bearerApiKey: []
components:
  schemas:
    FeedbackRequest:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/FeedbackRequest.json
          format: uri
          readOnly: true
          type: string
        agent_context:
          $ref: '#/components/schemas/FeedbackAgentContext'
          description: Optional calling-agent context for slicing feedback in evaluation.
        doc_id:
          description: Document the event concerns, from the result's doc_id.
          format: uuid
          type: string
        event_type:
          description: >-
            What happened: result_helpful / result_not_helpful (the result did
            or did not advance the task), passage_used (a passage was used or
            cited), read_abandoned (opened but abandoned), duplicate_result,
            stale_result (outdated content), spam_or_low_quality,
            missing_expected_source (a source you expected did not appear),
            unsafe_or_policy_issue.
          enum:
            - result_helpful
            - result_not_helpful
            - passage_used
            - read_abandoned
            - duplicate_result
            - stale_result
            - spam_or_low_quality
            - missing_expected_source
            - unsafe_or_policy_issue
          type: string
        notes:
          description: Free-text context, recorded for human review and offline evaluation.
          type: string
        passage_id:
          description: >-
            Specific passage the event concerns, from passages[].passage_id;
            most useful with passage_used.
          format: uuid
          type: string
        query:
          description: >-
            Query text the event relates to, useful when no search_id is
            available.
          type: string
        rank:
          description: One-based position the result had in the ranked list.
          format: int64
          minimum: 1
          type: integer
        search_id:
          description: >-
            The search_id returned by /v1/search. Ties feedback to the exact
            ranked list that produced the result, so ranking learns from the
            right context.
          format: uuid
          type: string
        session_id:
          description: >-
            Session the event belongs to (UUID), matching session_id from
            earlier responses.
          format: uuid
          type: string
      required:
        - event_type
      type: object
    FeedbackResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/FeedbackResponse.json
          format: uri
          readOnly: true
          type: string
        accepted:
          type: boolean
        access:
          $ref: '#/components/schemas/Access'
        feedback_id:
          type: string
        request_id:
          type: string
        session_id:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
      required:
        - request_id
        - feedback_id
        - session_id
        - access
        - accepted
      type: object
    ErrorEnvelope:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://alpha.api.trycaesar.com/ErrorEnvelope.json
          format: uri
          readOnly: true
          type: string
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error details.
        request_id:
          description: Server request identifier.
          type: string
        type:
          description: Envelope discriminator.
          enum:
            - error
          type: string
      required:
        - type
        - request_id
        - error
      type: object
    FeedbackAgentContext:
      additionalProperties: false
      properties:
        client_model:
          description: Calling model identifier.
          type: string
        task_type:
          description: Agent task type or evaluation bucket (e.g. 'coding' or 'research').
          type: string
      type: object
    Access:
      additionalProperties: false
      properties:
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
      required:
        - rate_limit
      type: object
    Usage:
      additionalProperties: false
      properties:
        bytes_returned:
          format: int64
          type: integer
        requests:
          format: int64
          type: integer
      required:
        - requests
        - bytes_returned
      type: object
    ErrorBody:
      additionalProperties: false
      properties:
        code:
          description: Stable machine-readable error code.
          type: string
        details:
          additionalProperties: {}
          description: Optional structured error details.
          type: object
        message:
          description: Human-readable error message.
          type: string
      required:
        - code
        - message
      type: object
    RateLimit:
      additionalProperties: false
      properties:
        limit_rps:
          format: int64
          type: integer
        remaining:
          format: int64
          type: integer
        reset_at:
          type: string
      required:
        - limit_rps
        - remaining
        - reset_at
      type: object
  securitySchemes:
    bearerApiKey:
      bearerFormat: API key
      scheme: bearer
      type: http

````