> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Send events

> Send a batch of website (`web`), game (`app`) or server (`server`) events. Web and app events use the publishable key in `X-Publishable-Key` (1 to 50 events). Server events use the secret key as `Authorization: Bearer` (1 to 100 events, at most 256 KB). A batch is all server events or has no server events.



## OpenAPI

````yaml /api/openapi.json post /v0/events
openapi: 3.1.0
info:
  title: Manalens API
  version: 0.1.0
  description: >-
    The public API of Manalens: event ingestion, profile properties and the
    Query API. Success bodies are the resource, with no envelope. Errors use the
    `Error` format. See https://docs.manalens.dev/api/overview.
servers:
  - url: https://api.manalens.dev
    description: API
  - url: https://events.manalens.dev
    description: Event ingestion
security: []
tags:
  - name: Events
    description: Send website, game and server events
  - name: Profiles
    description: Set and delete profile properties
  - name: Query
    description: Read analytics reports with an API key
paths:
  /v0/events:
    post:
      tags:
        - Events
      summary: Send events
      description: >-
        Send a batch of website (`web`), game (`app`) or server (`server`)
        events. Web and app events use the publishable key in
        `X-Publishable-Key` (1 to 50 events). Server events use the secret key
        as `Authorization: Bearer` (1 to 100 events, at most 256 KB). A batch is
        all server events or has no server events.
      operationId: sendEvents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/WebEventBatch'
                - $ref: '#/components/schemas/ServerEventBatch'
      responses:
        '202':
          description: The events are accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The number of accepted events
                required:
                  - accepted
        '400':
          description: >-
            `INVALID_EVENT`: an event failed validation, and no event of the
            batch is accepted. `MIXED_CHANNELS`: the batch mixes server events
            with web or app events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`UNAUTHORIZED`: the key is missing, unknown, or in the wrong header'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `FORBIDDEN`: the origin or page URL does not match the project.
            `SECRET_KEY_FROM_BROWSER`, `SECRET_KEY_REQUIRED`,
            `PUBLISHABLE_KEY_REQUIRED` or `WORKSPACE_SUSPENDED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '`TOO_LARGE`: a server batch is larger than 256 KB'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`: the project sent too many events this minute'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before a retry
              schema:
                type: integer
      security:
        - PublishableKey: []
        - SecretKey: []
      servers:
        - url: https://events.manalens.dev
          description: Event ingestion
        - url: https://api.manalens.dev
          description: API
