openapi: 3.0.1
info:
  title: Jitsu Event Batch 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: []
tags:
- name: Ingestion
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.
components:
  schemas:
    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).