Tasks

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

Endpoints

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

Retrieve code invites check access

Compatibility endpoint for released PostHog Desktop clients.

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "has_access": true,
  "has_loops_access": true
}

Status 503

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
}

Retrieve desktop access

Evaluate Desktop access for the selected project and organization.

Required API key scopes

llm_gateway:read

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "allowed": true,
  "reason": "startup_plan"
}

Status 503

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
}

List all tasks

Get a list of tasks for the current project, with optional filtering by origin product, stage, organization, repository, created_by, and the workflow (hog_flow_id) that created the task. By default, each row includes description. Pass basic=true for a summary row that omits description and includes description_preview, its first 1000 characters. Use the search parameter to match description text server-side.

Required API key scopes

task:read

Query parameters

all_team_tasks
boolean
Default: false
archived
string
One of: "true""false""all"
basic
boolean
Default: false
channel
string
ci_status
string
One of: "passing""failing""pending""none"
client_provenance
string
One of: "posthog_desktop"
commented_by
integer
created_by
integer
exclude_origin_product
string
One of: "onboarding""error_tracking""eval_clusters""user_created""slack""support_queue""session_summaries""posthog_ai""experiments""signal_report""autoresearch""signals_scout""scout_suggestions""support_reply""hogdesk""review_hog""image_builder""loop""mcp_analytics""signals_chat""task_analysis""workflow""space_setup""business_knowledge"
hog_flow_id
string
internal
string
One of: "true""false""all"
limit
integer
Default: 50
mentions
integer
offset
integer
Default: 0
ordering
string
One of: "-created_at""-last_activity_at"
organization
string
origin_product
string
pinned
boolean
pr_state
string
One of: "open""draft""merged""closed"
repository
string
search
string
stage
string
status
string
One of: "not_started""queued""in_progress""completed""failed""cancelled"

Response

Example request

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

Example response

Status 200 List of full task rows by default, or basic rows with description_preview when basic=true.

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",
      "task_number": 0,
      "slug": "string",
      "title": "string",
      "title_manually_set": true,
      "description": "string",
      "origin_product": "string",
      "runtime": "acp",
      "repository": "string",
      "repositories": [
        "string"
      ],
      "github_integration": 0,
      "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
      "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
      "json_schema": {},
      "internal": true,
      "archived": true,
      "archived_at": "2019-08-24T14:15:22Z",
      "latest_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
        "stage": "string",
        "branch": "string",
        "status": "string",
        "environment": "string",
        "runtime_adapter": "claude",
        "provider": "anthropic",
        "model": "string",
        "reasoning_effort": "off",
        "log_url": "http://example.com",
        "error_message": "string",
        "output": {},
        "task_summary": "string",
        "task_tags": [
          "string"
        ],
        "state": {},
        "artifacts": [
          {
            "id": "string",
            "name": "string",
            "type": "string",
            "source": "string",
            "size": 0,
            "content_type": "string",
            "metadata": {
              "skill_name": "string",
              "skill_source": "user",
              "content_sha256": "string",
              "bundle_format": "zip",
              "schema_version": 1
            },
            "storage_path": "string",
            "uploaded_at": "string",
            "uploaded_by": "agent",
            "uploaded_by_user_id": 0,
            "dismissed_at": "string",
            "url": "http://example.com"
          }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "completed_at": "2019-08-24T14:15:22Z",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "preview_available": true
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "last_activity_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"
      },
      "ci_prompt": "string",
      "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
      "slack_thread_references": [
        {
          "url": "string",
          "channel": "string",
          "created_at": "string"
        }
      ],
      "origin_key": "string"
    }
  ]
}

List all tasks

Required API key scopes

task:read

Query parameters

all_team_tasks
boolean
Default: false
archived
string
One of: "true""false""all"
basic
boolean
Default: false
channel
string
ci_status
string
One of: "passing""failing""pending""none"
client_provenance
string
One of: "posthog_desktop"
commented_by
integer
created_by
integer
exclude_origin_product
string
One of: "onboarding""error_tracking""eval_clusters""user_created""slack""support_queue""session_summaries""posthog_ai""experiments""signal_report""autoresearch""signals_scout""scout_suggestions""support_reply""hogdesk""review_hog""image_builder""loop""mcp_analytics""signals_chat""task_analysis""workflow""space_setup""business_knowledge"
hog_flow_id
string
internal
string
One of: "true""false""all"
limit
integer
Default: 50
mentions
integer
offset
integer
Default: 0
ordering
string
One of: "-created_at""-last_activity_at"
organization
string
origin_product
string
pinned
boolean
pr_state
string
One of: "open""draft""merged""closed"
repository
string
search
string
stage
string
status
string
One of: "not_started""queued""in_progress""completed""failed""cancelled"

Response

Example request

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

Example response

