# API Reference

Base URL: `https://api.example.com/v1`

Authentication: `Authorization: Bearer <token>`

## Endpoints

### `GET /items`

List items.

**Query parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | int | no | Max results (default 20, max 100) |
| `cursor` | string | no | Pagination cursor |
| `filter` | string | no | Filter expression |

**Response `200`**

```json
{
  "items": [{"id": "it_123", "name": "Example"}],
  "nextCursor": "eyJpZCI6..."
}
```

### `POST /items`

Create an item.

**Body**

```json
{
  "name": "string (required)",
  "description": "string (optional)"
}
```

**Response `201`** – the created item object.

**Errors**

| Code | Meaning |
|------|---------|
| `400` | Invalid body |
| `401` | Missing or invalid token |
| `429` | Rate limited – respect `Retry-After` |

## Rate limits

100 requests/minute per token. Exceeding returns `429`.

## Changelog

| Version | Date | Change |
|---------|------|--------|
| v1 | 2026-01-01 | Initial release |