Deepnote research: our notes on building agents
Get started
All endpoint groups

Deepnote Public API v2

Notebooks API

Notebooks, their blocks, runs, and schedules.

Base URL

https://api.deepnote.com/v2

Create a notebook

Creates an empty notebook inside the project identified by `projectId`.

post/notebooks

Request body

required
application/jsonCreateNotebookBody
projectIdrequiredstring:uuid

Project to create the notebook in.

namestring

Notebook name.

Responses

▸201Notebook created
application/jsonCreateNotebookResponse
notebookrequiredNotebook
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Project not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended or duplicate notebook name
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Get a notebook

get/notebooks/{notebookId}

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Responses

▸200Notebook details
application/jsonobject
notebookrequiredobject
▸400Validation error or project is suspended
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Update a notebook

Renames the notebook. Naming it "Init" designates the project init notebook, which can run as a prelude to other notebooks in the project.

patch/notebooks/{notebookId}

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Request body

required
application/jsonUpdateNotebookBody
namerequiredstring

Updated notebook name.

Responses

▸200Notebook updated
application/jsonUpdateNotebookResponse
notebookrequiredobject
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended, duplicate notebook name, or notebook management not allowed
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Delete a notebook

delete/notebooks/{notebookId}

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Responses

▸204Notebook deleted
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Duplicate a notebook

Duplicates the notebook inside its current project. The duplicated notebook receives an automatically generated unique name.

post/notebooks/{notebookId}/duplicate

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Responses

▸201Notebook duplicated
application/jsonDuplicateNotebookResponse
notebookrequiredNotebook
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions or notebook limit reached
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Reorder blocks in a notebook

Moves one or more active blocks as a group. Blocks omitted from `blockIds` keep their relative order.

post/notebooks/{notebookId}/reorder-blocks

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Request body

required
application/jsonReorderNotebookBlocksBody
blockIdsrequiredstring[]

Non-empty list of unique block IDs to move, in the desired moved-block order.

placementrequiredReorderNotebookBlocksPlacement

Responses

▸200Blocks reordered
application/jsonReorderNotebookBlocksResponse
blockIdsrequiredstring[]

Final active block order for the notebook.

▸400Validation error, e.g. unknown blockId or invalid placement
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

List historical runs for a notebook

get/notebooks/{notebookId}/runs

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

pageSizequeryinteger

Maximum number of items to return. Defaults to 20. Maximum: 100.

pageTokenquerystring

Opaque token returned by the previous page. Omit for the first page.

Responses

▸200Paginated list of runs
application/jsonListNotebookRunsResponse
runsrequiredListNotebookRun[]
paginationrequiredCursorPagination
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Get a notebook schedule

Returns the schedule for this notebook, or 404 when the notebook has none.

get/notebooks/{notebookId}/schedule

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Responses

▸200The notebook schedule
application/jsonGetNotebookScheduleResponse
schedulerequiredStoredNotebookSchedule
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook or schedule not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Create or update a notebook schedule

Creates or updates the schedule for a notebook. A project has at most one schedule, so scheduling a notebook moves an existing schedule from another notebook onto this one.

post/notebooks/{notebookId}/schedule

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Request body

required
application/jsonUpsertNotebookScheduleBody
cronrequiredstring

Cron expression for the schedule (e.g. "0 9 * * 1-5").

timezonestring

IANA timezone the cron expression runs in (e.g. "America/New_York").

Responses

▸200Schedule created or updated
application/jsonUpsertNotebookScheduleResponse
schedulerequiredNotebookSchedule
▸400Validation error, e.g. invalid cron expression or timezone
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Delete a notebook schedule

Removes the schedule for this notebook. Not gated on the scheduling entitlement, so a workspace whose plan or member roles changed can still turn a schedule off.

delete/notebooks/{notebookId}/schedule

Parameters

notebookIdpathrequiredstring

Opaque notebook identifier.

Responses

▸204Schedule deleted
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found, or it has no schedule
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring