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

# API Reference

> Complete reference for the Uplint REST API — files, contexts, and API keys.

## Base URL

```
https://api.uplint.dev
```

For local development:

```
http://localhost:8000
```

## Authentication

All endpoints require authentication via the `Authorization` header. Pass an API key or JWT token:

```bash theme={null}
Authorization: Bearer ul_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

See the [Authentication guide](/authentication) for details on API key scopes, lifecycle, and security best practices.

## Response format

All responses follow a consistent envelope format:

**Success:**

```json theme={null}
{
  "status": "SUCCESS",
  "message": "Human-readable description",
  "data": { ... },
  "timestamp": "2026-02-10T12:00:00Z"
}
```

**Error:**

```json theme={null}
{
  "status": "ERROR",
  "message": "Human-readable error description",
  "errors": ["Specific error detail"],
  "timestamp": "2026-02-10T12:00:00Z"
}
```

**Paginated lists** include a `pagination` object:

```json theme={null}
{
  "status": "SUCCESS",
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 47,
    "total_pages": 3
  }
}
```

## API groups

<CardGroup cols={2}>
  <Card title="Files" icon="file" href="/api-reference/files/upload">
    Upload, list, download, inspect, and delete files.
  </Card>

  <Card title="File Contexts" icon="folder-open" href="/api-reference/contexts/create">
    Create and manage upload pipelines with validation rules.
  </Card>

  <Card title="Storage Buckets" icon="database" href="/api-reference/storage/list">
    Register and route to multiple S3 buckets. Requires an `admin`-scoped key.
  </Card>

  <Card title="API Keys" icon="key" href="/api-reference/api-keys/create">
    Create, manage, and revoke scoped API keys.
  </Card>
</CardGroup>

## Rate limits

API-level rate limits apply per tenant. Context-level rate limits apply per file context and are configured when creating or updating a context.

When a rate limit is exceeded, the API returns a `429` status code.

## Status codes

| Code  | Description                                                    |
| ----- | -------------------------------------------------------------- |
| `200` | Success                                                        |
| `201` | Resource created                                               |
| `400` | Bad request — validation failed or file rejected               |
| `401` | Unauthorized — missing or invalid credentials                  |
| `404` | Resource not found                                             |
| `409` | Conflict — resource already exists or invalid state transition |
| `422` | Validation error — request body failed schema validation       |
| `429` | Rate limit exceeded                                            |