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

Deepnote Public API v2

Projects API

Projects and their contents.

Base URL

https://api.deepnote.com/v2

List projects

get/projects

Parameters

pageSizequeryinteger

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

pageTokenquerystring

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

nameContainsquerystring

Filter projects whose name contains this value (case-insensitive).

Responses

▸200Paginated list of projects
application/jsonListProjectsResponse
projectsrequiredListProjectsItem[]
paginationrequiredCursorPagination
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Create a project

post/projects

Request body

required
application/jsonCreateProjectBody
namerequiredstring

Project name.

folderIdstring:uuid

Folder to create the project in. Omit to create at the workspace root. Resolve a folder name to its ID via `GET /folders`.

projectType"standard" | "notebook" | "agent" | "data_app" | "streamlit_app"

Project type. Omit to create a `standard` project; `notebook` creates a single-notebook project; `agent` creates an Agent project; `data_app` creates a data app project; `streamlit_app` creates a Streamlit app project.

environmentIdstring:uuid

Environment (Docker image) for the project machine. Omit to use the default environment. List the options via `GET /environments`.

Responses

▸201Project created
application/jsonCreateProjectResponse
projectrequiredobject
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Folder or environment not found
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Get a project

get/projects/{projectId}

Parameters

projectIdpathrequiredstring:uuid

Responses

▸200Project details
application/jsonGetProjectResponse
projectrequiredobject
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Project not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring
▸500Internal server error
application/jsonErrorResponse
messagerequiredstring

Update a project

Updates data app settings (`dataApp`), the environment the project machine runs, and the folder the project is in. Set `dataApp.published` to `true` to publish a `data_app` project, or `false` to make it editor-only again. Publishing requires **Allow static file sharing in projects** in the workspace settings and permission to manage the app. Publishing never makes an app public: an app is opened to anyone with its link only by a project admin, in the app’s **Share** dialog in Deepnote, and that cannot be done through the API. Changing the environment restarts a running machine. This settings-only patch does not create a project content version.

patch/projects/{projectId}

Parameters

projectIdpathrequiredstring:uuid

Request body

required
application/jsonobject
dataAppobject
environmentIdstring:uuid

Environment (Docker image) for the project machine. A running machine restarts to apply it, which clears kernel state. List the options via `GET /environments`.

folderIdstring:uuid | null

Folder to move the project into, or null to move it to the workspace root. Resolve a folder name to its ID via `GET /folders`, or create it via `POST /folders`.

Responses

▸200Project updated
application/jsonUpdateProjectResponse
projectrequiredobject
▸400Validation error, or `dataApp.published` set on a project that is not a data app
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions or static file sharing is unavailable
application/jsonErrorResponse
messagerequiredstring
▸404Project, environment, or folder not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring
▸500Internal server error
application/jsonErrorResponse
messagerequiredstring

Delete a project

delete/projects/{projectId}

Parameters

projectIdpathrequiredstring:uuid

Responses

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

Mint a data app token

Mints the short-lived viewer token a data app uses to call the API, for the key owner, so the app can be developed outside Deepnote against the same API the published app uses. Only `data_app` projects can mint a token.

post/projects/{projectId}/data-app/token

Parameters

projectIdpathrequiredstring:uuid

Responses

▸200Token minted
application/jsonDataAppToken
tokenrequiredstring

Bearer token scoped to the data app run loop: read a notebook’s inputs, start a detached run, poll it.

apiOriginrequiredstring:uri

Origin to send the token to.

expiresAtSecondsrequiredinteger

Token expiry as a Unix timestamp in seconds.

▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸404Project not found, not a data app, or data app API access is unavailable to the key owner
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring
▸500Internal server error
application/jsonErrorResponse
messagerequiredstring

Get a page of a named dataframe

Returns one page of the full DataFrame that notebook code stored last under `name` with `deepnote_toolkit.artifacts.store_dataframe(df, name)`, as JSON rows. 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, a new frame was stored under the name, so start again at page 0. A 400 for a `pageIndex` below a `pageCount` served earlier means the same: a smaller frame replaced it. The 404 response does not say why there is nothing to serve: the project may not exist, or nothing may be stored under the name.

get/projects/{projectId}/dataframes/{name}

Parameters

projectIdpathrequiredstring:uuid
namepathrequiredstring

The name the frame is stored under. It matches `[A-Za-z0-9_-]{1,128}`.

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
▸404Project not found, or nothing is stored under the name
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

Export a project as a ZIP archive

Returns a ZIP archive containing one `.deepnote` YAML document per notebook. Block outputs and per-run execution metadata are excluded.

get/projects/{projectId}/export

Parameters

projectIdpathrequiredstring:uuid

Responses

▸200ZIP archive containing the project notebooks
application/zipstring:binary
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸404Project not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸422The project contains blocks that cannot be represented in a `.deepnote` document, or its requirements.txt is too large to parse
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring

Import a project ZIP archive

Reconciles an existing project from the ZIP produced by project export. Before applying changes, Deepnote creates a version-history snapshot of the project's current notebook state, which can be used to restore notebooks to their pre-import state. Importing a notebook clears the outputs and execution state of all its blocks; notebooks omitted from a partial import are unchanged. Each `.deepnote` document must contain exactly one notebook from the target project and use the same project name and, when present, integration attachments. The project name and declared integration attachments are applied during import; changing the project name requires project rename permission. Notebooks are matched by document-facing id. Missing notebooks are left untouched unless `deleteMissingNotebooks=true`. Requirements are not imported.

post/projects/{projectId}/import

Parameters

projectIdpathrequiredstring:uuid
baseModifiedAtquerystring:date-time

Structural version from the export this import is based on. The import returns 409 when the project structure has changed since this timestamp.

baseContentHashqueryProjectContentHash

Canonical content hash from the export this import is based on. The import returns 409 when the currently exported documents differ.

deleteMissingNotebooksquery"true" | "false"

Delete active project notebooks that are absent from the archive. Defaults to `false`, which leaves missing notebooks untouched.

forcequery"true" | "false"

Skip both lost-update checks and then import regardless of concurrent project changes. Defaults to `false`.

Request body

required
application/zipstring:binary

Responses

▸200Project notebooks reconciled
application/jsonImportProjectResponse
projectrequiredobject
notebooksrequiredobject[]
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions or notebook limit reached
application/jsonErrorResponse
messagerequiredstring
▸404Project not found
application/jsonErrorResponse
messagerequiredstring
▸409Project changed since the supplied base version or is suspended
application/jsonErrorResponse
messagerequiredstring
▸413Archive or document too large
application/jsonErrorResponse
messagerequiredstring
▸422Malformed archive or invalid `.deepnote` document structure
application/jsonErrorResponse
messagerequiredstring
▸429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring