Tasks

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

Endpoints

POST
POST
POST
POST
POST
GET
GET
POST
POST
GET
PATCH
POST
GET
GET
GET
POST
GET
POST
GET
POST
← Previous pageNext page →

Create tasks runs artifacts prepare upload

Reserve S3 object keys for task artifacts and return presigned POST forms for direct uploads.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/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/:task_id/runs/:id/artifacts/prepare_upload/\
	-d artifacts="array"

Example response

Status 200 Prepared 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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Create tasks runs artifacts presign

Returns a temporary, signed URL that can be used to download a specific artifact.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • storage_path
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/presign
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/:task_id/runs/:id/artifacts/presign/\
	-d storage_path="string"

Example response

Status 200 Presigned URL for the requested artifact
RESPONSE
{
  "url": "http://example.com",
  "expires_in": 0
}
Status 400 Invalid request
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Artifact not found

Create tasks runs cancel

Stop an active cloud run. Interrupts the agent, snapshots interactive sessions for later resume, tears down the sandbox, and marks the run cancelled. Idempotent: cancelling a finished run returns it unchanged.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • reason
    stringnull

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/cancel
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/:task_id/runs/:id/cancel/\
	-d reason=["string","null"]

Example response

Status 200 Run already finished; returned unchanged
RESPONSE
{
  "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": {},
  "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"
}
Status 202 Cancellation accepted
RESPONSE
{
  "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": {},
  "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"
}
Status 400 Run is not a cloud run
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 503 Cancellation could not be delivered; safe to retry
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create tasks runs clear conversation

Record a /clear boundary in a finished run's log so the next run in the chain starts with an empty conversation. Its checkpoints, artifacts, and visible history are unaffected. Only for a finished run: an active one has an agent that owns the clear, so send /clear to it as an ordinary message instead.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/clear_conversation
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/:task_id/runs/:id/clear_conversation/

Example response

Status 200 Run with the boundary recorded
RESPONSE
{
  "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": {},
  "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"
}
Status 404 Run not found
Status 409 Run is still active; send /clear to its agent
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Create tasks runs command

Queue user_message JSON-RPC commands through the task workflow and forward sandbox control commands to the agent server. Supports user_message, cancel, close, permission_response, set_config_option, mcp_response, native Pi RPC commands, and Pi queue operations.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • jsonrpc
  • method
  • params
    object
  • id

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/command
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/:task_id/runs/:id/command/\
	-d jsonrpc=undefined,\
	-d method=undefined

Example response

Status 200 Agent server response
RESPONSE
{
  "jsonrpc": "string",
  "id": null,
  "result": null,
  "error": {}
}
Status 400 Invalid command or no active sandbox
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 403 PostHog Desktop access is required to message this run's agent
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 429 Organization reached its PostHog Desktop usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 502 Agent server unreachable
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs connection token

Generate a JWT token for direct connection to the sandbox. Valid for 24 hours.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/connection_token
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/:task_id/runs/:id/connection_token/

Example response

Status 200 Connection token for direct sandbox connection
RESPONSE
{
  "token": "string"
}
Status 403 PostHog Desktop access is required
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 429 Organization reached its PostHog Desktop usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs logs

Fetch the logs for a task run as JSONL. If the run resumes from another (state.resume_from_run_id), each ancestor's log is concatenated first (oldest ancestor → ... → this run) so resume consumers see a single continuous history and can find the most recent git_checkpoint event regardless of which run emitted it.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/logs
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/:task_id/runs/:id/logs/

Example response

Status 200 Log content in JSONL format
Status 404 Task run not found

Create tasks runs relay message

Queue a Slack relay workflow to post a run message into the mapped Slack thread.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • text
    string
  • message_id
    stringnull
  • text_parts
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/relay_message
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/:task_id/runs/:id/relay_message/\
	-d text="string"

Example response

Status 200 Relay accepted
RESPONSE
{
  "status": "string",
  "relay_id": "string"
}
Status 404 Run not found

Create tasks runs resume in cloud

Resume an existing task run in a cloud sandbox. Terminates any existing workflow and starts a new one.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/resume_in_cloud
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/:task_id/runs/:id/resume_in_cloud/

Example response

Status 200 Run resumed in cloud
RESPONSE
{
  "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": {},
  "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"
}
Status 400 Run already active or workflow failed
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs session logs

Fetch session log entries for a task run with optional filtering by timestamp, event type, and limit.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Query parameters

  • after
    string
  • event_types
    string
  • exclude_types
    string
  • limit
    integer
    Default: 1000
  • offset
    integer
    Default: 0

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/session_logs
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/:task_id/runs/:id/session_logs/

Example response

Status 200 Filtered log events as JSON array
Status 404 Task run not found

Update tasks runs set output

Update the output field for a task run (e.g., PR URL, commit SHA, etc.)

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • output

Response


Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id/set_output
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/:task_id/runs/:id/set_output/\
	-d output=undefined

Example response

Status 200 Run with updated output
RESPONSE
{
  "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": {},
  "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"
}
Status 404 Run not found

Create tasks runs start

Start an existing cloud run after any initial run-scoped attachments have been uploaded.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Request parameters

  • pending_user_message
    string
  • pending_user_artifact_ids
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/start
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/:task_id/runs/:id/start/\
	-d pending_user_message="string"

