openapi: 3.0.3
info:
  title: Koala Server-Side API
  description: >
    RESTful server-side API for sending batched events, visitor identifications,
    and account traits to Koala's intent data platform. Supports profile-level
    and account-level batch ingestion for use in backend services, data pipelines,
    and edge compute environments where the JavaScript snippet cannot run.
  version: 1.0.0
  contact:
    name: Koala Developer Docs
    url: https://getkoala.com/docs/developer-guides/server-side
  termsOfService: https://getkoala.com/legal/terms
servers:
  - url: https://api2.getkoala.com/web/projects/{publicApiKey}
    description: Koala collection endpoint (replace {publicApiKey} with your workspace public API key)
    variables:
      publicApiKey:
        default: my-public-api-key
        description: Your Koala workspace public API key

paths:
  /batch:
    post:
      operationId: sendProfileBatch
      summary: Send profile-level batch events, identifies, and page views
      description: >
        Ingests a batch of events, identify calls, and/or page views tied to a
        single profile (visitor). Each request must include either a `profile_id`
        (UUID v4 read from the `ko_id` cookie) or an `email`. A maximum of 30
        entries each of events, identifies, and page_views per request is
        enforced. All entries in a single request must belong to the same person.
      tags:
        - Profile Ingestion
      parameters:
        - name: publicApiKey
          in: path
          required: true
          description: Your Koala workspace public API key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileBatchRequest'
            examples:
              identify:
                summary: Identify a visitor
                value:
                  profile_id: "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba"
                  email: "person@example.com"
              trackEvent:
                summary: Send a custom event
                value:
                  profile_id: "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba"
                  email: "netto@getkoala.com"
                  events:
                    - message_id: "abc123-unique-id"
                      type: "track"
                      event: "Created Account"
                      properties: {}
                      sent_at: "2022-11-09T23:57:14.776Z"
              sendTraits:
                summary: Send visitor traits
                value:
                  profile_id: "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba"
                  email: "user@example.org"
                  identifies:
                    - type: "identify"
                      sent_at: "2023-11-30T02:51:36.840Z"
                      traits:
                        email: "user@example.org"
                        billing_plan: "pro"
                        vip: true
                        is_current_customer: true
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Bad request — missing required identifier or malformed payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or missing public API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests — rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []

  /accounts/batch:
    post:
      operationId: sendAccountBatch
      summary: Send account-level batch events and traits
      description: >
        Ingests a batch of identify calls (traits) and/or events associated with
        a company account rather than an individual visitor. Each request must
        include either an `account_id` or `domain`. Koala will create a new
        Account automatically if the domain has not been tracked before.
        Use the optional `group_id` inside each identify to disambiguate
        multiple tenants sharing the same domain.
      tags:
        - Account Ingestion
      parameters:
        - name: publicApiKey
          in: path
          required: true
          description: Your Koala workspace public API key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountBatchRequest'
            examples:
              accountTraits:
                summary: Send account traits
                value:
                  domain: "getkoala.com"
                  identifies:
                    - type: "identify"
                      traits:
                        billing_plan: "pro"
                        vip: true
                        headcount: 100
              accountTraitsMultiTenant:
                summary: Send traits for multiple tenant groups
                value:
                  domain: "getkoala.com"
                  identifies:
                    - type: "identify"
                      traits:
                        group_id: "development-team"
                        billing_plan: "free"
                        vip: false
                    - type: "identify"
                      traits:
                        group_id: "marketing-team"
                        billing_plan: "pro"
                        vip: true
              accountEvent:
                summary: Send an account-level event
                value:
                  domain: "getkoala.com"
                  events:
                    - message_id: "event-uuid-1234"
                      type: "track"
                      event: "Workspace Created"
                      properties:
                        workspace_id: "1234567890"
                        workspace_name: "Acme, Inc."
                      sent_at: "2022-11-09T23:57:14.776Z"
      responses:
        '200':
          description: Batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: Bad request — missing required identifier or malformed payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — invalid or missing public API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests — rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []

