Ingest API reference

The ingest web service accepts events from the Aurora browser extension, or during log ingestion, and writes them directly into ClickHouse database. Use this page for the full contract, responses, and validation steps.

Endpoint: POST http://server:8080/ingest

Endpoint details

  • Purpose: Receive JSON event bodies and forward them to ClickHouse.
  • Expected Content-Type: application/json from the extension, or calling the API to ingest logs.

Request schema

Each request contains a single JSON object representing one event:

{
  "browser_id": "8f92f550-b3c4-4f63-9d2d-9b4c4c7a2d11",
  "method": "GET",
  "url": "https://example.com/resource",
  "timestamp": "2024-05-18T12:01:10.123Z"
}

Responses

  • 204 No Content: Insert succeeded.
  • 400 Bad Request: Body could not be read from the client request.
  • 405 Method Not Allowed: Non-POST method.
  • 502 Bad Gateway: ClickHouse request failed or rejected the payload (for example, invalid JSON).

Operational notes

  • The server usually runs on port 8080 and depends on the ClickHouse health probe before accepting traffic.
  • Payloads are streamed to ClickHouse to avoid buffering multiple events.
  • Use curl -sSf -X POST http://server:8080/ingest -d '{"browser_id":"demo","method":"GET","url":"https://example.com","timestamp":"2024-05-18T12:01:10.123Z"}' to validate end-to-end writes during testing.