HTTP API

You can use HTTP API to send data to Jitsu. This is useful if you want to send data from your backend.

Tip

In all examples below, replace your-jitsu-domain.com with your Jitsu installation domain, or domain linked to your Jitsu Cloud account.

Jitsu Cloud users may find domain in the top-right corner of Site's Setup Instruction page or attach custom domain for a specific Site and use it instead.

Authorization

Write Key authentication

Use X-Write-Key header to authenticate requests. The header should contain the write key of the site.

Basic authentication

Jitsu also supports basic authentication in the form of a base64 encoded username:password string.

Where Write Key must be provided as the username and the password field is left empty. E.g.: writeKey123: - despite empty password, the colon : is still required. After base64 encoding writeKey123: becomes d3JpdGVLZXkxMjM6Cg== and this is passed in the authorization header like so: Authorization: Basic d3JpdGVLZXkxMjM6Cg==.

Query parameter

You can also pass the writekey as a query parameter. This is useful for testing purposes, but not recommended for production use.

https://your-jitsu-domain.com/api/s/{event-type}?writekey=keyId:keySecret

Ingest endpoint

This endpoint can be used to send events to Jitsu:

https://your-jitsu-domain.com/api/s/{event-type}

Can be used both for browser and server-to-server events depending on Write Key type.

event-type could be:

  • page, track, identify or group
  • Use event as event_type if you want server to take actual event type from type field of the event payload

The endpoint accepts POST requests with events payload in JSON format.

Examples

curl --location 'https://your-jitsu-domain.com/api/s/page' \
--header 'Content-Type: application/json' \
--header 'X-Write-Key: keyId:keySecret' \
--data-raw '{
  "type": "page",
  "properties": {
    "title": "Example page event",
    "url": "https://example.com/",
    "path": "/",
    "hash": "",
    "search": "",
    "currency": "USD",
    "width": 1458,
    "height": 1186
  },
  "userId": "user@example.com",
  "anonymousId": "dBRu6l026JMy7mmUewl5WgCM",
  "timestamp": "2023-04-12T13:28:02.531Z",
  "sentAt": "2023-04-12T13:28:02.531Z",
  "messageId": "GBzdRBFz48ZnuUyASrVYUMKJ",
  "context": {
    "library": {
      "name": "jitsu-js",
      "version": "1.0.0"
    },
    "ip": "127.0.0.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/111.0",
    "locale": "en-US",
    "screen": {
      "width": 2304,
      "height": 1296,
      "innerWidth": 1458,
      "innerHeight": 1186,
      "density": 2
    },
    "traits": {
      "email": "user@example.com"
    },
    "page": {
      "path": "/",
      "referrer": "",
      "referring_domain": "",
      "host": "example.com",
      "search": "",
      "title": "Example page event",
      "url": "https://example.com/",
      "enconding": "UTF-8"
    },
    "campaign": {
      "name": "example",
      "source": "g"
    }
  },
  "receivedAt": "2023-04-12T13:28:02.531Z"
}'

Batch endpoint

This endpoint can be used to send multiple events in a single request. Can be used both for browser and server-to-server events depending on Write Key type.

Endpoint: https://your-jitsu-domain.com/v1/batch

This endpoint is compatible with Segment's batch endpoint and expects POST request with JSON payload in format:

{
  "batch": [
    {
      "type": "page",
      "properties": {
        "title": "Example page event",
        "url": "https://example.com/",
        ...
      },
      ...
    },
    ...
  ],
  "writeKey": "YOUR_WRITE_KEY",
  "context": {
    "device": {
      "type": "phone",
      ...
    }
  }
}

where:

  • batch - JSON array of events
  • writeKey - Write Key of the site
  • context - optional context object that will be merged with each event context

Synchronous Functions endpoint

This endpoint runs the functions pipeline configured for a single connection synchronously and returns the result in the response body. Unlike the ingest and batch endpoints — which accept the event and process it asynchronously — this endpoint waits for the function pipeline to finish and returns the transformed event(s), per-function execution status, and any console output produced by the functions.

This is useful for testing functions, or for use cases where you need the transformed event back in the same request (for example, server-side enrichment).

Endpoint: https://your-jitsu-domain.com/api/funcs/{conId}

where {conId} is the Connection ID that links a Site (stream) to a destination. The connection must belong to the stream identified by the provided Write Key, and must have at least one function configured.

The endpoint accepts a POST request with a single Jitsu event in JSON format. Authorization works exactly the same as for the other HTTP endpoints — see Authorization above (Write Key via the X-Write-Key header, Basic auth, Authorization: Bearer, or the writekey query parameter).

Example

curl --location 'https://your-jitsu-domain.com/api/funcs/con_abc123' \
--header 'Content-Type: application/json' \
--header 'X-Write-Key: keyId:keySecret' \
--data-raw '{
  "type": "track",
  "event": "Button Clicked",
  "messageId": "msg-123",
  "anonymousId": "anon-456",
  "properties": {
    "buttonName": "signup"
  }
}'

Response

On success (HTTP 200) the endpoint returns a JSON object:

{
  "events": [
    {
      "type": "track",
      "event": "Button Clicked",
      "messageId": "msg-123",
      "anonymousId": "anon-456",
      "properties": {
        "buttonName": "signup",
        "enriched": true
      }
    }
  ],
  "execLog": [
    { "eventIndex": 0, "functionId": "func-abc", "ms": 12.5 }
  ],
  "logs": [
    {
      "level": "info",
      "functionId": "func-abc",
      "functionType": "udf",
      "message": "Processing event",
      "args": [],
      "timestamp": "2026-03-10T12:00:00Z"
    }
  ]
}

where:

  • events - resulting events after the function pipeline runs. Usually a single-element array with the transformed event; an empty array means the event was dropped by a function.
  • execLog - execution status of each function in the pipeline. Each entry contains the functionId, the eventIndex it applies to, execution time in milliseconds (ms), an optional error object (name, message) if the function failed, and a dropped flag if the function dropped the event.
  • logs - console log entries (console.log, console.error, etc.) emitted by the functions, including level, functionId, functionType, message, args and timestamp.

If the connection has no functions configured, the endpoint responds with 204 No Content and no body.

Status codes

CodeMeaning
200Functions executed successfully. Response body contains the result described above.
204The connection has no functions configured. No body is returned.
400Bad request — wrong Content-Type, unreadable body, malformed JSON, or event processing error.
401The stream or connection could not be found for the provided Write Key.
500Internal error, or an error returned by the functions server.
504The functions server timed out while executing the pipeline.

Error responses have the shape { "error": "<message>" }. The message may include a short error ID for masked internal errors, e.g. error# a1b2c3: functions server error.