components:
  schemas:
    ProfileBatchRequest:
      type: object
      description: >
        Payload for the profile /batch endpoint. Must include at least one of
        `profile_id` or `email`. Optionally includes up to 30 each of
        `events`, `identifies`, and `page_views`.
      properties:
        profile_id:
          type: string
          format: uuid
          description: >
            UUID v4 anonymous visitor identifier read from the `ko_id` cookie set
            by the Koala JavaScript pixel.
          example: "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba"
        email:
          type: string
          format: email
          description: Known email address of the visitor for identity resolution.
          example: "person@example.com"
        events:
          type: array
          maxItems: 30
          description: Custom track events to associate with this profile.
          items:
            $ref: '#/components/schemas/TrackEvent'
        identifies:
          type: array
          maxItems: 30
          description: Identify calls carrying visitor trait data.
          items:
            $ref: '#/components/schemas/IdentifyCall'
        page_views:
          type: array
          maxItems: 30
          description: Page view events to associate with this profile.
          items:
            $ref: '#/components/schemas/PageView'
      anyOf:
        - required: [profile_id]
        - required: [email]

    AccountBatchRequest:
      type: object
      description: >
        Payload for the account /accounts/batch endpoint. Must include at least
        one of `account_id` or `domain`. Optionally includes `identifies` and
        `events` associated with the account.
      properties:
        account_id:
          type: string
          description: Koala internal account identifier.
          example: "acct_abc123"
        domain:
          type: string
          description: >
            The company domain (e.g. "example.com") used to identify or create
            the account. Koala creates a new Account if this domain is not yet
            tracked.
          example: "getkoala.com"
        identifies:
          type: array
          description: Account-level identify calls carrying trait data.
          items:
            $ref: '#/components/schemas/AccountIdentifyCall'
        events:
          type: array
          description: Account-level track events.
          items:
            $ref: '#/components/schemas/TrackEvent'
      anyOf:
        - required: [account_id]
        - required: [domain]

    TrackEvent:
      type: object
      description: A custom track event in the Segment-compatible format.
      required:
        - type
        - event
      properties:
        message_id:
          type: string
          description: >
            Optional idempotency key. If omitted, the event may be captured
            more than once on retry. Use a UUID or other unique string.
          example: "abc123-unique-id"
        type:
          type: string
          enum: [track]
          description: Must be "track".
        event:
          type: string
          description: Human-readable event name.
          example: "Created Account"
        properties:
          type: object
          description: Arbitrary key-value properties associated with the event.
          additionalProperties: true
        sent_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event was generated.
          example: "2022-11-09T23:57:14.776Z"

    IdentifyCall:
      type: object
      description: An identify call carrying visitor-level traits.
      required:
        - type
      properties:
        type:
          type: string
          enum: [identify]
          description: Must be "identify".
        sent_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the identify was generated.
          example: "2023-11-30T02:51:36.840Z"
        traits:
          type: object
          description: Arbitrary key-value traits to associate with the visitor.
          additionalProperties: true
          properties:
            email:
              type: string
              format: email
            billing_plan:
              type: string
            vip:
              type: boolean
            is_current_customer:
              type: boolean

    AccountIdentifyCall:
      type: object
      description: An identify call carrying account-level traits.
      required:
        - type
      properties:
        type:
          type: string
          enum: [identify]
          description: Must be "identify".
        sent_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the identify was generated.
        traits:
          type: object
          description: Arbitrary key-value traits to associate with the account.
          additionalProperties: true
          properties:
            group_id:
              type: string
              description: >
                Optional tenant disambiguator for companies with multiple groups.
              example: "development-team"
            billing_plan:
              type: string
            vip:
              type: boolean
            headcount:
              type: integer

    PageView:
      type: object
      description: A page view event in the Segment-compatible format.
      required:
        - type
      properties:
        message_id:
          type: string
          description: Optional idempotency key.
        type:
          type: string
          enum: [page]
          description: Must be "page".
        name:
          type: string
          description: Human-readable page name.
        properties:
          type: object
          description: Arbitrary properties including url, referrer, title, etc.
          additionalProperties: true
        sent_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the page view was captured.

    BatchResponse:
      type: object
      description: Successful batch acceptance response.
      properties:
        ok:
          type: boolean
          description: Indicates the batch was accepted.
          example: true

    ErrorResponse:
      type: object
      description: Error response body.
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code.

  headers:
    UserAgent:
      description: >
        Required. Identify your application to Koala. Requests without a
        User-Agent header may be flagged as bot traffic and not processed.
      schema:
        type: string
        example: "your-company-name/1.0.0"

tags:
  - name: Profile Ingestion
    description: Endpoints for sending events and traits tied to individual visitors (profiles).
  - name: Account Ingestion
    description: Endpoints for sending events and traits tied to company accounts.

externalDocs:
  description: Koala Developer Guides
  url: https://getkoala.com/docs/developer-guides/server-side