Best model for proactive agents? Explore our benchmark
Get started
All endpoint groups

Deepnote Public API v2

Blocks API

Notebook blocks (code, SQL, markdown, etc.).

Base URL

https://api.deepnote.com/v2

Create a block

post/blocks

Request body

required
application/jsonCreateBlockBody
notebookIdrequiredstring

Notebook to create the block in.

typerequired"code" | "sql" | "markdown" | "notebook-function" | "input-text" | "input-textarea" | "input-select" | "input-date" | "input-date-range" | "input-slider" | "input-file" | "input-checkbox" | "text-cell-h1" | "text-cell-h2" | "text-cell-h3" | "text-cell-p" | "text-cell-bullet" | "text-cell-todo" | "text-cell-callout" | "visualization" | "pivot-table" | "image" | "button" | "separator" | "big-number" | "agent"

Block type (e.g. "code", "sql", "markdown").

contentstring

Initial block content. Defaults to an empty string.

metadataobject

Block-type-specific metadata.

integrationIdstring:uuid

Integration ID to store in SQL block metadata as sql_integration_id.

positioninteger

Zero-based insertion index. Omit to append at the end.

includeNotebookBlockIdsboolean

When true, response includes all block IDs in the notebook.

Responses

▸201Block created
application/jsonCreateBlockResponse
blockrequiredBlock
notebookBlockIdsstring[]

All block IDs in the notebook (only when includeNotebookBlockIds is true).

▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Notebook not found, or integration does not exist in workspace
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended, or block type conflicts with requested integration
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Get a block

get/blocks/{blockId}

Parameters

blockIdpathrequiredstring

Opaque block identifier.

includeOutputsquery"true" | "false"

Also return the block's outputs in the live editor, from its last run there. Detached runs and sessions don't change them; get their outputs with `GET /runs/{runId}`. Scheduled runs do, unless their schedule has output syncing turned off. Defaults to `false`.

fullOutputsquery"true" | "false"

Return the outputs as stored. By default, outputs longer than 16384 characters as JSON get a notice in their place, with `outputHead` and `outputTail` showing how they start and end. When a block runs, its printed output (stdout and stderr) keeps only the last 1000 lines or 600000 characters, whichever is shorter, and is marked `"truncated": true`. The dropped text isn't stored, so this option can't return it. Defaults to `false`. Applies only with `includeOutputs=true`.

Responses

▸200Block details
application/jsonGetBlockResponse
blockrequiredBlockWithOutputs
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Block not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Update a block

patch/blocks/{blockId}

Parameters

blockIdpathrequiredstring

Opaque block identifier.

Request body

required
application/jsonobject
contentstring

Updated block content.

integrationIdstring:uuid

Integration ID to store in sql block metadata as sql_integration_id.

Responses

▸200Block updated
application/jsonUpdateBlockResponse
blockrequiredobject
▸400Bad request
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions to update the block
application/jsonErrorResponse
messagerequiredstring
▸404Block not found, or integration does not exist in workspace
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended, or block type conflicts with requested update
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Delete a block

delete/blocks/{blockId}

Parameters

blockIdpathrequiredstring

Opaque block identifier.

Responses

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

Get a stored dataframe page

Returns one page of the full DataFrame that a Python or SQL block stored on its last run, as JSON rows. The block must have `deepnote_store_dataframe` set in its metadata. Each row is an array of plain JSON values, one per column in the order of `columns`, and the `type` of a column says how its values are encoded: see the description of `columns`. Values are not truncated. To read the whole frame, request `pageIndex` 0 up to `pageCount` - 1 with the same `pageSize`, and compare `referenceId` across the pages: when it changes, the block ran again and replaced the frame, so start again at page 0. A 400 for a `pageIndex` below a `pageCount` served earlier means the same: a re-run replaced the frame with a smaller one. The 404 response does not say why there is nothing to serve: the block may not exist, may not store a dataframe, or may not have run yet.

get/blocks/{blockId}/dataframe

Parameters

blockIdpathrequiredstring

Opaque block identifier.

pageIndexqueryinteger

Zero-based page number. Defaults to 0.

pageSizequeryinteger

Rows per page. Defaults to 10. Maximum: 1000.

Responses

▸200One page of the stored dataframe
application/jsonDataframePage
referenceIdrequiredstring:uuid

Identifies the stored frame. It changes when a new frame replaces it, so compare it across pages.

rowCountrequiredinteger

Rows in the whole frame.

columnCountrequiredinteger

Columns in the frame.

pageIndexrequiredinteger
pageSizerequiredinteger
pageCountrequiredinteger

Pages of `pageSize` rows. An empty frame has one empty page.

columnsrequiredobject[]

The columns of the frame, in the order of the values in each row. The `type` of a column says how its values are encoded. `integer` and `float` are numbers, and NaN and infinities are `null`. `int64` is a decimal string such as `"9007199254740993"`. `boolean` is a boolean, and `string` is a string. `binary` is a base64 string. `decimal` is a plain decimal string at the scale of the column, such as `"123.45"`. `date` is `"YYYY-MM-DD"`. `timestamp` is ISO 8601 at millisecond precision, such as `"2024-01-02T03:04:05.678"`, with a trailing `Z` only when the column has a time zone. `time` is `"HH:MM:SS.sss"`. `duration` is a number of seconds. `list` is an array, `struct` is an object keyed by field name, and `map` is an array of `[key, value]` pairs, with the values inside them encoded by the same rules. `null` is `null`. A missing value is `null` in every type.

rowsrequiredobject[][]

The rows of the page, each an array of one value per column in the order of `columns`. A row's position in the frame is `pageIndex * pageSize` plus its position in the page.

▸400Validation error, or `pageIndex` is past the last page
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Block not found, or it has no stored dataframe
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸422The page cannot be served, and the message says why. When its JSON, its values (cells, and the list items, map keys, map values and struct fields in them) or the record batches it spans exceed the limits for one page, a smaller `pageSize` may help, since a page within one record batch reads and decompresses that batch alone. No `pageSize` helps when a single record batch of the frame is too large to read or decompress, the frame has too many columns, fields or dictionary values, the names and types of its columns alone exceed the JSON limit, or it uses delta dictionary batches, a compression codec or a column type the API cannot decode, such as an interval or a union. A page that holds a date or timestamp outside the years 0 to 9999 cannot be served either, though the pages without one can.
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded, or the server is reading as many dataframe pages as it can at once. Retry after `Retry-After` seconds.
application/jsonErrorResponse
messagerequiredstring