Skip to main content

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