Status 200 List of full task rows by default, or basic rows with description_preview when basic=true.

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",
      "task_number": 0,
      "slug": "string",
      "title": "string",
      "title_manually_set": true,
      "description": "string",
      "origin_product": "string",
      "runtime": "acp",
      "repository": "string",
      "repositories": [
        "string"
      ],
      "github_integration": 0,
      "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
      "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
      "json_schema": {},
      "internal": true,
      "archived": true,
      "archived_at": "2019-08-24T14:15:22Z",
      "latest_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
        "stage": "string",
        "branch": "string",
        "status": "string",
        "environment": "string",
        "runtime_adapter": "claude",
        "provider": "anthropic",
        "model": "string",
        "reasoning_effort": "off",
        "log_url": "http://example.com",
        "error_message": "string",
        "output": {},
        "task_summary": "string",
        "task_tags": [
          "string"
        ],
        "state": {},
        "artifacts": [
          {
            "id": "string",
            "name": "string",
            "type": "string",
            "source": "string",
            "size": 0,
            "content_type": "string",
            "metadata": {
              "skill_name": "string",
              "skill_source": "user",
              "content_sha256": "string",
              "bundle_format": "zip",
              "schema_version": 1
            },
            "storage_path": "string",
            "uploaded_at": "string",
            "uploaded_by": "agent",
            "uploaded_by_user_id": 0,
            "dismissed_at": "string",
            "url": "http://example.com"
          }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "completed_at": "2019-08-24T14:15:22Z",
        "scheduled_at": "2019-08-24T14:15:22Z",
        "preview_available": true
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "last_activity_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"
      },
      "ci_prompt": "string",
      "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
      "slack_thread_references": [
        {
          "url": "string",
          "channel": "string",
          "created_at": "string"
        }
      ],
      "origin_key": "string"
    }
  ]
}

Create tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Request parameters

title
string
title_manually_set
boolean
description
string
origin_product
repository
string | null
repositories
array
github_integration
integer | null
github_user_integration
string | null
signal_report
string | null
signal_report_task_relationship
string
json_schema
archived
boolean
ci_prompt
string | null
branch
string | null
runtime_adapter
model
string | null
reasoning_effort
initial_permission_mode
pending_user_message
string | null
pending_user_artifact_ids
array
auto_publish
boolean | null
channel
string | null
scheduled_at
string | null
start_run
boolean
Default: false
signal_report_discussion_question
string
naming_source
string
sandbox_environment_id
string | null
custom_image_id
string | null
runtime

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string",
  "run_error": "string"
}

Status 402 The organization is on a Self-driving free trial, so a report implementation opens no pull request (code `self_driving_free_trial`), or the organization reached its self-driving pull request limit

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 403 Agent-started runs are limited to the internal project and cannot start from a sandbox token. Immediate runs also require PostHog Desktop access and an enabled Pi cloud runtime.

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 429 Organization reached its PostHog Desktop usage limit, the signal report reached its task limit (code `signal_report_task_cap`), or the per-user creation rate limit fired

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 PostHog Desktop access could not be verified, or warm run activation is unavailable (code `warm_run_activation_unavailable`). After confirmed nondelivery, a retry_token permits retrying the same run and message with X-PostHog-Warm-Retry. Web retries for up to 20 seconds.

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 tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Request parameters

title
string
title_manually_set
boolean
description
string
origin_product
repository
string | null
repositories
array
github_integration
integer | null
github_user_integration
string | null
signal_report
string | null
signal_report_task_relationship
string
json_schema
archived
boolean
ci_prompt
string | null
branch
string | null
runtime_adapter
model
string | null
reasoning_effort
initial_permission_mode
pending_user_message
string | null
pending_user_artifact_ids
array
auto_publish
boolean | null
channel
string | null
scheduled_at
string | null
start_run
boolean
Default: false
signal_report_discussion_question
string
naming_source
string
sandbox_environment_id
string | null
custom_image_id
string | null
runtime

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string",
  "run_error": "string"
}

Status 402 The organization is on a Self-driving free trial, so a report implementation opens no pull request (code `self_driving_free_trial`), or the organization reached its self-driving pull request limit

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 403 Agent-started runs are limited to the internal project and cannot start from a sandbox token. Immediate runs also require PostHog Desktop access and an enabled Pi cloud runtime.

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 429 Organization reached its PostHog Desktop usage limit, the signal report reached its task limit (code `signal_report_task_cap`), or the per-user creation rate limit fired

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 PostHog Desktop access could not be verified, or warm run activation is unavailable (code `warm_run_activation_unavailable`). After confirmed nondelivery, a retry_token permits retrying the same run and message with X-PostHog-Warm-Retry. Web retries for up to 20 seconds.

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
}

Retrieve tasks

Retrieve a single task by ID.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200 Task

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string"
}

Retrieve tasks

Retrieve a single task by ID.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200 Task

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string"
}

Update tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

title
string
title_manually_set
boolean
description
string
origin_product
repository
string | null
repositories
array
github_integration
integer | null
github_user_integration
string | null
signal_report
string | null
signal_report_task_relationship
string
json_schema
archived
boolean
ci_prompt
string | null
branch
string | null
runtime_adapter
model
string | null
reasoning_effort
initial_permission_mode
pending_user_message
string | null
pending_user_artifact_ids
array
auto_publish
boolean | null
channel
string | null

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string"
}

