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

# Submit External Feedback

> Store an arbitrary evaluation/feedback JSON payload from an external system. The payload is stored as-is without validation. The optional external_id and conversation_id are sender-side identifiers kept as opaque strings for later correlation.

Store an evaluation or feedback payload produced by your own tooling — for example a
pipeline that scores ClarityQ's answers against your reference data.

The `payload` field accepts **any JSON** and is stored exactly as sent, without validation,
so your format can evolve freely without breaking the integration. The optional `source`,
`external_id`, and `conversation_id` fields are kept as opaque strings you can use to
correlate feedback records with your own systems later.

```text Example request theme={null}
POST /api/v1/products/{product_id}/external-feedback
Content-Type: application/json

{
  "source": "my-eval-pipeline",
  "external_id": "QUESTION_42",
  "conversation_id": "your-conversation-reference",
  "payload": {
    "passed": true,
    "overall_score": 95,
    "strengths": ["Accurate metric calculations"],
    "weaknesses": ["Could present SQL more explicitly"]
  }
}
```

```json Example response theme={null}
{
  "id": "811918ff-2dd0-4106-8afd-b26a1f18f461",
  "created_at": "2026-08-13T09:54:58Z"
}
```


## OpenAPI

````yaml post /api/v1/products/{product_id}/external-feedback
openapi: 3.1.0
info:
  title: ClarityQ API
  description: ClarityQ API, authenticated via API keys.
  version: 1.0.0
servers:
  - url: https://api.clarityq.ai
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/products/{product_id}/external-feedback:
    post:
      tags:
        - API
      summary: Submit external feedback
      description: >-
        Store an arbitrary evaluation/feedback JSON payload from an external
        system. The payload is stored as-is without validation. The optional
        external_id and conversation_id are sender-side identifiers kept as
        opaque strings for later correlation.
      operationId: >-
        submit_external_feedback_api_v1_products__product_id__external_feedback_post
      parameters:
        - name: product_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Product Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalFeedbackRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalFeedbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExternalFeedbackRequest:
      properties:
        source:
          type: string
          maxLength: 200
          title: Source
          description: Optional identifier of the sending system, e.g. 'my-eval-pipeline'.
          default: unknown
        external_id:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: External Id
          description: Sender-side identifier for this feedback item, e.g. a question id.
        conversation_id:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Conversation Id
          description: >-
            Conversation identifier as known to the sender. Stored as an opaque
            string; it may or may not be a ClarityQ conversation id.
        payload:
          additionalProperties: true
          type: object
          title: Payload
          description: Arbitrary feedback JSON, stored without validation.
      type: object
      required:
        - payload
      title: ExternalFeedbackRequest
      description: An external evaluation/feedback payload, stored as-is.
    ExternalFeedbackResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Server-assigned id of the stored feedback record.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the feedback was stored (RFC3339 UTC).
      type: object
      required:
        - id
        - created_at
      title: ExternalFeedbackResponse
      description: Acknowledgement that an external feedback payload was stored.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from the ClarityQ dashboard.

````