> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# Getting started

This page gets you to one authenticated request against `https://next-api.saturation.io/v1`, then walks the response shape.

## Get a token

Open Saturation and go to **Settings > Developers > API**. Create a personal token. The token acts as you in the workspace where you create it. See [Authentication](/authentication.md) and [Concepts](/concepts.md) for more.

## Make your first request

Send the token in the `Authorization` header on every request, formatted as `Bearer <token>`:

```bash
curl https://next-api.saturation.io/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

`GET /v1/me` returns the account behind the token.

## Understand the response

A request for one item returns that item directly:

```json
{
  "id": "usr_123",
  "type": "user",
  "name": "Your Name",
  "email": "you@example.com",
  "workspaces": [
    { "workspaceId": "ws_123", "workspaceRole": "admin" }
  ]
}
```

A list returns a `data` array. When `nextCursor` is present, pass it back to read the next page:

```json
{
  "data": []
}
```

Errors are wrapped, carrying a `success` flag, a machine-readable `code`, a human-readable `message`, and a `requestId`:

```json
{
  "success": false,
  "code": "not_found",
  "message": "Project prj_123 was not found.",
  "requestId": "req_abc"
}
```

The full response format and code list are in [Errors](/errors.md).

## Read your data

List your projects:

```bash
curl https://next-api.saturation.io/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Next

- [Quickstart](/quickstart.md): read budget totals and page transactions with TypeScript.
- [Pagination](/pagination.md): page through a `data` array with `nextCursor`.
- [Errors](/errors.md): error responses and status codes.