Getting started

To begin using the UptimeTea API, you'll need to understand a few key concepts.

Base URL

All API requests should be made to:

https://api.uptimetea.com

Authentication

Most endpoints require authentication using a Bearer token. Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Obtain your token by logging in via the authentication endpoints. Login tokens last 30 days. For long-running integrations, create an MCP token instead: it lasts 6 months and works as a Bearer token too.

Request bodies

Send JSON with a Content-Type: application/json header. Many endpoints expect the fields wrapped in the resource name, such as {"webhook": {"url": "..."}}. Each endpoint lists its body parameters with that prefix, like webhook.url.

HTTP status codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 200Successful request
• 400Bad request (validation errors)
• 401Unauthorized (invalid or missing token)
• 403Forbidden (your team role can't do this)
• 404Resource not found
• 429Rate limit exceeded
• 500Server error

Error response format

When an error occurs, the API returns a JSON object with an error message:

{
  "error": "Validation error message"
}

Rate limiting

Each API token can make 60 requests per minute. Requests without a token are counted per IP address. Health checks and the version endpoint are not limited.

Go over the limit and the API answers 429 Too Many Requests until the minute is up. The Retry-After header tells you how many seconds to wait before trying again:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded"
}

Wait for Retry-After seconds, then retry. Polling many watchers? Call List watchers once instead of fetching each watcher on its own.