Update tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

title
string
title_manually_set
boolean
description
string
origin_product
repository
string | null
repositories
array
github_integration
integer | null
github_user_integration
string | null
signal_report
string | null
signal_report_task_relationship
string
json_schema
archived
boolean
ci_prompt
string | null
branch
string | null
runtime_adapter
model
string | null
reasoning_effort
initial_permission_mode
pending_user_message
string | null
pending_user_artifact_ids
array
auto_publish
boolean | null
channel
string | null

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task_number": 0,
  "slug": "string",
  "title": "string",
  "title_manually_set": true,
  "description": "string",
  "origin_product": "string",
  "runtime": "acp",
  "repository": "string",
  "repositories": [
    "string"
  ],
  "github_integration": 0,
  "github_user_integration": "d46b8f4e-2e12-4354-88a4-723bb64114d3",
  "signal_report": "f46cde2b-d4ed-4f8c-8d95-dad529d245b3",
  "json_schema": {},
  "internal": true,
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
    "stage": "string",
    "branch": "string",
    "status": "string",
    "environment": "string",
    "runtime_adapter": "claude",
    "provider": "anthropic",
    "model": "string",
    "reasoning_effort": "off",
    "log_url": "http://example.com",
    "error_message": "string",
    "output": {},
    "task_summary": "string",
    "task_tags": [
      "string"
    ],
    "state": {},
    "artifacts": [
      {
        "id": "string",
        "name": "string",
        "type": "string",
        "source": "string",
        "size": 0,
        "content_type": "string",
        "metadata": {
          "skill_name": "string",
          "skill_source": "user",
          "content_sha256": "string",
          "bundle_format": "zip",
          "schema_version": 1
        },
        "storage_path": "string",
        "uploaded_at": "string",
        "uploaded_by": "agent",
        "uploaded_by_user_id": 0,
        "dismissed_at": "string",
        "url": "http://example.com"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "scheduled_at": "2019-08-24T14:15:22Z",
    "preview_available": true
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_activity_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"
  },
  "ci_prompt": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "slack_thread_references": [
    {
      "url": "string",
      "channel": "string",
      "created_at": "string"
    }
  ],
  "origin_key": "string"
}

Delete tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

id
string

Example request

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

Example response

Status 204 No response body

Delete tasks

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:write

Path parameters

id
string

Example request

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

Example response

Status 204 No response body

List all tasks artifacts

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "type": "string",
      "name": "string"
    }
  ]
}

List all tasks artifacts

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "type": "string",
      "name": "string"
    }
  ]
}

List all tasks comments

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

comment:read

Path parameters

id
string

Query parameters

artifact_id
string
cursor
string
include_resolved
boolean
Default: false
limit
integer
Default: 50

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "target": {
        "id": "string",
        "type": "string",
        "name": "string"
      },
      "content": "string",
      "content_truncated": true,
      "selected_text": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "reply_count": 0,
      "resolved": true
    }
  ],
  "next": "string"
}

List all tasks comments

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

comment:read

Path parameters

id
string

Query parameters

artifact_id
string
cursor
string
include_resolved
boolean
Default: false
limit
integer
Default: 50

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "target": {
        "id": "string",
        "type": "string",
        "name": "string"
      },
      "content": "string",
      "content_truncated": true,
      "selected_text": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "reply_count": 0,
      "resolved": true
    }
  ],
  "next": "string"
}

Retrieve tasks comments

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

comment:read

Path parameters

id
string
root_comment_id
string

Query parameters

comment_id
string
content_offset
integer
Default: 0
cursor
string
limit
integer
Default: 50

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "target": {
    "id": "string",
    "type": "string",
    "name": "string"
  },
  "resolved": true,
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "content": "string",
      "content_truncated": true,
      "content_next_offset": 0,
      "author": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "anchor": {
        "kind": "string",
        "quote": "string",
        "prefix": "string",
        "suffix": "string",
        "start": 0,
        "end": 1,
        "x": 1,
        "y": 1,
        "width": 1,
        "height": 1
      },
      "canvas_version_id": "string"
    }
  ],
  "next": "string"
}

Retrieve tasks comments

API for managing tasks within a project. Tasks represent units of work to be performed by an agent.

Required API key scopes

comment:read

Path parameters

id
string
root_comment_id
string

Query parameters

comment_id
string
content_offset
integer
Default: 0
cursor
string
limit
integer
Default: 50

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "target": {
    "id": "string",
    "type": "string",
    "name": "string"
  },
  "resolved": true,
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "content": "string",
      "content_truncated": true,
      "content_next_offset": 0,
      "author": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "anchor": {
        "kind": "string",
        "quote": "string",
        "prefix": "string",
        "suffix": "string",
        "start": 0,
        "end": 1,
        "x": 1,
        "y": 1,
        "width": 1,
        "height": 1
      },
      "canvas_version_id": "string"
    }
  ],
  "next": "string"
}