Tasks

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

Endpoints

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

← Previous pageNext page →

Create tasks handoff

Transfer ownership of a task to another member of the project: they take over driving it (steering, archiving, running), and future runs resolve GitHub authorship and notification recipients from them. Only the task's current owner can hand it off. Every run must be finished or canceled, and every sandbox must be shut down first. A task in a private space moves into the recipient's private space; a task in a shared space stays there.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

user
integer

Response

Example request

POST /api/projects/:project_id/tasks/:id/handoff
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/:id/handoff/\
	-d user="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{tasks-2_id}/handoff/".format(
        project_id=project_id,
		tasks-2_id="<the tasks-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"user": "integer"
	}
).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",
  "client_provenance": "posthog_desktop"
}

Status 403 Only a user may hand off a task.

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 handoff

Required API key scopes

task:write

Path parameters

id
string

Request parameters

user
integer

Response

Example request

POST /api/projects/:project_id/tasks/:id/handoff
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/:id/handoff/\
	-d user="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/tasks/{tasks-2_id}/handoff/".format(
        project_id=project_id,
		tasks-2_id="<the tasks-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"user": "integer"
	}
).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",
  "client_provenance": "posthog_desktop"
}

Status 403 Only a user may hand off a task.

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 pin

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

pinned
boolean

Response

Example request

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

Example response

Status 200

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

Create tasks pin

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

pinned
boolean

Response

Example request

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

Example response

Status 200

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

Create tasks presence

Idempotent upsert: marks the calling user + device_id as actively watching this task for the next ~60 seconds. While at least one device for the user has a non-expired presence row for this task, the push fanout will skip ALL of that user's other registered devices for task notifications — the contract is 'if any device is demonstrably watching, suppress the others'. Clients call this every ~30s while the task screen is foregrounded. device_id is the UUID of the caller's UserPushToken row.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

device_id
string

Example request

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

Example response

Status 204 Presence recorded for this device.

Status 404 `device_id` does not match a push token registered by the caller.

Create tasks presence

Required API key scopes

task:write

Path parameters

id
string

Request parameters

device_id
string

Example request

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

Example response

Status 204 Presence recorded for this device.

Status 404 `device_id` does not match a push token registered by the caller.

Delete tasks presence

Required API key scopes

task:write

Path parameters

id
string

Example request

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

Example response

Status 204 Presence recorded for this device.

Status 404 `device_id` does not match a push token registered by the caller.

Delete tasks presence

Required API key scopes

task:write

Path parameters

id
string

Example request

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

Example response

Status 204 Presence recorded for this device.

Status 404 `device_id` does not match a push token registered by the caller.

Retrieve tasks review

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

Query parameters

page
integer
Default: 1

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "url": "http://example.com",
  "title": "string",
  "state": "string",
  "ci_status": "string",
  "head_sha": "string",
  "files": [
    {
      "filename": "string",
      "status": "string",
      "additions": 0,
      "deletions": 0,
      "patch": "string",
      "truncated": true
    }
  ],
  "has_more": true
}

Retrieve tasks review

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

Query parameters

page
integer
Default: 1

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "url": "http://example.com",
  "title": "string",
  "state": "string",
  "ci_status": "string",
  "head_sha": "string",
  "files": [
    {
      "filename": "string",
      "status": "string",
      "additions": 0,
      "deletions": 0,
      "patch": "string",
      "truncated": true
    }
  ],
  "has_more": true
}

Create tasks run

Create a new task run and kick off the workflow. The response is the refreshed task with the created run under the top-level run key: read run.id for anything run-scoped, such as the run's stream and command endpoints. The top-level id is the task's, and latest_run mirrors run only as long as nothing newer starts — reading either of those as the created run is deprecated.

Required API key scopes

task:write

Path parameters

id
string

Response

Example request

Example response

Status 200 The refreshed task, plus the created run under the top-level `run` key

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",
  "client_provenance": "posthog_desktop",
  "run_error": "string",
  "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
  }
}

Status 400 Invalid task run payload

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 402 The organization is on a Self-driving free trial, so a report implementation opens no pull request (code `self_driving_free_trial`)

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 PostHog Desktop access is required, or Pi cloud runtime is disabled

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 404 Task not found

