Canvases

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`POST`
`GET`
`POST`
`GET`
`GET`
`POST`
`POST`
`GET`
`POST`
`GET`
`POST`
`POST`
`POST`
`POST`
`POST`

List all canvases

Canvases: agent-built sandboxed browser apps, filed into channels.

Source is versioned per publish and built server-side; the canvas app renders the published build's artifact from the isolated artifact origin.

Required API key scopes

canvas:read

Query parameters

channel
string
kind
string
One of: "component""freeform""grid"
limit
integer
offset
integer
ordering
string
One of: "-created_at""-updated_at"
search
string

Response

Example request

GET /api/projects/:project_id/canvases
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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",
      "name": "string",
      "kind": "freeform",
      "description": "string",
      "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
      "template_id": "string",
      "generation_task_id": "3dbed3af-6ffc-42e6-a65f-e4359d320aee",
      "pinned": true,
      "pinned_at": "2019-08-24T14:15:22Z",
      "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
      "published_build_id": "69a71d2a-40ba-4471-84c6-e403214736b9",
      "component_meta": {
        "size": {
          "defaultW": 1,
          "defaultH": 1,
          "minW": 1,
          "minH": 1,
          "maxW": 1,
          "maxH": 1
        },
        "configSchema": {}
      },
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "url": "string"
    }
  ]
}

Create canvases

Create a new, empty canvas in a channel; give it source by publishing a project.

Required API key scopes

canvas:write

Request parameters

name
string
channel_id
string
kind
Default: freeform
description
string
Default:
template_id
string
Default: freeform

Response

Example request

POST /api/projects/:project_id/canvases
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/canvases/\
	-d name="string",\
	-d channel_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string",
		"channel_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "kind": "freeform",
  "description": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "template_id": "string",
  "generation_task_id": "3dbed3af-6ffc-42e6-a65f-e4359d320aee",
  "pinned": true,
  "pinned_at": "2019-08-24T14:15:22Z",
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "published_build_id": "69a71d2a-40ba-4471-84c6-e403214736b9",
  "component_meta": {
    "size": {
      "defaultW": 1,
      "defaultH": 1,
      "minW": 1,
      "minH": 1,
      "maxW": 1,
      "maxH": 1
    },
    "configSchema": {}
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "url": "string"
}

Status 403 The sandbox token is not bound to this task or space.

Retrieve canvases

Canvases: agent-built sandboxed browser apps, filed into channels.

Source is versioned per publish and built server-side; the canvas app renders the published build's artifact from the isolated artifact origin.

Required API key scopes

canvas:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/canvases/: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/canvases/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "kind": "freeform",
  "description": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "template_id": "string",
  "generation_task_id": "3dbed3af-6ffc-42e6-a65f-e4359d320aee",
  "pinned": true,
  "pinned_at": "2019-08-24T14:15:22Z",
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "published_build_id": "69a71d2a-40ba-4471-84c6-e403214736b9",
  "component_meta": {
    "size": {
      "defaultW": 1,
      "defaultH": 1,
      "minW": 1,
      "minH": 1,
      "maxW": 1,
      "maxH": 1
    },
    "configSchema": {}
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "url": "string"
}

Update canvases

Update canvas metadata, including the space it belongs to.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

name
string
description
string
channel_id
string
pinned
boolean
generation_task_id
string | null

Response

Example request

PATCH /api/projects/:project_id/canvases/: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/canvases/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "kind": "freeform",
  "description": "string",
  "channel": "e03ac425-e659-44cf-b8d7-f4176416fcf2",
  "template_id": "string",
  "generation_task_id": "3dbed3af-6ffc-42e6-a65f-e4359d320aee",
  "pinned": true,
  "pinned_at": "2019-08-24T14:15:22Z",
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "published_build_id": "69a71d2a-40ba-4471-84c6-e403214736b9",
  "component_meta": {
    "size": {
      "defaultW": 1,
      "defaultH": 1,
      "minW": 1,
      "minH": 1,
      "maxW": 1,
      "maxH": 1
    },
    "configSchema": {}
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "url": "string"
}

Status 403 Only the canvas creator can change the name, description, space, or pin state.

Delete canvases

Canvases: agent-built sandboxed browser apps, filed into channels.

