Jitsu Batch API

openapi: 3.0.1
info:
  title: Jitsu Event Ingestion Batch 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: []
tags:
- name: Batch
paths:
  /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:
  schemas:
    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
    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
    IngestResponse:
      type: object
      description: Acknowledgement of accepted events.
      properties:
        ok:
          type: boolean
        receivedAt:
          type: string
          format: date-time
      additionalProperties: true
    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'
  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).