API Overview
Orbitr's REST API lets you programmatically manage sites, tasks, keywords, and analytics.
Base URL
All API requests are made to:
https://api.getorbitr.com/api/v1
Authentication
The Orbitr API uses JWT (JSON Web Token) authentication. Include your access token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN
See Authentication for details on obtaining tokens.
Request Format
- All request bodies must be JSON with
Content-Type: application/json - Query parameters are used for filtering and pagination
- Path parameters are used for resource identification
Response Format
All responses are JSON. Successful responses include the requested data directly:
{
"id": "abc123",
"name": "My Site",
"domain": "example.com"
}List endpoints return paginated results:
{
"items": [...],
"total": 42,
"page": 1,
"page_size": 20
}Error Handling
Errors return appropriate HTTP status codes with a JSON body:
{
"detail": "Resource not found"
}| Status Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request — check your parameters |
| 401 | Unauthorized — invalid or missing token |
| 403 | Forbidden — insufficient permissions |
| 404 | Not found |
| 422 | Validation error — request body doesn't match schema |
| 429 | Rate limited — slow down |
| 500 | Server error |
Rate Limiting
API requests are rate-limited per user. Current limits:
- Standard endpoints: 100 requests per minute
- Search/analytics endpoints: 30 requests per minute
When rate-limited, the API returns a 429 status code. Wait before retrying.
Pagination
List endpoints accept these query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
page_size | integer | 20 | Results per page (max 100) |
Versioning
The API is versioned via the URL path (/api/v1/). We maintain backward compatibility within a version and announce deprecations in advance.