Source is versioned per publish and built server-side; the canvas app renders the published build's artifact from the isolated artifact origin.

Required API key scopes

canvas:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/canvases/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create canvases actions

Invoke one registered action verb as the viewer.

The canvas must declare the verb in capabilities.posthog.actions (the reviewed permission boundary); the write itself runs with the viewer's own permissions, exactly as if they acted in the app.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

verb
string
payload
object

Response

Example request

POST /api/projects/:project_id/canvases/:id/actions/invoke
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/canvases/:id/actions/invoke/\
	-d verb="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/actions/invoke/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"verb": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "verb": "string",
  "result": {}
}

Status 400 Unknown verb, or the payload failed the verb's schema.

Status 403 The verb is not declared in the canvas's capabilities, actions are disabled for the team, or the caller is a sandbox.

Retrieve canvases builds

Read the canvas's build lifecycle: live pointers plus recent builds.

A publish queues a build; poll this until it is ready (the live pointer advances) or failed (fix the error diagnostics and publish again — the last good build stays live). Send the response's ETag back as If-None-Match to make the poll revalidate without a body.

Required API key scopes

canvas:read

Path parameters

id
string

Query parameters

scope
string
version_id
string

Response

Example request

GET /api/projects/:project_id/canvases/:id/builds
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/:id/builds/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/builds/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "published_build_id": "string",
  "current_version_id": "string",
  "builds": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
      "build_status": "queued",
      "diagnostics": [
        {
          "severity": "error",
          "code": "string",
          "message": "string",
          "path": "string",
          "line": 0
        }
      ],
      "manifest": {
        "entryHtml": "string",
        "assets": [
          {
            "path": "string",
            "contentHash": "string",
            "sizeBytes": 0
          }
        ],
        "dependencies": {
          "property1": "string",
          "property2": "string"
        },
        "canvasSdkVersion": "string",
        "legacyComponentPath": "string",
        "legacyCode": "string",
        "capabilities": {},
        "component": {}
      },
      "integrity": "string",
      "artifact_url": "string",
      "pinned": true,
      "created_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Status 304 Not modified — the client's cached lifecycle is current.

Create canvases build action

Apply a lifecycle action (retry, pin, unpin, cancel) to one build.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

action
build_id
string

Response

Example request

POST /api/projects/:project_id/canvases/:id/builds/action
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/canvases/:id/builds/action/\
	-d action=undefined,\
	-d build_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/builds/action/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"build_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
  "build_status": "queued",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "manifest": {
    "entryHtml": "string",
    "assets": [
      {
        "path": "string",
        "contentHash": "string",
        "sizeBytes": 0
      }
    ],
    "dependencies": {
      "property1": "string",
      "property2": "string"
    },
    "canvasSdkVersion": "string",
    "legacyComponentPath": "string",
    "legacyCode": "string",
    "capabilities": {},
    "component": {}
  },
  "integrity": "string",
  "artifact_url": "string",
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z"
}

Status 429 The team's build capacity is exhausted; retry shortly.

List all canvases comments

The comment threads on this canvas, newest first. Open threads only unless include_resolved is set.

Required API key scopes

canvas:readcomment:read

Path parameters

id
string

Query parameters

cursor
string
include_resolved
boolean
Default: false
limit
integer
Default: 50

Response

Example request

GET /api/projects/:project_id/canvases/:id/comments
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/:id/comments/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/comments/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "content": "string",
      "content_truncated": true,
      "selected_text": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "reply_count": 0,
      "resolved": true
    }
  ],
  "next": "string"
}

Retrieve canvases comments

One comment thread on this canvas: the root comment and its replies, oldest first.

Required API key scopes

canvas:readcomment:read

Path parameters

id
string
root_comment_id
string

Query parameters

comment_id
string
content_offset
integer
Default: 0
cursor
string
limit
integer
Default: 50

Response

Example request

GET /api/projects/:project_id/canvases/:id/comments/:root_comment_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/canvases/:id/comments/:root_comment_id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/comments/{root_comment_id}/".format(
        project_id=project_id,
		canvase_id="<the canvase id>",
		root_comment_id="<the root comment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resolved": true,
  "comments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "content": "string",
      "content_truncated": true,
      "content_next_offset": 0,
      "author": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "anchor": {
        "kind": "string",
        "quote": "string",
        "prefix": "string",
        "suffix": "string",
        "start": 0,
        "end": 1,
        "x": 1,
        "y": 1,
        "width": 1,
        "height": 1
      },
      "canvas_version_id": "string"
    }
  ],
  "next": "string"
}

