> ## Documentation Index > Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Custom Role > Updates a custom role's permission matrix. Every category is at least 'view' — omitted categories default to 'view'. System roles cannot be edited. The new matrix must not duplicate an existing role's. Requires a global API key. ## OpenAPI ````yaml /api-reference/openapi.json patch /api/v1/roles/{role_id} openapi: 3.1.0 info: title: AthenaHQ API description: >- AthenaHQ API provides programmatic access to manage your websites and prompts for AI-powered content optimization. version: 1.0.0 contact: email: support@athenahq.ai servers: - url: https://api.athenahq.ai description: Production server security: - apiKey: [] tags: - name: Basics description: Core API operations for managing websites and prompts - name: Metrics description: Metrics and analytics endpoints for tracking AI visibility - name: Billing description: Billing and credits endpoints for managing usage - name: Team Management description: Endpoints for managing team members and invitations - name: Groups description: Endpoints for managing groups of websites - name: Content description: >- Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL prompt breakdowns. - name: Pitch Workspace description: >- Endpoints for accessing pitch workspace reports — org-scoped pitch runs with competitors, prompts, attributes, and aggregate metrics. paths: /api/v1/roles/{role_id}: parameters: - name: role_id in: path required: true schema: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: >- The unique identifier of the role (a system role ID or a custom role ID) patch: tags: - Team Management summary: Update Custom Role description: >- Updates a custom role's permission matrix. Every category is at least 'view' — omitted categories default to 'view'. System roles cannot be edited. The new matrix must not duplicate an existing role's. Requires a global API key. operationId: updateRole requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRoleRequest' responses: '200': description: Role updated successfully content: application/json: schema: type: object required: - success - role properties: success: type: boolean example: true role: $ref: '#/components/schemas/Role' '400': description: Bad request - Invalid role ID format or permissions content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - Global API key required, or the role is a system role content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_global: value: error: 'Forbidden: global API key required' system_role: value: error: System roles can't be edited '404': description: Not found - Role does not exist in your organization content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Role not found '409': description: Conflict - Permissions duplicate an existing role's content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] components: schemas: UpdateRoleRequest: type: object description: Request body for updating a custom role's permissions required: - permissions properties: permissions: $ref: '#/components/schemas/PermissionMatrix' Role: type: object description: >- A role available in your organization — a built-in system role or a custom role. required: - role_id - name - slug - is_system - permissions - created_at properties: role_id: type: string pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ description: >- Unique identifier of the role. Usable as `role_id` in invites and member role updates. Built-in system roles use GUID-shaped sentinel IDs (e.g. `00000000-0000-0000-0000-000000000001`), not RFC 4122 UUIDs. name: type: string description: Display name of the role example: Content Manager slug: type: string description: Normalized name of the role (e.g. 'admin', 'content-manager') example: content-manager is_system: type: boolean description: >- Whether this is a built-in system role (Admin, Editor, Viewer, Billing). System roles cannot be edited or deleted. permissions: $ref: '#/components/schemas/PermissionMatrix' created_at: type: string description: When the role was created Error: type: object description: Error response object required: - error properties: error: type: string description: Error message describing what went wrong example: Unauthorized PermissionMatrix: type: object description: >- Per-category access levels for a role. Every category is at least 'view'; categories omitted on create/update default to 'view'. properties: content: type: string enum: - none - view - write prompts: type: string enum: - none - view - write competitors: type: string enum: - none - view - write analytics: type: string enum: - none - view - write integrations: type: string enum: - none - view - write brand_knowledge: type: string enum: - none - view - write team: type: string enum: - none - view - write billing: type: string enum: - none - view - write api: type: string enum: - none - view - write organization: type: string enum: - none - view - write securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- API key for authentication. You can create one [here](https://app.athenahq.ai/organization?tab=api). ````