openapi: 3.2.0
info:
  title: Permutive V2.0 API
  version: v2
  description: 'Operations tagged v2.0 across 2 of this provider''s published API definitions: permutive-events-api-openapi.yml, permutive-identity-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.permutive.app/v2.0
tags:
- name: v2.0
paths:
  /events:
    post:
      tags:
      - v2.0
      summary: Track an event
      description: This endpoint creates a new event for a user, persisting the event in Permutive for downstream consumption, such as for segmentation, insights, or routing to a data lake. It validates the event against the schema defined in your workspace, and generates an event ID for the event and optionally enriches the event with geo, ISP, and contextual data.
      operationId: createEvent
      parameters:
      - name: enrich
        in: query
        description: This boolean parameter determines whether to enrich the event with geo, ISP, and natural language processing data. By default, this is set to `true`.
        required: false
        schema:
          type: boolean
      - name: sdkp
        in: query
        description: "This boolean parameter is used to describe whether the event originated from a Permutive SDK on a client's device, where `true` denotes the event was from an SDK and `false` denotes an out-of-SDK event.\n\n By default, this parameter is set to `true`. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to `false`."
        required: false
        schema:
          type: boolean
      requestBody:
        description: "You must provide **either** a `user_id` **or** a non-empty list `aliases` of prioritized aliases to specify the user that the event belongs to.\n\n If a `user_id` is provided, it will be used directly to identify the user, ignoring any aliases provided. If only aliases are provided and none match, a new user ID is generated and the aliases are synced to it."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostEvent'
            examples:
              User ID request:
                summary: User ID request
                description: A request to create an event for a user with a user ID.
                value:
                  name: Pageview
                  user_id: 2008c38f-dece-4570-976d-87593ed001c3
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_string: hello, world!
                    my_number: 42
                    my_boolean: true
                    my_object:
                      inner_property_string: nested value
                      inner_property_integer: 69
              Aliases request:
                summary: Aliases request
                description: A request to create an event for a user with aliases.
                value:
                  name: Pageview
                  aliases:
                  - priority: 0
                    tag: email_sha256
                    id: user@example.com
                  - priority: 1
                    tag: some-third-party-id-provider
                    id: '1234567890'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_string: hello, world!
                    my_number: 42
                    my_boolean: true
                    my_object:
                      inner_property_string: nested value
                      inner_property_integer: 69
        required: true
      responses:
        '201':
          description: Event created successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EventResponse'
                - $ref: '#/components/schemas/EventUnenrichedResponse'
              examples:
                Enriched:
                  summary: Full response when enrich=true
                  value:
                    name: Pageview
                    user_id: 2008c38f-dece-4570-976d-87593ed001c3
                    time: '2026-01-01T12:00:00.000Z'
                    view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                    session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                    properties:
                      my_string: hello, world!
                      my_number: 42
                      my_boolean: true
                      my_object:
                        inner_property_string: nested value
                        inner_property_integer: 69
                Non-enriched:
                  summary: Minimal response when enrich=false
                  value:
                    user_id: 2008c38f-dece-4570-976d-87593ed001c3
                    time: '2026-01-01T12:00:00.000Z'
        '400':
          description: 'Bad request: malformed body or missing required parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid parameters:
                  summary: Invalid parameters
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: BadRequest
                      code: 1000
                      message: The values of one or more parameters are invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing request body:
                  summary: Missing request body
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: BadRequest
                      code: 1003
                      message: A request body was expected but not found.
                      docs: https://docs.permutive.com/api/errors
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: The resource requires authentication, which was not supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
      - Header: []
      - Parameter: []
    servers:
    - url: https://api.permutive.app/v2.0
  /users:
    post:
      tags:
      - v2.0
      summary: Create a user ID
      description: "This endpoint generates a new user ID that can be used to identify a user within Permutive.\n\n When you're not using an SDK, and you're interacting with this endpoint directly, it is your responsibility to store a user's ID. This endpoint responds with a Permtive user ID that can be used to identify a user within Permutive, to be stored by the client."
      operationId: createUserId
      responses:
        '200':
          description: New user ID created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewUserId'
              example:
                id: 2008c38f-dece-4570-976d-87593ed001c3
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: The resource requires authentication, which was not supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
      - Header: []
      - Parameter: []
    servers:
    - url: https://api.permutive.app/v2.0
  /identify:
    post:
      tags:
      - v2.0
      summary: Identify a user
      description: Associate one or more identities with a Permutive user, allowing you to identify users in multiple ways.
      operationId: identifyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyUser'
            example:
              user_id: 2008c38f-dece-4570-976d-87593ed001c3
              aliases:
              - priority: 0
                tag: email_sha256
                id: user@example.com
              - priority: 1
                tag: some-third-party-id-provider
                id: '1234567890'
      responses:
        '200':
          description: Resolved identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedIdentity'
              example:
                user_id: 2008c38f-dece-4570-976d-87593ed001c3
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: The resource requires authentication, which was not supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
      - Header: []
      - Parameter: []
    servers:
    - url: https://api.permutive.app/v2.0
  /users/{userId}/aliases:
    get:
      tags:
      - v2.0
      summary: Retrieve user identities
      description: Retrieves all identities available for a given user.
      operationId: getIdentities
      parameters:
      - name: userId
        in: path
        required: true
        description: The Permutive user ID of the user to retrieve identities for.
        schema:
          type: string
          format: uuid
          example: 2008c38f-dece-4570-976d-87593ed001c3
      responses:
        '200':
          description: List of resolved identities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityResponse'
              example:
              - id: user@example.com
                tag: email
                permutive_id: 2008c38f-dece-4570-976d-87593ed001c3
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: The resource requires authentication, which was not supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '403':
          description: 'Forbidden request: insufficient API key permissions'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: Unauthorized
                  code: 2001
                  message: The API key provided does not provide access to the request operation or resource.
                  docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: An error of unspecified nature was encountered while processing your request. Feel free to get in touch with us at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
      - Header: []
      - Parameter: []
    servers:
    - url: https://api.permutive.app/v2.0
