> ## 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. # Update a council sage (soft update) > Creates a new version of the council sage. ## OpenAPI ````yaml /openapi/private/specs/services/pl.yml patch /pl/council-sage/{council_sage_id} openapi: 3.1.0 info: title: Prompt Library (PL) Service API description: > The central configuration store for sages, council sages, contexts, and results. All entities use versioned soft-delete with history tables for full audit trails. ## 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. ## Sub-Modules - **Sage** -- Base sage templates (interview configurations) - **Council Sage** -- Council-specific sage instances with customizations - **Context** -- Job description and role analysis data - **Results** -- Evaluation template configurations (scoring, recommendations) ## Data Model - **Versioning** -- Every update creates a new version (soft update) - **Soft Delete** -- Delete sets `active = false` rather than removing rows - **History Tables** -- Each entity has a parallel `_history` table - **Relationships** -- Council Sage references Sage, Context, Results, and Status ## Query Patterns - `?details=1` -- Include full object details in list responses - `?active=true|false|all` -- Filter by active status - `?custom=1` -- Filter for custom sages only - List endpoints return `{id: object}` maps; get endpoints return single objects version: 1.0.0 contact: name: Platform Team servers: - url: '{protocol}://{host}:{port}' description: Prompt Library Service variables: protocol: default: https enum: - http - https host: default: localhost port: default: '5000' security: [] tags: - name: Sage description: Base sage template CRUD - name: Council Sage description: Council-specific sage instance CRUD and prompts - name: Context description: Job context CRUD (PL database) - name: Results description: Results template CRUD - name: Service description: Health checks and initialization paths: /pl/council-sage/{council_sage_id}: patch: tags: - Council Sage summary: Update a council sage (soft update) description: Creates a new version of the council sage. operationId: updateCouncilSage parameters: - $ref: '#/components/parameters/CouncilSageId' - $ref: '#/components/parameters/RequiredPermission_council_sage' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CouncilSageUpdate' responses: '200': description: Council sage updated content: application/json: schema: $ref: '#/components/schemas/CouncilSageResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: No JSON data provided '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: CouncilSageId: name: council_sage_id in: path required: true description: UUID of the council sage schema: type: string format: uuid example: c3d4e5f6-7890-4abc-def0-123456789abc RequiredPermission_council_sage: name: X-Permission-Info in: header required: false description: >- **Required JWT permission: `council_sage`** (informational only -- enforced server-side) schema: type: string schemas: CouncilSageUpdate: type: object properties: name: type: - string - 'null' role: type: - string - 'null' role_level: $ref: '#/components/schemas/RoleLevelEnum' instructions: type: - string - 'null' results_instructions: type: - string - 'null' intro_question: type: - string - 'null' duration: type: - integer - 'null' tone: type: - string - 'null' meta_data: type: - object - 'null' additionalProperties: true chat_avatar: type: - string - 'null' audio: type: - boolean - 'null' language_code: type: - string - 'null' followup_days: type: - integer - 'null' CouncilSageResponse: type: object description: Council sage record (from CouncilSageModel.to_dict()) properties: id: type: string format: uuid name: type: string role: type: string role_level: type: string instructions: type: - string - 'null' results_instructions: type: - string - 'null' context_id: type: string format: uuid intro_question: type: - string - 'null' duration: type: - integer - 'null' version: type: integer sage_id: type: string format: uuid council_id: type: string results_id: type: string format: uuid meta_data: type: - object - 'null' active: type: boolean tone: type: - string - 'null' status_id: type: string format: uuid chat_avatar: type: - string - 'null' language_code: type: - string - 'null' followup_days: type: - integer - 'null' audio: type: boolean is_demo: type: boolean is_internal: type: boolean language: type: boolean test_results: type: - object - 'null' ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message RoleLevelEnum: type: string enum: - entry - junior - mid - senior - principal - other description: | Experience level: - `entry` -- entry-level / intern - `junior` -- 0-2 years - `mid` -- 2-5 years - `senior` -- 5-10 years - `principal` -- 10+ years / staff - `other` -- fallback 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 apiKeyInsteadOfJwt: summary: API key sent to JWT-only endpoint value: error: Unauthorized - JWT token required, not API key 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 ````