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

# API Overview

> RoLearn REST API reference

The RoLearn API provides programmatic access to all platform data — trending games, forecasts, genre analytics, and more.

## Base URL

```
https://rolearn.dev/api
```

## Authentication

RoLearn supports three authentication paths. Which one you use depends on the client.

<AccordionGroup>
  <Accordion title="Browser / web app — HttpOnly cookies + CSRF">
    When you sign in through the web app, the server sets three cookies:

    | Cookie            | Lifetime | Notes                                                          |
    | ----------------- | -------- | -------------------------------------------------------------- |
    | `rolearn_access`  | 15 min   | Access JWT. `HttpOnly` — JavaScript cannot read it.            |
    | `rolearn_refresh` | 30 days  | Refresh token, scoped to `Path=/api/auth/refresh`, `HttpOnly`. |
    | `rolearn_csrf`    | session  | JS-readable double-submit CSRF token.                          |

    Because the access token lives in an `HttpOnly` cookie, XSS cannot steal it.
    On every state-changing request (`POST`/`PUT`/`DELETE`) the client must echo
    the `rolearn_csrf` cookie value back in an `X-CSRF-Token` header — the server
    rejects the request otherwise. The browser sends the cookies automatically;
    you do **not** send an `Authorization` header from the web app.
  </Accordion>

  <Accordion title="Desktop / CLI / server-to-server — Bearer JWT">
    Non-browser clients authenticate with the access token as a bearer credential:

    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://rolearn.dev/api/auth/me
    ```

    The login endpoint returns the access token in the JSON body for these
    clients (browsers ignore it and use the cookie instead). Refresh via
    `POST /api/auth/refresh`.
  </Accordion>

  <Accordion title="Third-party apps — read-only API key">
    Programmatic read access uses an API key sent in the `X-API-Key` header:

    ```bash theme={null}
    curl -H "X-API-Key: rk_live_XXXX" https://rolearn.dev/api/trending
    ```

    Only keys with the `read` scope authenticate the public read API. Ingest
    keys (`sdk:ingest` / `ingest:telemetry`) are rejected here — they authenticate
    only the SDK ingest endpoints. API-key access carries its own generous read
    limits but no write features (no tracking, no Dev Lens, no revenue sim).
  </Accordion>
</AccordionGroup>

Some read-only endpoints (trending, market overview) work without any
authentication but return limited, free-tier data.

### Token lifecycle

* **Refresh:** `POST /api/auth/refresh` rotates the refresh token (single-use, replay-protected) and issues a fresh access token.
* **Logout:** `POST /api/auth/logout` bumps the account's token version, revoking all existing sessions durably (single-active-session model).
* **OAuth sign-in:** Google, Roblox, Discord, and Twitter/X are supported via the standard authorization-code flow in addition to email + password.

<Note>
  The CSRF requirement and cookie model apply only to the first-party web app.
  Bearer and `X-API-Key` clients are not subject to CSRF (they carry no ambient
  cookie credential).
</Note>

## Rate Limits

Rate limits vary by plan and endpoint. The API returns standard HTTP 429 responses when limits are exceeded.

## Response Format

All responses are JSON. Successful responses return the data directly. Errors return:

```json theme={null}
{
  "detail": "Error description"
}
```

## Plan-Based Access

Many endpoints gate their response based on your subscription plan:

* **Explorer (Free)**: Limited data (e.g., 20 trending games, score-only ML predictions)
* **Builder**: Extended data (e.g., 100 trending games, detailed predictions)
* **Studio / Enterprise**: Full access (unlimited results, AI features, confidence intervals)

Some fields are restricted based on your plan level. Upgrade to access additional data.

## Endpoint surface

This reference documents the core market, game-intelligence, and account
endpoints. The full API is much larger — additional groups include:

| Area                                                                 | Prefix                              | Auth                     |
| -------------------------------------------------------------------- | ----------------------------------- | ------------------------ |
| Multiplatform SDK (ingest, analytics, segments, experiments, export) | `/api/sdk/*`                        | SDK ingest key / session |
| Brand Workspace (Enterprise)                                         | `/api/brand/*`, `/api/team-games/*` | session (Enterprise)     |
| Team & RBAC                                                          | `/api/team/*`                       | session (Enterprise)     |
| Intelligence (success patterns, DNA, creator feed, clones)           | `/api/intelligence/*`               | session                  |
| Keyword intelligence                                                 | `/api/keywords/*`                   | session                  |
| Update impact                                                        | `/api/update-impact/*`              | session                  |
| UGC catalog                                                          | `/api/ugc/*`                        | none (public)            |
| Marketplace                                                          | `/api/marketplace/*`                | session                  |
| Ad Performance (Enterprise)                                          | `/api/ads/*`                        | session / ads token      |
| RLBot                                                                | `/api/rlbot/*`                      | session                  |
| Billing / checkout                                                   | `/api/billing/*`                    | session / webhook        |

<Note>
  The complete, always-current spec is served as OpenAPI at
  [`/openapi.json`](https://rolearn.dev/openapi.json). Filter by path prefix to
  find a specific group (e.g. everything under `/api/sdk`). The SDK endpoints are
  also documented on the dedicated [SDK docs](https://rolearn.dev/sdk-docs) site.
</Note>