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

# Introduction

> Learn how to authenticate, handle errors, and paginate through the Timeless API.

The Timeless API is a REST API served over HTTPS. All requests and responses use JSON, and all endpoints require authentication.

**Base URL:**

```
https://api.timeless.day/v1
```

## Authentication

Authenticate by including your API token in the `Authorization` header using the `Bearer` scheme.

```bash theme={null}
curl https://api.timeless.day/v1/meetings \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

You can generate API tokens from your [Timeless dashboard](https://my.timeless.day/api-token). Tokens are 64-character hex strings. Keep them secret — treat them like passwords.

If authentication fails, the API returns a `401` response:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}
```

## Errors

The API uses standard HTTP status codes. All error responses share the same structure:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}
```

Validation errors include a `details` array identifying the invalid fields:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Request validation failed",
    "details": [
      {
        "field": "limit",
        "message": "Input should be less than or equal to 100"
      }
    ]
  }
}
```

| Status | Code             | Description                                  |
| ------ | ---------------- | -------------------------------------------- |
| 400    | `bad_request`    | Invalid request parameters or body           |
| 401    | `unauthorized`   | Missing or invalid API token                 |
| 403    | `forbidden`      | Token is valid but lacks permission          |
| 404    | `not_found`      | Resource does not exist or is not accessible |
| 429    | `rate_limited`   | Too many requests                            |
| 500    | `internal_error` | Unexpected server error                      |

## Rate limiting

Requests are rate limited per API token and IP address. The default limits are:

| Endpoint         | Limit              |
| ---------------- | ------------------ |
| Most endpoints   | 60 requests/minute |
| Webhook creation | 20 requests/minute |
| File upload      | 10 requests/minute |

Every response includes rate limit headers:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window   |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When you exceed the limit, the API returns `429` with a `Retry-After` header indicating how many seconds to wait.

## Pagination

List endpoints use cursor-based pagination. Responses include:

```json theme={null}
{
  "data": [...],
  "next_cursor": "eyJjcmV...",
  "has_more": true
}
```

Pass `cursor` as a query parameter to fetch the next page. Control page size with `limit` (1-100, default 25).

```bash theme={null}
curl "https://api.timeless.day/v1/meetings?limit=10&cursor=eyJjcmV..."  \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

When `has_more` is `false`, you have reached the end of the list.

## Resource IDs

All resources use prefixed IDs to make them easy to identify at a glance:

| Resource | Prefix  | Example       |
| -------- | ------- | ------------- |
| Meeting  | `mtg_`  | `mtg_abc123`  |
| Room     | `room_` | `room_abc123` |
| Document | `doc_`  | `doc_abc123`  |
| User     | `usr_`  | `usr_abc123`  |
| Speaker  | `spk_`  | `spk_abc123`  |
| Webhook  | `whk_`  | `whk_abc123`  |

## Expanding related resources

Some endpoints support an `expand` query parameter that includes related resources inline instead of requiring separate requests. For example, to include documents with meetings:

```bash theme={null}
curl "https://api.timeless.day/v1/meetings?expand=documents" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

When a field is expandable but not requested, it is omitted from the response entirely.