Jitsu Bulk / Batch API

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