API reference

420 operations on 149 paths, from the description's version 0.1.0 (OpenAPI 3.1.0). Download the description as openapi.json for an API client or a code generator. How the API works explains how to use them.

About the API

Upload files, query them with SQL, compose styled map layers, and publish read-only shareable views. Every capability the UI offers is one of these documented calls; the whole journey can be driven headlessly. Protected operations require a current cookie session or account bearer token. Every map, dataset, workflow, connection and project has one owner and is private to its owner unless a project shares it: a project's owner gives people the viewer or editor role, and they reach the project and everything filed in it, whoever owns it. A viewer reads; an editor also changes the content of its maps and workflows and runs its workflows; deletion, publication, sharing and transfer stay the owner's, and datasets change only by their owner. Connections are never shared, and standalone jobs, renders and downloads stay with the account that started them. Administrators have no additional content access. Dataset and connection names are owner-local: in SQL another person's reachable dataset is <sql name>.<dataset>, and a map's or workflow's SQL reads in its SQL home. Unreached and missing resources share the same refusal. Instance catalogues and saved palettes remain shared. User SQL reads named datasets only; direct or indirect file reads and path discovery are refused. Cookie mutations require the same trusted Origin. Identity-bearing responses, including authentication refusals, are private, no-store. Only entry, readiness and the token-scoped read-only published projection permit anonymous access. Maps and workflows have one durable editRevision, paired with state on document, child and list reads. Covered writes require X-Edit-Revision (MCP expected_revision); order writes and chain the accepted JSON result. Missing or malformed revisions return 400 invalid_request. Stale revisions return 409 stale_revision: This item has changed. Reload it before trying again. Refusal changes nothing. Reload explicitly and compose a new edit, never replay an old payload under a fresh token. This breaks unversioned writers and clients expecting bodyless covered successes. Whole-document deletion has no surviving revision. Viewport-only saves, picture refresh and run cancellation keep their documented exceptions. Attribution names the last accepted actor, not the owner; legacy authors can be unknown. Shared map undo retains original authors. Run starts use the plan revision; admitted runs track executable definitions, preserving concurrent layout and lifecycle changes. Unsupported methods on documented paths return 405 method_not_allowed with an exact Allow header after authentication. HEAD is bodyless and OPTIONS reports Allow.

Signing in

Session cookie dezfil_session

HttpOnly, SameSite=Lax session. Secure over HTTPS. On a listening port other than 3000 the name carries the port suffix, and DEZFIL_SESSION_COOKIE sets the name. Lasts the instance's session length, security.sessionDays, thirty days by default; each use renews it by the length stored then. Optional X-Dezfil-Account asserts the credential's expected account ID. A mismatch returns 401 authentication_required before dispatch. This transport precondition never supplies identity or changes ownership.

Bearer token

An account's API token. Its current account status and privileges are checked on every request; once a token's expiry passes it is refused with token_expired. Optional X-Dezfil-Account asserts the credential's expected account ID. A mismatch returns 401 authentication_required before dispatch. This transport precondition never supplies identity or changes ownership.

Examples

35 worked examples on 29 operations, each drawn as a request in curl and in JavaScript and followed by the answer it gets. They call http://localhost:3000; change the address if yours differs. Replace <YOUR_TOKEN> with your API token, which the examples sign in with wherever an operation takes one. API quickstart shows how to create your first token. The ids, revisions and other values an example sends are samples: replace each with your own, such as one an answer before it gave; the example's text says what it needs. A JSON answer is spread over lines here, though curl prints it on one. Save a JavaScript example under the name in its title and run it with Node.js 24 or later.

• POST /api/auth/sign-inSign in
• GET /api/accountRead your account
• GET /api/account/tokensList your API tokens
• POST /api/account/tokensCreate an API token
• DELETE /api/account/tokens/{id}Revoke your API token
• GET /api/instance/settingsRead instance configuration
• PATCH /api/instance/settingsChange instance settings
• GET /api/healthReadiness check
• GET /api/configRuntime client configuration
• GET /api/settingsWorkspace settings
• PATCH /api/settingsUpdate your settings
• GET /api/openapi.jsonThis OpenAPI description
• GET /api/tablesList tables
• POST /api/tablesUpload a file as one or more tables
• GET /api/catalogue/tablesRead the schema-only table catalogue
• POST /api/queryRun read-only SQL
• POST /api/query/exportDownload a query's full result
• GET /api/mapsList maps
• POST /api/mapsCreate a map
• GET /api/maps/{id}Read a map with its layers
• PATCH /api/maps/{id}Update a map
• POST /api/maps/{id}/layersCreate a layer from a SQL result
• POST /api/maps/{id}/publishPublish a map
• DELETE /api/maps/{id}/publishUnpublish a map
• DELETE /api/publications/{token}Revoke a deactivated owner's publication
• POST /api/operations/runRun an operation
• GET /api/operations/runs/{id}Read an operation run
• GET /api/assistantAssistant status
• POST /api/mcpMCP endpoint

Resource families

1. 01AccountsLocal accounts and authentication. 34 operations.
2. 02SystemHealth and configuration. 177 operations.
3. 03TablesUploaded data as queryable tables. 37 operations.
4. 04QueryRead-only SQL against tables. 4 operations.
5. 05MapsMaps group ordered, styled layers. 27 operations.
6. 06LayersA layer is SQL + name + style. 25 operations.
7. 07PublishRead-only shareable views. 17 operations.
8. 08SketchesDrawing as data: a draw session becomes one ordinary GeoParquet dataset plus one layer on its map. Features carry a stable id and drawn kind; the owning-layer cascade deletes layer and dataset together and is deliberately not undoable. 9 operations.
9. 09OperationsSpatial and data operations. Each produces a durable dataset with recorded provenance; the catalog describes the verbs this instance offers. 8 operations.
10. 10RecipesA recipe is a named, ordered list of steps whose dependencies point only backwards. It records what each step was made from, so when the data underneath changes the answer to 'what is now out of date' is a fact rather than a guess. Recipes are workspace objects like datasets — not owned by a map. 28 operations.
11. 11ProjectsAn optional named set over maps, workflows and datasets. A map or workflow is in at most one project; a dataset can be in several. Project workflows are workflow-origin recipes; builder-origin recipes cannot be project members. A project is also the one boundary of sharing: its owner gives people the viewer or editor role, and they reach everything filed in it, whoever owns it. Filing never changes who owns a resource or what a plain table name means in a map's or workflow's SQL. Deleting one dissolves the set, ends every person's reach through it and deletes nothing. 19 operations.
12. 12TemplatesFinished maps and workflow examples with their data, shipped in the image or listed by the template catalogue, for every signed-in account. A template belongs to no one and is listed among no one's maps, workflows or datasets. 10 operations.
13. 13AgentsDrive Dezfil from AI agents: the documented API surface, served as MCP tools, plus the in-product assistant. 13 operations.
14. 14Connections11 operations.
15. 15Published1 operation.
16. 16SchemasThe 189 shared schemas the operations refer to, each on a page of its own.
17. 17ErrorsEvery error code the API answers with: 144 of them.