Omnisend Event Metadata API

openapi: 3.2.0
info:
  contact: {}
  description: 'API for retrieving event metadata — event names, property schemas,

    and display metadata used by segmentation and automation consumers.'
  title: Event Metadata API
  version: 2026-preview
servers:
- url: https://api.omnisend.com/api
tags:
- name: Event Metadata
paths:
  /event-metadata:
    post:
      description: 'Declares a new brand-custom event schema. The event identity is the

        combination of `name` and `origin`; `displayName` and at least one

        top-level property are required. Optional metadata fields must be

        omitted rather than sent as null. The created event is returned with

        every node flagged `explicitlyDefined`.


        **Scopes:**

        `events.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      operationId: post_event_metadata
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteEventRequest'
        description: Event schema to create
        required: true
      responses:
        '201':
          description: The created event metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteEventResponse'
        '400':
          description: Invalid request body or field values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Event already exists or collides with a global lexicon event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: The event metadata was modified concurrently; retry the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      - Bearer: []
      summary: Create custom event metadata
      tags:
      - Event Metadata
    put:
      description: 'Merges changes into an existing brand-custom event, identified by

        `name` and `origin`. Only supplied fields are applied: omitted

        metadata and omitted properties are preserved, and no property is

        deleted. The type of an already explicitly-defined property cannot

        change. Optional metadata fields must be omitted rather than sent as

        null. The merged event is returned.


        **Scopes:**

        `events.write`


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      operationId: put_event_metadata
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WriteEventRequest'
        description: Event schema changes to merge
        required: true
      responses:
        '200':
          description: The merged event metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteEventResponse'
        '400':
          description: Invalid request body or field values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Event metadata does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Event is not API-owned or a property type conflict occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: The event metadata was modified concurrently; retry the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      - Bearer: []
      summary: Update custom event metadata
      tags:
      - Event Metadata
  /event-metadata/query:
    post:
      description: 'Returns event metadata entries for the given category, optionally filtered

        by event names and/or origins.


        **Supported categories:** `automations`, `events`, `segments`


        **API version scoping:**

        The events a category exposes depend on the requested `Omnisend-Version`; a date

        between releases resolves to the nearest earlier supported version. Brand-custom

        events are not version-scoped.


        **Event name filtering:**

        When `events` are provided, only events whose system name matches one of the

        given values are returned (exact, case-sensitive match).


        **Origin filtering:**

        By default the response includes Omnisend events together with events from every

        origin the brand has data for. When the brand is connected to a specific origin,

        that origin''s events are included as well. The optional `origins` filter narrows

        the response to the requested origins (OR-combined) within what the brand can

        already see; an origin the brand is not entitled to is never returned, even if

        requested.


        **Property inclusion:**

        When `includeProperties` is `true`, each event item includes its nested

        property tree, keyed by property name, with struct properties nesting their

        children under a recursive `properties` map. When omitted or `false`, only

        event-level metadata (`name`, `displayName`, `origins`) is returned.


        **Custom event exclusion:**

        When `excludeCustomEvents` is `true`, brand-custom events are omitted.

        When omitted or `false`, custom events are included.

        Set this to `true` when only well-known standard events are needed, for a more predictable response size.


        **Rate Limiting:**

        This endpoint is rate limited to 400 requests per minute.'
      operationId: post_event_metadata_query
      parameters:
      - $ref: '#/components/parameters/APIVersionHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryEventsRequest'
        description: Query parameters
        required: true
      responses:
        '200':
          description: List of event metadata entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '400':
          description: Invalid request body, missing or unsupported category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Authentication is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: API version has been retired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      - Bearer: []
      summary: Query events metadata
      tags:
      - Event Metadata
components:
  schemas:
    RateLimitProblem:
      description: Error response returned when the rate limit is exceeded. Use the retryAfter value to know when it is safe to retry the request.
      properties:
        detail:
          description: Human-readable explanation of this specific error occurrence
          example: A human-readable explanation of the error.
          type: string
        instance:
          description: Request trace identifier for support and debugging
          example: urn:omnisend:request:00000000-0000-0000-0000-000000000001
          type: string
        retryAfter:
          description: Seconds to wait before retrying the request
          example: 60
          type: integer
        status:
          description: HTTP status code
          example: 0
          type: integer
        title:
          description: Short description of the error type
          example: Problem
          type: string
        type:
          description: URI that identifies the error type
          example: https://problems.omnisend.com/problem
          type: string
      type: object
    WriteEventRequest:
      description: Request body for creating (POST) or merging (PUT) a brand-custom event-metadata schema. Optional metadata fields are pointers so PUT can distinguish an omitted field (preserve the stored value) from one explicitly set to an empty string.
      properties:
        displayName:
          description: Human-readable label. Required on POST; omit on PUT to keep the stored value.
          example: Loyalty Points Earned
          type: string
        name:
          description: Machine-readable event name
          example: loyalty points earned
          type: string
        origin:
          description: Single origin the schema belongs to
          example: api
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/WritePropertyNode'
          description: 'Property tree keyed by property name. Required with at least one key on POST;

            on PUT only the keys present are merged.'
          type: object
      required:
      - name
      - origin
      type: object
    EventsResponse:
      description: Root response envelope for all event metadata endpoints.
      properties:
        events:
          description: List of event metadata entries
          items:
            $ref: '#/components/schemas/EventItem'
          type: array
      type: object
    PropertyNode:
      description: A single property within an event. Struct properties nest their children under the recursive properties map.
      properties:
        description:
          description: Longer explanation of the property's meaning and allowed values
          example: 'Specifies from which channel the contact subscribed to. Possible values: Email, SMS, Push.'
          type: string
        displayName:
          description: Human-readable label for the property
          example: Product ID
          type: string
        explicitlyDefined:
          description: 'True when the property was declared via the write API rather than inferred

            from the global lexicon or scraped traffic'
          type: boolean
        group:
          description: Logical grouping for UI presentation (e.g. "Core", "Address")
          example: Core
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/PropertyNode'
          description: Child properties, present only for struct-typed properties.
          type: object
        type:
          description: Property data type
          enum:
          - string
          - stringList
          - integer
          - integerList
          - float
          - floatList
          - boolean
          - booleanList
          - date
          - dateList
          - struct
          - structList
          example: string
          type: string
      type: object
    Problem:
      description: Standard error response returned by all API endpoints on failure.
      properties:
        detail:
          description: Human-readable explanation of this specific error occurrence
          example: A human-readable explanation of the error.
          type: string
        instance:
          description: Request trace identifier for support and debugging
          example: urn:omnisend:request:00000000-0000-0000-0000-000000000001
          type: string
        status:
          description: HTTP status code
          example: 0
          type: integer
        title:
          description: Short description of the error type
          example: Problem
          type: string
        type:
          description: URI that identifies the error type
          example: https://problems.omnisend.com/problem
          type: string
      type: object
    EventItem:
      description: A single logical event with one schema variant. A logical event appears as multiple elements when its origins have different property structures (e.g. schema family omnisend vs shopify).
      properties:
        displayName:
          description: Human-readable label for the event
          example: Placed Order
          type: string
        explicitlyDefined:
          description: 'True when the event schema was declared via the write API rather than

            inferred from the global lexicon or scraped traffic'
          type: boolean
        name:
          description: Machine-readable event name (e.g. "placed order")
          example: placed order
          type: string
        origins:
          description: List of origins that contributed to this event variant
          example:
          - shopify
          - woocommerce
          items:
            type: string
          type: array
        properties:
          additionalProperties:
            $ref: '#/components/schemas/PropertyNode'
          description: 'Nested tree of properties belonging to this event variant, keyed by

            property name. Omitted when the request did not set includeProperties=true.'
          type: object
      type: object
    WriteEventResponse:
      description: Response envelope for the POST/PUT write endpoints, echoing the stored event.
      properties:
        event:
          allOf:
          - $ref: '#/components/schemas/EventItem'
          description: The stored event after the write was applied
      type: object
    QueryEventsRequest:
      description: Request body for the POST /event-metadata/query query endpoint.
      properties:
        category:
          description: Event category, resolved against the requested Omnisend-Version
          enum:
          - automations
          - events
          - segments
          example: automations
          type: string
        events:
          description: Optional list of event names to filter by
          example:
          - placed order
          items:
            type: string
          type: array
        excludeCustomEvents:
          description: 'When true, brand-custom events are omitted.

            When false or omitted, custom events are included.

            Set this to `true` when only well-known events are needed, for a more predictable response size.'
          example: true
          type: boolean
        includeProperties:
          description: 'When true, response items include the nested property tree.

            When false or omitted, only event-level metadata is returned.'
          example: false
          type: boolean
        origins:
          description: Optional list of origins to filter by (OR-combined)
          example:
          - shopify
          - api
          items:
            type: string
          type: array
      required:
      - category
      type: object
    WritePropertyNode:
      description: A single property in a write request. Optional metadata fields are pointers to mirror the PUT preserve-on-omit semantics at each nested node.
      properties:
        description:
          description: Longer explanation of the property. Omit on PUT to keep the stored value.
          type: string
        displayName:
          description: Human-readable label. Optional; omit on PUT to keep the stored value.
          example: Points
          type: string
        group:
          description: Logical grouping for UI presentation. Omit on PUT to keep the stored value.
          example: Core
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/WritePropertyNode'
          description: Child properties, only for struct-typed properties.
          type: object
        type:
          description: Property data type
          enum:
          - string
          - stringList
          - integer
          - integerList
          - float
          - floatList
          - boolean
          - booleanList
          - date
          - dateList
          - struct
          - structList
          example: integer
          type: string
      required:
      - type
      type: object
  parameters:
    APIVersionHeader:
      description: API version that specifies the response format and behaviour
      in: header
      name: Omnisend-Version
      required: true
      schema:
        type: string
        default: '2026-03-15'
  securitySchemes:
    ApiKeyAuth:
      description: 'API Key authentication. Value format: ''Omnisend-API-Key {api-key}'''
      in: header
      name: Authorization
      type: apiKey
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://app.omnisend.com/oauth2/token
          scopes:
            none: No scopes required — authorization is not enforced via OAuth2 scopes