Example response

Status 200 Task with updated latest run
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": {},
    "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"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_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"
    }
  ]
}
Status 400 Invalid start payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "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",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Task run not found
Status 429 Team is over its posthog_code usage limit
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

Retrieve tasks runs stream

Server-Sent Events stream of task run events. Events carry an id: line (a Redis stream id) usable as a resume cursor.

The server caps each connection at 900 seconds: it emits event: end with data: {"type": "rotated"} and closes. This does NOT mean the run finished — reconnect with the Last-Event-ID header set to the last received event id to resume without gaps or duplicates. Only treat the stream as complete when the run itself reaches a terminal status.

?start=latest consumers must also carry Last-Event-ID across reconnects: reconnecting without it re-resolves to the then-current latest event, silently skipping anything published while disconnected.

SDK consumers: do not call the generated fetch wrapper for this path — it will buffer the entire stream. Use the URL builder (getTasksRunsStreamRetrieveUrl) with a streaming fetch/EventSource-style consumer and the Last-Event-ID header instead.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Query parameters

  • start
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/stream
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/:task_id/runs/:id/stream/

Example response

Status 200

Retrieve tasks runs stream token

Generate a run-scoped JWT that authorizes reading this task run's live event stream via the agent-proxy.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/stream_token
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/:task_id/runs/:id/stream_token/

Example response

Status 200 Run-scoped token for reading the live event stream via the agent-proxy
RESPONSE
{
  "token": "string",
  "stream_base_url": "string"
}
Status 404 Task run not found

Retrieve tasks runs task session

API for managing task runs. Each run represents an execution of a task.

Required API key scopes

task:read

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id/task_session
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/:task_id/runs/:id/task_session/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "download_url": "http://example.com",
  "content_sha256": "string"
}
Status 404 Task session not found

Create tasks runs task session sync

API for managing task runs. Each run represents an execution of a task.

Required API key scopes

task:write

Path parameters

  • id
    string
  • task_id
    string

Response


Example request

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "content_sha256": "string"
}
Status 400 Missing required header
Status 403 Invalid task run token
Status 404 Task session not found
Status 409
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}

List all tasks runs living artifacts

Returns stable, versioned artifact handles created by the run's task.

Required API key scopes

task:read

Path parameters

  • run_id
    string
  • task_id
    string

Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_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/:task_id/runs/:run_id/living_artifacts/

Example response

Status 200 Living artifacts registered for this task run
RESPONSE
{
  "artifacts": [
    {
      "id": "string",
      "task_id": "string",
      "run_id": "string",
      "team_id": 0,
      "name": "string",
      "artifact_type": "slack_message",
      "adapter": "slack_message",
      "status": "active",
      "location": null,
      "metadata": null,
      "current_version": 0,
      "versions": [
        {}
      ],
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}
Status 404 Run not found

Create tasks runs living artifacts

Create a stable, editable artifact handle from direct markdown/text content or an existing run artifact. Slack adapters deliver into the mapped Slack thread; document artifacts use external connector storage when available.

Required API key scopes

task:write

Path parameters

  • run_id
    string
  • task_id
    string

Request parameters

  • name
    string
  • artifact_type
    Default: document
  • adapter
  • content
    string
  • content_base64
    string
  • content_type
    string
  • source_artifact_id
    string
  • source_storage_path
    string
  • metadata
    object

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts
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/:task_id/runs/:run_id/living_artifacts/\
	-d name="string"

Example response

Status 200 Created living artifact
RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "string"
}
Status 400 Invalid artifact payload
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Run not found

Retrieve tasks runs living artifacts

Return a stable living artifact handle and the current content when the adapter supports reads.

Required API key scopes

task:read

Path parameters

  • id
    string
  • run_id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts/: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/:task_id/runs/:run_id/living_artifacts/:id/

Example response

Status 200 Living artifact with current readable content
RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "string",
  "content": "string"
}
Status 404 Living artifact not found

Create tasks runs living artifacts

Commit a new version to an existing living artifact handle.

Required API key scopes

task:write

Path parameters

  • id
    string
  • run_id
    string
  • task_id
    string

Request parameters

  • name
    string
  • content
    string
  • content_base64
    string
  • content_type
    string
  • source_artifact_id
    string
  • source_storage_path
    string
  • metadata
    object

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:run_id/living_artifacts/:id/edit
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/:task_id/runs/:run_id/living_artifacts/:id/edit/\
	-d name="string"

Example response

Status 200 Updated living artifact
RESPONSE
{
  "id": "string",
  "task_id": "string",
  "run_id": "string",
  "team_id": 0,
  "name": "string",
  "artifact_type": "slack_message",
  "adapter": "slack_message",
  "status": "active",
  "location": null,
  "metadata": null,
  "current_version": 0,
  "versions": [
    {}
  ],
  "created_at": "string",
  "updated_at": "string"
}
Status 400 Invalid artifact update
RESPONSE
{
  "detail": "string",
  "error": "string",
  "type": "string",
  "code": "string",
  "attr": "string",
  "missing_artifact_ids": [
    "string"
  ],
  "limit_type": "burst",
  "reset_at": "string",
  "is_pro": true
}
Status 404 Living artifact not found
← Previous pageNext page →