> ## 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. # Start a screening interview > Begins the screening interview. Loads the council sage configuration, fetches the opening prompt, and initializes the chat history. Returns the screen ID, opening message, and council sage ID. Pass `?test=1` to flag this as a test screen. ## OpenAPI ````yaml /openapi/private/specs/services/screen.yml post /screen/start 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/start: post: tags: - Screen summary: Start a screening interview description: | Begins the screening interview. Loads the council sage configuration, fetches the opening prompt, and initializes the chat history. Returns the screen ID, opening message, and council sage ID. Pass `?test=1` to flag this as a test screen. operationId: startScreen parameters: - name: test in: query required: false description: Set to `1` to mark as test screen schema: type: integer enum: - 0 - 1 default: 0 - $ref: '#/components/parameters/RequiredPermission_screen' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartScreenRequest' example: council_sage_id: c3d4e5f6-7890-4abc-def0-123456789abc council_id: 6151186e-3b17-4fb2-a54d-ff327bf7a71a sage_name: Sage image: null responses: '200': description: Screen started with opening prompt content: application/json: schema: $ref: '#/components/schemas/StartScreenResponse' example: screen_id: d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a message: >- Hello! I'm Sage, and I'll be conducting your interview today. We have about 30 minutes together... council_sage_id: c3d4e5f6-7890-4abc-def0-123456789abc '400': description: Missing required fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noJsonBody: summary: No JSON payload value: error: No JSON data provided durationRequired: summary: Missing duration value: error: screen duration is required '401': $ref: '#/components/responses/Unauthorized' '404': description: Council sage not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Council sage not found '500': $ref: '#/components/responses/InternalError' security: - jwtAuth: [] components: parameters: RequiredPermission_screen: name: X-Permission-Info in: header required: false description: >- **Required JWT permission: `screen`** (informational only -- enforced server-side) schema: type: string schemas: StartScreenRequest: type: object required: - council_sage_id - council_id properties: council_sage_id: type: string format: uuid description: UUID of the council sage to use for screening council_id: type: string format: uuid description: UUID of the council sage_name: type: - string - 'null' description: Optional display name override for the sage image: type: - string - 'null' description: Base64-encoded reference image for verification StartScreenResponse: type: object properties: screen_id: type: string format: uuid description: UUID of the created screen message: type: string description: Opening prompt / greeting from the sage council_sage_id: type: string format: uuid description: UUID of the council sage used 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 ````