Permutive V2 API
The v2 API from Permutive — 2 operation(s) for v2.
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-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: Cohorts V2 API
version: '1'
description: Programmatically view and maintain cohort definitions
servers:
- url: https://api.permutive.app/cohorts-api
tags:
- name: v2
paths:
/v2/cohorts:
get:
tags:
- v2
summary: Retrieve all cohorts
description: 'By default this endpoint returns all cohorts belonging to the workspace to which the supplied API key belongs, plus any cohorts inherited from parent workspaces in the organization hierarchy. If the API key has the required access level, it is also possible to return segments belonging to child workspaces below the requesting workspace in the organization hierarchy.
The queries defining the behaviour of the cohorts are not returned from this endpoint. To retrieve the query of a given cohort, use the ''Retrieve individual cohort'' endpoint.'
operationId: getV2Cohorts
parameters:
- name: include-child-workspaces
in: query
description: Whether to return cohorts belonging to workspaces below the requesting workspace in the organization hierarchy. Defaults to false if not specified.
required: false
schema:
type: boolean
responses:
'200':
description: List of cohorts in summary form (excluding query)
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SegmentSummaryApiV2WithAudience'
example:
- id: 38470a62-9837-4c86-bbf3-45dd6d52dd83
code: 12345
name: Example Segment A
description: This segment is an example for documentation purposes
tags:
- tag_a
- tag_b
state: Enabled
workspace_id: 0bd63f73-6b67-4766-8c86-fa1d2cf87194
segment_type: real_time
created_at: '2022-09-22T15:44:29.513211710Z'
last_updated_at: '2022-09-22T15:44:29.513214670Z'
- id: be1e0886-4a52-442f-89e5-6bf0ff652ac7
code: 23456
name: Example Segment B
description: This is a second segment for documentation purposes
tags: []
state: Enabled
workspace_id: 0bd63f73-6b67-4766-8c86-fa1d2cf87194
segment_type: real_time
live_audience_size: 10000
created_at: '2022-09-22T15:44:29.513246606Z'
last_updated_at: '2022-09-22T15:44:29.513246784Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
status_code: 400
status: Bad Request
code: 1002
message: The provided request body was not structured as expected.
docs: https://developer.permutive.com/reference#errors
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7235#section-3.1
status_code: 401
status: Unauthorized
code: 2005
message: The supplied authentication is invalid.
docs: https://developer.permutive.com/reference#errors
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.3
status_code: 403
status: Forbidden
code: 2001
message: The API key provided does not provide access to the request operation or resource.
docs: https://developer.permutive.com/reference#errors
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
status_code: 404
status: Not Found
code: 3000
message: The requested resource does not exist.
docs: https://developer.permutive.com/reference#errors
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.8
status_code: 409
status: Conflict
code: 4000
message: A resource with this identifier already exists.
docs: https://developer.permutive.com/reference#errors
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.6.1
status_code: 500
status: Internal Server Error
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://developer.permutive.com/reference#errors
security:
- apiKeyAuth: []
post:
tags:
- v2
summary: Create cohort
description: 'This endpoint allows the creation of a new cohort. The query definition is provided using the Cohort API JSON query definition format.
The cohort will belong to the workspace which owns the provided API key.'
operationId: postV2Cohorts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSegmentV2'
example:
name: Example Segment A
description: This segment is an example for documentation purposes
query:
event: Pageview
frequency:
greater_than_or_equal_to: 2
where:
property: properties.client.url
condition:
contains: football
during:
the_last:
value: 30
unit: days
tags:
- tag_a
- tag_b
segment_type: real_time
required: true
responses:
'201':
description: Cohort in full (including query)
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentQueryApiV2'
example:
id: 38470a62-9837-4c86-bbf3-45dd6d52dd83
code: 12345
name: Example Segment A
description: This segment is an example for documentation purposes
query:
event: Pageview
frequency:
greater_than_or_equal_to: 2
where:
property: properties.client.url
condition:
contains: football
during:
the_last:
value: 30
unit: days
tags:
- tag_a
- tag_b
state: Enabled
segment_type: real_time
created_at: '2022-09-22T15:44:29.518935935Z'
last_updated_at: '2022-09-22T15:44:29.518937018Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
status_code: 400
status: Bad Request
code: 1002
message: The provided request body was not structured as expected.
docs: https://developer.permutive.com/reference#errors
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7235#section-3.1
status_code: 401
status: Unauthorized
code: 2005
message: The supplied authentication is invalid.
docs: https://developer.permutive.com/reference#errors
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.3
status_code: 403
status: Forbidden
code: 2001
message: The API key provided does not provide access to the request operation or resource.
docs: https://developer.permutive.com/reference#errors
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
status_code: 404
status: Not Found
code: 3000
message: The requested resource does not exist.
docs: https://developer.permutive.com/reference#errors
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.8
status_code: 409
status: Conflict
code: 4000
message: A resource with this identifier already exists.
docs: https://developer.permutive.com/reference#errors
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.6.1
status_code: 500
status: Internal Server Error
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://developer.permutive.com/reference#errors
security:
- apiKeyAuth: []
/v2/cohorts/{cohortId}:
get:
tags:
- v2
summary: Retrieve individual cohort
description: 'This endpoint returns details of a single cohort belonging either to the workspace that owns the requesting API key, or to a parent workspace if the requesting workspace inherits the cohort from that workspace.
If the requested cohort is not a lookalike-based cohort, the response will include the query definition.'
operationId: getV2CohortsCohortid
parameters:
- name: cohortId
in: path
description: Cohort UUID
required: true
schema:
type: string
example: 38470a62-9837-4c86-bbf3-45dd6d52dd83
responses:
'200':
description: Cohort in full (including query)
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentDetailApiV2WithAudience'
example:
id: 38470a62-9837-4c86-bbf3-45dd6d52dd83
code: 12345
name: Example Segment A
description: This segment is an example for documentation purposes
query:
event: Pageview
frequency:
greater_than_or_equal_to: 2
where:
property: properties.client.url
condition:
contains: football
during:
the_last:
value: 30
unit: days
tags:
- tag_a
- tag_b
state: Enabled
segment_type: real_time
live_audience_size: 10000
created_at: '2022-09-22T15:44:29.518393971Z'
last_updated_at: '2022-09-22T15:44:29.518395049Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
status_code: 400
status: Bad Request
code: 1002
message: The provided request body was not structured as expected.
docs: https://developer.permutive.com/reference#errors
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7235#section-3.1
status_code: 401
status: Unauthorized
code: 2005
message: The supplied authentication is invalid.
docs: https://developer.permutive.com/reference#errors
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.3
status_code: 403
status: Forbidden
code: 2001
message: The API key provided does not provide access to the request operation or resource.
docs: https://developer.permutive.com/reference#errors
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
status_code: 404
status: Not Found
code: 3000
message: The requested resource does not exist.
docs: https://developer.permutive.com/reference#errors
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.8
status_code: 409
status: Conflict
code: 4000
message: A resource with this identifier already exists.
docs: https://developer.permutive.com/reference#errors
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.6.1
status_code: 500
status: Internal Server Error
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://developer.permutive.com/reference#errors
security:
- apiKeyAuth: []
delete:
tags:
- v2
summary: Delete cohort
description: This endpoint allows deleting an existing cohort. Depending on the access level of the provided API key, it can delete cohorts owned by the requesting workspace, or also by child workspaces below the requesting workspace in the organization hierarchy. Lookalike-based cohorts cannot be deleted via the Cohort API.
operationId: deleteV2CohortsCohortid
parameters:
- name: cohortId
in: path
description: Cohort UUID
required: true
schema:
type: string
example: 38470a62-9837-4c86-bbf3-45dd6d52dd83
responses:
'200':
description: ''
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
status_code: 400
status: Bad Request
code: 1002
message: The provided request body was not structured as expected.
docs: https://developer.permutive.com/reference#errors
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7235#section-3.1
status_code: 401
status: Unauthorized
code: 2005
message: The supplied authentication is invalid.
docs: https://developer.permutive.com/reference#errors
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.3
status_code: 403
status: Forbidden
code: 2001
message: The API key provided does not provide access to the request operation or resource.
docs: https://developer.permutive.com/reference#errors
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
status_code: 404
status: Not Found
code: 3000
message: The requested resource does not exist.
docs: https://developer.permutive.com/reference#errors
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.8
status_code: 409
status: Conflict
code: 4000
message: A resource with this identifier already exists.
docs: https://developer.permutive.com/reference#errors
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.6.1
status_code: 500
status: Internal Server Error
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://developer.permutive.com/reference#errors
security:
- apiKeyAuth: []
patch:
tags:
- v2
summary: Update cohort
description: 'This endpoint allows updating an existing cohort. Depending on the access level of the provided API key, it can update cohorts owned by the requesting workspace, or also by child workspaces below the requesting workspace in the organization hierarchy. Lookalike-based cohorts cannot be updated via the Cohort API.
Any top level fields for which no value is provided in the request body will remain unchanged. Optional fields (currently only `description`) can be deleted by explicitly specifying `null` as the value.'
operationId: patchV2CohortsCohortid
parameters:
- name: cohortId
in: path
description: Cohort UUID
required: true
schema:
type: string
example: 38470a62-9837-4c86-bbf3-45dd6d52dd83
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentV2'
examples:
update all fields:
value:
name: New Segment Name
description: New Segment Description
query:
event: Pageview
frequency:
greater_than_or_equal_to: 2
where:
property: properties.client.url
condition:
contains: football
during:
the_last:
value: 30
unit: days
tags:
- tag_d
- tag_e
update a single field:
value:
name: New Segment Name
delete the cohort description:
value:
description: null
required: true
responses:
'200':
description: Cohort in full (including query)
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentQueryApiV2'
example:
id: 38470a62-9837-4c86-bbf3-45dd6d52dd83
code: 12345
name: Example Segment A
description: This segment is an example for documentation purposes
query:
event: Pageview
frequency:
greater_than_or_equal_to: 2
where:
property: properties.client.url
condition:
contains: football
during:
the_last:
value: 30
unit: days
tags:
- tag_a
- tag_b
state: Enabled
segment_type: real_time
created_at: '2022-09-22T15:44:29.518935935Z'
last_updated_at: '2022-09-22T15:44:29.518937018Z'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.1
status_code: 400
status: Bad Request
code: 1002
message: The provided request body was not structured as expected.
docs: https://developer.permutive.com/reference#errors
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7235#section-3.1
status_code: 401
status: Unauthorized
code: 2005
message: The supplied authentication is invalid.
docs: https://developer.permutive.com/reference#errors
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.3
status_code: 403
status: Forbidden
code: 2001
message: The API key provided does not provide access to the request operation or resource.
docs: https://developer.permutive.com/reference#errors
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.4
status_code: 404
status: Not Found
code: 3000
message: The requested resource does not exist.
docs: https://developer.permutive.com/reference#errors
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.5.8
status_code: 409
status: Conflict
code: 4000
message: A resource with this identifier already exists.
docs: https://developer.permutive.com/reference#errors
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
example:
request_id: b887517b-99a2-4ae0-bc32-93d1fb13d1b7
error:
type: https://tools.ietf.org/html/rfc7231#section-6.6.1
status_code: 500
status: Internal Server Error
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://developer.permutive.com/reference#errors
security:
- apiKeyAuth: []
components:
schemas:
SegmentType:
oneOf:
- $ref: '#/components/schemas/Offline'
- $ref: '#/components/schemas/RealTime'
Json: {}
HttpErrorResponse:
required:
- requestId
- error
type: object
properties:
requestId:
type: string
error:
$ref: '#/components/schemas/HttpError'
UpdateOrDelete_String:
type:
- string
- 'null'
Offline:
type: object
SegmentQueryApiV2:
required:
- id
- code
- name
- query
- state
- segmentType
- createdAt
- lastUpdatedAt
type: object
properties:
id:
type: string
code:
type: integer
name:
type: string
description:
type: string
query:
$ref: '#/components/schemas/Json'
tags:
type: array
items:
type: string
state:
type: string
enum:
- Enabled
- Disabled
workspaceId:
type: string
segmentType:
$ref: '#/components/schemas/SegmentType'
createdAt:
type: string
format: date-time
lastUpdatedAt:
type: string
format: date-time
HttpError:
required:
- status
- code
- message
type: object
properties:
status:
$ref: '#/components/schemas/HttpStatus'
code:
type: integer
message:
type: string
cause:
type: string
SegmentLookalikeApiWithAudience:
required:
- id
- code
- name
- state
- segmentType
- createdAt
- lastUpdatedAt
type: object
properties:
id:
type: string
code:
type: integer
name:
type: string
description:
type: string
tags:
type: array
items:
type: string
state:
type: string
enum:
- Enabled
- Disabled
workspaceId:
type: string
segmentType:
$ref: '#/components/schemas/SegmentType'
liveAudienceSize:
type: integer
createdAt:
type: string
format: date-time
lastUpdatedAt:
type: string
format: date-time
SegmentQueryApiV2WithAudience:
required:
- id
- code
- name
- query
- state
- segmentType
- createdAt
- lastUpdatedAt
type: object
properties:
id:
type: string
code:
type: integer
name:
type: stri
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permutive/refs/heads/main/openapi/permutive-v2-api-openapi.yml