Wizard

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

Endpoints

GET
POST
GET
GET
GET

List all wizard sessions

List wizard sessions for the project, ordered by started_at desc. This should only be called by the PostHog Wizard. Optional filters: ?workflow_id=<id> and ?skill_id=<id>.

Required API key scopes

wizard_session:read

Query parameters

  • limit
    integer
  • offset
    integer
  • skill_id
    string
  • workflow_id
    string

Response


Example request

GET /api/projects/:project_id/wizard/sessions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/wizard/sessions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "session_id": "string",
      "team_id": 0,
      "workflow_id": "string",
      "skill_id": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "run_phase": "idle",
      "tasks": [
        {
          "id": "string",
          "title": "string",
          "status": "pending"
        }
      ],
      "event_plan": {},
      "error": {},
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "is_stale": true
    }
  ]
}

Create wizard sessions

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.

Required API key scopes

wizard_session:write

Request parameters

  • session_id
    string
  • workflow_id
    string
  • skill_id
    string
  • started_at
    string
  • run_phase
  • tasks
    Click to open
    array
  • event_plan
    objectnull
  • error
    objectnull

Response


Example request

POST /api/projects/:project_id/wizard/sessions
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/wizard/sessions/\
	-d session_id="string",\
	-d workflow_id="string",\
	-d skill_id="string",\
	-d started_at="string",\
	-d run_phase=undefined,\
	-d tasks="array"

Example response

Status 200
RESPONSE
{
  "session_id": "string",
  "team_id": 0,
  "workflow_id": "string",
  "skill_id": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "run_phase": "idle",
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "status": "pending"
    }
  ],
  "event_plan": {},
  "error": {},
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}
Status 201
RESPONSE
{
  "session_id": "string",
  "team_id": 0,
  "workflow_id": "string",
  "skill_id": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "run_phase": "idle",
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "status": "pending"
    }
  ],
  "event_plan": {},
  "error": {},
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}

Retrieve wizard sessions

Retrieve a single wizard session by its session_id.

Required API key scopes

wizard_session:read

Path parameters

  • session_id
    string

Response


Example request

GET /api/projects/:project_id/wizard/sessions/:session_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/wizard/sessions/:session_id/

Example response

Status 200
RESPONSE
{
  "session_id": "string",
  "team_id": 0,
  "workflow_id": "string",
  "skill_id": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "run_phase": "idle",
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "status": "pending"
    }
  ],
  "event_plan": {},
  "error": {},
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}
Status 404 No session with that id for this project.

Retrieve wizard sessions latest

Return the single most-recent wizard session for a workflow (and optional skill), or 204 if none exists. Unlike list, this is a point lookup the app shell uses to decide whether to open the live SSE stream — it never returns a collection, and 'no run' is a 204 rather than a 404 so clients don't conflate it with a missing endpoint.

Required API key scopes

wizard_session:read

Query parameters

  • skill_id
    string
  • workflow_id
    string

Response


Example request

GET /api/projects/:project_id/wizard/sessions/latest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/wizard/sessions/latest/

Example response

Status 200
RESPONSE
{
  "session_id": "string",
  "team_id": 0,
  "workflow_id": "string",
  "skill_id": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "run_phase": "idle",
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "status": "pending"
    }
  ],
  "event_plan": {},
  "error": {},
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}
Status 204 No session for this workflow/skill in this project.

Retrieve wizard sessions stream

Server-Sent Events stream of wizard session updates for a (workflow_id, skill_id) pair. On connect, the current latest session (if any) is emitted as the first event; subsequent upserts are streamed in real time. The server closes the connection after 900 seconds with an event: end line so the client (EventSource) can reconnect.

SDK consumers: do not call the generated fetch wrapper for this path — it will buffer the entire infinite stream. Use the URL builder (getWizardSessionsStreamRetrieveUrl) with the browser's EventSource API instead.

Required API key scopes

wizard_session:read

Query parameters

  • skill_id
    string
  • workflow_id
    string

Example request

GET /api/projects/:project_id/wizard/sessions/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/wizard/sessions/stream/

Example response

Status 200

Community questions

Questions about this page? or post a community question.