openapi: 3.0.3
info:
title: PostHog actions API
version: 1.0.0
description: ''
tags:
- name: actions
paths:
/api/projects/{project_id}/actions/:
get:
operationId: actions_list
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
security:
- PersonalAPIKeyAuth:
- action:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedActionList'
text/csv:
schema:
$ref: '#/components/schemas/PaginatedActionList'
description: ''
x-explicit-tags:
- actions
post:
operationId: actions_create
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Action'
multipart/form-data:
schema:
$ref: '#/components/schemas/Action'
security:
- PersonalAPIKeyAuth:
- action:write
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
text/csv:
schema:
$ref: '#/components/schemas/Action'
description: ''
x-explicit-tags:
- actions
/api/projects/{project_id}/actions/{id}/:
get:
operationId: actions_retrieve
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this action.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
security:
- PersonalAPIKeyAuth:
- action:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
text/csv:
schema:
$ref: '#/components/schemas/Action'
description: ''
x-explicit-tags:
- actions
put:
operationId: actions_update
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this action.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Action'
multipart/form-data:
schema:
$ref: '#/components/schemas/Action'
security:
- PersonalAPIKeyAuth:
- action:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
text/csv:
schema:
$ref: '#/components/schemas/Action'
description: ''
x-explicit-tags:
- actions
patch:
operationId: actions_partial_update
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this action.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedAction'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedAction'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedAction'
security:
- PersonalAPIKeyAuth:
- action:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
text/csv:
schema:
$ref: '#/components/schemas/Action'
description: ''
x-explicit-tags:
- actions
delete:
operationId: actions_destroy
description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this action.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
security:
- PersonalAPIKeyAuth:
- action:write
responses:
'405':
description: No response body
x-explicit-tags:
- actions
/api/projects/{project_id}/actions/{id}/references/:
get:
operationId: actions_references_list
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this action.
required: true
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
security:
- PersonalAPIKeyAuth:
- action:read
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ActionReference'
text/csv:
schema:
type: array
items:
$ref: '#/components/schemas/ActionReference'
description: ''
x-explicit-tags:
- actions
/api/projects/{project_id}/actions/bulk_update_tags/:
post:
operationId: actions_bulk_update_tags_create
description: 'Bulk update tags on multiple objects.
Accepts:
- {"ids": [...], "action": "add"|"remove"|"set", "tags": ["tag1", "tag2"]}
Actions:
- "add": Add tags to existing tags on each object
- "remove": Remove specific tags from each object
- "set": Replace all tags on each object with the provided list'
parameters:
- in: query
name: format
schema:
type: string
enum:
- csv
- json
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- actions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUpdateTagsRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BulkUpdateTagsRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/BulkUpdateTagsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUpdateTagsResponse'
text/csv:
schema:
$ref: '#/components/schemas/BulkUpdateTagsResponse'
description: ''
x-explicit-tags:
- actions
components:
schemas:
BulkUpdateTagsResponse:
type: object
properties:
updated:
type: array
items:
$ref: '#/components/schemas/BulkUpdateTagsItem'
skipped:
type: array
items:
$ref: '#/components/schemas/BulkUpdateTagsError'
required:
- skipped
- updated
ActionStepMatchingEnum:
enum:
- contains
- regex
- exact
type: string
description: '* `contains` - contains
* `regex` - regex
* `exact` - exact'
RoleAtOrganizationEnum:
enum:
- engineering
- data
- product
- founder
- leadership
- marketing
- sales
- other
type: string
description: '* `engineering` - Engineering
* `data` - Data
* `product` - Product Management
* `founder` - Founder
* `leadership` - Leadership
* `marketing` - Marketing
* `sales` - Sales / Success
* `other` - Other'
PatchedAction:
type: object
description: Serializer mixin that handles tags for objects.
properties:
id:
type: integer
readOnly: true
name:
type: string
nullable: true
description: Name of the action (must be unique within the project).
maxLength: 400
description:
type: string
description: Human-readable description of what this action represents.
tags:
type: array
items: {}
post_to_slack:
type: boolean
description: Whether to post a notification to Slack when this action is triggered.
slack_message_format:
type: string
description: Custom Slack message format. Supports templates with event properties.
maxLength: 1200
steps:
type: array
items:
$ref: '#/components/schemas/ActionStepJSON'
description: Action steps defining trigger conditions. Each step matches events by name, properties, URL, or element attributes. Multiple steps are OR-ed together.
created_at:
type: string
format: date-time
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
deleted:
type: boolean
is_calculating:
type: boolean
readOnly: true
last_calculated_at:
type: string
format: date-time
team_id:
type: integer
readOnly: true
is_action:
type: boolean
readOnly: true
default: true
bytecode_error:
type: string
readOnly: true
nullable: true
pinned_at:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp when the action was pinned, or null if not pinned. Set any value to pin, null to unpin.
creation_context:
type: string
nullable: true
readOnly: true
_create_in_folder:
type: string
writeOnly: true
title: ' create in folder'
user_access_level:
type: string
nullable: true
readOnly: true
description: The effective access level the user has for this object
NullEnum:
enum:
- null
DatePropertyFilter:
type: object
description: Matches date/datetime values with date-specific operators.
properties:
key:
type: string
description: Key of the property you're filtering on. For example `email` or `$current_url`.
type:
allOf:
- $ref: '#/components/schemas/PropertyFilterTypeEnum'
default: event
description: 'Property type (event, person, session, etc.).
* `event` - event
* `event_metadata` - event_metadata
* `feature` - feature
* `person` - person
* `cohort` - cohort
* `element` - element
* `static-cohort` - static-cohort
* `dynamic-cohort` - dynamic-cohort
* `precalculated-cohort` - precalculated-cohort
* `group` - group
* `recording` - recording
* `log_entry` - log_entry
* `behavioral` - behavioral
* `session` - session
* `hogql` - hogql
* `data_warehouse` - data_warehouse
* `data_warehouse_person_property` - data_warehouse_person_property
* `error_tracking_issue` - error_tracking_issue
* `log` - log
* `log_attribute` - log_attribute
* `log_resource_attribute` - log_resource_attribute
* `span` - span
* `span_attribute` - span_attribute
* `span_resource_attribute` - span_resource_attribute
* `revenue_analytics` - revenue_analytics
* `flag` - flag
* `workflow_variable` - workflow_variable'
value:
type: string
description: Date or datetime string in ISO 8601 format (e.g. '2024-01-15' or '2024-01-15T10:30:00Z').
operator:
allOf:
- $ref: '#/components/schemas/DateOperatorEnum'
default: is_date_exact
description: 'Date comparison operator.
* `is_date_exact` - is_date_exact
* `is_date_before` - is_date_before
* `is_date_after` - is_date_after'
required:
- key
- value
ActionStepJSON:
type: object
properties:
event:
type: string
nullable: true
description: Event name to match (e.g. '$pageview', '$autocapture', or a custom event name).
properties:
type: array
items:
$ref: '#/components/schemas/ActionStepPropertyFilter'
nullable: true
description: Event or person property filters. Each item should have 'key' (string), 'value' (string, number, boolean, or array), optional 'operator' (exact, is_not, is_set, is_not_set, icontains, not_icontains, regex, not_regex, gt, gte, lt, lte), and optional 'type' (event, person).
selector:
type: string
nullable: true
description: CSS selector to match the target element (e.g. 'div > button.cta').
selector_regex:
type: string
nullable: true
readOnly: true
tag_name:
type: string
nullable: true
description: HTML tag name to match (e.g. "button", "a", "input").
text:
type: string
nullable: true
description: Element text content to match.
text_matching:
nullable: true
description: 'How to match the text value. Defaults to exact.
* `contains` - contains
* `regex` - regex
* `exact` - exact'
oneOf:
- $ref: '#/components/schemas/ActionStepMatchingEnum'
- $ref: '#/components/schemas/NullEnum'
href:
type: string
nullable: true
description: Link href attribute to match.
href_matching:
nullable: true
description: 'How to match the href value. Defaults to exact.
* `contains` - contains
* `regex` - regex
* `exact` - exact'
oneOf:
- $ref: '#/components/schemas/ActionStepMatchingEnum'
- $ref: '#/components/schemas/NullEnum'
url:
type: string
nullable: true
description: Page URL to match.
url_matching:
nullable: true
description: 'How to match the URL value. Defaults to contains.
* `contains` - contains
* `regex` - regex
* `exact` - exact'
oneOf:
- $ref: '#/components/schemas/ActionStepMatchingEnum'
- $ref: '#/components/schemas/NullEnum'
required:
- selector_regex
UserBasic:
type: object
properties:
id:
type: integer
readOnly: true
uuid:
type: string
format: uuid
readOnly: true
distinct_id:
type: string
nullable: true
maxLength: 200
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
email:
type: string
format: email
title: Email address
maxLength: 254
is_email_verified:
type: boolean
nullable: true
hedgehog_config:
type: object
additionalProperties: true
nullable: true
readOnly: true
role_at_organization:
nullable: true
oneOf:
- $ref: '#/components/schemas/RoleAtOrganizationEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
required:
- email
- hedgehog_config
- id
- uuid
ActionEnum:
enum:
- add
- remove
- set
type: string
description: '* `add` - add
* `remove` - remove
* `set` - set'
BulkUpdateTagsRequest:
type: object
properties:
ids:
type: array
items:
type: integer
description: List of object IDs to update tags on.
maxItems: 500
action:
allOf:
- $ref: '#/components/schemas/ActionEnum'
description: '''add'' merges with existing tags, ''remove'' deletes specific tags, ''set'' replaces all tags.
* `add` - add
* `remove` - remove
* `set` - set'
tags:
type: array
items:
type: string
description: Tag names to add, remove, or set.
required:
- action
- ids
- tags
ExistenceOperatorEnum:
enum:
- is_set
- is_not_set
type: string
description: '* `is_set` - is_set
* `is_not_set` - is_not_set'
ArrayPropertyFilterOperatorEnum:
enum:
- exact
- is_not
- in
- not_in
type: string
description: '* `exact` - exact
* `is_not` - is_not
* `in` - in
* `not_in` - not_in'
ExistencePropertyFilter:
type: object
description: Checks whether a property is set or not, without comparing values.
properties:
key:
type: string
description: Key of the property you're filtering on. For example `email` or `$current_url`.
type:
allOf:
- $ref: '#/components/schemas/PropertyFilterTypeEnum'
default: event
description: 'Property type (event, person, session, etc.).
* `event` - event
* `event_metadata` - event_metadata
* `feature` - feature
* `person` - person
* `cohort` - cohort
* `element` - element
* `static-cohort` - static-cohort
* `dynamic-cohort` - dynamic-cohort
* `precalculated-cohort` - precalculated-cohort
* `group` - group
* `recording` - recording
* `log_entry` - log_entry
* `behavioral` - behavioral
* `session` - session
* `hogql` - hogql
* `data_warehouse` - data_warehouse
* `data_warehouse_person_property` - data_warehouse_person_property
* `error_tracking_issue` - error_tracking_issue
* `log` - log
* `log_attribute` - log_attribute
* `log_resource_attribute` - log_resource_attribute
* `span` - span
* `span_attribute` - span_attribute
* `span_resource_attribute` - span_resource_attribute
* `revenue_analytics` - revenue_analytics
* `flag` - flag
* `workflow_variable` - workflow_variable'
operator:
allOf:
- $ref: '#/components/schemas/ExistenceOperatorEnum'
description: 'Existence check operator.
* `is_set` - is_set
* `is_not_set` - is_not_set'
required:
- key
- operator
ActionStepPropertyFilter:
oneOf:
- $ref: '#/components/schemas/StringPropertyFilter'
- $ref: '#/components/schemas/NumericPropertyFilter'
- $ref: '#/components/schemas/ArrayPropertyFilter'
- $ref: '#/components/schemas/DatePropertyFilter'
- $ref: '#/components/schemas/ExistencePropertyFilter'
BulkUpdateTagsItem:
type: object
properties:
id:
type: integer
tags:
type: array
items:
type: string
required:
- id
- tags
NumericPropertyFilter:
type: object
description: Matches numeric values with comparison operators.
properties:
key:
type: string
description: Key of the property you're filtering on. For example `email` or `$current_url`.
type:
allOf:
- $ref: '#/components/schemas/PropertyFilterTypeEnum'
default: event
description: 'Property type (event, person, session, etc.).
* `event` - event
* `event_metadata` - event_metadata
* `feature` - feature
* `person` - person
* `cohort` - cohort
* `element` - element
* `static-cohort` - static-cohort
* `dynamic-cohort` - dynamic-cohort
* `precalculated-cohort` - precalculated-cohort
* `group` - group
* `recording` - recording
* `log_entry` - log_entry
* `behavioral` - behavioral
* `session` - session
* `hogql` - hogql
* `data_warehouse` - data_warehouse
* `data_warehouse_person_property` - data_warehouse_person_property
* `error_tracking_issue` - error_tracking_issue
* `log` - log
* `log_attribute` - log_attribute
* `log_resource_attribute` - log_resource_attribute
* `span` - span
* `span_attribute` - span_attribute
* `span_resource_attribute` - span_resource_attribute
* `revenue_analytics` - revenue_analytics
* `flag` - flag
* `workflow_variable` - workflow_variable'
value:
type: number
format: double
description: Numeric value to compare against.
operator:
allOf:
- $ref: '#/components/schemas/NumericPropertyFilterOperatorEnum'
default: exact
description: 'Numeric comparison operator.
* `exact` - exact
* `is_not` - is_not
* `gt` - gt
* `lt` - lt
* `gte` - gte
* `lte` - lte'
required:
- key
- value
NumericPropertyFilterOperatorEnum:
enum:
- exact
- is_not
- gt
- lt
- gte
- lte
type: string
description: '* `exact` - exact
* `is_not` - is_not
* `gt` - gt
* `lt` - lt
* `gte` - gte
* `lte` - lte'
StringPropertyFilter:
type: object
description: Matches string values with text-oriented operators.
properties:
key:
type: string
description: Key of the property you're filtering on. For example `email` or `$current_url`.
type:
allOf:
- $ref: '#/components/schemas/PropertyFilterTypeEnum'
default: event
description: 'Property type (event, person, session, etc.).
* `event` - event
* `event_metadata` - event_metadata
* `feature` - feature
* `person` - person
* `cohort` - cohort
* `element` - element
* `static-cohort` - static-cohort
* `dynamic-cohort` - dynamic-cohort
* `precalculated-cohort` - precalculated-cohort
* `group` - group
* `recording` - recording
* `log_entry` - log_entry
* `behavioral` - behavioral
* `session` - session
* `hogql` - hogql
* `data_warehouse` - data_warehouse
* `data_warehouse_person_property` - data_warehouse_person_property
* `error_tracking_issue` - error_tracking_issue
* `log` - log
* `log_attribute` - log_attribute
* `log_resource_attribute` - log_resource_attribute
* `span` - span
* `span_attribute` - span_attribute
* `span_resource_attribute` - span_resource_attribute
* `revenue_analytics` - revenue_analytics
* `flag` - flag
* `workflow_variable` - workflow_variable'
value:
type: string
description: String value to match against.
operator:
allOf:
- $ref: '#/components/schemas/StringMatchOperatorEnum'
default: exact
description: 'String comparison operator.
* `exact` - exact
* `is_not` - is_not
* `icontains` - icontains
* `not_icontains` - not_icontains
* `regex` - regex
* `not_regex` - not_regex'
required:
- key
- value
BlankEnum:
enum:
- ''
BulkUpdateTagsError:
type: object
properties:
id:
type: integer
reason:
type: string
required:
- id
- reason
ActionReference:
type: object
properties:
type:
type: string
description: 'Resource type: insight, experiment, cohort, or hog_function'
id:
type: string
description: Resource ID (integer or UUID depending on type)
name:
type: string
description: Resource name
url:
type: string
description: Relative URL to the resource
created_at:
type: string
format: date-time
nullable: true
description: When the resource was created
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
nullable: true
description: User who created the resource
required:
- created_at
- created_by
- id
- name
- type
- url
Action:
type: object
description: Serializer mixin that handles tags for objects.
properties:
id:
type: integer
readOnly: true
name:
type: string
nullable: true
description: Name of the action (must be unique within the project).
maxLength: 400
description:
type: string
description: Human-readable description of what this action represents.
tags:
type: array
items: {}
post_to_slack:
type: boolean
description: Whether to post a notification to Slack when this action is triggered.
slack_message_format:
type: string
description: Custom Slack message format. Supports templates with event properties.
maxLength: 1200
steps:
type: array
items:
$ref: '#/components/schemas/ActionStepJSON'
description: Action steps defining trigger conditions. Each step matches events by name, properties, URL, or element attributes. Multiple steps are OR-ed together.
created_at:
type: string
format: date-time
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
deleted:
type: boolean
is_calculating:
type: boolean
readOnly: true
last_calculated_at:
type: string
format: date-time
team_id:
type: integer
readOnly: true
is_action:
type: boolean
readOnly: true
default: true
bytecode_error:
type: string
readOnly: true
nullable: true
pinned_at:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp when the action was pinned, or null if not pinned. Set any value to pin, null to unpin.
creation_context:
type: string
nullable: true
readOnly: true
_create_in_folder:
type: string
writeOnly: true
title: ' create in folder'
user_access_level:
type: string
nullable: true
readOnly: true
description: The effective access level the user has for this object
required:
- bytecode_error
- created_at
- created_by
- creation_context
- id
- is_action
- is_calculating
- team_id
- user_access_level
ArrayPropertyFilter:
type: object
description: Matches against a list of values (OR semantics for exact/is_not, set membership for in/not_in).
properties:
key:
type: string
description: Key of the property you're filtering on. For example `email` or `$current_url`.
type:
allOf:
- $ref: '#/components/schemas/PropertyFilterTypeEnum'
default: event
description: 'Property type (event, person, session, etc.).
* `event` - event
* `event_metadata` - event_metadata
* `feature` - feature
* `person` - person
* `cohort` - cohort
* `element` - element
* `static-cohort` - static-cohort
* `dynamic-cohort` - dynamic-cohort
* `precalculated-cohort` - precalculated-cohort
* `group` - group
* `recording` - recording
* `log_entry` - log_entry
* `behavioral` - behavioral
* `session` - session
* `hogql` - hogql
* `data_warehouse` - data_warehouse
* `data_warehouse_person_property` - data_warehouse_person_property
* `error_tracking_issue` - error_tracking_issue
* `log` - log
* `log_attribute` - log_attribute
* `log_resource_attribute` - log_resource_attribute
* `span` - span
* `span_attribute` - span_attribute
* `span_resource_attribute` - span_resource_attribute
* `revenue_analytics` - revenue_analytics
* `flag` - flag
* `workflow_variable` - workflow_variable'
value:
type: array
items:
type: string
description: List of values to match. For example `["test@example.com", "ok@example.com"]`.
operator:
allOf:
- $ref: '#/components/schemas/ArrayPropertyFilterOperatorEnum'
default: exact
description: 'Array comparison operator.
* `exact` - exact
* `is_not` - is_not
* `in` - in
* `not_in` - not_in'
required:
- key
- value
StringMatchOperatorEnum:
enum:
- exact
- is_not
- icontains
- not_icontains
- regex
- not_regex
type: string
description: '* `exact` - exact
* `is_not` - is_not
* `icontains` - icontains
* `not_icontains` - not_icontains
* `regex` - regex
* `not_regex` - not_regex'
PropertyFilterTypeEnum:
enum:
- event
- event_metadata
- feature
- person
- cohort
- elem
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posthog/refs/heads/main/openapi/posthog-actions-api-openapi.yml