Quick start
1
Create an API key
In the dashboard go to Settings > API Keys and create a key. See Authentication.
2
Make a request
3
Read the response
Every response is JSON with a
success flag. On success the payload is in data; on failure the problem is in error.Base URL
All API requests should be made to:API Version
The current public API version is 1.0. Version information is returned in theX-API-Version: 1.0 response header.
Versioning is metadata only at present: API URLs use the /api/... route prefix, not /api/v1/..., and clients do not need to send an X-API-Version request header.
Request Format
All requests use JSON for both request bodies and responses.Headers
Request Example
Response Format
All API responses follow a consistent format for predictable error handling and data access.Success Response
Successful requests return a200-299 HTTP status code with the following structure:
Error Response
Failed requests return a4xx or 5xx HTTP status code with this structure. details is optional and its shape depends on the error:
Paginated Response
Endpoints that paginate use one of two conventions, so check the specific endpoint’s reference page before assuming a shape. Offset-based (used by list endpoints such asGET /api/monitors) nests results and pagination metadata under data:
Pagination
Offset-based list endpoints, such asGET /api/monitors, accept:
Pagination Example
Rate Limiting
UptimeIO implements rate limiting to ensure fair access and service stability.Rate Limit Headers
Responses to API key requests include rate limit information in the headers:Rate Limit
API key requests are limited per organization, shared by all of its keys:
See Authentication for per-key limits.
Handling Rate Limits
If you exceed the rate limit, you’ll receive a429 Too Many Requests response with a Retry-After header (seconds until the window resets):
1
Check Rate Limit Headers
Monitor the
X-RateLimit-Remaining header to anticipate when you’re approaching limits.2
Wait for Retry-After
When rate limited, wait the number of seconds in the
Retry-After header before retrying:3
Avoid redundant requests
Use filters and pagination rather than fetching everything repeatedly.
HTTP Status Codes
The UptimeIO API uses standard HTTP status codes to indicate request success or failure:Request Examples
- curl
- JavaScript
- Python
- TypeScript
Common Patterns
Handling Errors
Always check thesuccess flag and handle errors gracefully:
Pagination Loop
Iterate through all results usinglimit/offset: