PostHog Notebooks API
The notebooks API from PostHog — 16 operation(s) for notebooks.
The notebooks API from PostHog — 16 operation(s) for notebooks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/posthog-notebooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: PostHog Notebooks API
version: 1.0.0
description: ''
tags:
- name: Notebooks
paths:
/api/projects/{project_id}/notebooks/:
get:
operationId: notebooks_list
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- in: query
name: contains
schema:
type: string
description: "Filter for notebooks that match a provided filter.\n Each match pair is separated by a colon,\n multiple match pairs can be sent separated by a space or a comma"
examples:
FilterForNotebooksThatHaveAnyRecording:
value: recording:true
summary: Filter for notebooks that have any recording
FilterForNotebooksThatDoNotHaveAnyRecording:
value: recording:false
summary: Filter for notebooks that do not have any recording
FilterForNotebooksThatHaveASpecificRecording:
value: recording:the-session-recording-id
summary: Filter for notebooks that have a specific recording
- in: query
name: created_by
schema:
type: string
format: uuid
description: The UUID of the Notebook's creator
- in: query
name: date_from
schema:
type: string
format: date-time
description: Filter for notebooks created after this date & time
- in: query
name: date_to
schema:
type: string
format: date-time
description: Filter for notebooks created before this date & time
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- $ref: '#/components/parameters/ProjectIdPath'
- in: query
name: user
schema:
type: string
description: If any value is provided for this parameter, return notebooks created by the logged in user.
tags:
- Notebooks
security:
- PersonalAPIKeyAuth:
- notebook:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedNotebookMinimalList'
description: ''
x-explicit-tags:
- notebooks
summary: Notebooks list
x-summary-source: derived
post:
operationId: notebooks_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
security:
- PersonalAPIKeyAuth:
- notebook:write
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
description: ''
x-explicit-tags:
- notebooks
summary: Notebooks create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/:
get:
operationId: notebooks_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
security:
- PersonalAPIKeyAuth:
- notebook:read
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
description: ''
x-explicit-tags:
- notebooks
summary: Notebooks retrieve
x-summary-source: derived
put:
operationId: notebooks_update
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
security:
- PersonalAPIKeyAuth:
- notebook:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
description: ''
x-explicit-tags:
- notebooks
summary: Notebooks update
x-summary-source: derived
patch:
operationId: notebooks_partial_update
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedNotebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedNotebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedNotebook'
security:
- PersonalAPIKeyAuth:
- notebook:write
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
description: ''
x-explicit-tags:
- notebooks
summary: Notebooks partial update
x-summary-source: derived
delete:
operationId: notebooks_destroy
description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
security:
- PersonalAPIKeyAuth:
- notebook:write
responses:
'405':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks destroy
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/activity/:
get:
operationId: notebooks_activity_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
security:
- PersonalAPIKeyAuth:
- activity_log:read
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks activity retrieve
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/collab/save/:
post:
operationId: notebooks_collab_save_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NotebookCollabSave'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/NotebookCollabSave'
multipart/form-data:
schema:
$ref: '#/components/schemas/NotebookCollabSave'
required: true
security:
- PersonalAPIKeyAuth:
- notebook:write
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks collab save create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/collab/stream/:
get:
operationId: notebooks_collab_stream_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
security:
- PersonalAPIKeyAuth:
- notebook:read
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks collab stream retrieve
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/hogql/execute/:
post:
operationId: notebooks_hogql_execute_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks hogql execute create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/config/:
post:
operationId: notebooks_kernel_config_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel config create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/dataframe/:
get:
operationId: notebooks_kernel_dataframe_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel dataframe retrieve
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/execute/:
post:
operationId: notebooks_kernel_execute_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel execute create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/execute/stream/:
post:
operationId: notebooks_kernel_execute_stream_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel execute stream create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/restart/:
post:
operationId: notebooks_kernel_restart_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel restart create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/start/:
post:
operationId: notebooks_kernel_start_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel start create
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/status/:
get:
operationId: notebooks_kernel_status_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel status retrieve
x-summary-source: derived
/api/projects/{project_id}/notebooks/{short_id}/kernel/stop/:
post:
operationId: notebooks_kernel_stop_create
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
- in: path
name: short_id
schema:
type: string
required: true
tags:
- Notebooks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Notebook'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Notebook'
multipart/form-data:
schema:
$ref: '#/components/schemas/Notebook'
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks kernel stop create
x-summary-source: derived
/api/projects/{project_id}/notebooks/activity/:
get:
operationId: notebooks_all_activity_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- Notebooks
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks all activity retrieve
x-summary-source: derived
/api/projects/{project_id}/notebooks/recording_comments/:
get:
operationId: notebooks_recording_comments_retrieve
description: The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.
parameters:
- $ref: '#/components/parameters/ProjectIdPath'
tags:
- Notebooks
responses:
'200':
description: No response body
x-explicit-tags:
- notebooks
summary: Notebooks recording comments retrieve
x-summary-source: derived
components:
schemas:
NullEnum:
enum:
- null
PatchedNotebook:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: UUID of the notebook.
short_id:
type: string
readOnly: true
description: Short alphanumeric identifier used in URLs and API lookups.
title:
type:
- string
- 'null'
description: Title of the notebook.
maxLength: 256
content:
description: Notebook content as a ProseMirror JSON document structure.
text_content:
type:
- string
- 'null'
description: Plain text representation of the notebook content for search.
version:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Version number for optimistic concurrency control. Must match the current version when updating content.
deleted:
type: boolean
description: Whether the notebook has been soft-deleted.
created_at:
type: string
format: date-time
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
last_modified_at:
type: string
format: date-time
readOnly: true
last_modified_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
user_access_level:
type:
- string
- 'null'
readOnly: true
description: The effective access level the user has for this object
_create_in_folder:
type: string
writeOnly: true
title: ' create in folder'
PaginatedNotebookMinimalList:
type: object
required:
- count
- results
properties:
count:
type: integer
example: 123
next:
type:
- string
- 'null'
format: uri
example: http://api.example.org/accounts/?offset=400&limit=100
previous:
type:
- string
- 'null'
format: uri
example: http://api.example.org/accounts/?offset=200&limit=100
results:
type: array
items:
$ref: '#/components/schemas/NotebookMinimal'
UserBasic:
type: object
properties:
id:
type: integer
readOnly: true
uuid:
type: string
format: uuid
readOnly: true
distinct_id:
type:
- string
- 'null'
maxLength: 200
first_name:
type: string
maxLength: 150
last_name:
type: string
maxLength: 150
email:
type: string
format: email
title: Email address
maxLength: 254
is_email_verified:
type:
- boolean
- 'null'
hedgehog_config:
type:
- object
- 'null'
additionalProperties: true
readOnly: true
role_at_organization:
oneOf:
- $ref: '#/components/schemas/RoleAtOrganizationEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
required:
- email
- hedgehog_config
- id
- uuid
BlankEnum:
enum:
- ''
NotebookCollabSave:
type: object
properties:
client_id:
type: string
description: Unique identifier for the client session.
version:
type: integer
description: The collab version the client's steps are based on.
steps:
type: array
items: {}
description: List of ProseMirror step JSON objects to apply.
content:
description: The resulting ProseMirror document after applying the steps locally.
text_content:
type: string
default: ''
description: Plain text for search indexing.
title:
type: string
description: Updated notebook title.
cursor_head:
type:
- integer
- 'null'
description: ProseMirror cursor head position after applying steps.
required:
- client_id
- content
- steps
- version
Notebook:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: UUID of the notebook.
short_id:
type: string
readOnly: true
description: Short alphanumeric identifier used in URLs and API lookups.
title:
type:
- string
- 'null'
description: Title of the notebook.
maxLength: 256
content:
description: Notebook content as a ProseMirror JSON document structure.
text_content:
type:
- string
- 'null'
description: Plain text representation of the notebook content for search.
version:
type: integer
maximum: 2147483647
minimum: -2147483648
description: Version number for optimistic concurrency control. Must match the current version when updating content.
deleted:
type: boolean
description: Whether the notebook has been soft-deleted.
created_at:
type: string
format: date-time
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
last_modified_at:
type: string
format: date-time
readOnly: true
last_modified_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
user_access_level:
type:
- string
- 'null'
readOnly: true
description: The effective access level the user has for this object
_create_in_folder:
type: string
writeOnly: true
title: ' create in folder'
required:
- created_at
- created_by
- id
- last_modified_at
- last_modified_by
- short_id
- user_access_level
NotebookMinimal:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: UUID of the notebook.
short_id:
type: string
readOnly: true
description: Short alphanumeric identifier used in URLs and API lookups.
title:
type:
- string
- 'null'
readOnly: true
description: Title of the notebook.
deleted:
type: boolean
readOnly: true
description: Whether the notebook has been soft-deleted.
created_at:
type: string
format: date-time
readOnly: true
created_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
last_modified_at:
type: string
format: date-time
readOnly: true
last_modified_by:
allOf:
- $ref: '#/components/schemas/UserBasic'
readOnly: true
user_access_level:
type:
- string
- 'null'
readOnly: true
description: The effective access level the user has for this object
_create_in_folder:
type: string
writeOnly: true
title: ' create in folder'
required:
- created_at
- created_by
- deleted
- id
- last_modified_at
- last_modified_by
- short_id
- title
- user_access_level
RoleAtOrganizationEnum:
enum:
- engineering
- data
- product
- founder
- leadership
- marketing
- sales
- other
type: string
description: '* `engineering` - Engineering
* `data` - Data
* `product` - Product Management
* `founder` - Founder
* `leadership` - Leadership
* `marketing` - Marketing
* `sales` - Sales / Success
* `other` - Other'
parameters:
ProjectIdPath:
in: path
name: project_id
required: true
schema:
type: string
description: Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
securitySchemes:
PersonalAPIKeyAuth:
type: http
scheme: bearer
x-tagGroups:
- name: All endpoints
tags:
- LLM Analytics
- actions
- activity_log
- activity_logs
- advanced_activity_logs
- alerts
- annotations
- approval_policies
- batch_exports
- cdp
- change_requests
- code
- code-invites
- cohorts
- comments
- conversations
- core
- customer_analytics
- customer_journeys
- customer_profile_configs
- dashboard_templates
- dashboards
- data_color_themes
- data_modeling_jobs
- data_warehouse
- dataset_items
- datasets
- desktop_recordings
- domains
- early_access_feature
- early_access_features
- elements
- endpoints
- environments
- error_tracking
- evaluation_runs
- evaluations
- event_definitions
- event_filter
- event_schemas
- events
- experiment_holdouts
- experiment_saved_metrics
- experiments
- exports
- external_data_schemas
- external_data_sources
- feature_flags
- file_system
- file_system_shortcut
- flag_value
- groups
- groups_types
- health_issues
- heatmap_screenshots
- heatmaps
- hog_flows
- hog_function_templates
- hog_functions
- insight_variables
- insights
- integrations
- invites
- js-snippet
- legal_documents
- lineage
- live_debugger_breakpoints
- llm_analytics
- llm_prompts
- llm_skills
- logs
- managed_viewsets
- max
- max_tools
- mcp_server_installations
- mcp_servers
- mcp_store
- mcp_tools
- members
- notebooks
- oauth_applications
- object_media_previews
- organizations
- persisted_folder
- persons
- platform_features
- plugin_configs
- product_analytics
- product_tours
- project_secret_api_keys
- projects
- property_definitions
- proxy_records
- public_hog_function_templates
- query
- replay
- reverse_proxy
- role_external_references
- roles
- sandbox-environments
- sandbox_environments
- saved
- schema_property_groups
- sdk_doctor
- session_group_summaries
- session_recording_playlists
- session_recordings
- session_summaries
- sessions
- signals
- subscriptions
- surveys
- taggers
- task-automations
- task-runs
- task_automations
- tasks
- uploaded_media
- user_home_settings
- user_interviews
- users
- visual_review
- warehouse_dag
- warehouse_model_paths
- warehouse_saved_queries
- warehouse_saved_query_folders
- warehouse_tables
- warehouse_view_link
- warehouse_view_links
- web_analytics
- web_experiments
- web_vitals
- welcome
- workflows