tasks
tasks

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

put/api/projects/{project_id}/tasks/{id}/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/tasks/{id}/
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

idstring required
project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

titlestring

Short human-readable title. Auto-generated from description when omitted.

title_manually_setboolean

Whether the title was set by a human (vs auto-generated from the description).

descriptionstring

Free-form description of the work to be done. Used as the prompt passed to the agent.

origin_product'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' | 'metrics_import'
  • onboarding - Onboarding
  • error_tracking - Error Tracking
  • eval_clusters - Eval Clusters
  • user_created - User Created
  • slack - Slack
  • support_queue - Support Queue
  • session_summaries - Session Summaries
  • posthog_ai - PostHog AI
  • experiments - Experiments
  • signal_report - Signal Report
  • autoresearch - Autoresearch
  • signals_scout - Signals Scout
  • scout_suggestions - Signals Scout Suggestions
  • support_reply - Support Reply
  • hogdesk - HogDesk
  • review_hog - ReviewHog
  • image_builder - Image Builder
  • loop - Loop
  • mcp_analytics - MCP Analytics
  • signals_chat - Signals Chat
  • task_analysis - Task Analysis
  • workflow - Workflow
  • space_setup - Space Setup
  • business_knowledge - Business Knowledge
  • metrics_import - Metrics Import
repositorystring nullable

Target GitHub repository in organization/repo format (e.g. posthog/posthog-js).

repositoriesstring[]

GitHub repositories available to this task, each in organization/repo format.

github_integrationinteger nullable

GitHub integration for this task.

github_user_integrationstring uuid nullable

User-scoped GitHub integration to use for user-authored cloud runs.

signal_reportstring uuid nullable

Signal report this task implements, when created from a report.

signal_report_task_relationshipstring

How the created task relates to the signal report (e.g. 'implementation', 'discussion'). Recorded as a signals task_run work-log entry; 'implementation' also opens the auto-start spend gate. Any routing-safe identifier (lowercase letters, numbers, '_', '-') is accepted except labels reserved for server-created tasks ('research', 'repo_selection', 'scout'). Non-implementation labels count toward the report's discussion task limit.

json_schemaunknown
archivedboolean

If true, the task is hidden from default list responses.

ci_promptstring nullable

Custom prompt for CI fixes. If blank, a default prompt will be used.

branchstring nullable

Base branch for the first run when start_run is true, or for matching a pre-warmed run. Omit to use the repository's default branch. Write-only and not persisted on the task.

modelstring nullable

LLM model for the first run when start_run is true, or for matching a pre-warmed run. Write-only.

pending_user_messagestring nullable

First user message when start_run is true or creation reuses a pre-warmed run. This message can differ from description. Ignored if creation does not start a run. Write-only and not persisted on the task.

pending_user_artifact_idsstring[]

Run artifact ids (already uploaded to the pre-warmed Run) to attach to the forwarded first message when creation reuses that warm Run, e.g. skill bundles or file attachments. If any id is missing from the warm Run's manifest, warm reuse is skipped and the task is created cold. Ignored when no warm Run is matched. Not supported when start_run is true.

auto_publishboolean nullable

When true, the agent pushes its work and opens a draft pull request on completion without an explicit request. Applies when start_run is true or creation reuses a pre-warmed run. Resumed runs keep this setting. Ignored if creation does not start a run. Write-only and not persisted on the task.

channelstring uuid nullable

Channel this task is owned by (the channel it was kicked off in).

Response

idstring uuid required
task_numberinteger nullable required
slugstring required
titlestring required
title_manually_setboolean required
descriptionstring required
origin_productstring required
runtime'acp' | 'pi' required
  • acp - ACP
  • pi - Pi
repositorystring nullable required
repositoriesstring[] required
github_integrationinteger nullable required
github_user_integrationstring uuid nullable required
signal_reportstring uuid nullable required
json_schemaobject nullable required
internalboolean required
archivedboolean required
archived_atstring date-time nullable required
created_atstring date-time nullable
updated_atstring date-time nullable
last_activity_atstring date-time nullable
ci_promptstring nullable required
channelstring uuid nullable
origin_keystring nullable

Stable key of the server-side flow that created this task, e.g. desktop_onboarding_session:<user_id>. Null for tasks people create themselves.

Changes

No recorded changes to this operation across all 1 revision of this API.