Actions API Reference

Actions

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`GET`
`POST`

List all actions

Required API key scopes

action:read

Query parameters

format
string
One of: "csv""json"
limit
integer
offset
integer
search
string

Response

Example request

GET /api/projects/:project_id/actions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/actions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "tags": [
        null
      ],
      "post_to_slack": true,
      "slack_message_format": "string",
      "steps": [
        {
          "event": "string",
          "properties": [
            {
              "key": "string",
              "type": "event",
              "value": "string",
              "operator": "exact"
            }
          ],
          "selector": "string",
          "selector_regex": "string",
          "tag_name": "string",
          "text": "string",
          "text_matching": "contains",
          "href": "string",
          "href_matching": "contains",
          "url": "string",
          "url_matching": "contains"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "deleted": true,
      "is_calculating": true,
      "last_calculated_at": "2019-08-24T14:15:22Z",
      "team_id": 0,
      "is_action": true,
      "bytecode_error": "string",
      "pinned_at": "2019-08-24T14:15:22Z",
      "creation_context": "string",
      "_create_in_folder": "string",
      "user_access_level": "string"
    }
  ]
}

Create actions

Required API key scopes

action:write

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
description
string
tags
array
post_to_slack
boolean
slack_message_format
string
steps
array
deleted
boolean
last_calculated_at
string
pinned_at
stringnull
_create_in_folder
string

Response

Example request

POST /api/projects/:project_id/actions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/\
	-d name=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/actions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "tags": [
    null
  ],
  "post_to_slack": true,
  "slack_message_format": "string",
  "steps": [
    {
      "event": "string",
      "properties": [
        {
          "key": "string",
          "type": "event",
          "value": "string",
          "operator": "exact"
        }
      ],
      "selector": "string",
      "selector_regex": "string",
      "tag_name": "string",
      "text": "string",
      "text_matching": "contains",
      "href": "string",
      "href_matching": "contains",
      "url": "string",
      "url_matching": "contains"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "deleted": true,
  "is_calculating": true,
  "last_calculated_at": "2019-08-24T14:15:22Z",
  "team_id": 0,
  "is_action": true,
  "bytecode_error": "string",
  "pinned_at": "2019-08-24T14:15:22Z",
  "creation_context": "string",
  "_create_in_folder": "string",
  "user_access_level": "string"
}

Retrieve actions

Required API key scopes

action:read

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Response

Example request

GET /api/projects/:project_id/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/actions/{action_id}/".format(
        project_id=project_id,
		action_id="<the action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "tags": [
    null
  ],
  "post_to_slack": true,
  "slack_message_format": "string",
  "steps": [
    {
      "event": "string",
      "properties": [
        {
          "key": "string",
          "type": "event",
          "value": "string",
          "operator": "exact"
        }
      ],
      "selector": "string",
      "selector_regex": "string",
      "tag_name": "string",
      "text": "string",
      "text_matching": "contains",
      "href": "string",
      "href_matching": "contains",
      "url": "string",
      "url_matching": "contains"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "deleted": true,
  "is_calculating": true,
  "last_calculated_at": "2019-08-24T14:15:22Z",
  "team_id": 0,
  "is_action": true,
  "bytecode_error": "string",
  "pinned_at": "2019-08-24T14:15:22Z",
  "creation_context": "string",
  "_create_in_folder": "string",
  "user_access_level": "string"
}

Update actions

Required API key scopes

action:write

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
description
string
tags
array
post_to_slack
boolean
slack_message_format
string
steps
array
deleted
boolean
last_calculated_at
string
pinned_at
stringnull
_create_in_folder
string

Response

Example request

PATCH /api/projects/:project_id/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/:id/\
	-d name=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/actions/{action_id}/".format(
        project_id=project_id,
		action_id="<the action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "tags": [
    null
  ],
  "post_to_slack": true,
  "slack_message_format": "string",
  "steps": [
    {
      "event": "string",
      "properties": [
        {
          "key": "string",
          "type": "event",
          "value": "string",
          "operator": "exact"
        }
      ],
      "selector": "string",
      "selector_regex": "string",
      "tag_name": "string",
      "text": "string",
      "text_matching": "contains",
      "href": "string",
      "href_matching": "contains",
      "url": "string",
      "url_matching": "contains"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "deleted": true,
  "is_calculating": true,
  "last_calculated_at": "2019-08-24T14:15:22Z",
  "team_id": 0,
  "is_action": true,
  "bytecode_error": "string",
  "pinned_at": "2019-08-24T14:15:22Z",
  "creation_context": "string",
  "_create_in_folder": "string",
  "user_access_level": "string"
}

Delete actions

Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

Required API key scopes

action:write

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

DELETE /api/projects/:project_id/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/actions/{action_id}/".format(
        project_id=project_id,
		action_id="<the action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 405 No response body

List all actions references

Required API key scopes

action:read

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/projects/:project_id/actions/:id/references
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/:id/references/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/actions/{action_id}/references/".format(
        project_id=project_id,
		action_id="<the action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "type": "string",
  "id": "string",
  "name": "string",
  "url": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  }
}

Create actions bulk update tags

Bulk update tags on multiple objects.

PAT access: this action has no required_scopes= on the decorator — inheriting viewsets must add "bulk_update_tags" to their scope_object_write_actions list to accept personal API keys. Without that opt-in, APIScopePermission rejects PAT requests with "This action does not support personal API key access". Done per-viewset so granting <scope>:write for one resource doesn't leak access to sibling resources that share this mixin.

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

Query parameters

format
string
One of: "csv""json"

Request parameters

ids
array
action
tags
array

Response

Example request

POST /api/projects/:project_id/actions/bulk_update_tags
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/actions/bulk_update_tags/\
	-d ids="array",\
	-d action=undefined,\
	-d tags="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/actions/bulk_update_tags/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array",
		"tags": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "updated": [
    {
      "id": 0,
      "tags": [
        "string"
      ]
    }
  ],
  "skipped": [
    {
      "id": 0,
      "reason": "string"
    }
  ]
}

Actions

Endpoints

List all actions

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create actions

Required API key scopes

Query parameters

Request parameters

Response

Example request

Example response

Status 201

Retrieve actions

Required API key scopes

Path parameters

Query parameters

Response

Example request

Example response

Status 200

Update actions

Required API key scopes

Path parameters

Query parameters

Request parameters

Response

Example request

Example response

Status 200

Delete actions

Required API key scopes

Path parameters

Query parameters

Example request

Example response

Status 405 No response body

List all actions references

Required API key scopes

Path parameters

Query parameters

Example request

Example response

Status 200

Create actions bulk update tags

Query parameters

Request parameters

Response

Example request

Example response

Status 200

Community questions