Notebooks

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

Endpoints

GET
POST
GET
POST
DELETE
POST
GET
PATCH
DELETE
GET
POST
POST
POST
GET
POST
POST
GET
POST
POST
Next page →

List all notebooks

Also available via the PostHog MCP server:

  • notebooks-list — List notebooks

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:read

Query parameters

  • contains
    string
  • created_by
    string
  • date_from
    string
  • date_to
    string
  • limit
    integer
  • offset
    integer
  • user
    string

Response


Example request

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

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",
      "short_id": "string",
      "title": "string",
      "deleted": true,
      "created_at": "2019-08-24T14:15:22Z",
      "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"
      },
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_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"
      },
      "user_access_level": "string",
      "_create_in_folder": "string"
    }
  ]
}

Create notebooks

Also available via the PostHog MCP server:

  • notebooks-create — Create notebook

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:write

Request parameters

  • title
    stringnull
  • content
  • text_content
    stringnull
  • version
    integer
  • deleted
    boolean
  • _create_in_folder
    string

Response


Example request

POST /api/projects/:project_id/notebooks
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/notebooks/\
	-d title=["string","null"]

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "title": "string",
  "content": null,
  "text_content": "string",
  "version": -2147483648,
  "deleted": true,
  "created_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "last_modified_at": "2019-08-24T14:15:22Z",
  "last_modified_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"
  },
  "user_access_level": "string",
  "parent_resource": {
    "type": "account",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "_create_in_folder": "string"
}

List all notebooks sharing

Required API key scopes

sharing_configuration:read

Path parameters

  • notebook_id
    string

Example request

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

Example response

Status 200
RESPONSE
{
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "access_token": "string",
  "settings": null,
  "password_required": true,
  "share_passwords": [
    {
      "id": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "note": "string",
      "created_by_email": "string",
      "is_active": true
    }
  ],
  "user_access_level": "string"
}

Create notebooks sharing passwords

Create a new password for the sharing configuration.

Required API key scopes

sharing_configuration:write

Path parameters

  • notebook_id
    string

Request parameters

  • enabled
    boolean
  • settings
  • password_required
    boolean

Response


Example request

POST /api/projects/:project_id/notebooks/:notebook_id/sharing/passwords
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/notebooks/:notebook_id/sharing/passwords/\
	-d created_at="string"

Example response

Status 200
RESPONSE
{
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "access_token": "string",
  "settings": null,
  "password_required": true,
  "share_passwords": [
    {
      "id": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "note": "string",
      "created_by_email": "string",
      "is_active": true
    }
  ],
  "user_access_level": "string"
}

Delete notebooks sharing passwords

Delete a password from the sharing configuration.

Required API key scopes

sharing_configuration:write

Path parameters

  • notebook_id
    string
  • password_id
    string

Example request

DELETE /api/projects/:project_id/notebooks/:notebook_id/sharing/passwords/:password_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/notebooks/:notebook_id/sharing/passwords/:password_id/

Example response

Status 204 No response body

Create notebooks sharing refresh

Required API key scopes

sharing_configuration:write

Path parameters

  • notebook_id
    string

Request parameters

  • enabled
    boolean
  • settings
  • password_required
    boolean

Response


Example request

POST /api/projects/:project_id/notebooks/:notebook_id/sharing/refresh
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/notebooks/:notebook_id/sharing/refresh/\
	-d created_at="string"

Example response

Status 200
RESPONSE
{
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "access_token": "string",
  "settings": null,
  "password_required": true,
  "share_passwords": [
    {
      "id": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "note": "string",
      "created_by_email": "string",
      "is_active": true
    }
  ],
  "user_access_level": "string"
}

Retrieve notebooks

Also available via the PostHog MCP server:

  • notebooks-retrieve — Get notebook

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:read

Path parameters

  • short_id
    string

Response


Example request

GET /api/projects/:project_id/notebooks/:short_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/notebooks/:short_id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "title": "string",
  "content": null,
  "text_content": "string",
  "version": -2147483648,
  "deleted": true,
  "created_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "last_modified_at": "2019-08-24T14:15:22Z",
  "last_modified_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"
  },
  "user_access_level": "string",
  "parent_resource": {
    "type": "account",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "_create_in_folder": "string"
}

Update notebooks