Create canvases connectors

Call one declared connector tool as the viewer.

The canvas must declare the provider and tool in capabilities.connectors (the reviewed permission boundary); the call runs with the viewer's own connection, so two viewers of the same canvas see their own data.

Required API key scopes

canvas:writeuser:read

Path parameters

id
string

Request parameters

approval_token
string
provider
string
tool
string
arguments
object

Response

Example request

POST /api/projects/:project_id/canvases/:id/connectors/call
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/canvases/:id/connectors/call/\
	-d provider="string",\
	-d tool="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/connectors/call/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"provider": "string",
		"tool": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "approval_token": "string",
  "status": "ok",
  "result": {},
  "detail": "string",
  "truncated": true,
  "connect_path": "string"
}

Status 400 The arguments failed the tool's schema.

Status 403 The provider or tool is not declared in the canvas's capabilities, connectors are not enabled for the team, or the caller is a sandbox.

Create canvases draft

Stage a complete source project as a draft version and build it, without publishing.

The draft gets the same validation, versioning, and server-side build as a publish, but the canvas's head and live build never move, so nothing changes for viewers. Promote the version with promote to make it live. The response reports how the draft's declared capabilities widen the current head's, so growth in access can be reviewed before it ships. No version guard applies: a draft conflicts with nothing.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

project
prompt
string

Response

Example request

POST /api/projects/:project_id/canvases/:id/draft
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/canvases/:id/draft/\
	-d project=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/draft/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "version_id": "string",
  "build": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
    "build_status": "queued",
    "diagnostics": [
      {
        "severity": "error",
        "code": "string",
        "message": "string",
        "path": "string",
        "line": 0
      }
    ],
    "manifest": {
      "entryHtml": "string",
      "assets": [
        {
          "path": "string",
          "contentHash": "string",
          "sizeBytes": 0
        }
      ],
      "dependencies": {
        "property1": "string",
        "property2": "string"
      },
      "canvasSdkVersion": "string",
      "legacyComponentPath": "string",
      "legacyCode": "string",
      "capabilities": {},
      "component": {}
    },
    "integrity": "string",
    "artifact_url": "string",
    "pinned": true,
    "created_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z"
  },
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "capability_widening": {
    "widens": true,
    "insights_added": [
      "string"
    ],
    "capture_events_added": [
      "string"
    ],
    "inline_queries_enabled": true,
    "agent_requests_enabled": true,
    "network_origins_added": [
      "string"
    ],
    "state_scopes_added": [
      "string"
    ],
    "actions_added": [
      "string"
    ],
    "connectors_added": [
      {
        "provider": "string",
        "tools": [
          "string"
        ]
      }
    ]
  }
}

Status 400 The source project failed validation.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ]
}

Status 429 The team's build capacity is exhausted; retry shortly.

Retrieve canvases drafts

The canvas's staged draft versions, newest first, each with its latest build status.

A draft is a version that was built but never made the head. Preview one with source?version_id=, then make it live with promote.

Required API key scopes

canvas:read

Path parameters

id
string

Example request

GET /api/projects/:project_id/canvases/:id/drafts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/:id/drafts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/drafts/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "version_id": "string",
  "prompt": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "build_status": "queued",
  "build_id": "string"
}

Create canvases edit

Publish file edits against the canvas's current source project.

Diff-aware alternative to sending the complete project: operations replace text inside a file, write, delete, or rename files, applied in order to the head the caller read. expected_current_version_id is mandatory here — relative edits against an unverified base could silently merge into someone else's newer work.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

operations
array
capabilities
prompt
string
name
string
expected_current_version_id
string | null

Response

Example request

POST /api/projects/:project_id/canvases/: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/canvases/:id/edit/\
	-d expected_current_version_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/edit/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"expected_current_version_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "canvas": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "kind": "freeform",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "current_version_id": "string",
    "published_build_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "current_version_id": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "build": {
    "id": "string",
    "build_status": "queued",
    "diagnostics": [
      {
        "severity": "error",
        "code": "string",
        "message": "string",
        "path": "string",
        "line": 0
      }
    ]
  }
}

