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.
projectType"standard" | "notebook" | "agent"Project type. Omit to create a `standard` project; `notebook` creates a single-notebook project; `agent` creates an Agent project.
Responses
▸201Project created
CreateProjectResponseprojectrequiredobject▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Folder 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
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
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 block types 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