Permutive V2.0 API
The v2.0 API from Permutive — 4 operation(s) for v2.0.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/permutive-v2-0-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
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