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

# Organization API and token management

> API endpoints for token management, repository metrics, policy inspection, and run ingestion.

Raigal Cloud provides a REST API to query scores, inspect active policies, manage tokens, and ingest CLI run payloads.

## Authentication

All API requests must include a valid Bearer token in the `Authorization` header:

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

> [!NOTE]
>
> Generate API keys at [app.raigal.dev/settings](https://app.raigal.dev/settings) under **API Tokens**.

## Endpoints

### 1. Identity check

Verify the active token and return the authenticated user, organization, evaluation trial or license plan status, and allowed repository owners.

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

Response:

```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. Organization quality policy

Retrieve active quality thresholds and locked rules configured for the organization or a specific repository.

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

Response:

```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. Ingest CLI run

Submit an evaluation run payload generated by the CLI (`raigal ci` or `raigal scan`):

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

Request body (strict `Run` contract schema):

```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": []
  }
}
```

Response:

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

## Token management

Tokens can be created in the web dashboard or via the tokens API:

### Create API token

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

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

Response:

```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]
>
> Store your token when created. The full token string is shown once. Raigal Cloud stores a SHA-256 hash and cannot recover lost tokens.

### Dashboard and repository management

Repository management, branch tracking, and token revocation are available through the web interface at [app.raigal.dev/settings](https://app.raigal.dev/settings) using your authenticated browser session.


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