components:
  schemas:
    WebEventBatch:
      type: object
      properties:
        events:
          minItems: 1
          maxItems: 50
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - page
                  - track
                  - identify
              event:
                type: string
                minLength: 1
                maxLength: 128
              message_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              channel:
                type: string
                enum:
                  - web
                  - app
              version:
                type: string
                maxLength: 32
              original_timestamp:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
              context:
                anyOf:
                  - type: object
                    properties:
                      page:
                        type: object
                        properties:
                          path:
                            type: string
                            maxLength: 2048
                            format: starts_with
                            pattern: ^\/.*
                          title:
                            type: string
                            maxLength: 300
                          url:
                            type: string
                            maxLength: 2048
                            format: uri
                        required:
                          - path
                          - title
                          - url
                      referrer:
                        type: string
                        maxLength: 2048
                      utm_source:
                        type: string
                        maxLength: 255
                      utm_medium:
                        type: string
                        maxLength: 255
                      utm_campaign:
                        type: string
                        maxLength: 255
                      utm_term:
                        type: string
                        maxLength: 255
                      utm_content:
                        type: string
                        maxLength: 255
                      utm_id:
                        type: string
                        maxLength: 255
                      utm_source_platform:
                        type: string
                        maxLength: 255
                      utm_creative_format:
                        type: string
                        maxLength: 255
                      utm_marketing_tactic:
                        type: string
                        maxLength: 255
                      gclid:
                        type: string
                        maxLength: 255
                      gbraid:
                        type: string
                        maxLength: 255
                      wbraid:
                        type: string
                        maxLength: 255
                      fbclid:
                        type: string
                        maxLength: 255
                      msclkid:
                        type: string
                        maxLength: 255
                      ttclid:
                        type: string
                        maxLength: 255
                      twclid:
                        type: string
                        maxLength: 255
                      li_fat_id:
                        type: string
                        maxLength: 255
                      rdt_cid:
                        type: string
                        maxLength: 255
                      ScCid:
                        type: string
                        maxLength: 255
                      gad_source:
                        type: string
                        maxLength: 255
                      ref:
                        type: string
                        maxLength: 255
                      paid_source:
                        type: string
                        maxLength: 255
                      click_id:
                        type: string
                        maxLength: 255
                      locale:
                        type: string
                        maxLength: 32
                      utc_offset:
                        type: integer
                        minimum: -720
                        maximum: 840
                      library_name:
                        type: string
                        maxLength: 64
                      library_version:
                        type: string
                        maxLength: 32
                      app:
                        type: object
                        properties:
                          platform:
                            type: string
                            enum:
                              - windows
                              - macos
                              - linux
                              - web
                              - android
                              - ios
                              - other
                          storefront:
                            type: string
                            enum:
                              - steam
                              - itch
                              - epic
                              - gog
                              - app_store
                              - play
                              - other
                          app_version:
                            type: string
                            minLength: 1
                            maxLength: 32
                            pattern: ^[A-Za-z0-9._+\- ]+$
                          build:
                            type: string
                            minLength: 1
                            maxLength: 64
                            pattern: ^[A-Za-z0-9._+\- ]+$
                          engine:
                            type: string
                            enum:
                              - godot
                              - unity
                              - unreal
                              - other
                        required:
                          - platform
                        additionalProperties: false
                    required:
                      - page
                      - referrer
                    additionalProperties: false
                  - type: object
                    properties:
                      app:
                        type: object
                        properties:
                          platform:
                            type: string
                            enum:
                              - windows
                              - macos
                              - linux
                              - web
                              - android
                              - ios
                              - other
                          storefront:
                            type: string
                            enum:
                              - steam
                              - itch
                              - epic
                              - gog
                              - app_store
                              - play
                              - other
                          app_version:
                            type: string
                            minLength: 1
                            maxLength: 32
                            pattern: ^[A-Za-z0-9._+\- ]+$
                          build:
                            type: string
                            minLength: 1
                            maxLength: 64
                            pattern: ^[A-Za-z0-9._+\- ]+$
                          engine:
                            type: string
                            enum:
                              - godot
                              - unity
                              - unreal
                              - other
                        required:
                          - platform
                        additionalProperties: false
                      locale:
                        type: string
                        maxLength: 32
                      utc_offset:
                        type: integer
                        minimum: -720
                        maximum: 840
                      library_name:
                        type: string
                        maxLength: 64
                      library_version:
                        type: string
                        maxLength: 32
                    required:
                      - app
                    additionalProperties: false
              properties:
                default: {}
                type: object
                propertyNames:
                  type: string
                additionalProperties:
                  anyOf:
                    - type: string
                      maxLength: 1024
                    - type: number
                    - type: boolean
                    - type: 'null'
              traits:
                type: object
                propertyNames:
                  type: string
                  minLength: 1
                  maxLength: 100
                additionalProperties:
                  anyOf:
                    - type: string
                      maxLength: 1024
                    - type: number
                    - type: boolean
                    - type: 'null'
              user_id:
                type: string
                minLength: 1
                maxLength: 255
              anonymous_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              session_id:
                type: string
                minLength: 1
                maxLength: 64
                pattern: ^[A-Za-z0-9_.:-]+$
            required:
              - type
              - message_id
              - channel
              - version
              - original_timestamp
              - context
            additionalProperties: false
      required:
        - events
      additionalProperties: false
      description: Web and app events, with the publishable key
    ServerEventBatch:
      type: object
      properties:
        events:
          minItems: 1
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              channel:
                type: string
                const: server
              type:
                type: string
                enum:
                  - track
                  - identify
              event:
                type: string
                minLength: 1
                maxLength: 128
              message_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              original_timestamp:
                type: string
                format: date-time
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
              anonymous_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              user_id:
                type: string
                minLength: 1
                maxLength: 255
              session_id:
                type: string
                minLength: 1
                maxLength: 64
                pattern: ^[A-Za-z0-9_.:-]+$
              properties:
                default: {}
                type: object
                propertyNames:
                  type: string
                additionalProperties:
                  anyOf:
                    - type: string
                      maxLength: 1024
                    - type: number
                    - type: boolean
                    - type: 'null'
              traits:
                type: object
                propertyNames:
                  type: string
                  minLength: 1
                  maxLength: 100
                additionalProperties:
                  anyOf:
                    - type: string
                      maxLength: 1024
                    - type: number
                    - type: boolean
                    - type: 'null'
              context:
                type: object
                properties:
                  page:
                    type: object
                    properties:
                      path:
                        type: string
                        maxLength: 2048
                        format: starts_with
                        pattern: ^\/.*
                      title:
                        type: string
                        maxLength: 300
                      url:
                        type: string
                        maxLength: 2048
                        format: uri
                    additionalProperties: false
                  app:
                    type: object
                    properties:
                      platform:
                        type: string
                        enum:
                          - windows
                          - macos
                          - linux
                          - web
                          - android
                          - ios
                          - other
                      storefront:
                        type: string
                        enum:
                          - steam
                          - itch
                          - epic
                          - gog
                          - app_store
                          - play
                          - other
                      app_version:
                        type: string
                        minLength: 1
                        maxLength: 32
                        pattern: ^[A-Za-z0-9._+\- ]+$
                      build:
                        type: string
                        minLength: 1
                        maxLength: 64
                        pattern: ^[A-Za-z0-9._+\- ]+$
                      engine:
                        type: string
                        enum:
                          - godot
                          - unity
                          - unreal
                          - other
                    required:
                      - platform
                    additionalProperties: false
                  ip:
                    anyOf:
                      - type: string
                        format: ipv4
                        pattern: >-
                          ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$
                      - type: string
                        format: ipv6
                        pattern: >-
                          ^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$
                  user_agent:
                    type: string
                    minLength: 1
                    maxLength: 1024
                  country:
                    type: string
                    pattern: ^[A-Za-z]{2}$
                  locale:
                    type: string
                    maxLength: 32
                  device:
                    type: string
                    enum:
                      - desktop
                      - mobile
                      - tablet
                  os:
                    type: string
                    enum:
                      - windows
                      - macos
                      - ios
                      - android
                      - linux
                      - other
                  browser:
                    type: string
                    enum:
                      - chrome
                      - safari
                      - firefox
                      - edge
                      - opera
                      - other
                  library_name:
                    type: string
                    maxLength: 64
                  library_version:
                    type: string
                    maxLength: 32
                additionalProperties: false
            required:
              - channel
              - type
            additionalProperties: false
      required:
        - events
      additionalProperties: false
      description: Server events, with the secret key
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable code. Branch on it.
            message:
              type: string
              description: A human-readable text. The wording can change.
            request_id:
              description: 'INTERNAL only: quote it when you contact support'
              type: string
          required:
            - code
            - message
      required:
        - error
      description: >-
        The error format of every endpoint. See
        https://docs.manalens.dev/api/errors.
  securitySchemes:
    PublishableKey:
      type: apiKey
      in: header
      name: X-Publishable-Key
      description: The publishable key (`mana_pk_...`). It sends web and app events only.
    SecretKey:
      type: http
      scheme: bearer
      description: >-
        The secret key (`mana_sk_...`), from your backend only. It sends server
        events only.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.