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

# Create observations

> Post one or more observations to a project. Same batch payload as the MCP `post_observations` tool: set `user_id`, `interaction_id`, and `user_sentiment` once, then list each observation in `observations`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/project/{project_id}/observations/
openapi: 3.1.0
info:
  title: Correl8 API
  description: >-
    Public REST API for Correl8 custom integrations — observations, guidelines,
    and research answers. MCP integration is documented separately.
  version: 1.0.0
servers:
  - url: https://api.correl8.ai
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/project/{project_id}/observations/:
    post:
      tags:
        - Observations
      summary: Create observations
      description: >-
        Post one or more observations to a project. Same batch payload as the
        MCP `post_observations` tool: set `user_id`, `interaction_id`, and
        `user_sentiment` once, then list each observation in `observations`.
      operationId: createObservations
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Project UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObservationBatchCreate'
            example:
              user_id: user-42
              interaction_id: conv_9f3a2b1c
              user_sentiment: negative
              observations:
                - title: Enter key did not submit message
                  description: >-
                    The user pressed Enter in the chat composer expecting the
                    message to send. The message stayed in the input field.
      responses:
        '201':
          description: Observations created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationBatchCreateResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: Project not found or key not authorized for this project
components:
  schemas:
    ObservationBatchCreate:
      type: object
      required:
        - user_id
        - interaction_id
        - user_sentiment
        - observations
      properties:
        user_id:
          type: string
          maxLength: 512
          description: Your identifier for the end user
        interaction_id:
          type: string
          maxLength: 512
          description: Your identifier for the conversation thread
        user_sentiment:
          type: string
          description: Sentiment label applied to all items. See Sentiment docs.
          enum:
            - very negative
            - negative
            - neutral
            - positive
            - very positive
        observed_at:
          type: string
          format: date-time
          description: >-
            Optional timestamp applied to all items. Defaults to server time if
            omitted.
        observations:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/ObservationItemCreate'
          description: >-
            One or more observations (max 50 per request). Do not nest user_id,
            interaction_id, user_sentiment, or observed_at inside items.
    ObservationBatchCreateResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Observation'
    Error:
      type: object
      properties:
        detail: {}
    ObservationItemCreate:
      type: object
      required:
        - title
        - description
      properties:
        title:
          type: string
          maxLength: 500
          description: Short plain-text summary
        description:
          type: string
          description: Plain prose paragraphs with context
    Observation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
        interaction_id:
          type: string
        source:
          type: string
        title:
          type: string
        description:
          type: string
        user_sentiment:
          type: string
          description: Sentiment label.
          enum:
            - very negative
            - negative
            - neutral
            - positive
            - very positive
        observed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        config:
          type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Project API key prefixed with `ApiKey`, e.g. `Authorization: ApiKey
        c8.xxx`. Alternatively use header `X-Api-Key: c8.xxx`.

````