Status 429 Team is over its posthog_code usage limit, or the task's signal report has reached its task limit (code `signal_report_task_cap`)

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 run

Required API key scopes

task:write

Path parameters

id
string

Response

Example request

Example response

Status 200 The refreshed task, plus the created run under the top-level `run` key

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",
  "client_provenance": "posthog_desktop",
  "run_error": "string",
  "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
  }
}

Status 400 Invalid task run payload

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 402 The organization is on a Self-driving free trial, so a report implementation opens no pull request (code `self_driving_free_trial`)

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 PostHog Desktop access is required, or Pi cloud runtime is disabled

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 404 Task not found

Status 429 Team is over its posthog_code usage limit, or the task's signal report has reached its task limit (code `signal_report_task_cap`)

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 staged artifacts finalize upload

Verify staged S3 uploads and cache their metadata so they can be attached to the next run created for this task.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

artifacts
array

Response

Example request

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

Example response

Status 200 Finalized staged artifacts available for the next task run

RESPONSE
{
  "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"
    }
  ]
}

Status 400 Invalid artifact payload

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 404 Task not found

Create tasks staged artifacts finalize upload

Verify staged S3 uploads and cache their metadata so they can be attached to the next run created for this task.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

artifacts
array

Response

Example request

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

Example response

Status 200 Finalized staged artifacts available for the next task run

RESPONSE
{
  "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"
    }
  ]
}

Status 400 Invalid artifact payload

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 404 Task not found

Create tasks staged artifacts prepare upload

Reserve S3 object keys for task attachments before creating a new run and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

artifacts
array

Response

Example request

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

Example response

Status 200 Prepared staged uploads for the requested artifacts

RESPONSE
{
  "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",
      "expires_in": 0,
      "presigned_post": {
        "url": "http://example.com",
        "fields": {
          "property1": "string",
          "property2": "string"
        }
      }
    }
  ]
}

Status 400 Invalid artifact payload

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 404 Task not found

Create tasks staged artifacts prepare upload

Reserve S3 object keys for task attachments before creating a new run and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

artifacts
array

Response

Example request

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

Example response

Status 200 Prepared staged uploads for the requested artifacts

RESPONSE
{
  "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",
      "expires_in": 0,
      "presigned_post": {
        "url": "http://example.com",
        "fields": {
          "property1": "string",
          "property2": "string"
        }
      }
    }
  ]
}

Status 400 Invalid artifact payload

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 404 Task not found

Retrieve tasks usage

Return estimated model and cloud compute costs attributed to a task.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "token_cost_usd": 0.1,
  "compute_cost_usd": 0.1,
  "total_cost_usd": 0.1
}

Retrieve tasks usage

Return estimated model and cloud compute costs attributed to a task.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "token_cost_usd": 0.1,
  "compute_cost_usd": 0.1,
  "total_cost_usd": 0.1
}

Create tasks warm resume

Warm an idling successor for the task's latest terminal Run while the user composes the next message. The successor restores the prior snapshot when compatible and waits for the normal run endpoint to activate it. Best-effort: returns an empty body when warming is disabled, capped, or the task advanced to another Run.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

resume_from_run_id
string
runtime_adapter
model
string
reasoning_effort
initial_permission_mode

Response

Example request

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

Example response

Status 200 Successor Run provisioned, or an empty body when warming is unavailable or the source run changed.

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec"
}

Status 403 PostHog Desktop access is required

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 404 Task not found

Status 429 Team is over its posthog_code usage 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
}

Create tasks warm resume

Required API key scopes

task:write

Path parameters

id
string

Request parameters

resume_from_run_id
string
runtime_adapter
model
string
reasoning_effort
initial_permission_mode

Response

Example request

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

Example response

Status 200 Successor Run provisioned, or an empty body when warming is unavailable or the source run changed.

RESPONSE
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec"
}

Status 403 PostHog Desktop access is required

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 404 Task not found

Status 429 Team is over its posthog_code usage 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
}

← Previous pageNext page →