wizard

Upsert a wizard session. The session_id key is the idempotency anchor — reposting the same session_id replaces the existing row. Returns 201 on create, 200 on update.

post/api/projects/{project_id}/wizard/sessions/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/wizard/sessions/
  • Auth: HTTP bearer

Path parameters

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

handoff_textstring nullable

Markdown handoff doc for the run (the wizard's setup report). Send it once the run has produced one; omitting it on later pushes keeps the stored value.

session_idstring required

Stable identifier the wizard mints for this run (format: '{workflow_id}-{skill_id}-{started_at_iso}'). Reposting with the same session_id upserts the existing row.

workflow_idstring required

High-level workflow being run, e.g. 'onboarding', 'migration', 'audit'.

skill_idstring required

Specific skill within the workflow, e.g. 'nextjs', 'django', 'laravel'.

started_atstring date-time required

UTC timestamp when the wizard started this run. Matches the timestamp encoded in session_id.

run_phase'idle' | 'running' | 'completed' | 'error' required
  • idle - IDLE
  • running - RUNNING
  • completed - COMPLETED
  • error - ERROR
event_planobject nullable

Optional structured plan of events the wizard intends to instrument. Schema is workflow-specific.

errorobject nullable

Populated when run_phase='error'. Shape: { type: string, message: string }.

Response

session_idstring required
team_idinteger required
workflow_idstring required
skill_idstring required
started_atstring date-time required
run_phase'idle' | 'running' | 'completed' | 'error' required
  • idle - IDLE
  • running - RUNNING
  • completed - COMPLETED
  • error - ERROR
event_planobject nullable required
errorobject nullable required
handoff_textstring nullable required

Markdown handoff doc the wizard produced for this run (its setup report), or null while the run hasn't written one.

created_atstring date-time required
updated_atstring date-time required
is_staleboolean required

Changes

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