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

# Append a message to the screen

> Sends a candidate message to the AI and returns the AI's response.
Loads the screen history from Redis, sends the message through the
AI model with full conversation context, and saves the updated history.

If the interview duration has elapsed, the AI receives an ENDTIME signal.




## OpenAPI

````yaml /openapi/private/specs/services/screen.yml patch /screen/{screen_id}
openapi: 3.1.0
info:
  title: Screen Service API
  description: >
    Manages candidate screening interviews (screens). Handles the full interview

    lifecycle from creation through AI-driven conversation to results generation

    and identity verification.


    ## Authentication

    All endpoints require authentication via one of two methods:

    - **API Key**: Pass the key in the `X-Auth` header (service-to-service
    calls)

    - **JWT Token**: Pass a Bearer token in the `Authorization` header
    (user-facing calls)


    The required permission level is noted per endpoint.


    ## Screen Lifecycle

    1. **Create** -- Initialize a chat session

    2. **Start** -- Begin the screen with an opening prompt (returns screen_id,
    message, council_sage_id)

    3. **Append** -- Send candidate messages and receive AI responses (PATCH)

    4. **End** -- End the interview (auto or manual)

    5. **Results** -- Generate and retrieve evaluation results

    6. **Verify** -- Identity verification via image comparison


    ## Business Rules

    - Screens are backed by Redis for real-time chat history

    - Duration is enforced; messages sent after time expires trigger ENDTIME

    - Verification uses face detection and comparison scoring

    - Test screens simulate the full interview flow for sage validation

    - Results can be generated, refreshed, and regenerated
  version: 1.0.0
  contact:
    name: Platform Team
servers:
  - url: '{protocol}://{host}:{port}'
    description: Screen Service
    variables:
      protocol:
        default: https
        enum:
          - http
          - https
      host:
        default: localhost
      port:
        default: '5000'
security: []
tags:
  - name: Screen
    description: Screen interview lifecycle
  - name: Results
    description: Screen results and evaluation
  - name: Verify
    description: Identity verification
  - name: Test
    description: Test screen execution
  - name: Service
    description: Health checks and initialization
paths:
  /screen/{screen_id}:
    patch:
      tags:
        - Screen
      summary: Append a message to the screen
      description: >
        Sends a candidate message to the AI and returns the AI's response.

        Loads the screen history from Redis, sends the message through the

        AI model with full conversation context, and saves the updated history.


        If the interview duration has elapsed, the AI receives an ENDTIME
        signal.
      operationId: appendScreen
      parameters:
        - $ref: '#/components/parameters/ScreenId'
        - $ref: '#/components/parameters/RequiredPermission_screen'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  description: Candidate's message text
            example:
              content: I have 5 years of experience with Python and Django...
      responses:
        '200':
          description: AI response returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: AI's response message
              example:
                message: >-
                  That's great! Can you tell me more about a specific project
                  where you used Django at scale?
        '400':
          description: Missing screen ID or content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No JSON data provided
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Screen not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Screen not found
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - jwtAuth: []
components:
  parameters:
    ScreenId:
      name: screen_id
      in: path
      required: true
      description: UUID of the screen
      schema:
        type: string
        format: uuid
      example: d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a
    RequiredPermission_screen:
      name: X-Permission-Info
      in: header
      required: false
      description: >-
        **Required JWT permission: `screen`** (informational only -- enforced
        server-side)
      schema:
        type: string
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            noApiKey:
              summary: Missing API key
              value:
                error: Unauthorized - API key required
            invalidApiKey:
              summary: Invalid API key
              value:
                error: Unauthorized - Invalid API key
            noToken:
              summary: Missing JWT token
              value:
                error: Unauthorized - No valid token
            invalidToken:
              summary: Invalid or expired JWT
              value:
                error: Unauthorized3
            insufficientPermissions:
              summary: Token lacks required permission
              value:
                error: Unauthorized4
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal server error
  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: User JWT token passed in Authorization header

````