Deepnote Public API v2
Projects API
Projects and their contents.
Base URL
https://api.deepnote.com/v2List projects
/projectsParameters
pageSizequeryintegerMaximum number of items to return. Defaults to 50. Maximum: 100.
pageTokenquerystringOpaque token returned by the previous page. Omit for the first page.
nameContainsquerystringFilter projects whose name contains this value (case-insensitive).
Responses
▸200Paginated list of projects
ListProjectsResponseprojectsrequiredListProjectsItem[]paginationrequiredCursorPagination▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringCreate a project
/projectsRequest body
CreateProjectBodynamerequiredstringProject name.
folderIdstring:uuidFolder 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:uuidEnvironment (Docker image) for the project machine. Omit to use the default environment. List the options via `GET /environments`.
Responses
▸201Project created
CreateProjectResponseprojectrequiredobject▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Folder or environment not found
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringGet a project
/projects/{projectId}Parameters
projectIdpathrequiredstring:uuidResponses
▸200Project details
GetProjectResponseprojectrequiredobject▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Project not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringUpdate 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.
/projects/{projectId}Parameters
projectIdpathrequiredstring:uuidRequest body
objectdataAppobjectenvironmentIdstring:uuidEnvironment (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 | nullFolder 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
UpdateProjectResponseprojectrequiredobject▸400Validation error, or `dataApp.published` set on a project that is not a data app
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions or static file sharing is unavailable
ErrorResponsemessagerequiredstring▸404Project, environment, or folder not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringDelete a project
/projects/{projectId}Parameters
projectIdpathrequiredstring:uuidResponses
▸204Project deleted
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Project not found
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringMint 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.
/projects/{projectId}/data-app/tokenParameters
projectIdpathrequiredstring:uuidResponses
▸200Token minted
DataAppTokentokenrequiredstringBearer token scoped to the data app run loop: read a notebook’s inputs, start a detached run, poll it.
apiOriginrequiredstring:uriOrigin to send the token to.
expiresAtSecondsrequiredintegerToken expiry as a Unix timestamp in seconds.
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸404Project not found, not a data app, or data app API access is unavailable to the key owner
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringGet 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.
/projects/{projectId}/dataframes/{name}Parameters
projectIdpathrequiredstring:uuidnamepathrequiredstringThe name the frame is stored under. It matches `[A-Za-z0-9_-]{1,128}`.
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▸404Project not found, or nothing is stored under the name
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.
ErrorResponsemessagerequiredstringExport 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.
/projects/{projectId}/exportParameters
projectIdpathrequiredstring:uuidResponses
▸200ZIP archive containing the project notebooks
string:binary▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸404Project not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸422The project contains blocks that cannot be represented in a `.deepnote` document, or its requirements.txt is too large to parse
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringImport 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.
/projects/{projectId}/importParameters
projectIdpathrequiredstring:uuidbaseModifiedAtquerystring:date-timeStructural version from the export this import is based on. The import returns 409 when the project structure has changed since this timestamp.
baseContentHashqueryProjectContentHashCanonical 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
string:binaryResponses
▸200Project notebooks reconciled
ImportProjectResponseprojectrequiredobjectnotebooksrequiredobject[]▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions or notebook limit reached
ErrorResponsemessagerequiredstring▸404Project not found
ErrorResponsemessagerequiredstring▸409Project changed since the supplied base version or is suspended
ErrorResponsemessagerequiredstring▸413Archive or document too large
ErrorResponsemessagerequiredstring▸422Malformed archive or invalid `.deepnote` document structure
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring