Endpoint
POST /api/v2/ingest
The V2 ingest endpoint is the primary entry point for all event data flowing into Contox. It accepts events from the MCP server, CLI, VS Code extension, and any custom integration.
Authentication
This endpoint uses HMAC-SHA256 signatures for authentication. See HMAC Signing for the complete signing process.
Required headers
| Header | Description |
|---|---|
Content-Type | Must be application/json |
X-Contox-Project | Your project ID |
X-Contox-Timestamp | Unix timestamp used in signature |
X-Contox-Signature | HMAC-SHA256 signature prefixed with sha256= |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
event | string | Yes | Event type identifier |
payload | object | Yes | Event-specific data |
Event types
The following event types are accepted:
| Event | Description |
|---|---|
session_save | Save session work with summary and changes |
scan_result | Codebase scan results |
git_digest | Git commit digest data |
context_update | Context creation or update |
memory_operation | Memory CRUD operation |
Example request
bash
curl -X POST https://contox.dev/api/v2/ingest \
-H "Content-Type: application/json" \
-H "X-Contox-Project: proj_abc123" \
-H "X-Contox-Timestamp: 1705312200" \
-H "X-Contox-Signature: sha256=a1b2c3d4..." \
-d '{
"event": "session_save",
"payload": {
"summary": "Implemented user authentication with JWT",
"changes": [
{
"category": "implementation",
"title": "JWT auth middleware",
"content": "Added auth middleware at src/middleware/auth.ts"
}
]
}
}'
Response
The endpoint returns 202 Accepted on success, indicating the event has been queued for processing:
json
{
"eventId": "evt_abc123def456",
"sessionId": "sess_xyz789"
}
| Field | Type | Description |
|---|---|---|
eventId | string | Unique identifier for the ingested event |
sessionId | string | The session this event was associated with |
Event processing
Ingested events are processed asynchronously:
- The raw event is stored immediately
- Associated blobs (diffs, content) are uploaded to storage
- The event is linked to an existing session or a new session is created (sessions have a 4-hour window)
- Events remain as raw data until enrichment is triggered
Enrichment is triggered separately via the session enrich endpoint.
Error responses
| Status | Error | Cause |
|---|---|---|
| 400 | Invalid request body | Malformed JSON or missing required fields |
| 401 | Invalid signature | HMAC signature verification failed |
| 401 | Timestamp expired | Timestamp older than 5 minutes |
| 404 | Project not found | Invalid project ID |
| 429 | Rate limit exceeded | Too many requests |
Next steps
- HMAC Signing -- How to sign ingest requests
- V2 Sessions -- Manage sessions and trigger enrichment
- V2 Pipeline Guide -- Understand the full event pipeline