API and agentsAPI reference
Templates
Finished 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 on 7 paths.
/api/templates
GETList templates
Sign-in Session cookie or Bearer tokenMCP tool list_templates
Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. Responses, including refusals, are private, no-store. Answers from what this server holds and sends nothing. Shipped templates first, in the image's order; then the entries of the catalogue list this process last read, in its index's order, a shipped id winning over an entry naming it; then the downloaded templates that list does not name, so the shipped and downloaded ones show whatever the catalogue's state. A card takes the newest listed version unless the installed one is as new: an entry naming the installed version is drawn as installed, and an absent one is present false with the size its first open downloads. The catalogue's state says whether that list was read and, if not, why. Call POST /api/templates/refresh to read the catalogue again.
Responses
200
Success.
application/json401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/templates/refresh
POSTRefresh the template catalogue
Sign-in Session cookie or Bearer tokenMCP tool refresh_templates
Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. Responses, including refusals, are private, no-store. Cookie requests require the same trusted Origin; a bearer token calls directly. Reads the catalogue's index at the address in effect (templatesCatalogueUrl, or the folder DEZFIL_TEMPLATES_CATALOGUE names), then each listed template's pictures in the index's order, at most 2 MB each and 64 MB for the list, through the egress check, redirects included, within the link import's time bound (DEZFIL_REMOTE_TIMEOUT_S), with no credential on any request. At most once in ten minutes after a successful read, or thirty seconds after a refused or failed read: inside that window it sends nothing and answers the list kept; while a read is under way it joins it. The list kept is replaced only once a new read is whole, and a read finishing after the address or the switch changed is discarded. Refused, sending nothing: 409 templates_catalogue_off while an admin has turned the catalogue off, and 400 service_address_unreadable for a saved address the instance's key no longer opens. A catalogue that fails answers the list with its state. Answers the list, as GET /api/templates does.
Responses
200
Success.
application/json400401403409503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/templates/downloads
DELETERemove the downloaded templates
Sign-in Session cookie or Bearer tokenMCP tool remove_template_downloads
Requires a current admin through cookie or bearer authentication, rechecked on every call. Cookie requests require the same trusted Origin; an admin bearer token calls directly. Responses, including refusals, are private, no-store. Removes every template version downloaded to this server when the call began, with the engine's copies of its data that no installed version needs any more; shipped templates, and every copy anyone made, are untouched. Each version is retired as a dataset's file is: no open, copy or render begun after the call finds it, readers already under way finish first, and only then are its files removed; a download that lands meanwhile stays. A removed template downloads again at its next open or copy while the catalogue lists it. Sends nothing outside this server. Removing when nothing is downloaded answers the same, with nothing removed. Answers how many versions went and the bytes their folders took. The embedded assistant asks for confirmation before calling; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.
Responses
200
Success.
application/json400401403503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
DELETE, OPTIONS
Also on this path: OPTIONS under System.
/api/templates/{id}
GETRead a template
Sign-in Session cookie or Bearer tokenMCP tool get_template
Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. Responses, including refusals, are private, no-store. Answers one template's card, as the list draws it, how it is made and, once its version is installed on this server, what that version holds: its map's id (read through GET /api/maps/{id}), its datasets as measured and a workflow example's steps with their parameters and its saved canvas arrangement. Sends nothing. Reads the version the query names, else the one its card takes now. An id no shipped, downloaded or listed template has, or a version that is neither installed nor the one the catalogue's last list names, answers 404 template_not_listed; a version that is not a whole number from 1, 400 invalid_request.
Parameters
idPathrequiredThe template's id: lowercase letters, digits and hyphens, the same across its versions.
stringpattern
^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$versionQueryThe version to read: one installed on this server, or the one the catalogue's last list names. Without it, the version its card takes now: the newest listed, unless the installed one is as new.
integerminimum
1
Responses
200
Success.
application/json400401403404503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 400, 401, 403, 404, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
/api/templates/{id}/fetch
POSTFetch a template
Sign-in Session cookie or Bearer tokenMCP tool fetch_template
At most 65,536 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. Responses, including refusals, are private, no-store. Cookie requests require the same trusted Origin; a bearer token calls directly. Downloads one version of a template so it opens and copies with no further request: the version the body names, else the one its card takes now. An installed version (shipped, or downloaded before) answers at once and sends nothing; a shipped template has its shipped version alone. Otherwise the version must be the one the catalogue list this process last read names (POST /api/templates/refresh reads it again). Its archive is read from its address through the egress check, redirects included, within the link import's time bound (DEZFIL_REMOTE_TIMEOUT_S), with no credential on any request, or from the catalogue's folder; its size and SHA-256 are checked against the index; then it is unpacked and admitted as a client's documents are, every dataset read through the upload's reader, every layer and step bound to the template's own data and nothing else, each layer drawing within the defaults of the render cap and of Bytes drawn per layer as its view renders it, whatever this instance sets (template_invalid names the limit); and only then is it installed. Two calls for one version download it once, and downloads run one at a time on this instance. A version installed before stays as it is. Refused, coded, leaving nothing installed: 404 template_not_listed for a version neither installed nor listed; 409 templates_catalogue_off while an admin has turned the catalogue off; 400 service_address_unreadable for a saved address the instance's key no longer opens; 413 template_archive_too_large (over the declared size or 150 MB), template_unpacked_too_large or template_picture_too_large; 422 template_checksum_mismatch and the template reader's other codes, template_reference_outside among them for a layer or step naming a dataset that is not the template's; 403 egress_blocked; 502 remote_fetch_failed; 504 remote_timeout. Answers the version installed.
Parameters
idPathrequiredThe template's id: lowercase letters, digits and hyphens, the same across its versions.
stringpattern
^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
Request body (optional)
At most 65,536 bytes (64 KiB); a larger body is refused with request_body_too_large.
application/json
object
versionintegerminimum1The version to fetch; without it, the one the template's card takes now.
No other keys.
Responses
200
Success.
application/json400401403404409413422502503504default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/templates/{id}/copy
POSTCopy a template
Sign-in Session cookie or Bearer tokenMCP tool copy_template
At most 65,536 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. Responses, including refusals, are private, no-store. Cookie requests require the same trusted Origin; a bearer token calls directly. Makes a copy of one installed version of a template into a new project of the caller's, private under the ownership rules, all of it or nothing: the version the body names, else the installed one. The copy is local and sends nothing: an installed version is copied whether the catalogue still lists it or not, and with the catalogue off; a listed version that is not installed is refused with 409 template_not_installed, so fetch it first (POST /api/templates/{id}/fetch). The project is named as the body says (trimmed, 1 to 120 characters), else after the template's title, and its note carries a line naming the template, its version and the day. Filed in it, under fresh identities: the template's map with every layer, widget, the legend order, camera, basemap and timeline, each widget, the legend order and the timeline bound to the copied layers, its SQL home the caller's; a workflow example's workflow, each step the caller's own, reading the datasets and the earlier outputs as landed and declaring its output as landed, each bundled result recorded as the caller's output of its step by no job and no run (the workflow read gives such a step no lastSuccessAt and its templateResult until the step's first run replaces it), its canvas layout with every position under the copy's step or the dataset as landed and every note; and every dataset and bundled result of the template, the caller's, under its name in the template or the next free name by the suffix rule (_2, _3), reserved against the caller's datasets and every output name their workflows declare, each layer's SQL naming the dataset as landed. A copied dataset's source reads template, with the template's id and version in its sourceParams, and it is never refreshed. The map's card images are the template's pictures, saved after the copy with evidence naming the copied datasets; when they cannot be saved the copy stands and its card shows the placeholder until the map's first capture. A second copy makes a second project of the same name with its datasets suffixed, the first unchanged; copies made at once each land whole under distinct names. Refused, coded, with nothing created: 404 template_not_listed for a version neither installed nor listed; 409 template_not_installed; 409 templates_catalogue_off for a version not installed while an admin has turned the catalogue off; 400 service_address_unreadable for a saved address the instance's key no longer opens; 422 template_reference_unbound for a layer naming a dataset the copy does not make, or a step reading one; 422 template_record_mismatch and the template reader's other codes for an installed version that changed on disk; 400 invalid_request for a body that is not an optional name and version; 413 request_body_too_large. Answers the project with its members.
Parameters
idPathrequiredThe template's id: lowercase letters, digits and hyphens, the same across its versions.
stringpattern
^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$
Request body (optional)
At most 65,536 bytes (64 KiB); a larger body is refused with request_body_too_large.
application/json
object
namestringThe new project's name, trimmed, 1 to 120 characters; without it, the template's title.
versionintegerminimum1The installed version to copy; without it, the installed one.
No other keys.
Responses
201
Created.
application/json400401403404409413422503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
OPTIONS, POST
Also on this path: OPTIONS under System.
/api/templates/{id}/picture
GETRead a template's picture
Sign-in Session cookie or Bearer token
Every signed-in account, through cookie or bearer authentication; an anonymous request is refused. The picture is private and kept by the browser for five minutes; refusals are private, no-store. The card's map picture as PNG, in the theme named (light when none is): from disk for a shipped or downloaded version, else as the catalogue's last list kept it. 404 not_found when its card's picture is not kept; an unknown id answers 404 template_not_listed.
Parameters
idPathrequiredThe template's id: lowercase letters, digits and hyphens, the same across its versions.
stringpattern
^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$themeQueryThe theme's picture: light (the default) or dark.
string
One of
light,dark
Responses
200
The picture.
image/pngstringformat
binary400401403404503default
Error with a machine-readable code and human message.
application/json405
method_not_allowed: the method is unsupported for this path.
application/jsonAllowHeaderExactly the documented methods for this path.
stringalways
GET, HEAD, OPTIONS
HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 400, 401, 403, 404, 405, 503, defaultAllow
GET, HEAD, OPTIONSAutomatic HEAD uses GET with no response body.
Also on this path: OPTIONS under System.
7439201b