> ## 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.

# Listar roles

> Devuelve todos los roles de tu organización: los integrados (Admin, Editor, Viewer, Billing) y los personalizados, cada uno con su matriz de permisos resuelta. Usa el `role_id` para asignar un rol mediante invitaciones o actualizaciones de miembros. Requiere una clave de API global.



## OpenAPI

````yaml es/api-reference/openapi.json get /api/v1/roles
openapi: 3.1.0
info:
  title: API de AthenaHQ
  description: >-
    La API de AthenaHQ ofrece acceso programático para gestionar tus sitios web
    y consultas para optimizar el contenido con IA.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
  - url: https://api.athenahq.ai
    description: Servidor de producción
security:
  - apiKey: []
tags:
  - name: Basics
    description: Operaciones principales de la API para gestionar sitios web y consultas
  - name: Metrics
    description: Endpoints de métricas y análisis para monitorizar la visibilidad en IA
  - name: Billing
    description: Endpoints de facturación y créditos para gestionar el uso
  - name: Team Management
    description: Endpoints para gestionar miembros del equipo e invitaciones
  - name: Groups
    description: Endpoints para gestionar grupos de sitios web
  - name: Content
    description: >-
      Endpoints para acceder a los datos del centro de contenidos: pestañas, URL
      monitorizadas y desglose de consultas por URL.
  - name: Pitch Workspace
    description: >-
      Endpoints para acceder a los informes del espacio de propuestas:
      ejecuciones de propuestas con alcance de organización, con competidores,
      consultas, atributos y métricas agregadas.
  - name: Knowledge Base
    description: >-
      Endpoints para leer la base de conocimientos de la marca: datos aprobados
      sobre la marca y los pilares que los organizan.
paths:
  /api/v1/roles:
    get:
      tags:
        - Team Management
      summary: Listar roles
      description: >-
        Devuelve todos los roles de tu organización: los integrados (Admin,
        Editor, Viewer, Billing) y los personalizados, cada uno con su matriz de
        permisos resuelta. Usa el `role_id` para asignar un rol mediante
        invitaciones o actualizaciones de miembros. Requiere una clave de API
        global.
      operationId: listRoles
      responses:
        '200':
          description: Respuesta correcta con la lista de roles
          content:
            application/json:
              schema:
                type: object
                required:
                  - roles
                properties:
                  roles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        '401':
          description: 'Sin autorización: falta la clave de API o no es válida'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'Acceso denegado: se requiere una clave de API global'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Forbidden: global API key required'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    Role:
      type: object
      description: >-
        Rol disponible en tu organización: un rol integrado del sistema o un rol
        personalizado.
      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: >-
            Identificador único del rol. Se puede usar como `role_id` en
            invitaciones y actualizaciones de roles. Los roles integrados usan
            ID centinela con formato GUID (p. ej.,
            `00000000-0000-0000-0000-000000000001`), no UUID RFC 4122.
        name:
          type: string
          description: Nombre visible del rol
          example: Content Manager
        slug:
          type: string
          description: Nombre normalizado del rol (p. ej., 'admin', 'content-manager')
          example: content-manager
        is_system:
          type: boolean
          description: >-
            Indica si es un rol integrado del sistema (Admin, Editor, Viewer,
            Billing). Los roles del sistema no se pueden editar ni eliminar.
        permissions:
          $ref: '#/components/schemas/PermissionMatrix'
        created_at:
          type: string
          description: Cuándo se creó el rol
    Error:
      type: object
      description: Objeto de respuesta de error
      required:
        - error
      properties:
        error:
          type: string
          description: Mensaje de error que describe qué ha fallado
          example: Unauthorized
    PermissionMatrix:
      type: object
      description: >-
        Niveles de acceso por categoría de un rol. Todas las categorías tienen
        al menos 'view'; las omitidas al crear o actualizar tienen 'view' por
        defecto.
      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: >-
        Clave de API para autenticarse. Puedes crear una
        [aquí](https://app.athenahq.ai/organization?tab=api).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.