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
403	`usage_limit_exceeded`	The free trial has ended, so recording (bots, uploads, automation changes) is blocked
403	`upload_limit_exceeded`	The plan’s daily API upload limit is used up
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
Send the note-taker to a meeting link	10 requests/minute and 60 requests/hour per user

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.

Plan limits

On top of the limits above, each account has daily limits that depend on its plan. They apply per user across all of that user’s API tokens and MCP connections. Credits stay the usage budget: a free trial ends when its credits are used up.

Plan	API and MCP calls per day	API uploads per day	Recording (bots, uploads)
Free, active trial	100	5 files	While trial credits remain
Free, trial ended	100	Blocked	Blocked
Pro / Team	250	5 files	Allowed
Max / Business	No daily limit	100 files	Allowed
Enterprise	No daily limit	100 files, adjustable by contract	Allowed

The call window lasts 24 hours from its first request, and the upload count resets at 00:00 UTC. Going over the daily call limit returns 429 with Retry-After, and going over the upload limit returns 403 upload_limit_exceeded. Accounts on a limited plan also get an X-Timeless-Notice response header (and, over MCP, an extra text block on each tool result) with a link to upgrade.

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`
Team	`team_`	`team_abc123`
Permission	`perm_`	`perm_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

Settings

Rooms

Team

Documents

Upload

Webhooks

Authentication

Errors

Rate limiting

Plan limits

Resource IDs

​Authentication

​Errors

​Rate limiting

​Plan limits

​Pagination

​Resource IDs

​Expanding related resources

Authentication

Errors

Rate limiting

Plan limits

Pagination

Resource IDs

Expanding related resources