Status 400 An operation did not apply (a missing file, or old_string matched no place or several), or the edited project failed validation.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ]
}

Status 403 Only the canvas creator can supply a name when editing.

Status 409 The canvas moved past expected_current_version_id (a concurrent publish or a revert).

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}

Status 429 The team's build capacity is exhausted; retry shortly.

Retrieve canvases layout

Read a grid canvas's layout document and its current_version_id.

Always call this before editing: pass the returned version id as expected_current_version_id on publish/patch so concurrent edits are not overwritten. A grid canvas with no versions yet returns the default empty layout with a null version id.

Required API key scopes

canvas:read

Path parameters

id
string

Query parameters

include_components
boolean
version_id
string

Response

Example request

GET /api/projects/:project_id/canvases/:id/layout
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/canvases/:id/layout/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/layout/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "canvas": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "kind": "freeform",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "current_version_id": "string",
    "published_build_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "layout": {
    "schemaVersion": 1,
    "grid": {
      "columns": 4,
      "rowHeight": 24,
      "gap": 48
    },
    "placements": [
      {
        "id": "string",
        "status": "pending",
        "component": "string",
        "version": "string",
        "x": 0,
        "y": 0,
        "w": 1,
        "h": 1,
        "config": {},
        "prompt": "string",
        "generationTaskId": "string"
      }
    ]
  },
  "current_version_id": "string",
  "component_lifecycles": [
    {
      "canvas_id": "string",
      "requested_version_id": "string",
      "published_build_id": "string",
      "current_version_id": "string",
      "builds": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
          "build_status": "queued",
          "diagnostics": [
            {
              "severity": "error",
              "code": "string",
              "message": "string",
              "path": "string",
              "line": 0
            }
          ],
          "manifest": {
            "entryHtml": "string",
            "assets": [
              {
                "path": "string",
                "contentHash": "string",
                "sizeBytes": 0
              }
            ],
            "dependencies": {
              "property1": "string",
              "property2": "string"
            },
            "canvasSdkVersion": "string",
            "legacyComponentPath": "string",
            "legacyCode": "string",
            "capabilities": {},
            "component": {}
          },
          "integrity": "string",
          "artifact_url": "string",
          "pinned": true,
          "created_at": "2019-08-24T14:15:22Z",
          "finished_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

Status 304 Not modified — the client's cached layout is current.

Status 400 The canvas is not a grid canvas.

Create canvases layout patch

Apply surgical operations to the grid canvas's current layout.

The default write path for both the editor and agents: add, move, resize, fill, or remove one placement without resending the layout. expected_current_version_id is mandatory so an agent filling a box and a user rearranging widgets cannot overwrite each other.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

operations
array
prompt
string
expected_current_version_id
string | null

Response

Example request

POST /api/projects/:project_id/canvases/:id/layout/patch
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/canvases/:id/layout/patch/\
	-d operations="array",\
	-d expected_current_version_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/layout/patch/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"operations": "array",
		"expected_current_version_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "canvas": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "kind": "freeform",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "current_version_id": "string",
    "published_build_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "layout": {
    "schemaVersion": 1,
    "grid": {
      "columns": 4,
      "rowHeight": 24,
      "gap": 48
    },
    "placements": [
      {
        "id": "string",
        "status": "pending",
        "component": "string",
        "version": "string",
        "x": 0,
        "y": 0,
        "w": 1,
        "h": 1,
        "config": {},
        "prompt": "string",
        "generationTaskId": "string"
      }
    ]
  },
  "current_version_id": "string"
}

Status 400 An operation targeted a missing placement, or the edited layout failed validation.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ]
}

Status 409 The canvas moved past expected_current_version_id.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}

Create canvases layout publish

Publish a complete layout document as the grid canvas's new head version.

Layout is data, not code: the new version is live immediately, with no build. Validation errors reject the publish (400) and leave the canvas untouched; a stale expected_current_version_id is rejected with 409.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

layout
prompt
string
expected_current_version_id
string | null

Response

Example request

