# 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 ```bash 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" }' ``` ```bash curl --location 'https://your-jitsu-domain.com/api/s/identify' \ --header 'Content-Type: application/json' \ --header 'X-Write-Key: abc123' \ --data-raw '{ "type": "identify", "userId": "user@example.com", "traits": { "email": "user@example.com" }, "anonymousId": "aTc2kpU1m9gMARgq9RAizRyj", "timestamp": "2023-04-12T13:28:47.743Z", "sentAt": "2023-04-12T13:28:47.743Z", "messageId": "PgLUzb855vhdmhROLXXGy9zP", "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/113.0", "locale": "en-US", "screen": { "width": 2304, "height": 1296, "innerWidth": 2304, "innerHeight": 1186, "density": 2 }, "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:47.743Z" }' ``` ```bash curl --location 'https://your-jitsu-domain.com/api/s/track' \ --header 'Content-Type: application/json' \ --header 'X-Write-Key: abc123' \ --data-raw '{ "type": "track", "event": "testEvent", "properties": { "testProp": "test event properties" }, "userId": "user@example.com", "anonymousId": "bKTtbVZw3yiqCJvCSJgjVeXp", "timestamp": "2023-04-12T13:29:04.690Z", "sentAt": "2023-04-12T13:29:04.690Z", "messageId": "voV6fulcZR4CTVnN89AnxFnC", "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:29:04.690Z" }' ``` ## 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](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/#batch) and expects POST request with JSON payload in format: ```json { "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