Developers
Build integrations and extend Upstat programmatically. The Upstat API follows Stripe-style conventions for consistency and developer experience.
Authentication
Generate API tokens and configure permissions.
Error Handling
Error types, codes, and troubleshooting.
Rate Limits
Request limits and retry strategies.
API Reference
Complete endpoint documentation.
Quick Start
Base URL
All API requests use:
https://api.upstat.ioAuthentication
Authenticate using a Bearer token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...API tokens are account-scoped with configurable permissions per resource. Create and manage tokens in Settings > API.
Permissions: Each token has granular CRUD permissions for resources:
| Resource | Permissions |
|---|---|
| Monitors | read, create, update, delete |
| Incidents | read, create, update, delete |
| Heartbeats | read, create, update, delete |
| Catalog | read, create, update, delete |
| On-Call | read, create, update, delete |
| Runbooks | read, create, update, delete |
| Status Pages | read, create, update, delete |
| Maintenance | read, create, update, delete |
See Authentication for details on creating and managing API tokens.
Versioning
The API uses date-based versioning via the Upstat-Version header:
Upstat-Version: 2025-01-15| Behavior | Description |
|---|---|
| Account pinning | Your account is pinned to the current version when you create your first API token |
| Header override | Use Upstat-Version header to request a specific version |
| Response header | Every response includes Upstat-Version indicating the version used |
Breaking changes are released twice yearly. New endpoints and optional fields are added without version changes.
Request Format
Content-Type: application/json
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <jwt_token> |
Content-Type | For POST/PATCH | Must be application/json |
Idempotency-Key | Recommended for POST | UUID v4, max 255 characters |
Upstat-Version | Optional | Override account’s pinned version |
Field Naming:
| Location | Convention | Example |
|---|---|---|
| JSON fields | snake_case | interval_seconds, created_at |
| URL paths | kebab-case | /status-pages, /on-call |
| Query params | snake_case | starting_after, created_gte |
Response Format
All responses are JSON. Single objects include an object field identifying the type:
Conventions:
| Convention | Format | Example |
|---|---|---|
| IDs | Prefixed strings | mon_NffrFeUfNV2Hib |
| Timestamps | Unix epoch (seconds) | 1680893993 |
| Booleans | Lowercase | true, false |
| Empty values | Explicit | null, {}, [] |
ID Prefixes:
| Resource | Prefix | Example |
|---|---|---|
| Monitor | mon_ | mon_NffrFeUfNV2Hib |
| Incident | inc_ | inc_1MtGwK2eZvKYlo |
| Alert | alt_ | alt_3Ln0H22eZvKYlo |
| Check | chk_ | chk_2Pm1J33fAvLZmp |
| Status Page | stp_ | stp_4Qo2K44gBwMAno |
| API Token | tok_ | tok_5Rp3L55hCxNBop |
Request ID:
Every response includes a unique request ID for debugging:
Request-Id: req_NffrFeUfNV2HibInclude this ID when contacting support.
Pagination
Lists use cursor-based pagination with a wrapper object:
Parameters:
| Parameter | Default | Description |
|---|---|---|
limit | 10 | Number of objects to return (1-100) |
starting_after | - | Cursor: fetch objects after this ID |
ending_before | - | Cursor: fetch objects before this ID |
starting_after and ending_before are mutually exclusive.
Example:
# First page
GET /monitors?limit=10
# Next page (using last ID from previous response)
GET /monitors?limit=10&starting_after=mon_NffrFeUfNV2Hib
# Previous page
GET /monitors?limit=10&ending_before=mon_QwertYuiOp1234Idempotency
For safe retries on POST requests, include an Idempotency-Key header:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000| Behavior | Description |
|---|---|
| Storage | Keys are stored for 24 hours |
| Replay | Subsequent requests with same key return cached response |
| Conflict | Different parameters with same key return 409 Conflict |
When a cached response is returned, the response includes:
Idempotent-Replayed: trueMetadata
User-defined key-value pairs can be attached to objects:
Limits:
| Constraint | Value |
|---|---|
| Maximum keys | 50 per object |
| Key length | Max 40 characters |
| Value length | Max 500 characters |
Updating: Use PATCH to update individual keys. Set a key to empty string "" to remove it.
Warning: Never store sensitive data (credentials, PII) in metadata.
Errors
Errors are wrapped in an error object:
Error Types:
| Type | HTTP Status | Description |
|---|---|---|
api_error | 500 | Internal server error |
authentication_error | 401 | Invalid API key |
invalid_request_error | 400, 404 | Invalid parameters or resource not found |
rate_limit_error | 429 | Too many requests |
permission_error | 403 | Insufficient permissions |
idempotency_error | 409 | Idempotency key conflict |
HTTP Status Codes:
| Code | Meaning |
|---|---|
| 200 | OK - Successful GET or PATCH |
| 201 | Created - Successful POST |
| 204 | No Content - Successful DELETE |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn’t exist |
| 409 | Conflict - Idempotency key conflict |
| 422 | Unprocessable Entity - Validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Include Request-Id for support |
See Error Handling for the full error code reference.
Rate Limits
API requests are rate limited per token and account:
| Scope | Window | Limit |
|---|---|---|
| Per API Token | 1 minute | 1,000 requests |
| Per API Token | 1 hour | 10,000 requests |
| Per Account | 1 minute | 5,000 requests |
Response Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200When rate limited (429):
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200See Rate Limits for retry strategies.
Resources
| Resource | Description |
|---|---|
| Monitors | Create, update, and manage uptime monitors |
| Incidents | Trigger, update, and resolve incidents |
| Heartbeats | Manage heartbeat monitors and pings |
| On-Call | Manage schedules and rotations |
| Status Pages | Update components and post incidents |
| Catalog | Manage services and dependencies |
| Runbooks | Runbook documentation and procedures |
| Maintenance | Maintenance windows and schedules |