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

# API reference

> The Samsa public REST API — base URL, authentication, and conventions.

<Info>
  This page covers the conventions that apply to every endpoint. The full,
  endpoint-by-endpoint reference — generated from the API's OpenAPI specification —
  is in the groups in the sidebar:
  [Image Generation](/api-reference/images/overview),
  [Image Editing](/api-reference/edits/overview),
  [Video Generation](/api-reference/videos/overview),
  [Model Training](/api-reference/model-training/overview),
  [Models](/api-reference/models/overview), and
  [Account & Usage](/api-reference/account/overview). For a working end-to-end
  example, see the [quickstart](/quickstart).
</Info>

## Base URL

```
https://api.samsa.ai/public/v1
```

## Authentication

Every request must carry an organization API key as a bearer token:

```
Authorization: Bearer samsa_sk_your_key_here
```

Keys are organization-owned, scoped, and shown once at creation. See
[Create an API key](/quickstart#create-an-api-key) to get one.

## Conventions

* **Asynchronous jobs** — generation endpoints return `202 Accepted` with a job
  `id`; poll the matching `GET` endpoint for status, or supply a `webhook_url` to
  be notified on completion.
* **Statuses** — jobs move through `pending`, `processing`, and then a terminal
  `completed`, `failed`, or `cancelled`.
* **Scopes** — most endpoints require a scope on the key (for example,
  `images.generate`); `GET /me` needs only a valid key. A key missing a required
  scope receives `403`.
* **Errors** — non-2xx responses return a structured JSON error body with a
  `type`, `code`, `message`, and `request_id`.
* **Credits** — actions draw from the organization's credit pool; an exhausted
  pool returns `402`.
* **Rate limits** — requests are limited per key; exceeding the limit returns
  `429` with a `Retry-After` header.