components:
  schemas:
    EventUnenrichedResponse:
      title: Event response (unenriched)
      type: object
      required:
      - user_id
      - time
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID of the user that the tracked event belongs to.
        time:
          type: string
          format: date-time
          description: The ISO 8601 timestamp of the event.
    EventResponse:
      title: Event response (regular)
      type: object
      required:
      - user_id
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID of the user that the tracked event belongs to.
        name:
          type: string
          description: The name of the event collection the tracked event belongs to. The name is case-insensitive and must only contain characters in `[a-zA-Z0-9_]`.
        time:
          type: string
          format: date-time
          description: The ISO 8601 timestamp of the event.
        view_id:
          type: string
          format: uuid
          description: The identifier for the view in which the tracked event took place.
        session_id:
          type: string
          format: uuid
          description: The identifier for the session in which the tracked event took place.
        segments:
          type: array
          items:
            type: integer
          description: The list of segment codes that the user belonged to at the time the event was tracked.
        cohorts:
          type: array
          items:
            type: string
          description: The list of cohort IDs that the user belonged to at the time the event was tracked.
        properties:
          type: object
          title: JSON
          description: The properties that belong to the tracked event. These properties adhere to the specific schema configured for this event collection.
    PrioritizedAlias:
      title: PrioritizedAlias
      type: object
      required:
      - priority
      - tag
      - id
      properties:
        priority:
          type: integer
          format: int32
          description: The priority of the alias, where `0` is the highest priority.
        tag:
          type: string
          description: The tag is a string used to identify the type of alias, e.g. `email_sha256` or `myInternalID`.
        id:
          type: string
          description: The identifier for the alias, e.g. `user@example.com` or `1234567890`.
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
      - request_id
      - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          description: Details of the error that occurred.
          required:
          - status
          - code
          - message
          - docs
          properties:
            status:
              type: string
              enum:
              - BadRequest
              - Unauthorized
              - NotFound
              - Conflict
              - Gone
              - InternalServerError
              - Forbidden
              description: The type of error that occurred.
            code:
              type: integer
              format: int32
              description: A numeric code that identifies the error.
            message:
              type: string
              description: A human-readable message describing the error.
            docs:
              type: string
              format: uri
              description: A URL to the documentation for the error.
            cause:
              type: string
              description: A human-readable message describing additional details of the error.
    RequestId:
      title: RequestId
      type: string
      format: uuid
      description: A unique identifier for the request that caused the error.
    PostEvent:
      title: PostEvent
      type: object
      required:
      - name
      properties:
        user_id:
          type: string
          format: uuid
          description: "The Permutive user ID of the user that the event belongs to.\n\n If you do not provide a user ID, you must provide a non-empty list of aliases in the `aliases` field."
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritizedAlias'
          minItems: 1
          description: "A non-empty list of prioritized aliases that the user is associated with. If you do not provide a list of aliases, you must provide a user ID in the `user_id` field.\n\n Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities.\n\n When multiple aliases are provided, priorities are used to determine the order in which aliases are attempted for resolution to a Permutive user ID, where priority `0` has the highest priority."
        name:
          type: string
          description: The name of the event collection this event belongs to. The name is case-insensitive and must only contain characters in `[a-zA-Z0-9_]`.
        view_id:
          type: string
          format: uuid
          description: The identifier for the view in which the event is taking place. This is used to group events within a single page or screen view.
        session_id:
          type: string
          format: uuid
          description: The identifier for the session in which the event is taking place. This is used to group events within a user session.
        segments:
          type: array
          items:
            type: integer
          description: The list of segment codes that the user belonged to at the time of the event.
        cohorts:
          type: array
          items:
            type: string
          description: The list of cohort IDs that the user belonged to at the time of the event.
        properties:
          type: object
          title: JSON
          description: The properties that belong to this event. These properties must adhere to the specific schema configured for this event collection.
    NewUserId:
      title: User ID response
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The newly generated Permutive user ID.
    ResolvedIdentity:
      title: Resolved identity
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: The resolved user ID.
    IdentityResponse:
      title: Identity response
      type: object
      properties:
        id:
          type: string
          description: The identity value.
        tag:
          type: string
          description: The identity tag/type.
        permutive_id:
          type: string
          format: uuid
          description: The resolved Permutive user ID.
    IdentifyUser:
      title: Identify response
      type: object
      required:
      - user_id
      - aliases
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID currently assigned to the user.
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritizedAlias'
          description: A list of prioritized aliases that the user is associated with. If no aliases are provided, the user ID will be returned.
  securitySchemes:
    Header:
      type: apiKey
      name: X-API-Key
      in: header
    Parameter:
      type: apiKey
      name: k
      in: query
x-refined-from:
- permutive-events-api-openapi.yml
- permutive-identity-api-openapi.yml