Base URL
All API requests are made to:
https://contox.dev/api
Every endpoint path documented in this reference is relative to this base URL. For example, the projects endpoint is accessible at https://contox.dev/api/projects.
Request format
The Contox API follows standard REST conventions:
- Content-Type: All request bodies must be sent as
application/json - Accept: All responses are returned as
application/json - Methods: Standard HTTP methods (
GET,POST,PATCH,DELETE) are used throughout
Response structure
Success responses
Successful responses return the appropriate HTTP status code (200, 201, 202) with a JSON body containing the requested data.
{
"id": "proj_abc123",
"name": "My Project",
"createdAt": "2025-01-15T10:30:00Z"
}
List endpoints return arrays:
[
{ "id": "proj_abc123", "name": "Project A" },
{ "id": "proj_def456", "name": "Project B" }
]
Error responses
All errors follow a consistent format:
{
"error": "A human-readable error message describing what went wrong"
}
Common HTTP status codes:
| Status | Meaning |
|---|---|
| 400 | Bad Request -- invalid parameters or body |
| 401 | Unauthorized -- missing or invalid authentication |
| 403 | Forbidden -- insufficient permissions |
| 404 | Not Found -- resource does not exist |
| 409 | Conflict -- resource already exists or state conflict |
| 429 | Too Many Requests -- rate limit exceeded |
| 500 | Internal Server Error -- something went wrong on our end |
Security headers
Every response includes the following security headers:
| Header | Value |
|---|---|
X-Content-Type-Options | nosniff |
X-Frame-Options | DENY |
Referrer-Policy | strict-origin-when-cross-origin |
Strict-Transport-Security | max-age=31536000; includeSubDomains |
CORS
Cross-Origin Resource Sharing is configured for the following origins:
https://contox.devhttps://www.contox.devhttps://app.contox.dev
Requests from other origins will be rejected by the browser.
Versioning
The V2 endpoints (under /api/v2/) represent the latest version of the API with enhanced capabilities including HMAC authentication, event-driven ingestion, and AI-powered enrichment. The V1 endpoints remain available and functional.
Next steps
- Authentication -- Learn how to authenticate your requests
- Rate Limits -- Understand usage limits and how to handle them
- Projects -- Start managing your projects