API Reference

The Inslytic Ingestion API accepts events via HTTP. Use this to send events from any language or platform — not just the official SDKs.

Download OpenAPI spec — use with Swagger UI, Postman, or any OpenAPI-compatible tool.

Base URL

https://api.inslytic.com

Authentication

All requests require a Bearer token in the Authorization header. The token is your project API key, found in the dashboard under Settings → Project.

Authorization: Bearer your-api-key

POST /v1/ingest

Sends one or more events for ingestion. Accepts up to 1,000 events per request.

Request

curl

curl -X POST https://api.inslytic.com/v1/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "events": [
      {
        "eventName": "page_viewed",
        "timestamp": "2026-02-16T10:30:00.000Z",
        "anonymousId": "anon-123",
        "sessionId": "sess-456",
        "consentGiven": true,
        "properties": {
          "path": "/pricing"
        },
        "pageUrl": "https://example.com/pricing",
        "pageTitle": "Pricing"
      }
    ]
  }'

Request body

The request body must contain an events array with 1-1,000 event objects.

Event fields

Parameter	Type	Required	Description
eventName	string	Required	Name of the event (e.g., "page_viewed", "button_clicked").
timestamp	string	Required	ISO 8601 UTC timestamp.
anonymousId	string	Required	Anonymous device/session identifier.
sessionId	string	Required	Session identifier.
consentGiven	boolean	Required	Whether the user has given consent for tracking.
userId	string \| null	Optional	Identified user ID. Null for anonymous events.
properties	Record<string, string>	Optional	Custom key-value pairs. Defaults to {}.
pageUrl	string	Optional	Full URL of the page.
pageTitle	string	Optional	Title of the page.
referrer	string	Optional	Referrer URL.
utmSource	string \| null	Optional	UTM source parameter.
utmMedium	string \| null	Optional	UTM medium parameter.
utmCampaign	string \| null	Optional	UTM campaign parameter.
deviceType	"desktop" \| "mobile" \| "tablet"	Optional	Device type.
browser	string	Optional	Browser name.
os	string	Optional	Operating system.

Response

On success (HTTP 202):

{
  "accepted": 1
}

Error responses

Parameter	Type	Required	Description
400	Bad Request	Optional	Invalid JSON or event validation failed. Response includes error details.
401	Unauthorized	Optional	Missing or invalid API key.
429	Too Many Requests	Optional	Rate limit exceeded. Wait and retry.

Validation error example

{
  "error": "Validation failed",
  "details": [
    "Event 0: eventName is required",
    "Event 0: timestamp is required"
  ]
}

Rate limits

The API uses a token bucket rate limiter per project. Each event in a request costs one token. The default limit is 1,000 events per minute per project.

Tokens refill every 60 seconds
Batch requests cost N tokens (one per event)
When rate-limited, you receive HTTP 429
Use exponential backoff when retrying

Health check

GET /health returns HTTP 200 with {"status":"ok"}. No authentication required.