Introduction

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.

curl https://api.timeless.day/v1/meetings \
  -H "Authorization: Bearer YOUR_API_TOKEN"

You can generate API tokens from your Timeless dashboard. Tokens are 64-character hex strings. Keep them secret — treat them like passwords. If authentication fails, the API returns a 401 response:

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

Errors

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

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

Validation errors include a details array identifying the invalid fields:

{
  "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:

{
  "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).

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`

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

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.

Overview

Meetings

Rooms

Documents

Upload

Webhooks

Authentication

Errors

Rate limiting

Resource IDs

​Authentication

​Errors

​Rate limiting

​Pagination

​Resource IDs

​Expanding related resources

Authentication

Errors

Rate limiting

Pagination

Resource IDs

Expanding related resources