Configuration surface for managing workspaces, sites/streams, write keys, destinations, and connections. In self-hosted Jitsu this is backed by the Console application and its configuration store; in Jitsu Cloud it is managed through the use.jitsu.com console. Programmatic management is not a stable, broadly published public REST contract, so it is documented here at the platform level.
openapi: 3.0.1
info:
title: Jitsu Event Ingestion API
description: >-
HTTP event ingestion API for Jitsu, the open-source real-time event data
pipeline and Segment alternative. Events are sent to POST /api/s/{type}
(browser) or POST /api/s/s2s/{type} (server-to-server) for page, track,
identify, and group events. Batches use POST /v1/batch (Segment-compatible
envelope) and large archive uploads use POST /api/s/bulk. Requests are
authenticated with a Write Key passed via the X-Write-Key header, HTTP
Basic auth, or a writeKey query parameter. The server URL below is the
Jitsu Cloud ingestion host; self-hosted deployments expose the same paths
on your own domain.
termsOfService: https://jitsu.com/tos
contact:
name: Jitsu
url: https://jitsu.com/
license:
name: MIT
url: https://github.com/jitsucom/jitsu/blob/main/LICENSE
version: '2.0'
servers:
- url: https://use.jitsu.com
description: Jitsu Cloud ingestion host (self-hosted deployments use your own domain)
security:
- WriteKeyHeader: []
- WriteKeyBasic: []
paths:
/api/s/{type}:
post:
operationId: ingestEvent
tags:
- Ingestion
summary: Ingest a single browser event of the given type.
description: >-
Accepts a single analytics event (page, track, identify, group, or the
generic event). Mirrors the Segment event shape.
parameters:
- name: type
in: path
required: true
description: Event type.
schema:
type: string
enum: [page, track, identify, group, event]
- name: writeKey
in: query
required: false
description: Write Key (keyId:keySecret) as an alternative to the header or Basic auth.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Event accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestResponse'
'401':
description: Missing or invalid Write Key.
/api/s/s2s/{type}:
post:
operationId: ingestServerEvent
tags:
- Ingestion
summary: Ingest a single server-to-server event of the given type.
description: >-
Server-to-server ingestion variant. Identical payload to /api/s/{type}
but intended for trusted backend callers; IP/UserAgent are not inferred
from the request and should be supplied in context.
parameters:
- name: type
in: path
required: true
schema:
type: string
enum: [page, track, identify, group, event]
- name: writeKey
in: query
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
responses:
'200':
description: Event accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestResponse'
'401':
description: Missing or invalid Write Key.
/v1/batch:
post:
operationId: ingestBatch
tags:
- Batch
summary: Ingest a batch of events (Segment-compatible).
description: >-
Accepts a Segment-compatible batch envelope containing a batch array of
events, with an optional top-level writeKey and shared context.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
responses:
'200':
description: Batch accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestResponse'
'401':
description: Missing or invalid Write Key.
/api/s/bulk:
post:
operationId: ingestBulk
tags:
- Batch
summary: Bulk-load an archive of events synchronously.
description: >-
Accepts a large multipart upload of events (field name "file") for
synchronous loading into destinations. Supports fallback=true to skip
malformed events instead of failing the whole batch.
parameters:
- name: fallback
in: query
required: false
description: When true, malformed events are skipped instead of failing the batch.
schema:
type: boolean
default: false
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: Newline-delimited JSON of events to load.
responses:
'200':
description: Bulk load accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestResponse'
'401':
description: Missing or invalid Write Key.
components:
securitySchemes:
WriteKeyHeader:
type: apiKey
in: header
name: X-Write-Key
description: Write Key in the form keyId:keySecret.
WriteKeyBasic:
type: http
scheme: basic
description: HTTP Basic auth with the Write Key as the username (password empty).
schemas:
Event:
type: object
description: A single analytics event following the Segment-style shape.
properties:
type:
type: string
enum: [page, track, identify, group]
description: Event classification.
event:
type: string
description: Event name (for track events).
userId:
type: string
description: Known user identifier.
anonymousId:
type: string
description: Anonymous (pre-identify) identifier.
properties:
type: object
additionalProperties: true
description: Custom event properties (track / page).
traits:
type: object
additionalProperties: true
description: User or group traits (identify / group).
groupId:
type: string
description: Group identifier (group events).
messageId:
type: string
description: Unique message identifier for deduplication.
timestamp:
type: string
format: date-time
description: Event timestamp (ISO 8601).
context:
$ref: '#/components/schemas/Context'
Context:
type: object
description: Contextual metadata attached to an event.
properties:
library:
type: object
additionalProperties: true
ip:
type: string
userAgent:
type: string
locale:
type: string
page:
type: object
additionalProperties: true
campaign:
type: object
additionalProperties: true
screen:
type: object
additionalProperties: true
traits:
type: object
additionalProperties: true
additionalProperties: true
Batch:
type: object
description: Segment-compatible batch envelope.
properties:
writeKey:
type: string
description: Optional top-level Write Key.
context:
$ref: '#/components/schemas/Context'
batch:
type: array
items:
$ref: '#/components/schemas/Event'
required:
- batch
IngestResponse:
type: object
description: Acknowledgement of accepted events.
properties:
ok:
type: boolean
receivedAt:
type: string
format: date-time
additionalProperties: true