API Reference
Complete REST API reference for Owlmetry. Base URL, authentication, and endpoint documentation.
Complete REST API reference for Owlmetry.
Base URL
All API endpoints are served from:
https://api.owlmetry.com/v1SDK event ingestion uses a separate subdomain:
https://ingest.owlmetry.com/v1Both subdomains route to the same Fastify server on port 4000. The split exists for operational clarity and independent rate limiting.
Authentication
Owlmetry supports two authentication methods:
JWT Cookie (Dashboard)
Used by the web dashboard. Obtained by verifying an email code via POST /v1/auth/verify-code. The server sets an httpOnly cookie named token with a 10-year maxAge — web sessions do not expire.
Cookie: token=eyJhbGciOiJIUzI1NiIs...Bearer Token (API Keys)
Used by SDKs, the CLI, and programmatic access. Pass the API key in the Authorization header:
Authorization: Bearer owl_agent_abc123...There are three key types:
| Type | Prefix | Purpose |
|---|---|---|
| Client | owl_client_ | SDK event ingestion (scoped to an app) |
| Agent | owl_agent_ | CLI and programmatic read/write access (scoped to a team) |
| Import | owl_import_ | Bulk historical data import via POST /v1/import (scoped to an app) |
Error Responses
All error responses follow a consistent format:
{
"error": "Description of what went wrong"
}Common HTTP status codes:
| Code | Meaning |
|---|---|
| 400 | Bad request -- missing or invalid parameters |
| 401 | Unauthorized -- missing or invalid credentials |
| 403 | Forbidden -- insufficient permissions or role |
| 404 | Not found -- resource does not exist or is not accessible |
| 409 | Conflict -- duplicate resource (e.g., slug already exists) |
| 410 | Gone -- invitation expired or already accepted |
| 429 | Rate limited -- too many requests |
Pagination
List endpoints use cursor-based pagination. Responses include:
{
"events": [...],
"cursor": "2024-01-15T10:30:00.000Z",
"has_more": true
}Pass the cursor value as a query parameter to fetch the next page. Default page size is 50, maximum is 200.
| Parameter | Type | Description |
|---|---|---|
limit | number | Items per page (1-200, default 50) |
cursor | string | Cursor from previous response for next page |
Rate Limiting
The ingest and events endpoints use an in-memory token bucket rate limiter:
- 100 tokens max per identity (API key, user, or IP)
- 10 tokens refilled per second
- One token consumed per request
When the limit is exceeded, the server returns 429 Too Many Requests with a Retry-After: 1 header.
Data Mode
Most read endpoints accept a data_mode query parameter to filter development vs. production data:
| Value | Behavior |
|---|---|
production | Only production events (default) |
development | Only development events (is_dev: true) |
all | Both production and development events |
Additional endpoints
Beyond the endpoints documented in this section, the API also exposes:
| Area | Notes |
|---|---|
| Attachments | Reserve, upload, list, download (signed URL), and delete event attachments; query per-project/user quota usage. |
| Integrations | Per-project third-party integrations (currently RevenueCat). Also covers the RevenueCat sync endpoints and the POST /v1/webhooks/revenuecat/:projectId webhook receiver. |
| MCP | POST /mcp, GET /mcp, DELETE /mcp — Model Context Protocol endpoint for AI coding agents. Authenticated with an owl_agent_* Bearer token. See the MCP docs. |