Platform API Reference

Platform

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

Endpoints

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

← Previous page

List all comments

Also available via the PostHog MCP server:
comments-list — List comments and discussion threads.

Required API key scopes

comment:read

Query parameters

completed
string
One of: "any""open""completed"
cursor
string
item_id
string
kind
string
One of: "any""comment""task"
scope
string
search
string
source_comment
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
  "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "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,
      "mentions": [
        0
      ],
      "slug": "string",
      "is_task": false,
      "completed_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"
      },
      "content": "string",
      "rich_content": null,
      "version": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "item_id": "string",
      "item_context": null,
      "scope": "string",
      "completed_at": "2019-08-24T14:15:22Z",
      "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
    }
  ]
}

Create comments

Required API key scopes

comment:write

Request parameters

deleted
booleannull
mentions
array
slug
string
is_task
boolean
Default: false
content
stringnull
rich_content
item_id
stringnull
item_context
scope
string
source_comment
stringnull

Response

Example request

POST /api/projects/:project_id/comments
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/comments/\
	-d scope="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/comments/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"scope": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "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,
  "mentions": [
    0
  ],
  "slug": "string",
  "is_task": false,
  "completed_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"
  },
  "content": "string",
  "rich_content": null,
  "version": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "item_context": null,
  "scope": "string",
  "completed_at": "2019-08-24T14:15:22Z",
  "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
}

Retrieve comments

Required API key scopes

comment:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/comments/: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/comments/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/comments/{platform_features-3_id}/".format(
        project_id=project_id,
		platform_features-3_id="<the platform features-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "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,
  "mentions": [
    0
  ],
  "slug": "string",
  "is_task": false,
  "completed_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"
  },
  "content": "string",
  "rich_content": null,
  "version": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "item_context": null,
  "scope": "string",
  "completed_at": "2019-08-24T14:15:22Z",
  "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
}

Update comments

Required API key scopes

comment:write

Path parameters

id
string

Request parameters

deleted
booleannull
mentions
array
slug
string
is_task
boolean
Default: false
content
stringnull
rich_content
item_id
stringnull
item_context
scope
string
source_comment
stringnull

Response

Example request

PATCH /api/projects/:project_id/comments/: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/comments/:id/\
	-d created_by=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/comments/{platform_features-3_id}/".format(
        project_id=project_id,
		platform_features-3_id="<the platform features-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "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,
  "mentions": [
    0
  ],
  "slug": "string",
  "is_task": false,
  "completed_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"
  },
  "content": "string",
  "rich_content": null,
  "version": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "item_context": null,
  "scope": "string",
  "completed_at": "2019-08-24T14:15:22Z",
  "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
}

Delete comments

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

Required API key scopes

comment:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/comments/: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/comments/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/comments/{platform_features-3_id}/".format(
        project_id=project_id,
		platform_features-3_id="<the platform features-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 405 No response body

Create comments complete

Mark a task-comment as complete. Sets completed_at and completed_by. 400 if the comment is not a task or is already complete.

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/comments/:id/complete
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/comments/:id/complete/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/comments/{platform_features-3_id}/complete/".format(
        project_id=project_id,
		platform_features-3_id="<the platform features-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "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,
  "mentions": [
    0
  ],
  "slug": "string",
  "is_task": false,
  "completed_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"
  },
  "content": "string",
  "rich_content": null,
  "version": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "item_context": null,
  "scope": "string",
  "completed_at": "2019-08-24T14:15:22Z",
  "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
}

Create comments reopen

Reopen a completed task-comment. Clears completed_at and completed_by. 400 if the comment is not a task or is already open.

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/comments/:id/reopen
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/comments/:id/reopen/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/comments/{platform_features-3_id}/reopen/".format(
        project_id=project_id,
		platform_features-3_id="<the platform features-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "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,
  "mentions": [
    0
  ],
  "slug": "string",
  "is_task": false,
  "completed_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"
  },
  "content": "string",
  "rich_content": null,
  "version": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "item_id": "string",
  "item_context": null,
  "scope": "string",
  "completed_at": "2019-08-24T14:15:22Z",
  "source_comment": "aecfc6dd-f4f2-4252-b81d-e21a9112c0dc"
}

Retrieve comments thread

Required API key scopes

comment:read

Path parameters

id
string

Example request

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

Example response

Status 200 No response body

Retrieve comments count

Required API key scopes

comment:read

Example request

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

Example response

Status 200 No response body

Retrieve user home settings

Get the authenticated user's pinned sidebar tabs and configured homepage for the current team. Pass @me as the UUID.

Required API key scopes

user:read

Path parameters

uuid
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "tabs": [
    {
      "id": "string",
      "pathname": "string",
      "search": "string",
      "hash": "string",
      "title": "string",
      "customTitle": "string",
      "iconType": "string",
      "sceneId": "string",
      "sceneKey": "string",
      "sceneParams": null,
      "pinned": true
    }
  ],
  "homepage": {
    "id": "string",
    "pathname": "string",
    "search": "string",
    "hash": "string",
    "title": "string",
    "customTitle": "string",
    "iconType": "string",
    "sceneId": "string",
    "sceneKey": "string",
    "sceneParams": null,
    "pinned": true
  }
}

Update user home settings

Update the authenticated user's pinned sidebar tabs and/or homepage for the current team. Pass @me as the UUID. Send tabs to replace the pinned tab list, homepage to set the home destination (any PostHog URL — dashboard, insight, search results, scene). Either field may be omitted to leave it unchanged; sending homepage: null or {} clears the homepage.

Required API key scopes

user:write

Path parameters

uuid
string

Request parameters

tabs
array
homepage

Response

Example request

PATCH /api/user_home_settings/:uuid
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/user_home_settings/:uuid/\
	-d tabs="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/user_home_settings/{uuid}/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"tabs": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "tabs": [
    {
      "id": "string",
      "pathname": "string",
      "search": "string",
      "hash": "string",
      "title": "string",
      "customTitle": "string",
      "iconType": "string",
      "sceneId": "string",
      "sceneKey": "string",
      "sceneParams": null,
      "pinned": true
    }
  ],
  "homepage": {
    "id": "string",
    "pathname": "string",
    "search": "string",
    "hash": "string",
    "title": "string",
    "customTitle": "string",
    "iconType": "string",
    "sceneId": "string",
    "sceneKey": "string",
    "sceneParams": null,
    "pinned": true
  }
}

← Previous page

Platform

Endpoints

List all comments

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create comments

Required API key scopes

Request parameters

Response

Example request

Example response

Status 201

Retrieve comments

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update comments

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete comments

Required API key scopes

Path parameters

Example request

Example response

Status 405 No response body

Create comments complete

Path parameters

Response

Example request

Example response

Status 200

Create comments reopen

Path parameters

Response

Example request

Example response

Status 200

Retrieve comments thread

Required API key scopes

Path parameters

Example request

Example response

Status 200 No response body

Retrieve comments count

Required API key scopes

Example request

Example response

Status 200 No response body

Retrieve user home settings

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update user home settings

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Community questions