Wizard

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

Endpoints

GET
GET
POST
GET
PATCH
GET
GET
GET
GET
GET
POST
GET
GET
GET

List all wizard registry

List Wizard programs available for this project.

Required API key scopes

wizard_session:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

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": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "wizard_version": "string",
      "command": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "required_programs": [
        "string"
      ],
      "supported_environments": [
        "local"
      ]
    }
  ]
}

List all wizard runs

List Wizard runs for this project, ordered from newest to oldest.

Required API key scopes

wizard_session:read

Query parameters

  • created_after
    string
  • limit
    integer
  • offset
    integer
  • status
    array

Response


Example request

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

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": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "created_by_id": 0,
      "created_by": {
        "id": 0,
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com"
      },
      "environment": "local",
      "workspace": {
        "type": "local_folder",
        "project_name": "string"
      },
      "program": {
        "id": "string",
        "name": "string",
        "description": "string",
        "wizard_version": "string",
        "command": [
          "string"
        ],
        "tags": [
          "string"
        ],
        "required_programs": [
          "string"
        ],
        "supported_environments": [
          "local"
        ]
      },
      "status": "created",
      "error_code": "string",
      "error_message": "string",
      "stage": "dispatching",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "deadline_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create wizard runs

Create a local or cloud Wizard run for a project workspace.

Required API key scopes

wizard_session:write

Request parameters

  • program_id
    string
  • environment
  • workspace
  • idempotency_key
    string
  • wizard_version
    string

Response


Example request

POST /api/projects/:project_id/wizard/runs
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/runs/\
	-d program_id="string",\
	-d environment=undefined,\
	-d workspace=undefined

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com"
  },
  "environment": "local",
  "workspace": {
    "type": "local_folder",
    "project_name": "string"
  },
  "program": {
    "id": "string",
    "name": "string",
    "description": "string",
    "wizard_version": "string",
    "command": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "required_programs": [
      "string"
    ],
    "supported_environments": [
      "local"
    ]
  },
  "status": "created",
  "error_code": "string",
  "error_message": "string",
  "stage": "dispatching",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z"
}
Status 400
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 403
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 404
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 429
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Retrieve wizard runs

Retrieve a Wizard run in this project.

Required API key scopes

wizard_session:read

Path parameters

  • run_id
    string

Response


Example request

GET /api/projects/:project_id/wizard/runs/:run_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/runs/:run_id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com"
  },
  "environment": "local",
  "workspace": {
    "type": "local_folder",
    "project_name": "string"
  },
  "program": {
    "id": "string",
    "name": "string",
    "description": "string",
    "wizard_version": "string",
    "command": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "required_programs": [
      "string"
    ],
    "supported_environments": [
      "local"
    ]
  },
  "status": "created",
  "error_code": "string",
  "error_message": "string",
  "stage": "dispatching",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z"
}
Status 404
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Update wizard runs

Change the terminal status of a local Wizard run.

Required API key scopes

wizard_session:write

Path parameters

  • run_id
    string

Request parameters

  • status
  • error_code
    string | null

Response


Example request

PATCH /api/projects/:project_id/wizard/runs/:run_id
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/wizard/runs/:run_id/\
	-d status=undefined

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com"
  },
  "environment": "local",
  "workspace": {
    "type": "local_folder",
    "project_name": "string"
  },
  "program": {
    "id": "string",
    "name": "string",
    "description": "string",
    "wizard_version": "string",
    "command": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "required_programs": [
      "string"
    ],
    "supported_environments": [
      "local"
    ]
  },
  "status": "created",
  "error_code": "string",
  "error_message": "string",
  "stage": "dispatching",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "started_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z",
  "deadline_at": "2019-08-24T14:15:22Z"
}
Status 400
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 403
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 404
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 409
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

List all wizard runs artifacts

List metadata for artifacts produced by a Wizard run.

Required API key scopes

wizard_session:read

Path parameters

  • run_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/wizard/runs/:run_id/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/wizard/runs/:run_id/artifacts/

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": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
      "artifact_type": "git_diff",
      "size_bytes": 0,
      "content_hash": "string",
      "additions": 0,
      "removals": 0,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}
Status 404
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Retrieve wizard runs artifacts content

Get the unified git diff stored for a Wizard run artifact.

Required API key scopes

wizard_session:read

Path parameters

  • id
    string
  • run_id
    string

Example request

GET /api/projects/:project_id/wizard/runs/:run_id/artifacts/:id/content
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/runs/:run_id/artifacts/:id/content/

Example response

Status 200
Status 404
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}
Status 413
RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Retrieve wizard runs stream

Stream the current run state and subsequent updates. Use EventSource to consume this endpoint.

Required API key scopes

wizard_session:read

Path parameters

  • run_id
    string

Example request

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

Example response

Status 200
Status 204 No response body

Retrieve wizard runs tasks

API endpoints for managing Wizard run tasks. Access is scoped to the Wizard only.

The Wizard should be the only client that can update the tasks of a run.

Required API key scopes

wizard_run:read

Path parameters

  • run_id
    string

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "tasks": [
    {
      "name": "string",
      "status": "created",
      "created_at": "2019-08-24T14:15:22Z",
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "failed_at": "2019-08-24T14:15:22Z",
      "error_message": "string"
    }
  ]
}

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
    Default: 50
  • offset
    integer
    Default: 0
  • 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": [
    {
      "pending_input": {
        "id": "string",
        "asked_at": "2019-08-24T14:15:22Z",
        "question_count": 1,
        "sensitive": false,
        "prompts": [
          "string"
        ]
      },
      "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": {},
      "handoff_text": "string",
      "created_by": {
        "id": 0,
        "first_name": "string",
        "email": "string"
      },
      "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

  • pending_input
  • handoff_text
    string | null
  • session_id
    string
  • workflow_id
    string
  • skill_id
    string
  • started_at
    string
  • run_phase
  • tasks
    Click to open
    array
  • event_plan
    object | null
  • error
    object | null

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
{
  "pending_input": {
    "id": "string",
    "asked_at": "2019-08-24T14:15:22Z",
    "question_count": 1,
    "sensitive": false,
    "prompts": [
      "string"
    ]
  },
  "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": {},
  "handoff_text": "string",
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}
Status 201
RESPONSE
{
  "pending_input": {
    "id": "string",
    "asked_at": "2019-08-24T14:15:22Z",
    "question_count": 1,
    "sensitive": false,
    "prompts": [
      "string"
    ]
  },
  "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": {},
  "handoff_text": "string",
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "is_stale": true
}
Status 403 The session belongs to a different user.

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
{
  "pending_input": {
    "id": "string",
    "asked_at": "2019-08-24T14:15:22Z",
    "question_count": 1,
    "sensitive": false,
    "prompts": [
      "string"
    ]
  },
  "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": {},
  "handoff_text": "string",
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "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
{
  "pending_input": {
    "id": "string",
    "asked_at": "2019-08-24T14:15:22Z",
    "question_count": 1,
    "sensitive": false,
    "prompts": [
      "string"
    ]
  },
  "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": {},
  "handoff_text": "string",
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "string"
  },
  "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