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

# API de la organización y gestión de tokens

> Endpoints de la API para gestión de tokens, métricas de repositorios, inspección de políticas e ingesta de ejecuciones.

Raigal Cloud proporciona una API REST para consultar puntuaciones, inspeccionar políticas activas, gestionar tokens e ingerir resultados de la CLI.

## Autenticación

Todas las solicitudes deben incluir un token Bearer válido en la cabecera `Authorization`:

```http theme={null}
Authorization: Bearer rgl_live_tu_clave_api_aqui
```

> [!NOTE]
>
> Genera claves de API en [app.raigal.dev/settings](https://app.raigal.dev/settings) en la sección **API Tokens**.

## Endpoints

### 1. Comprobación de identidad

Verifica el token activo y devuelve el usuario autenticado, organización, estado de la prueba o licencia, y propietarios de repositorios autorizados.

```http theme={null}
GET /v1/whoami
```

Respuesta:

```json theme={null}
{
  "user": {
    "id": "user_2tQ...",
    "email": "dev@acme.com"
  },
  "org": {
    "id": "org_2tQ...",
    "name": "Acme Engineering",
    "status": "active"
  },
  "plan": "active",
  "trial_started_at": null,
  "trial_ends_at": null,
  "allowed_owners": [
    {
      "id": 1234567,
      "login": "acme"
    }
  ]
}
```

### 2. Política de calidad de la organización

Recupera los umbrales de calidad y las reglas bloqueadas para la organización o para un repositorio concreto.

```http theme={null}
GET /v1/policy?repo=acme%2Fbackend-api
```

Respuesta:

```json theme={null}
{
  "version": 1,
  "hash": "7b8f9a2e...",
  "config": {
    "ci": {
      "failBelow": 80
    },
    "rules": {
      "ai-slop/swallowed-exception": "error"
    },
    "exclude": []
  },
  "locked": [
    "ci.failBelow",
    "rules.ai-slop/swallowed-exception"
  ]
}
```

### 3. Ingesta de ejecuciones de la CLI

Envía un informe de análisis generado por la CLI (`raigal ci` o `raigal scan`):

```http theme={null}
POST /v1/runs
Content-Type: application/json
```

Cuerpo de la solicitud (esquema estricto del contrato `Run`):

```json theme={null}
{
  "run_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
  "command": "ci",
  "repo": {
    "provider": "github",
    "slug": "acme/backend-api"
  },
  "owner_verified": true,
  "git": {
    "branch": "main",
    "head_sha": "e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3",
    "base_ref": "main"
  },
  "ci": {
    "provider": "github-actions",
    "run_url": "https://github.com/acme/backend-api/actions/runs/123456"
  },
  "flags": ["changes"],
  "cli_version": "0.2.5",
  "started_at": "2026-10-21T10:00:00.000Z",
  "ended_at": "2026-10-21T10:00:12.000Z",
  "exit_code": 0,
  "steps": [
    { "seq": 0, "name": "engine:ai-slop", "ok": true, "ms": 45 },
    { "seq": 1, "name": "engine:security", "ok": true, "ms": 32 }
  ],
  "report": {
    "score": 92,
    "scoreable": true,
    "files_scanned": 12,
    "findings": []
  }
}
```

Respuesta:

```json theme={null}
{
  "ok": true,
  "run_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a"
}
```

## Gestión de tokens

Los tokens se pueden crear en el panel web o mediante la API de tokens:

### Crear token de API

```http theme={null}
POST /api/tokens
Content-Type: application/json

{
  "name": "Production Deploy Runner"
}
```

Respuesta:

```json theme={null}
{
  "token": "rgl_live_8f3a9b1c7e2d...",
  "prefix": "rgl_live_8f3a",
  "name": "Production Deploy Runner",
  "id": "key_9b2e...",
  "created_at": "2026-10-21T10:00:00.000Z"
}
```

> [!WARNING]
>
> Guarda tu token nada más crearlo. El valor completo se muestra una sola vez. Raigal Cloud solo guarda el hash SHA-256 y no puede recuperar tokens perdidos.

### Gestión de repositorios y panel web

La gestión de proyectos, ramas activas y revocación de tokens se realiza desde la interfaz web en [app.raigal.dev/settings](https://app.raigal.dev/settings) con tu sesión autenticada del navegador.


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