Also available via the PostHog MCP server:

  • notebooks-partial-update — Update notebook

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Request parameters

  • title
    stringnull
  • content
  • text_content
    stringnull
  • version
    integer
  • deleted
    boolean
  • _create_in_folder
    string

Response


Example request

PATCH /api/projects/:project_id/notebooks/:short_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/notebooks/:short_id/\
	-d title=["string","null"]

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "title": "string",
  "content": null,
  "text_content": "string",
  "version": -2147483648,
  "deleted": true,
  "created_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "last_modified_at": "2019-08-24T14:15:22Z",
  "last_modified_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"
  },
  "user_access_level": "string",
  "parent_resource": {
    "type": "account",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "_create_in_folder": "string"
}

Delete notebooks

Also available via the PostHog MCP server:

  • notebooks-destroy — Delete notebook

Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Example request

DELETE /api/projects/:project_id/notebooks/:short_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/notebooks/:short_id/

Example response

Status 405 No response body

Retrieve notebooks activity

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

activity_log:read

Path parameters

  • short_id
    string

Example request

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

Example response

Status 200 No response body

Create notebooks collab markdown save

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Request parameters

  • client_id
    string
  • version
    integer
  • content
  • text_content
    string
    Default:
  • title
    string
  • cursor

Example request

POST /api/projects/:project_id/notebooks/:short_id/collab/markdown_save
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/notebooks/:short_id/collab/markdown_save/\
	-d client_id="string",\
	-d version="integer",\
	-d content=undefined

Example response

Status 200 No response body

Create notebooks collab presence

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Request parameters

  • client_id
    string
  • version
    integer
  • cursor

Example request

POST /api/projects/:project_id/notebooks/:short_id/collab/presence
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/notebooks/:short_id/collab/presence/\
	-d client_id="string",\
	-d version="integer",\
	-d cursor=undefined

Example response

Status 204 No response body

Create notebooks collab save

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Request parameters

  • client_id
    string
  • version
    integer
  • steps
    array
  • content
  • text_content
    string
    Default:
  • title
    string
  • cursor_head
    integernull

Example request

POST /api/projects/:project_id/notebooks/:short_id/collab/save
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/notebooks/:short_id/collab/save/\
	-d client_id="string",\
	-d version="integer",\
	-d steps="array",\
	-d content=undefined

Example response

Status 200 No response body

Retrieve notebooks collab stream

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Required API key scopes

notebook:read

Path parameters

  • short_id
    string

Example request

GET /api/projects/:project_id/notebooks/:short_id/collab/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/notebooks/:short_id/collab/stream/

Example response

Status 200 No response body

Create notebooks hogql execute

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

  • short_id
    string

Request parameters

  • title
    stringnull
  • content
  • text_content
    stringnull
  • version
    integer
  • deleted
    boolean
  • _create_in_folder
    string

Example request

POST /api/projects/:project_id/notebooks/:short_id/hogql/execute
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/notebooks/:short_id/hogql/execute/\
	-d title=["string","null"]

Example response

Status 200 No response body

Create notebooks kernel config

Set the notebook's kernel compute configuration. Applies at sandbox provision time: a currently running kernel keeps its resources until restarted.

Required API key scopes

notebook:write

Path parameters

  • short_id
    string

Request parameters

  • cpu_cores
    number
  • memory_gb
    number
  • idle_timeout_seconds
    integer

Response


Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/config
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/notebooks/:short_id/kernel/config/\
	-d cpu_cores="number"

Example response

Status 200
RESPONSE
{
  "cpu_cores": 0,
  "memory_gb": 0,
  "idle_timeout_seconds": 0,
  "restart_required": true
}

Retrieve notebooks kernel dataframe

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

  • short_id
    string

Example request

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

Example response

Status 200 No response body

Create notebooks kernel execute

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

  • short_id
    string

Request parameters

  • title
    stringnull
  • content
  • text_content
    stringnull
  • version
    integer
  • deleted
    boolean
  • _create_in_folder
    string

Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/execute
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/notebooks/:short_id/kernel/execute/\
	-d title=["string","null"]

Example response

Status 200 No response body

Create notebooks kernel execute stream

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

  • short_id
    string

Request parameters

  • title
    stringnull
  • content
  • text_content
    stringnull
  • version
    integer
  • deleted
    boolean
  • _create_in_folder
    string

Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/execute/stream
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/notebooks/:short_id/kernel/execute/stream/\
	-d title=["string","null"]

Example response

Status 200 No response body
Next page →