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

# API Overview

> REST API for programmatic access to your Sluice data — jobs, queues, workers, and real-time events.

The Sluice API is served at `https://sluice.sh/api`. All endpoints return JSON and follow consistent error handling conventions.

## Authentication

All endpoints (except `/api/health`) require authentication. See the [Authentication](/api/authentication) page for details.

| Endpoint            | Auth method                                |
| ------------------- | ------------------------------------------ |
| `POST /api/ingest`  | API key via `Authorization: Bearer sk_...` |
| All other endpoints | Session cookie (dashboard)                 |

## Rate limits

The free tier allows 10,000 ingested events per day. The `POST /api/ingest` endpoint enforces this limit and returns `429` with a `Retry-After` header when exceeded.

Dashboard API endpoints (jobs, queues, workers) are not rate-limited in V0.

## Error format

All error responses follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed schema validation.",
    "docs_url": "https://docs.sluice.sh/troubleshooting/api-errors",
    "details": {}
  }
}
```

| Field            | Type      | Description                                                                          |
| ---------------- | --------- | ------------------------------------------------------------------------------------ |
| `error.code`     | `string`  | Machine-readable error code (e.g., `VALIDATION_ERROR`, `NOT_FOUND`, `UNAUTHORIZED`). |
| `error.message`  | `string`  | Human-readable description of what went wrong.                                       |
| `error.docs_url` | `string`  | Link to the relevant troubleshooting page.                                           |
| `error.details`  | `object?` | Additional context — field-level validation errors, for example.                     |

## HTTP status codes

| Code  | Meaning                                                                      |
| ----- | ---------------------------------------------------------------------------- |
| `200` | Success                                                                      |
| `201` | Resource created                                                             |
| `400` | Bad request — invalid JSON, schema validation failure, or invalid parameters |
| `401` | Unauthorized — missing or invalid API key / session                          |
| `404` | Resource not found                                                           |
| `409` | Conflict — resource already exists                                           |
| `429` | Rate limited or daily usage limit exceeded                                   |
| `500` | Internal server error                                                        |

## Pagination

The API uses two pagination styles:

**Cursor-based** (for jobs): Returns a `nextCursor` token. Pass it as the `cursor` query parameter to get the next page. Best for real-time data where new records are constantly being added.

```json theme={null}
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6Ij...",
    "limit": 50,
    "total": 1234
  }
}
```

**Page-based** (for queues, workers): Uses `page` and `limit` query parameters with a total count.

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "totalPages": 1
  }
}
```

## Endpoints

| Method | Path                                             | Description                       |
| ------ | ------------------------------------------------ | --------------------------------- |
| `POST` | [`/api/ingest`](/api/ingest)                     | Ingest events from SDK or agent   |
| `GET`  | [`/api/jobs`](/api/jobs/list)                    | List and search jobs              |
| `GET`  | [`/api/jobs/:id`](/api/jobs/get)                 | Get job detail with state history |
| `POST` | [`/api/jobs/:id/retry`](/api/jobs/retry)         | Retry a failed job                |
| `POST` | [`/api/jobs/:id/revoke`](/api/jobs/revoke)       | Revoke/cancel a job               |
| `POST` | [`/api/jobs/bulk/retry`](/api/jobs/bulk-retry)   | Retry multiple jobs               |
| `POST` | [`/api/jobs/bulk/revoke`](/api/jobs/bulk-revoke) | Revoke multiple jobs              |
| `GET`  | [`/api/queues`](/api/queues)                     | List queues with metrics          |
| `GET`  | [`/api/workers`](/api/workers)                   | List workers with status          |
| `GET`  | [`/api/events/stream`](/api/events-stream)       | Server-Sent Events stream         |
| `GET`  | [`/api/health`](/api/health)                     | Health check                      |