Ingest Contract

POST /ingest accepts batches of request events from the SDKs. Contract version 1.1 only adds optional fields to version 1, so SDKs written for v1 keep working unchanged.

Request

POST /ingest
X-Nolax-Key: nlx_proj_xxxxxxxxxxxx
Content-Type: application/json
Content-Encoding: gzip
X-Nolax-Batch-Id: 3f2b8a52-6d0e-4c43-9a43-5f6f0c7c9d11
X-Nolax-SDK: node/1.1.0

X-Nolax-Batch-Id and X-Nolax-SDK are optional. The body is JSON:

json

{
  "environment": "production",
  "events": [
    {
      "method": "GET",
      "path": "/api/users",
      "statusCode": 200,
      "responseTime": 142,
      "payloadSize": 1024,
      "ip": "203.0.113.1",
      "userAgent": "MyApp/1.0",
      "timestamp": "2026-10-12T10:30:00.000Z"
    }
  ]
}

Limits

| Field | Rule | | --- | --- | | events | 1 to 1,000 per request | | environment | production, staging or development, any case. prod, stage and dev are accepted | | method | A standard HTTP method, any case | | path | At most 256 characters. The server removes query strings, fragments and ; parameters | | statusCode | Integer from 100 to 599 | | responseTime | Milliseconds, zero or more, capped at 600,000 | | userAgent | At most 255 characters. Longer values are truncated | | ip | At most 64 characters | | timestamp | Within 24 hours in the past and 5 minutes in the future. Outside that range the server uses its own time |

ip and userAgent may be absent or null.

Responses

The server validates each event on its own. Valid events are accepted and invalid ones are counted and dropped, so one bad event does not lose a batch.

| Status | Meaning | | --- | --- | | 202 | Events accepted. The body reports accepted, rejected and up to five errors with the event index, field and reason | | 400 | The body is unreadable, events is missing, empty or over 1,000 entries, the environment is unknown, or no event was valid | | 401 | The API key is missing or invalid | | 429 | code: "PLAN_LIMIT". The monthly event limit for your plan is reached. Retrying does not help |

Example 202 body:

json

{
  "message": "Events accepted for processing",
  "count": 118,
  "accepted": 118,
  "rejected": 2,
  "errors": [{ "index": 5, "field": "path", "reason": "Path is empty" }]
}

Test it

bash

gzip -c payload.json > payload.json.gz
curl -i -X POST https://server.nolax.net/ingest \
  -H "X-Nolax-Key: $NOLAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @payload.json.gz

A 202 means the key and payload are good. See Batching and Retries for how the SDKs react to each status.