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

# API Reference

> REST API for Lyceum Cloud

The Lyceum Cloud REST API exposes every dashboard feature: launching runs and VMs, deploying inference, managing storage and secrets, billing, and account settings. Every endpoint is listed in the **Endpoints** group in the sidebar, generated directly from the OpenAPI spec.

## Base URL

```
https://api.lyceum.technology/api/v2/external
```

## Authentication

Every request takes a bearer token in the `Authorization` header. Two token types are accepted:

| Token       | Format       | Lifetime                                     | When to use                                            |
| ----------- | ------------ | -------------------------------------------- | ------------------------------------------------------ |
| **API key** | `lk_...`     | Long-lived, until revoked or expired         | CLI, CI, scripts, integrations                         |
| **JWT**     | Standard JWT | Short-lived, refreshable via `/auth/refresh` | Interactive sessions, dashboard, browser-based testing |

Generate API keys from the [API Keys](/docs/configuration/api-keys) page in the dashboard. The full key value is shown exactly once at creation, store it in a secret manager immediately.

```bash theme={null}
curl https://api.lyceum.technology/api/v2/external/billing/credits \
  -H "Authorization: Bearer lk_your_api_key"
```

## Organization context

Every billable resource (runs, VMs, deployments, balance, history) belongs to an [organization](/docs/account/organizations). The server resolves the org for each request in this order:

1. **API key org**, Keys created under `/orgs/{slug}/api-keys` carry the org. No header needed.
2. **`X-Org-Slug` header**, On JWT requests, pin the org by slug. The server verifies your membership.
3. **Default org**, If neither is present, the request falls back to the membership flagged as your default (auto-created at signup).

```bash theme={null}
# JWT + explicit org
curl https://api.lyceum.technology/api/v2/external/billing/credits \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "X-Org-Slug: acme"
```

## Login (JWT flow)

```bash theme={null}
curl -X POST https://api.lyceum.technology/api/v2/external/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

The response includes `access_token` and `refresh_token`. Pass the access token as `Authorization: Bearer <access_token>`. When it expires, call `POST /auth/refresh` with the refresh token to get a new pair.

## Validation errors

Endpoints return HTTP `422` with a structured `HTTPValidationError` body when the request payload is malformed or missing required fields. Other failures return standard HTTP status codes (`400`, `401`, `403`, `404`, `5xx`) with a `detail` field describing the error.

## Endpoint groups

The full endpoint list is in the sidebar under **Endpoints**, grouped by tag. Highlights:

| Group                                       | Purpose                                                         | Doc page                                                      |
| ------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
| **Authentication**                          | `/auth/login`, `/auth/refresh`                                  | [Quickstart](/docs/quickstart)                                |
| **Organizations**                           | `/orgs`, `/orgs/{slug}`, members, balance, transactions         | [Organizations](/docs/account/organizations)                  |
| **Org API Keys**                            | `/orgs/{slug}/api-keys/...`                                     | [API Keys](/docs/configuration/api-keys)                      |
| **Org Invites**                             | `/orgs/{slug}/invites/...`, `/invites/{token}`, `/invites/mine` | [Organizations](/docs/account/organizations#inviting-members) |
| **Streaming Execution**                     | Submit Python runs, fetch status, abort                         | [Launch a Run](/docs/serverless/launch-run)                   |
| **Docker Execution**                        | Submit Docker image runs                                        | [Launch a Run](/docs/serverless/launch-run)                   |
| **Docker Compose Execution**                | Submit Compose stacks                                           | [Launch a Run](/docs/serverless/launch-run)                   |
| **GPU Selection Execution**                 | Fan out across GPU types                                        | [Runs](/docs/serverless/runs)                                 |
| **Workload Management**                     | List, abort, stop runs                                          | [Runs](/docs/serverless/runs)                                 |
| **Execution Management**                    | Get/delete a run, fetch timing                                  | [Runs](/docs/serverless/runs)                                 |
| **Observability - Logs**                    | Loki-backed log queries                                         | [Logs](/docs/observability/logs)                              |
| **Observability - GPU Metrics**             | DCGM and system metrics per execution                           | [GPU & System Metrics](/docs/observability/metrics)           |
| **Machine Types**                           | Hardware catalogue and pricing                                  | [Launch a Run](/docs/serverless/launch-run)                   |
| **Pricing**                                 | Full price book across all meters (`/pricing`)                  | [Launch a Run](/docs/serverless/launch-run)                   |
| **User Quotas**                             | Hardware profiles your account can use                          | [Settings](/docs/account/settings)                            |
| **Storage Files** / **Storage Credentials** | Per-user S3 bucket                                              | [Storage](/docs/configuration/storage)                        |
| **Environment Variables**                   | Secrets injected into runs                                      | [Secrets](/docs/serverless/secrets)                           |
| **Dedicated Deployment External**           | Create, get, list, stop dedicated deployments                   | [Dedicated Inference](/docs/inference/dedicated)              |
| **Billing**                                 | Credits, history, invoices                                      | [Billing](/docs/account/billing)                              |
| **VMs**                                     | Provision and manage GPU virtual machines                       | [Your VMs](/docs/instances/vms)                               |

For end-to-end worked examples, submit a run, poll status, fetch logs and metrics, see [End-to-End API Workflow](/examples/api-integration).