POST /api/projects/:project_id/canvases/:id/layout/publish
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/canvases/:id/layout/publish/\
	-d layout=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/layout/publish/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "canvas": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "kind": "freeform",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "current_version_id": "string",
    "published_build_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "layout": {
    "schemaVersion": 1,
    "grid": {
      "columns": 4,
      "rowHeight": 24,
      "gap": 48
    },
    "placements": [
      {
        "id": "string",
        "status": "pending",
        "component": "string",
        "version": "string",
        "x": 0,
        "y": 0,
        "w": 1,
        "h": 1,
        "config": {},
        "prompt": "string",
        "generationTaskId": "string"
      }
    ]
  },
  "current_version_id": "string"
}

Status 400 The canvas is not a grid canvas, or the layout failed validation.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ]
}

Status 409 The canvas moved past expected_current_version_id.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}

Create canvases promote

Make a draft version the canvas's live head.

A draft whose build is ready goes live immediately, with no rebuild; otherwise a fresh build is queued. Returns that build.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

version_id
string
expected_current_version_id
string | null

Response

Example request

POST /api/projects/:project_id/canvases/:id/promote
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/canvases/:id/promote/\
	-d version_id="string",\
	-d expected_current_version_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/promote/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"version_id": "string",
		"expected_current_version_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
  "build_status": "queued",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "manifest": {
    "entryHtml": "string",
    "assets": [
      {
        "path": "string",
        "contentHash": "string",
        "sizeBytes": 0
      }
    ],
    "dependencies": {
      "property1": "string",
      "property2": "string"
    },
    "canvasSdkVersion": "string",
    "legacyComponentPath": "string",
    "legacyCode": "string",
    "capabilities": {},
    "component": {}
  },
  "integrity": "string",
  "artifact_url": "string",
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z"
}

Status 409 The canvas moved past expected_current_version_id (a concurrent publish or a revert).

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}

Status 429 The team's build capacity is exhausted; retry shortly.

Create canvases publish

Publish a complete source project as the canvas's new head version.

Validation errors reject the publish (400) and leave the canvas untouched; a stale expected_current_version_id is rejected with 409. A successful publish queues a server-side build.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

project
prompt
string
name
string
expected_current_version_id
string | null

Response

Example request

POST /api/projects/:project_id/canvases/:id/publish
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/canvases/:id/publish/\
	-d project=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/publish/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "canvas": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "kind": "freeform",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "current_version_id": "string",
    "published_build_id": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "current_version_id": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "build": {
    "id": "string",
    "build_status": "queued",
    "diagnostics": [
      {
        "severity": "error",
        "code": "string",
        "message": "string",
        "path": "string",
        "line": 0
      }
    ]
  }
}

Status 400 The source project failed validation.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ]
}

Status 403 Only the canvas creator can supply a name when publishing.

Status 409 The canvas moved past expected_current_version_id (a concurrent publish or a revert).

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}

Status 429 The team's build capacity is exhausted; retry shortly.

Create canvases publish current version

Queue a build for the current source version without changing source or metadata.

Required API key scopes

canvas:write

Path parameters

id
string

Request parameters

expected_current_version_id
string

Response

Example request

POST /api/projects/:project_id/canvases/:id/publish-current-version
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/canvases/:id/publish-current-version/\
	-d expected_current_version_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/canvases/{canvase_id}/publish-current-version/".format(
        project_id=project_id,
		canvase_id="<the canvase id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"expected_current_version_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_version_id": "adb2dc89-2007-42cb-8da1-8d6c68cbf772",
  "build_status": "queued",
  "diagnostics": [
    {
      "severity": "error",
      "code": "string",
      "message": "string",
      "path": "string",
      "line": 0
    }
  ],
  "manifest": {
    "entryHtml": "string",
    "assets": [
      {
        "path": "string",
        "contentHash": "string",
        "sizeBytes": 0
      }
    ],
    "dependencies": {
      "property1": "string",
      "property2": "string"
    },
    "canvasSdkVersion": "string",
    "legacyComponentPath": "string",
    "legacyCode": "string",
    "capabilities": {},
    "component": {}
  },
  "integrity": "string",
  "artifact_url": "string",
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z"
}

Status 409 The canvas moved past expected_current_version_id.

RESPONSE
{
  "detail": "string",
  "code": "string",
  "current_version_id": "string"
}