Deepnote Public API v2
Blocks API
Notebook blocks (code, SQL, markdown, etc.).
Base URL
https://api.deepnote.com/v2Create a block
/blocksRequest body
CreateBlockBodynotebookIdrequiredstringNotebook 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").
contentstringInitial block content. Defaults to an empty string.
metadataobjectBlock-type-specific metadata.
integrationIdstring:uuidIntegration ID to store in SQL block metadata as sql_integration_id.
positionintegerZero-based insertion index. Omit to append at the end.
includeNotebookBlockIdsbooleanWhen true, response includes all block IDs in the notebook.
Responses
▸201Block created
CreateBlockResponseblockrequiredBlocknotebookBlockIdsstring[]All block IDs in the notebook (only when includeNotebookBlockIds is true).
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Notebook not found, or integration does not exist in workspace
ErrorResponsemessagerequiredstring▸409Project is suspended, or block type conflicts with requested integration
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringGet a block
/blocks/{blockId}Parameters
blockIdpathrequiredstringOpaque 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
GetBlockResponseblockrequiredBlockWithOutputs▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Block not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringUpdate a block
/blocks/{blockId}Parameters
blockIdpathrequiredstringOpaque block identifier.
Request body
objectcontentstringUpdated block content.
integrationIdstring:uuidIntegration ID to store in sql block metadata as sql_integration_id.
Responses
▸200Block updated
UpdateBlockResponseblockrequiredobject▸400Bad request
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions to update the block
ErrorResponsemessagerequiredstring▸404Block not found, or integration does not exist in workspace
ErrorResponsemessagerequiredstring▸409Project is suspended, or block type conflicts with requested update
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringDelete a block
/blocks/{blockId}Parameters
blockIdpathrequiredstringOpaque block identifier.
Responses
▸204Block deleted
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Block not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringGet 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.
/blocks/{blockId}/dataframeParameters
blockIdpathrequiredstringOpaque block identifier.
pageIndexqueryintegerZero-based page number. Defaults to 0.
pageSizequeryintegerRows per page. Defaults to 10. Maximum: 1000.
Responses
▸200One page of the stored dataframe
DataframePagereferenceIdrequiredstring:uuidIdentifies the stored frame. It changes when a new frame replaces it, so compare it across pages.
rowCountrequiredintegerRows in the whole frame.
columnCountrequiredintegerColumns in the frame.
pageIndexrequiredintegerpageSizerequiredintegerpageCountrequiredintegerPages 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
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Block not found, or it has no stored dataframe
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸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.
ErrorResponsemessagerequiredstring▸429Rate limit exceeded, or the server is reading as many dataframe pages as it can at once. Retry after `Retry-After` seconds.
ErrorResponsemessagerequiredstring