Task

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

Endpoints

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

List all task channels

List channels the requester can access, sorted by name and ID. Includes public channels, their personal #me channel, and private channels they belong to. Call provision_defaults to create missing default channels. Send limit and offset to get a page with count, next, previous, and results. Without limit, the response is an array of all accessible channels.

Required API key scopes

task:read

Query parameters

limit
integer
offset
integer

Response

Example request

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

Example response

Status 200 List of channels

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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "channel_type": "string",
      "github_integration": 0,
      "repositories": [
        "string"
      ],
      "auto_archive_after_days": 0,
      "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": "string",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "string"
      },
      "starred": true,
      "system_role": "personal"
    }
  ]
}

Create task channels

Create a channel. Public channels use lowercase names with hyphens. If a public channel has that name, return it. The name general returns the project's general space. Private channels always get a new ID, even if another channel has the same name. The requester and users in member_ids with project access become members. New channels are starred for the requester unless star is false. The names "me" and "personal" are reserved.

Required API key scopes

task:write

Request parameters

name
string
channel_type
Default: public
member_ids
array
star
boolean
Default: true

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "channel_type": "string",
  "github_integration": 0,
  "repositories": [
    "string"
  ],
  "auto_archive_after_days": 0,
  "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": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "starred": true,
  "system_role": "personal"
}

List all task channels feed

A channel's system announcements in chronological order.

Required API key scopes

task:read

Path parameters

channel_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

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

Example response

Status 200 Feed messages, chronological

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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
      "author": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "string"
      },
      "author_kind": "string",
      "event": "string",
      "payload": {},
      "content": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create task channels feed

API for a channel's system-announcement feed — durable "PostHog agent" rows (context created, CONTEXT.md being built) rendered alongside the channel's task cards. Read by any team member for a public channel; personal channels are owner-only.

Required API key scopes

task:write

Path parameters

channel_id
string

Request parameters

event
payload
created_at
string

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "author": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "author_kind": "string",
  "event": "string",
  "payload": {},
  "content": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve task channels

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "channel_type": "string",
  "github_integration": 0,
  "repositories": [
    "string"
  ],
  "auto_archive_after_days": 0,
  "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": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "starred": true,
  "system_role": "personal"
}

Update task channels

Required API key scopes

task:write

Path parameters

id
string

Request parameters

name
string
github_integration
integer | null
repositories
array
auto_archive_after_days
integer | null
channel_type

Response

Example request

PATCH /api/projects/:project_id/task_channels/: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/task_channels/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "channel_type": "string",
  "github_integration": 0,
  "repositories": [
    "string"
  ],
  "auto_archive_after_days": 0,
  "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": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "starred": true,
  "system_role": "personal"
}

Delete task channels

Required API key scopes

task:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/task_channels/: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/task_channels/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Status 409 The space still contains tasks or canvases.

RESPONSE
{
  "detail": "string"
}

Retrieve task channels context generation

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}

Retrieve task channels instructions

The channel's latest CONTEXT.md instructions. A channel with no published instructions reads as a blank version 0 — publish against base_version 0 to create version 1.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "content": "string",
  "version": 0,
  "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": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  }
}

Update task channels instructions

Publish a new version of the channel's CONTEXT.md instructions. Pass base_version (the version you read) so a concurrent edit is rejected with 409 instead of overwritten.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

content
string
base_version
integer | null

Response

Example request

PATCH /api/projects/:project_id/task_channels/:id/instructions
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/task_channels/:id/instructions/\
	-d content="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/instructions/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"content": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "content": "string",
  "version": 0,
  "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": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  }
}

Delete task channels instructions

Required API key scopes

task:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/task_channels/:id/instructions
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/task_channels/:id/instructions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/instructions/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Retrieve task channels instructions versions

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/task_channels/:id/instructions/versions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/task_channels/:id/instructions/versions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/instructions/versions/".format(
        project_id=project_id,
		task_channel_id="<the task channel 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": [
    {
      "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
      "content": "string",
      "version": 0,
      "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": "string",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "string"
      }
    }
  ]
}

Retrieve task channels members

List the members of a private channel. Return an empty list for public and personal channels. Return 404 if the requester cannot access the channel.

Required API key scopes

task:read

Path parameters

id
string

Example request

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

Example response

Status 200 Channel members

RESPONSE
{
  "id": 0,
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "distinct_id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "is_email_verified": true,
  "hedgehog_config": {},
  "role_at_organization": "string"
}

Create task channels setup

Starts one unattended task in the channel that resolves the metric, writes the context page and, for a goal, creates the tracking canvas and the loops. The task becomes the channel's context generation task.

Required API key scopes

task:writecanvas:writehog_flow:writeperson:readgroup:readintegration:readuser:readquery:readaction:readdata_catalog:readinsight:readdashboard:readfeature_flag:readexperiment:readerror_tracking:readsession_recording:readevent_definition:readproperty_definition:readproject:readorganization:readsurvey:read

Path parameters

id
string

Request parameters

kind
goal
feature
repository
string | null

Response

Example request

POST /api/projects/:project_id/task_channels/:id/setup
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/task_channels/:id/setup/\
	-d kind=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/setup/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 201 The setup task that started

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}

Status 409 Space setup is already running

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Status 503 A setup dependency is unavailable

RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "retry_token": "string",
  "reason": "startup_plan",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create task channels star

Required API key scopes

task:write

Path parameters

id
string

Request parameters

starred
boolean

Example request

POST /api/projects/:project_id/task_channels/:id/star
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/task_channels/:id/star/\
	-d starred="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/task_channels/{task_channel_id}/star/".format(
        project_id=project_id,
		task_channel_id="<the task channel id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"starred": "boolean"
	}
).json()

Example response

Status 204 No response body

Retrieve task channels contributors

For each channel the requester can access, list the people who own at least one task or canvas in it, most recently active first. Channels with no owners are left out.

Required API key scopes

task:read

Example request

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

Example response

Status 200 The task and canvas owners of each channel

RESPONSE
{
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "people": [
    {
      "id": 0,
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "distinct_id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "is_email_verified": true,
      "hedgehog_config": {},
      "role_at_organization": "string"
    }
  ]
}

Create task channels onboarding session

Open the agent session a new user lands in, in the team's #general space. Reads the company's homepage, so it takes a few seconds and is deliberately not part of provisioning, which blocks the app opening. Callers fire it without awaiting it when provision_defaults reports personal_created.

Required API key scopes

task:write

Response

Example request

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

Example response

Status 200 The session that was started

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}