{ "openapi": "3.1.0", "info": { "title": "Dezfil API", "version": "0.1.0", "description": "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 ., 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." }, "tags": [ { "name": "Accounts", "description": "Local accounts and authentication." }, { "name": "System", "description": "Health and configuration." }, { "name": "Tables", "description": "Uploaded data as queryable tables." }, { "name": "Query", "description": "Read-only SQL against tables." }, { "name": "Maps", "description": "Maps group ordered, styled layers." }, { "name": "Layers", "description": "A layer is SQL + name + style." }, { "name": "Publish", "description": "Read-only shareable views." }, { "name": "Sketches", "description": "Drawing 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." }, { "name": "Operations", "description": "Spatial and data operations. Each produces a durable dataset with recorded provenance; the catalog describes the verbs this instance offers." }, { "name": "Recipes", "description": "A 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." }, { "name": "Projects", "description": "An 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." }, { "name": "Templates", "description": "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." }, { "name": "Agents", "description": "Drive Dezfil from AI agents: the documented API surface, served as MCP tools, plus the in-product assistant." } ], "paths": { "/api/auth/entry": { "get": { "summary": "Authentication entry information", "description": "The instance name, sign-in message, lost-password contact, landing page, the shortest password a password chosen on these screens needs, and setup availability. The landing page value does not change navigation. Before setup, the legacy display name may prefill Name. Never returns a signed-in person's identity or account preferences. Private, no-store.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthEntry" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/auth/setup": { "post": { "summary": "Create the first account", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Cookie mutations and entry submissions require an Origin matching the trusted request origin. Explicit bearer authentication does not use cookies. Responses are private, no-store. Atomically creates the sole initial admin, adopts legacy preferences and establishes a cookie session. Once any account exists, setup_complete refuses further creation. Password derivations share two active slots and at most eight waiters: six ordinary and two reserved protected, each waiting at most five seconds. FIFO within each class; validated links and signed-in current-password work are protected, including the second password-change derivation. Protected work takes the next free slot but at most one active slot, even with ordinary slots idle. Ordinary work may use both; running work is never pre-empted. A fourth simultaneous protected caller is refused at once and may retry immediately without a login lockout; the busy response advises a one-second retry. Known and unknown sign-ins are ordinary. Overflow or deadline answers authentication_busy. Cancellation removes waiters; native work owns its slot until it settles. Recovery issuance derives nothing.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The address the instance is opened at, its scheme, host and port, such as http://localhost:3000. Missing or another origin: 403 forbidden." } ], "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "email": { "type": "string", "description": "Local email identity, normalized for case and surrounding whitespace." }, "password": { "type": "string", "minLength": 8, "writeOnly": true, "description": "At least eight characters; very common passwords are refused. No character classes are required." } }, "required": [ "name", "email", "password" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable when provenance is missing, or authentication_busy: Authentication is busy. Try again shortly. Capacity refusal has error.retryAfter: 1, Retry-After: 1 and private, no-store; no credentials, link consumption, profile or password changes, or login failures result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "One second for authentication_busy.", "schema": { "type": "integer", "const": 1 } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/auth/sign-in": { "post": { "summary": "Sign in", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Cookie mutations and entry submissions require an Origin matching the trusted request origin. Explicit bearer authentication does not use cookies. Responses are private, no-store. Unknown email and wrong password share invalid_credentials. Valid credentials for a deactivated account return account_deactivated. Account failure limits apply only to sources with recent failures; a correct password from a source without recent failures can sign in even when the account budget is exhausted. Failures from every source count against the account, and source limits always apply. Cancellation after derivation starts retains the source reservation against its per-address budget (the instance setting, twenty attempts by default) until the fifteen-minute window expires, refunds the account reservation and adds no failures, preserving the clean-source exception. Limits return rate_limited with Retry-After, retryAfter seconds and retryAt (ISO timestamp); waiting restores admission. Password derivations share two active slots and at most eight waiters: six ordinary and two reserved protected, each waiting at most five seconds. FIFO within each class; validated links and signed-in current-password work are protected, including the second password-change derivation. Protected work takes the next free slot but at most one active slot, even with ordinary slots idle. Ordinary work may use both; running work is never pre-empted. A fourth simultaneous protected caller is refused at once and may retry immediately without a login lockout; the busy response advises a one-second retry. Known and unknown sign-ins are ordinary. Overflow or deadline answers authentication_busy. Cancellation removes waiters; native work owns its slot until it settles. Recovery issuance derives nothing.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The address the instance is opened at, its scheme, host and port, such as http://localhost:3000. Missing or another origin: 403 forbidden.", "examples": { "quickstart": { "summary": "Sign in as Ana Diaz", "value": "http://localhost:3000" } } } ], "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "description": "Local email identity, normalized for case and surrounding whitespace." }, "password": { "type": "string", "writeOnly": true } }, "required": [ "email", "password" ] }, "examples": { "quickstart": { "summary": "Sign in as Ana Diaz", "description": "Needs an account on the instance. Origin names the address the instance is opened at. The answer sets the session cookie, which creating a token accepts.", "value": { "email": "ana@example.com", "password": "" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" }, "examples": { "quickstart": { "summary": "Sign in as Ana Diaz", "description": "Needs an account on the instance. Origin names the address the instance is opened at. The answer sets the session cookie, which creating a token accepts.", "value": { "account": { "id": "5f0c2d9e-8a41-4b7e-9c3a-2e6f1b8d7a40", "name": "Ana Diaz", "email": "ana@example.com", "sqlName": "ana_diaz", "isAdmin": true, "status": "active", "isOriginal": true, "createdAt": "2026-10-20T09:00:00.626Z", "updatedAt": "2026-10-20T09:00:00.626Z", "lastSignInAt": "2026-10-20T09:00:00.787Z" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds until another attempt is permitted.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "ingress_unavailable when provenance is missing, or authentication_busy: Authentication is busy. Try again shortly. Capacity refusal has error.retryAfter: 1, Retry-After: 1 and private, no-store; no credentials, link consumption, profile or password changes, or login failures result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "One second for authentication_busy.", "schema": { "type": "integer", "const": 1 } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/auth/redeem": { "post": { "summary": "Redeem a sign-in link", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Cookie mutations and entry submissions require an Origin matching the trusted request origin. Explicit bearer authentication does not use cookies. Responses are private, no-store. An ordinary admin-issued link expires after the instance's link lifetime it was issued with, security.linkDays, seven days by default; local filesystem recovery issues a fifteen-minute link. Both are consumed once. Invalid, expired, replaced and reused links return invalid_link without changing the password or session. Success replaces the browser's cookie with the recipient's session, even when another account was signed in. Password derivations share two active slots and at most eight waiters: six ordinary and two reserved protected, each waiting at most five seconds. FIFO within each class; validated links and signed-in current-password work are protected, including the second password-change derivation. Protected work takes the next free slot but at most one active slot, even with ordinary slots idle. Ordinary work may use both; running work is never pre-empted. A fourth simultaneous protected caller is refused at once and may retry immediately without a login lockout; the busy response advises a one-second retry. Known and unknown sign-ins are ordinary. Overflow or deadline answers authentication_busy. Cancellation removes waiters; native work owns its slot until it settles. Recovery issuance derives nothing.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "parameters": [ { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The address the instance is opened at, its scheme, host and port, such as http://localhost:3000. Missing or another origin: 403 forbidden." } ], "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "secret": { "type": "string", "writeOnly": true }, "password": { "type": "string", "minLength": 8, "writeOnly": true, "description": "At least eight characters; very common passwords are refused. No character classes are required." } }, "required": [ "secret", "password" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable when provenance is missing, or authentication_busy: Authentication is busy. Try again shortly. Capacity refusal has error.retryAfter: 1, Retry-After: 1 and private, no-store; no credentials, link consumption, profile or password changes, or login failures result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "One second for authentication_busy.", "schema": { "type": "integer", "const": 1 } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/auth/session": { "get": { "summary": "Read your current session identity", "description": "Rechecks the presented cookie or bearer against current account and credential state. Invalid or revoked credentials return authentication_required. Private, no-store.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/auth/sign-out": { "post": { "summary": "Sign out", "description": "Cookie mutations and entry submissions require an Origin matching the trusted request origin. Explicit bearer authentication does not use cookies. Responses are private, no-store. Ends the current browser session and clears its cookie. A bearer has no browser session to end; API tokens are revoked through their own controls.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedOut" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/account": { "get": { "summary": "Read your account", "description": "Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns only the authenticated account's profile. No password or credential material is returned.", "tags": [ "Accounts" ], "x-tool": "get_account", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read your account" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" }, "examples": { "signedIn": { "summary": "Read the account a token belongs to", "description": "Needs a token.", "value": { "account": { "id": "5f0c2d9e-8a41-4b7e-9c3a-2e6f1b8d7a40", "name": "Ana Diaz", "email": "ana@example.com", "sqlName": "ana_diaz", "isAdmin": true, "status": "active", "isOriginal": true, "createdAt": "2026-10-20T09:00:00.626Z", "updatedAt": "2026-10-20T09:00:00.626Z", "lastSignInAt": "2026-10-20T09:00:00.787Z" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Update your account", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Password derivations share two active slots and at most eight waiters: six ordinary and two reserved protected, each waiting at most five seconds. FIFO within each class; validated links and signed-in current-password work are protected, including the second password-change derivation. Protected work takes the next free slot but at most one active slot, even with ordinary slots idle. Ordinary work may use both; running work is never pre-empted. A fourth simultaneous protected caller is refused at once and may retry immediately without a login lockout; the busy response advises a one-second retry. Known and unknown sign-ins are ordinary. Overflow or deadline answers authentication_busy. Cancellation removes waiters; native work owns its slot until it settles. Recovery issuance derives nothing.Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Changes only your own name or email. An email change requires currentPassword and replaces the sign-in email. Duplicate emails return email_taken, regardless of case or surrounding whitespace. Missing or incorrect current passwords return current_password_required. Current-password checks on password and email changes share one allowance per account, apart from sign-in accounting: the Failed sign-ins per account count (security.failedPerAccount, five by default) within a fixed fifteen minutes. Missing or incorrect current passwords count; busy refusals, failing password work and a caller who leaves before the check starts do not; a caller who leaves after it starts keeps that place taken until the window ends. Concurrent checks never exceed what is left. Past the count, checks return rate_limited with Retry-After, retryAfter seconds and retryAt (ISO timestamp) before any password work. A correct current password clears this count and leaves sign-in's untouched; a sign-in clears only its own. The complete patch is validated before any write; account identity, role and status cannot be submitted.", "tags": [ "Accounts" ], "x-tool": "update_account", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated your account" }, "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "email": { "type": "string" }, "currentPassword": { "type": "string", "writeOnly": true, "description": "Your current password." } }, "required": [], "anyOf": [ { "required": [ "name" ] }, { "required": [ "email" ] } ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: too many wrong current passwords for this account within the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds until another check is permitted.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/account/password": { "post": { "summary": "Change your password", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Password derivations share two active slots and at most eight waiters: six ordinary and two reserved protected, each waiting at most five seconds. FIFO within each class; validated links and signed-in current-password work are protected, including the second password-change derivation. Protected work takes the next free slot but at most one active slot, even with ordinary slots idle. Ordinary work may use both; running work is never pre-empted. A fourth simultaneous protected caller is refused at once and may retry immediately without a login lockout; the busy response advises a one-second retry. Known and unknown sign-ins are ordinary. Overflow or deadline answers authentication_busy. Cancellation removes waiters; native work owns its slot until it settles. Recovery issuance derives nothing.Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Requires currentPassword. The new password needs at least eight characters and cannot be very common; no character classes are required. Wrong current passwords return current_password_required; weak new passwords return weak_password. Current-password checks on password and email changes share one allowance per account, apart from sign-in accounting: the Failed sign-ins per account count (security.failedPerAccount, five by default) within a fixed fifteen minutes. Missing or incorrect current passwords count; busy refusals, failing password work and a caller who leaves before the check starts do not; a caller who leaves after it starts keeps that place taken until the window ends. Concurrent checks never exceed what is left. Past the count, checks return rate_limited with Retry-After, retryAfter seconds and retryAt (ISO timestamp) before any password work. A correct current password clears this count and leaves sign-in's untouched; a sign-in clears only its own. Keeps the calling browser session, ends your other sessions and leaves API tokens valid. A bearer caller has no browser session to preserve.", "tags": [ "Accounts" ], "x-tool": "change_password", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Change your password?", "consequence": "Your other browser sessions will end. API tokens stay valid.", "subject": { "path": "/api/account", "argument": "", "name": "account.name" } }, "x-display": { "verb": "Changed your password" }, "x-confirm": true, "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "currentPassword": { "type": "string", "writeOnly": true, "description": "Your current password." }, "password": { "type": "string", "minLength": 8, "writeOnly": true } }, "required": [ "currentPassword", "password" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordChanged" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: too many wrong current passwords for this account within the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds until another check is permitted.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/account/tokens": { "get": { "summary": "List your API tokens", "description": "Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Lists only your own tokens, including revoked and expired ones, each with when it expires. Secrets and hashes are never returned.", "tags": [ "Accounts" ], "x-tool": "list_api_tokens", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read your API tokens" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokens" }, "examples": { "twoTokens": { "summary": "List your tokens", "description": "Needs a token. Lists the two tokens made above, without their secrets.", "value": { "tokens": [ { "id": "3c9e7a14-5b2f-4d81-9e6a-0f4b8c2d1e73", "name": "Quickstart", "createdAt": "2026-10-20T09:00:00.791Z", "lastUsedAt": "2026-10-20T09:00:00.795Z", "revokedAt": null, "expiresAt": null }, { "id": "a81f3d52-7c64-4e09-b2d7-6e5c9f0a3b18", "name": "Nightly import", "createdAt": "2026-10-20T09:00:00.794Z", "lastUsedAt": null, "revokedAt": null, "expiresAt": null } ] } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create an API token", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Creates a named API/MCP token for your own account. The secret is returned only on creation. It authenticates with your current account permissions and is refused while the account is deactivated. It lasts as long as the instance's rule for new tokens said at its creation, or never expires; expiresAt says when, a later change of the rule moves no token's expiry, and once it passes the token is refused with token_expired.", "tags": [ "Accounts" ], "x-tool": "create_api_token", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Create an API token for your account?", "consequence": "The token grants your current permissions until it is revoked or expires, or the account is deactivated.", "subject": { "path": "/api/account", "argument": "", "name": "account.name" } }, "x-display": { "verb": "Created an API token" }, "x-confirm": true, "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "examples": { "quickstart": { "summary": "Create the token Quickstart", "description": "Needs a signed-in session: the cookie signing in sets, sent with Origin, or a token. The secret is in this answer only; send it as the bearer token from then on.", "value": { "name": "Quickstart" } }, "nightlyImport": { "summary": "Create a second token with the first", "description": "Needs a token.", "value": { "name": "Nightly import" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiToken" }, "examples": { "quickstart": { "summary": "Create the token Quickstart", "description": "Needs a signed-in session: the cookie signing in sets, sent with Origin, or a token. The secret is in this answer only; send it as the bearer token from then on.", "value": { "id": "3c9e7a14-5b2f-4d81-9e6a-0f4b8c2d1e73", "name": "Quickstart", "createdAt": "2026-10-20T09:00:00.791Z", "lastUsedAt": null, "revokedAt": null, "expiresAt": null, "secret": "" } }, "nightlyImport": { "summary": "Create a second token with the first", "description": "Needs a token.", "value": { "id": "a81f3d52-7c64-4e09-b2d7-6e5c9f0a3b18", "name": "Nightly import", "createdAt": "2026-10-20T09:00:00.794Z", "lastUsedAt": null, "revokedAt": null, "expiresAt": null, "secret": "" } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/account/tokens/{id}": { "delete": { "summary": "Revoke your API token", "description": "Cookie or bearer authentication is required. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Permanently refuses this token on later requests. Only your own tokens can be revoked; unknown or other-account IDs return not_found without changes. Repeated revocation is harmless.", "tags": [ "Accounts" ], "x-tool": "revoke_api_token", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Revoke {target}?", "consequence": "Clients using this token will lose access.", "subject": { "path": "/api/account/tokens", "argument": "id", "name": "name", "collection": "tokens", "identity": "id" } }, "x-display": { "verb": "Revoked an API token" }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Your token's ID, never its secret.", "examples": { "nightlyImport": { "summary": "Revoke the token Nightly import", "value": "a81f3d52-7c64-4e09-b2d7-6e5c9f0a3b18" } } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRevoked" }, "examples": { "nightlyImport": { "summary": "Revoke the token Nightly import", "description": "Needs a token and the id of the token to revoke. The revoked token's next call answers authentication_required.", "value": { "revoked": true } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Your token's ID, never its secret." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/{id}/deletion-preview": { "get": { "summary": "Preview user deletion", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns only the account identity already visible in Users, totals per owned kind and distinct other active people whose present reach shrinks. Never returns private names, project references, rosters or content. The opaque confirmation is bound to the target, requesting admin, eligibility generation, inventory identities, publication links, grants and filings. Same-count swaps, publication changes and a reactivate/deactivate cycle invalidate it; unrelated surviving-document edits do not. A pending deletion returns its identifier and unfinished state instead. Self and active-target refusals are identical to deletion. This read erases nothing.", "tags": [ "Accounts" ], "x-tool": "preview_user_deletion", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read a deletion preview" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The other account to preview." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionPreviewResult" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The other account to preview." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "409": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The other account to preview." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/deletions/{id}": { "get": { "summary": "Read user deletion status", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns pending or needs-retry for unfinished deletion. A pending deletion also carries admittedReads, the reads admitted before it that it still waits on: erasure starts once they settle, and a count that stays above zero means a reader has not let go. An unreadable deletion record returns 409 deletion_unreadable and remains untouched. No stage, failure detail or content is exposed. Completed identifiers return 404 not_found because their temporary records have been removed; after an accepted response, clients may refresh list_users to reconcile a missing identifier. A missing identifier without prior acceptance is not proof that an account was deleted.", "tags": [ "Accounts" ], "x-tool": "get_user_deletion", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read account deletion status" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The accepted deletion identifier, not an account id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionProgress" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The accepted deletion identifier, not an account id." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "409": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The accepted deletion identifier, not an account id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/deletions/{id}/finish": { "post": { "summary": "Finish deleting a user", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Deletion is permanent erasure of the account and everything it owns, wherever filed; shared reach and published links end. Owned projects dissolve and surviving members' work becomes unfiled. No handover occurs. Deactivation keeps shared reads, copies, runs and links. Except for never-redeemed invitations, deletion purges all geocode, isochrone and Overpass answer caches; later requests contact providers again. The identifying SQL name stays reserved forever for an ever-active account; completion frees its email. Others' derived datasets and stored SQL, lineage and run text remain theirs and can retain names or personal text. Issued private copies keep their shipped lifetime; completion waits for prepared files to settle or expire and cleanup to finish. Recorded input evidence identifies affected foreign card images, tiles, renders and prepared files; existing unattributed card images owned by others remain. Deleting a workflow removes its run records while its output datasets remain. Host snapshots, backups, logs, providers, browser-local SQL/conversations, exports, downloaded files and databases written through connections are outside erasure; restoring a backup can revive data and credentials. This is neither disk-remanence erasure nor anonymization. Pending or needs-retry is unfinished, never completed success: use status or Finish deleting with the same identifier; the account and its work stay inaccessible. Finishing rewrites the whole metadata store and pauses every response. An outside database reader or insufficient free working space on the data volume or SQLite temporary filesystem can prevent compaction; release the reader or restore space, then Finish deleting safely with the same identifier. Resumes the accepted deletion, including after restart, without changing its identifier or repeating completed dissolution. Concurrent requests join the same work. An unreadable record returns 409 deletion_unreadable without changing any files. Completed identifiers return 404 not_found.", "tags": [ "Accounts" ], "x-tool": "finish_user_deletion", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true }, { "resource": "maps", "collection": true }, { "resource": "layers", "collection": true }, { "resource": "tables", "collection": true }, { "resource": "publications", "collection": true }, { "resource": "recipes", "collection": true }, { "resource": "runs", "collection": true }, { "resource": "projects", "collection": true }, { "resource": "connections", "collection": true }, { "resource": "assistant", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Finish deleting this account?", "consequence": "This permanently erases the account and everything it owns. Other people lose shared access and published links stop working. This cannot be undone.", "subject": { "path": "/api/users", "argument": "id", "name": "account.name", "collection": "deletions", "identity": "id" } }, "x-display": { "verb": "Continued account deletion" }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The accepted deletion identifier, not an account id." } ], "responses": { "200": { "description": "Deletion completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionStatus" } } } }, "202": { "description": "Deletion is pending or needs retry; erasure is unfinished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionStatus" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The accepted deletion identifier, not an account id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users": { "get": { "summary": "List users", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Lists invited, active and deactivated accounts, their role and last sign-in. isOriginal permanently identifies the first account. The separate deletions array lists unfinished reservations with their deletion id, pending or needs-retry state and the existing Users identity; it remains available after profile erasure and disappears on completion. An unreadable deletion appears separately as {id, state: unreadable}, without an account identity. It does not block other users, invitations or access changes; its status and continuation return deletion_unreadable. Deleted accounts are absent from users. Passwords, credential hashes and sign-in links are never returned.", "tags": [ "Accounts" ], "x-tool": "list_users", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the users" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Invite a user", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Reserves a name and normalized email and returns a signInUrl once. The recipient chooses a password when opening the link; this instance sends no email. The link expires after the instance's link lifetime, security.linkDays, seven days by default, and keeps the lifetime it was issued with. isAdmin defaults to false and an admin may explicitly grant it. Duplicate emails return email_taken regardless of case or surrounding whitespace, including invited and deactivated accounts. An email awaiting deletion completion remains reserved, including after its profile is removed, and never offers reactivation. For a deactivated duplicate the error carries accountId and canReactivate: true; reactivate that account instead of creating another.", "tags": [ "Accounts" ], "x-tool": "invite_user", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true, "result": "account.id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Invite this person to the instance?", "consequence": "They can sign in with the permissions you grant when they choose a password.", "subject": { "path": "/api/account", "argument": "", "name": "account.name" } }, "x-display": { "verb": "Invited {subject}", "subject": { "resource": "accounts", "result": "account.id", "name": [ "account.name", "name" ] } }, "x-confirm": true, "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string" }, "isAdmin": { "type": "boolean", "default": false } }, "required": [ "name", "email" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedSignInLink" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Email already reserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInvitationConflict" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/{id}": { "delete": { "summary": "Delete a user", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Deletion is permanent erasure of the account and everything it owns, wherever filed; shared reach and published links end. Owned projects dissolve and surviving members' work becomes unfiled. No handover occurs. Deactivation keeps shared reads, copies, runs and links. Except for never-redeemed invitations, deletion purges all geocode, isochrone and Overpass answer caches; later requests contact providers again. The identifying SQL name stays reserved forever for an ever-active account; completion frees its email. Others' derived datasets and stored SQL, lineage and run text remain theirs and can retain names or personal text. Issued private copies keep their shipped lifetime; completion waits for prepared files to settle or expire and cleanup to finish. Recorded input evidence identifies affected foreign card images, tiles, renders and prepared files; existing unattributed card images owned by others remain. Deleting a workflow removes its run records while its output datasets remain. Host snapshots, backups, logs, providers, browser-local SQL/conversations, exports, downloaded files and databases written through connections are outside erasure; restoring a backup can revive data and credentials. This is neither disk-remanence erasure nor anonymization. Pending or needs-retry is unfinished, never completed success: use status or Finish deleting with the same identifier; the account and its work stay inaccessible. Finishing rewrites the whole metadata store and pauses every response. An outside database reader or insufficient free working space on the data volume or SQLite temporary filesystem can prevent compaction; release the reader or restore space, then Finish deleting safely with the same identifier. First deactivate an ever-active target separately and call preview_user_deletion. Submit confirm: true, the opaque confirmation and the exact current email for an ever-active account. A never-redeemed invitation requires explicit confirmation but no email; it is removed wholly and frees its SQL name. No private content read is granted. Missing confirmation returns invalid_request; self_change_refused takes precedence over account_not_deactivated. Acceptance rechecks eligibility and the owned inventory in the same transaction; a stale eligible preview returns deletion_changed without effects. A repeated acceptance returns the same unfinished identifier and state without restarting cleanup. After completion, this target and the completed deletion identifier return not_found.", "tags": [ "Accounts" ], "x-tool": "delete_user", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true }, { "resource": "maps", "collection": true }, { "resource": "layers", "collection": true }, { "resource": "tables", "collection": true }, { "resource": "publications", "collection": true }, { "resource": "recipes", "collection": true }, { "resource": "runs", "collection": true }, { "resource": "projects", "collection": true }, { "resource": "connections", "collection": true }, { "resource": "assistant", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete this account and its work?", "consequence": "This permanently erases the account and everything it owns. Other people lose shared access and published links stop working. This cannot be undone.", "subject": { "path": "/api/users", "argument": "id", "name": "name", "collection": "users", "identity": "id" } }, "x-display": { "verb": "Requested account deletion" }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The other account to delete." } ], "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "confirm": { "type": "boolean", "const": true }, "confirmation": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Opaque value from this admin's current deletion preview." }, "email": { "type": "string", "description": "Exact account email, required when the account has ever signed in." } }, "required": [ "confirm", "confirmation" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Deletion completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionStatus" } } } }, "202": { "description": "Deletion is pending or needs retry; erasure is unfinished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionStatus" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Change user access", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Grants or removes admin status, deactivates or reactivates the same account. Self-deactivation and self-removal of admin status return self_change_refused even with another admin. Competing changes cannot remove every active admin. A patch is applied atomically or not at all. Deactivation ends sessions and refuses tokens; reactivation restores token eligibility without reviving ended sessions. Reactivating an unaccepted invitation returns it to invited status. This operation does not delete accounts or content. Accepted deletion refuses reactivation with deletion_in_progress, including during final cleanup after the profile is removed.", "tags": [ "Accounts" ], "x-tool": "update_user_access", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Change access for {target}?", "consequence": "Role changes apply immediately. Deactivation ends browser sessions and refuses API tokens.", "subject": { "path": "/api/users", "argument": "id", "name": "name", "collection": "users", "identity": "id" } }, "x-display": { "verb": "Changed access for {subject}", "subject": { "resource": "accounts", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account to change." } ], "requestBody": { "x-byte-limit": 65536, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "isAdmin": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "deactivated" ] } }, "required": [], "anyOf": [ { "required": [ "isAdmin" ] }, { "required": [ "status" ] } ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The other account to delete." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/{id}/sign-in-link": { "post": { "summary": "Issue a new sign-in link", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns a one-time signInUrl expiring after the instance's link lifetime, security.linkDays, seven days by default; the link keeps the lifetime it was issued with. Replaces every earlier unused link, invalidates the current password and ends browser sessions while API tokens stay valid. The recipient chooses their password and enters as this account even if another account was signed in. An expired, replaced or consumed link grants no access. This instance sends no email; share the returned link with its recipient.", "tags": [ "Accounts" ], "x-tool": "issue_user_sign_in_link", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Issue a new sign-in link for {target}?", "consequence": "The current password and earlier links will stop working. Browser sessions will end; API tokens stay valid.", "subject": { "path": "/api/users", "argument": "id", "name": "name", "collection": "users", "identity": "id" } }, "x-display": { "verb": "Issued a sign-in link for {subject}", "subject": { "resource": "accounts", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account receiving the sign-in link." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedSignInLink" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account receiving the sign-in link." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/settings": { "get": { "summary": "Read instance configuration", "description": "Requires a current admin account through a cookie session or bearer token, rechecked on every call. Responses, including refusals, are private, no-store. Returns every instance and platform definition with its effective value, source, stored value (including a shadowed value), lock and invalid-override state. A non-empty environment variable locks the setting even when invalid; invalid numeric overrides use the default without returning the override text. Empty numeric overrides are absent; a set empty assistant model list retains its default model alone. Environment changes require a restart. Provider keys report set or not set; the encryption key reports environment, data-directory or not-yet-present. Address value and defaultValue expose scheme and host only, never user information, paths, queries or fragments; malformed addresses report set and unreadable. A service address or the satellite tile template an admin stored reads as set with its scheme and host, or as set and unreadable once the instance's encryption key no longer opens it; its storedValue is always null. The satellite tile template in effect, stored or set by DEZFIL_SATELLITE_URL, also reads with userInformation true while it carries a user name or password, which is never given: the imagery is not drawn from such an address. The satellite credit an admin stored reads as stored while DEZFIL_SATELLITE_ATTRIBUTION is unset, and as the variable's, with the stored credit as storedValue, while it is set. The template catalogue's address (templatesCatalogueUrl) reads as a service address does; while DEZFIL_TEMPLATES_CATALOGUE names a folder on this server instead of an http or https address, it reads as set with folder true, and the folder's path is never given. Trusted engine memory (trustedMemoryMb) defaults to 3072 MB and Bytes drawn per layer (renderCapBytes) to 134217728 bytes; both are deployment-controlled and reject writes. Data processing time limit (dataProcessingTimeoutS) defaults to 3600 seconds, accepts stored whole seconds from 60 to 21600, and resets with null. Trusted imports, refreshes, geometry and sketch changes, template installation and export conversion use the Data processing time limit. Trusted work shares the configured memory budget and a dedicated scratch allowance of four times that value; restart clears abandoned spill. Exhaustion answers engine_memory_exceeded, naming memory or scratch and DEZFIL_TRUSTED_MEMORY_MB. Upload reception and processing each use the value admitted when reception begins, with separate deadlines. Layer renders and dataset map features count their complete inline answer against Bytes drawn per layer as it is built; above it a layer takes its tile road or answers the errored layer render_bytes_exceeded, and dataset map features answer ok:false with a reason. Slider, Overture and OpenStreetMap previews and the sketch features read count theirs too and answer 422 render_bytes_exceeded above it. The built-in documentedDefault stays as documented, including any path. Contextual defaults carry a rule when there is no single address or value. The read generates no key, writes no configuration file, contacts no service and initializes no engine. Capacities report admitted geocode rows and travel-time origins per run, without promising a configured provider. Also returns the fixed maximum image dimension, package version, stable process start time and warnings when the effective query timeout is at or above the run timeout. Services report each provider cache (geocode, isochrone, overpass) with the bytes its answers take, how many it holds and its budget in MB, and the Overture release list this process keeps: how many releases, the newest and when it was listed, or not listed yet. Parts report each part of this server, starting nothing and running no program: the query engine's library version, whether the engine has started and the extensions it loaded; whether the tile builder and the image renderer's browser are executable files where their settings point, by a file check, the tile builder's version once this server has run it, and Images at once; the metadata database's file name. basemapStyles is the basemap library, oldest first, hidden styles included: each style's id, name, address, credit, whether it is offered and when it was added.", "tags": [ "System" ], "x-tool": "get_instance_settings", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read instance configuration" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceSettings" }, "examples": { "defaults": { "summary": "Read the instance's settings", "description": "Needs an admin's token. On a new instance run from a checkout with DEZFIL_DATA_DIR=/data and PORT=3000.", "value": { "settings": { "uploadMaxMb": { "key": "uploadMaxMb", "environment": "DEZFIL_UPLOAD_MAX_MB", "label": "Largest upload", "purpose": "Size cap for one uploaded file.", "defaultValue": 5120, "unit": "MB", "write": { "kind": "integer", "min": 1, "max": 102400 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "5120", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 5120, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "dataProcessingTimeoutS": { "key": "dataProcessingTimeoutS", "environment": "DEZFIL_DATA_PROCESSING_TIMEOUT_S", "label": "Data processing time limit", "purpose": "Time to receive one upload, and, counted apart, time for one data processing job, such as an import.", "defaultValue": 3600, "unit": "seconds", "write": { "kind": "integer", "min": 60, "max": 21600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "3600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 3600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "remoteMaxMb": { "key": "remoteMaxMb", "environment": "DEZFIL_REMOTE_MAX_MB", "label": "Largest link import", "purpose": "Size cap for a URL or object-store import.", "defaultValue": 2048, "unit": "MB", "write": { "kind": "integer", "min": 1, "max": 102400 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "remoteTimeoutS": { "key": "remoteTimeoutS", "environment": "DEZFIL_REMOTE_TIMEOUT_S", "label": "Link import time limit", "purpose": "Time for one link import's whole download.", "defaultValue": 300, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 3600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "300", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 300, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overtureMaxKm2": { "key": "overtureMaxKm2", "environment": "DEZFIL_OVERTURE_MAX_KM2", "label": "Overture area", "purpose": "The largest area one Overture import of places may cover; other themes may cover more or less, by how dense they are.", "defaultValue": 25000, "unit": "km²", "write": { "kind": "integer", "min": 1, "max": 1000000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "25000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 25000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "osmMaxKm2": { "key": "osmMaxKm2", "environment": "DEZFIL_OSM_MAX_KM2", "label": "OpenStreetMap area", "purpose": "The largest area one OpenStreetMap import may cover.", "defaultValue": 10000, "unit": "km²", "write": { "kind": "integer", "min": 1, "max": 1000000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "10000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 10000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassTimeoutS": { "key": "overpassTimeoutS", "environment": "DEZFIL_OVERPASS_TIMEOUT_S", "label": "Overpass time limit", "purpose": "Time budget sent with every Overpass query.", "defaultValue": 60, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 900 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassMaxsizeMb": { "key": "overpassMaxsizeMb", "environment": "DEZFIL_OVERPASS_MAXSIZE_MB", "label": "Overpass response budget", "purpose": "Response budget sent to Overpass; twice this aborts locally.", "defaultValue": 512, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "512", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 512, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassCacheHours": { "key": "overpassCacheHours", "environment": "DEZFIL_OVERPASS_CACHE_H", "label": "Overpass cache freshness", "purpose": "How long an Overpass response stays fresh.", "defaultValue": 24, "unit": "hours", "write": { "kind": "integer", "min": 1, "max": 720 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "24", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 24, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassCacheMb": { "key": "overpassCacheMb", "environment": "DEZFIL_OVERPASS_CACHE_MB", "label": "Overpass cache size", "purpose": "Cache size budget, evicted oldest first.", "defaultValue": 2048, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "queryTimeoutS": { "key": "queryTimeoutS", "environment": "DEZFIL_QUERY_TIMEOUT_S", "label": "Query time limit", "purpose": "Time for one query, whether the SQL people run, a layer, an inspection, a preview or a published map.", "defaultValue": 60, "unit": "seconds", "write": { "kind": "integer", "min": 5, "max": 600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "queryMemoryMb": { "key": "queryMemoryMb", "environment": "DEZFIL_QUERY_MEMORY_MB", "label": "Engine memory", "purpose": "Memory the engine that runs people's SQL may use, shared by every query.", "defaultValue": 2048, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "trustedMemoryMb": { "key": "trustedMemoryMb", "environment": "DEZFIL_TRUSTED_MEMORY_MB", "label": "Trusted engine memory", "purpose": "Memory the engine that imports and processes data may use; it may spill up to four times this to disk.", "defaultValue": 3072, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "3072", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 3072, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "previewRows": { "key": "previewRows", "environment": "DEZFIL_PREVIEW_ROWS", "label": "Rows shown in results", "purpose": "Row cap for result previews.", "defaultValue": 1000, "unit": "rows", "write": { "kind": "integer", "min": 10, "max": 100000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "renderCapFeatures": { "key": "renderCapFeatures", "environment": "DEZFIL_RENDER_CAP_FEATURES", "label": "Features drawn per layer", "purpose": "The most features a layer draws, and the count past which a points layer is drawn from tiles.", "defaultValue": 250000, "unit": "features", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "250000", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 250000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "renderCapBytes": { "key": "renderCapBytes", "environment": "DEZFIL_RENDER_CAP_BYTES", "label": "Bytes drawn per layer", "purpose": "The largest answer one layer may draw from, in bytes of uncompressed JSON.", "defaultValue": 134217728, "unit": "bytes", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "134217728", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 134217728, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "sliderPreviewRows": { "key": "sliderPreviewRows", "environment": "DEZFIL_SLIDER_PREVIEW_ROWS", "label": "Slider preview rows", "purpose": "Source points transferred for interactive slider previews.", "defaultValue": 50000, "unit": "rows", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "50000", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 50000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publishFreshnessS": { "key": "publishFreshnessS", "environment": "DEZFIL_PUBLISH_FRESHNESS_S", "label": "Published freshness", "purpose": "Cache window for published views.", "defaultValue": 30, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "30", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 30, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "tileBuildTimeoutS": { "key": "tileBuildTimeoutS", "environment": "DEZFIL_TILE_BUILD_TIMEOUT_S", "label": "Tile build time limit", "purpose": "Time budget for each background tile-build stage.", "defaultValue": 600, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "600", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRenderTimeoutS": { "key": "exportRenderTimeoutS", "environment": "DEZFIL_EXPORT_RENDER_TIMEOUT_S", "label": "Time limit per image", "purpose": "Time for one image, its wait for a turn included.", "defaultValue": 90, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 300 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "90", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 90, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRequestTimeoutS": { "key": "exportRequestTimeoutS", "environment": "DEZFIL_EXPORT_REQUEST_TIMEOUT_S", "label": "Image request time limit", "purpose": "Deadline for each request made by the render page.", "defaultValue": 20, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRenderConcurrency": { "key": "exportRenderConcurrency", "environment": "DEZFIL_EXPORT_RENDER_CONCURRENCY", "label": "Images at once", "purpose": "Images the server draws at the same time.", "defaultValue": 2, "unit": "renders", "write": { "kind": "integer", "min": 1, "max": 8 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "2", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 2, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "toolAttachmentMaxMb": { "key": "toolAttachmentMaxMb", "environment": "DEZFIL_TOOL_ATTACHMENT_MAX_MB", "label": "Tool attachment size", "purpose": "The largest file a tool hands back to the assistant or an agent, such as an exported image.", "defaultValue": 32, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "32", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 32, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantStepBudget": { "key": "assistantStepBudget", "environment": "DEZFIL_ASSISTANT_STEP_BUDGET", "label": "Assistant steps", "purpose": "Maximum model and tool steps per request.", "defaultValue": 20, "unit": "steps", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookTimeoutS": { "key": "assistantLookTimeoutS", "environment": "DEZFIL_ASSISTANT_LOOK_TIMEOUT_S", "label": "Map check time limit", "purpose": "Time for one of the assistant's map checks, its wait for a turn included.", "defaultValue": 30, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "30", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 30, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookRetention": { "key": "assistantLookRetention", "environment": "DEZFIL_ASSISTANT_LOOK_RETENTION", "label": "Retained map checks", "purpose": "Map check pictures kept in memory, oldest dropped first; a restart clears them.", "defaultValue": 256, "unit": "images", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "256", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 256, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookRetentionMb": { "key": "assistantLookRetentionMb", "environment": "DEZFIL_ASSISTANT_LOOK_RETENTION_MB", "label": "Map check storage", "purpose": "Memory the kept map check pictures may take.", "defaultValue": 96, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "96", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 96, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodePaceMs": { "key": "geocodePaceMs", "environment": "DEZFIL_GEOCODE_PACE_MS", "label": "Address finder pace", "purpose": "Minimum request gap; zero means no gap.", "defaultValue": 1000, "unit": "milliseconds", "write": { "kind": "integer", "min": 0, "max": 60000 }, "parsing": "non-negative", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeMatchCacheHours": { "key": "geocodeMatchCacheHours", "environment": "DEZFIL_GEOCODE_MATCH_CACHE_HOURS", "label": "Address match freshness", "purpose": "How long matched addresses are cached.", "defaultValue": 720, "unit": "hours", "write": { "kind": "integer", "min": 24, "max": 8760 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "720", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 720, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeNoMatchCacheHours": { "key": "geocodeNoMatchCacheHours", "environment": "DEZFIL_GEOCODE_NO_MATCH_CACHE_HOURS", "label": "Unmatched address freshness", "purpose": "How long no-match answers are cached.", "defaultValue": 24, "unit": "hours", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "24", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 24, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeCacheMb": { "key": "geocodeCacheMb", "environment": "DEZFIL_GEOCODE_CACHE_MB", "label": "Address cache size", "purpose": "Size budget for cached geocoding answers.", "defaultValue": 64, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "64", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 64, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochronePaceMs": { "key": "isochronePaceMs", "environment": "DEZFIL_ISOCHRONE_PACE_MS", "label": "Travel-time pace", "purpose": "Minimum routing request gap; zero means no gap.", "defaultValue": 1000, "unit": "milliseconds", "write": { "kind": "integer", "min": 0, "max": 60000 }, "parsing": "non-negative", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneRequestTimeoutS": { "key": "isochroneRequestTimeoutS", "environment": "DEZFIL_ISOCHRONE_REQUEST_TIMEOUT_S", "label": "Travel-time request limit", "purpose": "Deadline for one routing exchange.", "defaultValue": 20, "unit": "seconds", "write": { "kind": "integer", "min": 1, "max": 120 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "20", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneCacheHours": { "key": "isochroneCacheHours", "environment": "DEZFIL_ISOCHRONE_CACHE_HOURS", "label": "Travel-time cache freshness", "purpose": "How long complete routing answers are cached.", "defaultValue": 168, "unit": "hours", "write": { "kind": "integer", "min": 24, "max": 8760 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "168", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 168, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneCacheMb": { "key": "isochroneCacheMb", "environment": "DEZFIL_ISOCHRONE_CACHE_MB", "label": "Travel-time cache size", "purpose": "Size budget for cached routing answers.", "defaultValue": 64, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "64", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 64, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeRequestTimeoutS": { "key": "geocodeRequestTimeoutS", "environment": "DEZFIL_GEOCODE_REQUEST_TIMEOUT_S", "label": "Address request limit", "purpose": "Deadline for one geocoding exchange.", "defaultValue": 10, "unit": "seconds", "write": { "kind": "integer", "min": 1, "max": 120 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "10", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 10, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationTimeoutS": { "key": "operationTimeoutS", "environment": "DEZFIL_OPERATION_TIMEOUT_S", "label": "Time limit per run", "purpose": "Time for one tool run, not counting its wait for a turn.", "defaultValue": 600, "unit": "seconds", "write": { "kind": "integer", "min": 30, "max": 7200 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationConcurrency": { "key": "operationConcurrency", "environment": "DEZFIL_OPERATION_CONCURRENCY", "label": "Operation runs at once", "purpose": "Tool runs at the same time; they share the engine that runs people's SQL.", "defaultValue": 1, "unit": "runs", "write": { "kind": "integer", "min": 1, "max": 8 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationQueueMax": { "key": "operationQueueMax", "environment": "DEZFIL_OPERATION_QUEUE_MAX", "label": "Operation runs waiting", "purpose": "Tool runs that may wait for a turn.", "defaultValue": 20, "unit": "runs", "write": { "kind": "integer", "min": 1, "max": 200 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "20", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationHistoryPerSubject": { "key": "operationHistoryPerSubject", "environment": "DEZFIL_OPERATION_HISTORY_PER_SUBJECT", "label": "Run history depth", "purpose": "Runs kept in each run history, such as a workflow step's; its latest success is always kept.", "defaultValue": 20, "unit": "runs", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publicRateLimit": { "key": "publicRateLimit", "environment": "DEZFIL_PUBLIC_RATE_LIMIT", "label": "Requests per source", "purpose": "Requests one visitor may make to published maps, counted by network address across every published map.", "defaultValue": 60, "unit": "per 10 seconds", "write": { "kind": "integer", "min": 1, "max": 10000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publicTileRateLimit": { "key": "publicTileRateLimit", "environment": "DEZFIL_PUBLIC_TILE_RATE_LIMIT", "label": "Tile requests per source", "purpose": "Tile requests one visitor may make to published maps, counted by network address across every published map.", "defaultValue": 600, "unit": "per 10 seconds", "write": { "kind": "integer", "min": 1, "max": 100000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantAutoCheck": { "key": "assistantAutoCheck", "environment": "DEZFIL_ASSISTANT_AUTO_CHECK", "kind": "boolean", "label": "Automatic map check", "purpose": "Check the rendered map after an assistant turn changes it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": true, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "dataDir": { "key": "dataDir", "environment": "DEZFIL_DATA_DIR", "kind": "path", "label": "Data directory", "purpose": "The single durable directory for tables, tiles and metadata.", "defaultValue": { "rule": "working-directory/data" }, "documentedDefault": "./data; /data in the container", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "/data", "source": "environment", "locked": true, "invalidOverride": false, "storedValue": null }, "secretKey": { "key": "secretKey", "environment": "DEZFIL_SECRET_KEY", "kind": "secret", "label": "Encryption key", "purpose": "The key that encrypts saved connection passwords and service addresses.", "defaultValue": { "rule": "key-file-or-generate" }, "documentedDefault": "generated", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "status": "not-yet-present" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "trustedProxies": { "key": "trustedProxies", "environment": "DEZFIL_TRUSTED_PROXIES", "kind": "list", "label": "Trusted proxies", "purpose": "The proxies whose forwarded visitor address, host, scheme and port Dezfil accepts.", "defaultValue": [], "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "sessionCookie": { "key": "sessionCookie", "environment": "DEZFIL_SESSION_COOKIE", "kind": "text", "label": "Session cookie name", "purpose": "Browser session cookie name, derived from the listening port unless overridden.", "defaultValue": { "rule": "listening-port" }, "documentedDefault": "port-based", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "dezfil_session", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "egressAllowlist": { "key": "egressAllowlist", "environment": "DEZFIL_EGRESS_ALLOWLIST", "kind": "list", "label": "Allowed destinations", "purpose": "Hosts on a private network that the server may reach.", "defaultValue": [], "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "objectStoreCredentials": { "key": "objectStoreCredentials", "environment": "DEZFIL_OBJECT_STORE_CREDENTIALS", "kind": "boolean", "label": "Object-store credentials", "purpose": "Read cloud storage links with the server's own credentials.", "defaultValue": false, "documentedDefault": "off", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": false, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "s3Endpoint": { "key": "s3Endpoint", "environment": "DEZFIL_S3_ENDPOINT", "kind": "address", "label": "S3 endpoint", "purpose": "The S3-compatible store that s3:// links are read from without the server's credentials.", "defaultValue": { "rule": "aws-bucket-endpoint" }, "documentedDefault": "AWS", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "rule": "aws-bucket-endpoint" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassUrl": { "key": "overpassUrl", "environment": "DEZFIL_OVERPASS_URL", "kind": "address", "label": "Overpass endpoint", "purpose": "Endpoint for OpenStreetMap imports.", "defaultValue": { "set": true, "origin": "https://overpass-api.de" }, "documentedDefault": "https://overpass-api.de/api/interpreter", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": true, "origin": "https://overpass-api.de" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overtureS3Endpoint": { "key": "overtureS3Endpoint", "environment": "DEZFIL_OVERTURE_S3_ENDPOINT", "kind": "address", "label": "Overture endpoint", "purpose": "S3-compatible override for the public Overture bucket.", "defaultValue": { "set": false }, "documentedDefault": "unset, the public bucket", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "tippecanoe": { "key": "tippecanoe", "environment": "DEZFIL_TIPPECANOE", "kind": "path", "label": "Tile builder", "purpose": "The program that builds vector tiles.", "defaultValue": "tippecanoe", "documentedDefault": "tippecanoe", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "tippecanoe", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "basemapUrl": { "key": "basemapUrl", "environment": "DEZFIL_BASEMAP_URL", "kind": "address", "label": "Basemap address", "purpose": "A basemap style that Auto draws in both themes, in place of the built-in ones.", "defaultValue": { "rule": "built-in-basemap-for-theme" }, "documentedDefault": "built-in styles", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "rule": "built-in-basemap-for-theme" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "basemapAttribution": { "key": "basemapAttribution", "environment": "DEZFIL_BASEMAP_ATTRIBUTION", "kind": "text", "label": "Basemap credit", "purpose": "The credit maps show for the style DEZFIL_BASEMAP_URL names.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "satelliteUrl": { "key": "satelliteUrl", "environment": "DEZFIL_SATELLITE_URL", "kind": "address", "label": "Satellite template", "purpose": "Raster tile template enabling satellite imagery.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048, "placeholders": [ "{z}", "{x}", "{y}" ], "userInformation": "refused" }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "satelliteAttribution": { "key": "satelliteAttribution", "environment": "DEZFIL_SATELLITE_ATTRIBUTION", "kind": "text", "label": "Satellite credit", "purpose": "Credit line required by the imagery provider.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 160, "empty": "null" }, "value": null, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "geocoderUrl": { "key": "geocoderUrl", "environment": "DEZFIL_GEOCODER_URL", "kind": "address", "label": "Address finder", "purpose": "Nominatim-compatible endpoint for search and batch geocoding.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneUrl": { "key": "isochroneUrl", "environment": "DEZFIL_ISOCHRONE_URL", "kind": "address", "label": "Travel-time endpoint", "purpose": "Valhalla-compatible endpoint for travel-time areas.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "templatesCatalogueUrl": { "key": "templatesCatalogueUrl", "environment": "DEZFIL_TEMPLATES_CATALOGUE", "kind": "address", "label": "Catalogue address", "purpose": "Where the template catalogue's index is read.", "defaultValue": { "set": true, "origin": "https://github.com" }, "documentedDefault": "https://github.com/Dezfil/templates/releases/latest/download/index.json", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048, "folder": "variable" }, "value": { "set": true, "origin": "https://github.com" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "anthropicApiKey": { "key": "anthropicApiKey", "environment": "ANTHROPIC_API_KEY", "kind": "secret", "label": "Anthropic credential", "purpose": "Enables the assistant with this provider.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "openaiApiKey": { "key": "openaiApiKey", "environment": "OPENAI_API_KEY", "kind": "secret", "label": "OpenAI credential", "purpose": "Enables the assistant with this provider.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiProvider": { "key": "aiProvider", "environment": "DEZFIL_AI_PROVIDER", "kind": "choice", "label": "Assistant provider", "purpose": "Selects the provider when more than one credential is present.", "defaultValue": { "rule": "first-provider-with-key" }, "documentedDefault": "first key set", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModel": { "key": "aiModel", "environment": "DEZFIL_AI_MODEL", "kind": "text", "label": "Assistant model", "purpose": "Overrides the provider's default model.", "defaultValue": { "rule": "provider-default-model" }, "documentedDefault": "provider default", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModelsAnthropic": { "key": "aiModelsAnthropic", "environment": "DEZFIL_AI_MODELS_ANTHROPIC", "kind": "list", "label": "Anthropic model offer", "purpose": "Narrows and orders the catalogue; a set empty list offers only the default.", "defaultValue": { "rule": "effective-provider-catalogue" }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [ "claude-opus-5", "claude-fable-5", "claude-sonnet-5", "claude-haiku-4" ], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModelsOpenai": { "key": "aiModelsOpenai", "environment": "DEZFIL_AI_MODELS_OPENAI", "kind": "list", "label": "OpenAI model offer", "purpose": "Narrows and orders the catalogue; a set empty list offers only the default.", "defaultValue": { "rule": "effective-provider-catalogue" }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [ "gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-nova" ], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantOffer": { "key": "assistantOffer", "environment": "DEZFIL_ASSISTANT_OFFER", "kind": "choice", "label": "Assistant operation offer", "purpose": "With subset, the assistant starts with the page's own tools and looks up the rest; with full, it starts with every tool the page allows.", "defaultValue": "subset", "documentedDefault": "subset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "subset", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "chromiumPath": { "key": "chromiumPath", "environment": "DEZFIL_CHROMIUM_PATH", "kind": "path", "label": "Image renderer", "purpose": "The headless browser that draws image exports and map pictures.", "defaultValue": "/usr/bin/chromium", "documentedDefault": "/usr/bin/chromium", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "/usr/bin/chromium", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "instanceName": { "key": "instanceName", "label": "Instance name", "purpose": "Name beside the wordmark and in browser titles.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 80, "empty": "null" }, "value": null, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "signInMessage": { "key": "signInMessage", "label": "Sign-in message", "purpose": "Optional message on the sign-in page.", "defaultValue": "", "documentedDefault": "empty", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 280, "empty": "null" }, "value": "", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "lostPasswordContact": { "key": "lostPasswordContact", "label": "Lost-password contact", "purpose": "Contact line for password recovery; empty uses the built-in line.", "defaultValue": "", "documentedDefault": "empty", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 120, "empty": "null" }, "value": "", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "landingPage": { "key": "landingPage", "label": "Landing page", "purpose": "Preferred entry destination after sign-in.", "defaultValue": "home", "documentedDefault": "home", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "home", "projects", "maps", "workflows", "data", "sql" ] }, "value": "home", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.basemap": { "key": "newMap.basemap", "label": "Basemap", "purpose": "The basemap a new map starts on. Auto follows the theme; a basemap the instance no longer offers starts on Auto.", "defaultValue": "auto", "documentedDefault": "auto", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "auto", "dark", "light", "streets", "satellite" ] }, "value": "auto", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.latitude": { "key": "newMap.latitude", "label": "Starting latitude", "purpose": "The latitude a new map opens at.", "defaultValue": 40, "documentedDefault": "40", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": -85, "max": 85 }, "value": 40, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.longitude": { "key": "newMap.longitude", "label": "Starting longitude", "purpose": "The longitude a new map opens at.", "defaultValue": 0, "documentedDefault": "0", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": -180, "max": 180 }, "value": 0, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.zoom": { "key": "newMap.zoom", "label": "Starting zoom", "purpose": "The zoom a new map opens at.", "defaultValue": 1.3, "documentedDefault": "1.3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0, "max": 22 }, "value": 1.3, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.legendCorner": { "key": "newMap.legendCorner", "label": "Legend corner", "purpose": "Where a new map's legend sits.", "defaultValue": "bottom-left", "documentedDefault": "bottom-left", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "top-left", "top-right", "bottom-left", "bottom-right" ] }, "value": "bottom-left", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.colorCycle": { "key": "newLayer.colorCycle", "label": "Color cycle", "purpose": "The palette whose colors new layers take in turn, drawn sketches included.", "defaultValue": "uber_viz_qualitative", "documentedDefault": "uber_viz_qualitative", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "uber_viz_qualitative", "bold", "tab10", "paired", "dark2", "set3" ] }, "value": "uber_viz_qualitative", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.pointOpacity": { "key": "newLayer.pointOpacity", "label": "Point opacity", "purpose": "How opaque a new points layer is drawn, unless it is created with a style.", "defaultValue": 72, "documentedDefault": "72", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 72, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.lineOpacity": { "key": "newLayer.lineOpacity", "label": "Line opacity", "purpose": "How opaque a new lines layer is drawn, unless it is created with a style.", "defaultValue": 95, "documentedDefault": "95", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 95, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.areaOpacity": { "key": "newLayer.areaOpacity", "label": "Area opacity", "purpose": "How opaque a new areas layer is drawn, unless it is created with a style.", "defaultValue": 50, "documentedDefault": "50", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 50, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.lineWidth": { "key": "newLayer.lineWidth", "label": "Line width", "purpose": "How wide a new lines layer is drawn, unless it is created with a style.", "defaultValue": 2, "documentedDefault": "2", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0.5, "max": 50 }, "unit": "px", "value": 2, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.pointRadius": { "key": "newLayer.pointRadius", "label": "Point radius", "purpose": "How large a new layer's points are drawn, unless it is created with a style.", "defaultValue": 3, "documentedDefault": "3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0.5, "max": 100 }, "unit": "px", "value": 3, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.opens": { "key": "canvas.opens", "label": "Canvas opens", "purpose": "Whether a workflow canvas opens full screen or framed.", "defaultValue": "full", "documentedDefault": "full", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "full", "framed" ] }, "value": "full", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.minimap": { "key": "canvas.minimap", "label": "Canvas minimap", "purpose": "When a workflow canvas shows its minimap until the person chooses: auto shows it from six nodes.", "defaultValue": "auto", "documentedDefault": "auto", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "auto", "always", "never" ] }, "value": "auto", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.resultsBand": { "key": "canvas.resultsBand", "label": "Canvas results band", "purpose": "Whether a workflow canvas opens with its results band closed or open until the person chooses.", "defaultValue": "closed", "documentedDefault": "closed", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "closed", "open" ] }, "value": "closed", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "sqlConsole.textSize": { "key": "sqlConsole.textSize", "label": "SQL text size", "purpose": "The text size the SQL console's editor opens at.", "defaultValue": "12", "documentedDefault": "12", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "11", "12", "13", "14", "16" ] }, "unit": "px", "value": "12", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "sqlConsole.lineWrap": { "key": "sqlConsole.lineWrap", "label": "SQL line wrap", "purpose": "Whether the SQL console's editor wraps long lines.", "defaultValue": false, "documentedDefault": "off", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": false, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imageExport.width": { "key": "imageExport.width", "label": "Image starting width", "purpose": "The width a fresh image export card opens at.", "defaultValue": "1920", "documentedDefault": "1920", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1280", "1920", "2560" ] }, "unit": "px", "value": "1920", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imageExport.shape": { "key": "imageExport.shape", "label": "Image starting shape", "purpose": "The shape a fresh image export card opens at.", "defaultValue": "4:3", "documentedDefault": "4:3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "16:9", "4:3", "1:1" ] }, "value": "4:3", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.sessionDays": { "key": "security.sessionDays", "label": "Stay signed in for", "purpose": "How long a session lasts after its last use. A session keeps the expiry it holds; its next use renews it by this length.", "defaultValue": "30", "documentedDefault": "30", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1", "7", "30", "90" ] }, "unit": "days", "value": "30", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.linkDays": { "key": "security.linkDays", "label": "Invite and reset links last", "purpose": "How long an invitation or a password reset link stays valid. A link keeps the lifetime it was issued with.", "defaultValue": "7", "documentedDefault": "7", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1", "3", "7", "14" ] }, "unit": "days", "value": "7", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.failedPerAccount": { "key": "security.failedPerAccount", "label": "Failed sign-ins per account", "purpose": "Failed sign-ins for one account, within a fixed 15 minutes, before its next attempt pauses. Wrong current passwords on password and email changes pause those changes at the same count, counted apart. Never above the count per address.", "defaultValue": 5, "documentedDefault": "5", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 3, "max": 100 }, "unit": "per 15 minutes", "value": 5, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.failedPerAddress": { "key": "security.failedPerAddress", "label": "Failed sign-ins per address", "purpose": "Failed sign-ins from one network address, within a fixed 15 minutes, before its next attempt pauses. Never below the count per account.", "defaultValue": 20, "documentedDefault": "20", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 1000 }, "unit": "per 15 minutes", "value": 20, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.passwordMin": { "key": "security.passwordMin", "label": "Shortest password", "purpose": "The fewest characters a password set from now may have. Passwords set earlier keep signing in.", "defaultValue": 8, "documentedDefault": "8", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 8, "max": 64 }, "unit": "characters", "value": 8, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "tokens.create": { "key": "tokens.create", "label": "Who may create tokens", "purpose": "Whether every account or only admins may create API tokens. Tokens made earlier keep working.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "tokens.expiry": { "key": "tokens.expiry", "label": "New tokens expire after", "purpose": "The lifetime a new API token takes, from its creation. Tokens made earlier keep their own.", "defaultValue": "never", "documentedDefault": "never", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "never", "30d", "90d", "1y" ] }, "value": "never", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.publish": { "key": "publishing.publish", "label": "Who may publish", "purpose": "Whether every account, only admins or no one may publish a map or change a publication. Published maps stay public and can be unpublished.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins", "none" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.embedding": { "key": "publishing.embedding", "label": "Embedding on other sites", "purpose": "Which other sites may show a published page in a frame: any site, only the listed sites (at least one), or none.", "defaultValue": "any", "documentedDefault": "any", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "any", "listed", "off" ] }, "value": "any", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.embedSites": { "key": "publishing.embedSites", "label": "Listed sites", "purpose": "The sites that may show a published page in a frame while embedding is limited to listed sites; never empty while it is.", "defaultValue": [], "documentedDefault": "none", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "list", "timing": "live", "secret": false, "editable": true, "write": { "kind": "sites", "maxSites": 50 }, "value": [], "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "connections.create": { "key": "connections.create", "label": "Who may add database connections", "purpose": "Whether every account or only admins may add a database connection. Connections made earlier keep working.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imports.links": { "key": "imports.links", "label": "Who may import from links", "purpose": "Whether every account or only admins may import from web addresses and cloud storage. Link datasets keep refreshing.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.dark": { "key": "basemaps.dark", "label": "Dark", "purpose": "Whether Dark is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.light": { "key": "basemaps.light", "label": "Light", "purpose": "Whether Light is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.streets": { "key": "basemaps.streets", "label": "Streets", "purpose": "Whether Streets is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.satellite": { "key": "basemaps.satellite", "label": "Satellite", "purpose": "Whether Satellite is offered, while imagery is set up, where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.singleMapStyles": { "key": "basemaps.singleMapStyles", "label": "Style addresses on single maps", "purpose": "Whether a map may take a style address the library does not offer. Off, such an address is refused on any map, for everyone, admins included; a map that holds one keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "templates.catalogue": { "key": "templates.catalogue", "label": "Use the catalogue", "purpose": "Whether the server reads the template catalogue: its list, its pictures and its downloads. Off, it reaches the catalogue for nothing; shipped and downloaded templates still open and copy.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "port": { "key": "port", "environment": "PORT", "kind": "text", "label": "Listening port", "purpose": "Port used by the server and its internal API calls.", "defaultValue": { "rule": "runtime-port-or-request-origin" }, "documentedDefault": "3000 in the container", "scope": "platform", "readBy": "admin", "changedBy": "platform", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "3000", "source": "environment", "locked": true, "invalidOverride": false, "storedValue": null }, "extensionDir": { "key": "extensionDir", "environment": "DUCKDB_EXTENSION_DIR", "kind": "path", "label": "Engine extensions", "purpose": "Location of the baked offline extension bundle.", "defaultValue": { "rule": "engine-default-extension-directory" }, "documentedDefault": "/app/duckdb-extensions in the container", "scope": "platform", "readBy": "admin", "changedBy": "platform", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "rule": "engine-default-extension-directory" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null } }, "capacities": { "geocodeRows": 27, "isochroneOrigins": 13 }, "maxImageDimension": 4096, "version": "0.1.0", "startedAt": "2026-10-20T09:00:00.000Z", "warnings": [], "parts": { "query_engine": { "version": "1.5.4", "started": true, "extensions": [ "spatial", "h3", "json" ] }, "tile_builder": { "found": true, "version": null }, "image_renderer": { "found": false, "available": false, "imagesAtOnce": 2 }, "metadata_database": { "file": "metadata.sqlite" } }, "basemapStyles": [], "services": { "geocode": { "bytes": 0, "answers": 0, "budgetMb": 64 }, "isochrone": { "bytes": 0, "answers": 0, "budgetMb": 64 }, "overpass": { "bytes": 0, "answers": 0, "budgetMb": 2048 }, "overture": { "listed": false } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Change instance settings", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin through cookie or bearer authentication, rechecked inside the write transaction on every call. Cookie mutations require the same trusted Origin; an admin bearer token calls directly with no additional scope or approval step. Responses, including refusals, are private, no-store. Submit only editable keys; omitted keys stay unchanged and null clears a stored value. The complete body is validated against the committed configuration under one write lock. A refusal or failed commit changes nothing. Non-editable keys answer 400 invalid_request as read-only regardless of their environment. A non-empty environment variable locks an editable setting, including invalid overrides and null writes. A locked editable key answers 409 setting_locked, taking precedence over 400 invalid_request for unknown, non-editable, wrong-kind, non-whole, out-of-range, over-length or invalid-choice entries, a site list entry that is not http or https with a host and an optional port, a resulting queryTimeoutS at or above operationTimeoutS, a resulting security.failedPerAddress below security.failedPerAccount, and a resulting publishing.embedding of listed with no publishing.embedSites. Messages identify all failing known keys and their reasons, unknown keys by their entry position and a refused site by its position, without echoing arbitrary input. The sign-in counts, and embedding with its sites, are checked when a body changes either side. An existing environment timeout mismatch is reported in warnings and blocks no unrelated change. Concurrent different-key edits both land; the last accepted value wins on one key. There is no stale-write rejection or Undo. Stored changes apply live to new work; admitted work keeps its budget. Lowered concurrency cancels nothing, increased concurrency wakes waiters after commit, and lowered queue limits keep accepted waiters. Public limits apply against the existing window count. Environment changes need a restart. Returns the same configuration as the read, with the same secret and address disclosure rules. No secret is accepted. The four service addresses (geocoderUrl, isochroneUrl, overpassUrl, s3Endpoint), the satellite imagery's tile template (satelliteUrl) and the template catalogue's address (templatesCatalogueUrl) are write-only: each is stored encrypted and read back as its scheme and host alone; a refusal names the key and never repeats the address. The catalogue's address is http or https here: a folder on the server is named by DEZFIL_TEMPLATES_CATALOGUE alone. The template must also hold {z}, {x} and {y}, a refusal naming the ones missing, and carry no user name or password, refused before any lookup with a sentence saying the imagery is not drawn from such an address and the key belongs in the path or the query. Before the write, an address is also refused (400 invalid_request, with the egress policy's own sentence) when that policy would refuse a request to it now, a template with each placeholder filled with a digit: a literal in loopback, private, carrier-grade, link-local or metadata, unique-local, unspecified, multicast or reserved space, mapped and NAT64 forms included, or a name all of whose addresses resolve there, unless DEZFIL_EGRESS_ALLOWLIST names it. A name that does not resolve at save is kept; every request to the address is checked again. The embedded assistant asks for confirmation before calling on pages admitting writes; SQL and workflow assistants refuse this update. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "update_instance_settings", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "settings", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Change instance settings?", "consequence": "These settings apply to the whole instance. Limits affect new work; admitted work keeps its budget. There is no Undo.", "subject": { "path": null, "argument": "", "name": "" } }, "x-display": { "verb": "Changed instance settings" }, "x-confirm": true, "requestBody": { "required": true, "x-byte-limit": 65536, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceSettingsPatch" }, "examples": { "previewRows": { "summary": "Show 2,000 rows in results", "description": "Needs an admin's token. previewRows is the key of Rows shown in results; the answer is every setting, as reading them answers, with the new value stored.", "value": { "previewRows": 2000 } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceSettings" }, "examples": { "previewRows": { "summary": "Show 2,000 rows in results", "description": "Needs an admin's token. previewRows is the key of Rows shown in results; the answer is every setting, as reading them answers, with the new value stored.", "value": { "settings": { "uploadMaxMb": { "key": "uploadMaxMb", "environment": "DEZFIL_UPLOAD_MAX_MB", "label": "Largest upload", "purpose": "Size cap for one uploaded file.", "defaultValue": 5120, "unit": "MB", "write": { "kind": "integer", "min": 1, "max": 102400 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "5120", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 5120, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "dataProcessingTimeoutS": { "key": "dataProcessingTimeoutS", "environment": "DEZFIL_DATA_PROCESSING_TIMEOUT_S", "label": "Data processing time limit", "purpose": "Time to receive one upload, and, counted apart, time for one data processing job, such as an import.", "defaultValue": 3600, "unit": "seconds", "write": { "kind": "integer", "min": 60, "max": 21600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "3600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 3600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "remoteMaxMb": { "key": "remoteMaxMb", "environment": "DEZFIL_REMOTE_MAX_MB", "label": "Largest link import", "purpose": "Size cap for a URL or object-store import.", "defaultValue": 2048, "unit": "MB", "write": { "kind": "integer", "min": 1, "max": 102400 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "remoteTimeoutS": { "key": "remoteTimeoutS", "environment": "DEZFIL_REMOTE_TIMEOUT_S", "label": "Link import time limit", "purpose": "Time for one link import's whole download.", "defaultValue": 300, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 3600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "300", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 300, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overtureMaxKm2": { "key": "overtureMaxKm2", "environment": "DEZFIL_OVERTURE_MAX_KM2", "label": "Overture area", "purpose": "The largest area one Overture import of places may cover; other themes may cover more or less, by how dense they are.", "defaultValue": 25000, "unit": "km²", "write": { "kind": "integer", "min": 1, "max": 1000000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "25000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 25000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "osmMaxKm2": { "key": "osmMaxKm2", "environment": "DEZFIL_OSM_MAX_KM2", "label": "OpenStreetMap area", "purpose": "The largest area one OpenStreetMap import may cover.", "defaultValue": 10000, "unit": "km²", "write": { "kind": "integer", "min": 1, "max": 1000000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "10000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 10000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassTimeoutS": { "key": "overpassTimeoutS", "environment": "DEZFIL_OVERPASS_TIMEOUT_S", "label": "Overpass time limit", "purpose": "Time budget sent with every Overpass query.", "defaultValue": 60, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 900 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassMaxsizeMb": { "key": "overpassMaxsizeMb", "environment": "DEZFIL_OVERPASS_MAXSIZE_MB", "label": "Overpass response budget", "purpose": "Response budget sent to Overpass; twice this aborts locally.", "defaultValue": 512, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "512", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 512, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassCacheHours": { "key": "overpassCacheHours", "environment": "DEZFIL_OVERPASS_CACHE_H", "label": "Overpass cache freshness", "purpose": "How long an Overpass response stays fresh.", "defaultValue": 24, "unit": "hours", "write": { "kind": "integer", "min": 1, "max": 720 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "24", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 24, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassCacheMb": { "key": "overpassCacheMb", "environment": "DEZFIL_OVERPASS_CACHE_MB", "label": "Overpass cache size", "purpose": "Cache size budget, evicted oldest first.", "defaultValue": 2048, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "queryTimeoutS": { "key": "queryTimeoutS", "environment": "DEZFIL_QUERY_TIMEOUT_S", "label": "Query time limit", "purpose": "Time for one query, whether the SQL people run, a layer, an inspection, a preview or a published map.", "defaultValue": 60, "unit": "seconds", "write": { "kind": "integer", "min": 5, "max": 600 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "queryMemoryMb": { "key": "queryMemoryMb", "environment": "DEZFIL_QUERY_MEMORY_MB", "label": "Engine memory", "purpose": "Memory the engine that runs people's SQL may use, shared by every query.", "defaultValue": 2048, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "2048", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 2048, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "trustedMemoryMb": { "key": "trustedMemoryMb", "environment": "DEZFIL_TRUSTED_MEMORY_MB", "label": "Trusted engine memory", "purpose": "Memory the engine that imports and processes data may use; it may spill up to four times this to disk.", "defaultValue": 3072, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "3072", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 3072, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "previewRows": { "key": "previewRows", "environment": "DEZFIL_PREVIEW_ROWS", "label": "Rows shown in results", "purpose": "Row cap for result previews.", "defaultValue": 1000, "unit": "rows", "write": { "kind": "integer", "min": 10, "max": 100000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 2000, "source": "stored", "locked": false, "invalidOverride": false, "storedValue": 2000 }, "renderCapFeatures": { "key": "renderCapFeatures", "environment": "DEZFIL_RENDER_CAP_FEATURES", "label": "Features drawn per layer", "purpose": "The most features a layer draws, and the count past which a points layer is drawn from tiles.", "defaultValue": 250000, "unit": "features", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "250000", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 250000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "renderCapBytes": { "key": "renderCapBytes", "environment": "DEZFIL_RENDER_CAP_BYTES", "label": "Bytes drawn per layer", "purpose": "The largest answer one layer may draw from, in bytes of uncompressed JSON.", "defaultValue": 134217728, "unit": "bytes", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "134217728", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 134217728, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "sliderPreviewRows": { "key": "sliderPreviewRows", "environment": "DEZFIL_SLIDER_PREVIEW_ROWS", "label": "Slider preview rows", "purpose": "Source points transferred for interactive slider previews.", "defaultValue": 50000, "unit": "rows", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "50000", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 50000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publishFreshnessS": { "key": "publishFreshnessS", "environment": "DEZFIL_PUBLISH_FRESHNESS_S", "label": "Published freshness", "purpose": "Cache window for published views.", "defaultValue": 30, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "30", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 30, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "tileBuildTimeoutS": { "key": "tileBuildTimeoutS", "environment": "DEZFIL_TILE_BUILD_TIMEOUT_S", "label": "Tile build time limit", "purpose": "Time budget for each background tile-build stage.", "defaultValue": 600, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "600", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRenderTimeoutS": { "key": "exportRenderTimeoutS", "environment": "DEZFIL_EXPORT_RENDER_TIMEOUT_S", "label": "Time limit per image", "purpose": "Time for one image, its wait for a turn included.", "defaultValue": 90, "unit": "seconds", "write": { "kind": "integer", "min": 10, "max": 300 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "90", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 90, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRequestTimeoutS": { "key": "exportRequestTimeoutS", "environment": "DEZFIL_EXPORT_REQUEST_TIMEOUT_S", "label": "Image request time limit", "purpose": "Deadline for each request made by the render page.", "defaultValue": 20, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "exportRenderConcurrency": { "key": "exportRenderConcurrency", "environment": "DEZFIL_EXPORT_RENDER_CONCURRENCY", "label": "Images at once", "purpose": "Images the server draws at the same time.", "defaultValue": 2, "unit": "renders", "write": { "kind": "integer", "min": 1, "max": 8 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "2", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 2, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "toolAttachmentMaxMb": { "key": "toolAttachmentMaxMb", "environment": "DEZFIL_TOOL_ATTACHMENT_MAX_MB", "label": "Tool attachment size", "purpose": "The largest file a tool hands back to the assistant or an agent, such as an exported image.", "defaultValue": 32, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "32", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 32, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantStepBudget": { "key": "assistantStepBudget", "environment": "DEZFIL_ASSISTANT_STEP_BUDGET", "label": "Assistant steps", "purpose": "Maximum model and tool steps per request.", "defaultValue": 20, "unit": "steps", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookTimeoutS": { "key": "assistantLookTimeoutS", "environment": "DEZFIL_ASSISTANT_LOOK_TIMEOUT_S", "label": "Map check time limit", "purpose": "Time for one of the assistant's map checks, its wait for a turn included.", "defaultValue": 30, "unit": "seconds", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "30", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 30, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookRetention": { "key": "assistantLookRetention", "environment": "DEZFIL_ASSISTANT_LOOK_RETENTION", "label": "Retained map checks", "purpose": "Map check pictures kept in memory, oldest dropped first; a restart clears them.", "defaultValue": 256, "unit": "images", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "256", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 256, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantLookRetentionMb": { "key": "assistantLookRetentionMb", "environment": "DEZFIL_ASSISTANT_LOOK_RETENTION_MB", "label": "Map check storage", "purpose": "Memory the kept map check pictures may take.", "defaultValue": 96, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "96", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 96, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodePaceMs": { "key": "geocodePaceMs", "environment": "DEZFIL_GEOCODE_PACE_MS", "label": "Address finder pace", "purpose": "Minimum request gap; zero means no gap.", "defaultValue": 1000, "unit": "milliseconds", "write": { "kind": "integer", "min": 0, "max": 60000 }, "parsing": "non-negative", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeMatchCacheHours": { "key": "geocodeMatchCacheHours", "environment": "DEZFIL_GEOCODE_MATCH_CACHE_HOURS", "label": "Address match freshness", "purpose": "How long matched addresses are cached.", "defaultValue": 720, "unit": "hours", "write": { "kind": "integer", "min": 24, "max": 8760 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "720", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 720, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeNoMatchCacheHours": { "key": "geocodeNoMatchCacheHours", "environment": "DEZFIL_GEOCODE_NO_MATCH_CACHE_HOURS", "label": "Unmatched address freshness", "purpose": "How long no-match answers are cached.", "defaultValue": 24, "unit": "hours", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "24", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 24, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeCacheMb": { "key": "geocodeCacheMb", "environment": "DEZFIL_GEOCODE_CACHE_MB", "label": "Address cache size", "purpose": "Size budget for cached geocoding answers.", "defaultValue": 64, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "64", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 64, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochronePaceMs": { "key": "isochronePaceMs", "environment": "DEZFIL_ISOCHRONE_PACE_MS", "label": "Travel-time pace", "purpose": "Minimum routing request gap; zero means no gap.", "defaultValue": 1000, "unit": "milliseconds", "write": { "kind": "integer", "min": 0, "max": 60000 }, "parsing": "non-negative", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1000", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1000, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneRequestTimeoutS": { "key": "isochroneRequestTimeoutS", "environment": "DEZFIL_ISOCHRONE_REQUEST_TIMEOUT_S", "label": "Travel-time request limit", "purpose": "Deadline for one routing exchange.", "defaultValue": 20, "unit": "seconds", "write": { "kind": "integer", "min": 1, "max": 120 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "20", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneCacheHours": { "key": "isochroneCacheHours", "environment": "DEZFIL_ISOCHRONE_CACHE_HOURS", "label": "Travel-time cache freshness", "purpose": "How long complete routing answers are cached.", "defaultValue": 168, "unit": "hours", "write": { "kind": "integer", "min": 24, "max": 8760 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "168", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 168, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneCacheMb": { "key": "isochroneCacheMb", "environment": "DEZFIL_ISOCHRONE_CACHE_MB", "label": "Travel-time cache size", "purpose": "Size budget for cached routing answers.", "defaultValue": 64, "unit": "MB", "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "64", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 64, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "geocodeRequestTimeoutS": { "key": "geocodeRequestTimeoutS", "environment": "DEZFIL_GEOCODE_REQUEST_TIMEOUT_S", "label": "Address request limit", "purpose": "Deadline for one geocoding exchange.", "defaultValue": 10, "unit": "seconds", "write": { "kind": "integer", "min": 1, "max": 120 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "10", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 10, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationTimeoutS": { "key": "operationTimeoutS", "environment": "DEZFIL_OPERATION_TIMEOUT_S", "label": "Time limit per run", "purpose": "Time for one tool run, not counting its wait for a turn.", "defaultValue": 600, "unit": "seconds", "write": { "kind": "integer", "min": 30, "max": 7200 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationConcurrency": { "key": "operationConcurrency", "environment": "DEZFIL_OPERATION_CONCURRENCY", "label": "Operation runs at once", "purpose": "Tool runs at the same time; they share the engine that runs people's SQL.", "defaultValue": 1, "unit": "runs", "write": { "kind": "integer", "min": 1, "max": 8 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "1", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 1, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationQueueMax": { "key": "operationQueueMax", "environment": "DEZFIL_OPERATION_QUEUE_MAX", "label": "Operation runs waiting", "purpose": "Tool runs that may wait for a turn.", "defaultValue": 20, "unit": "runs", "write": { "kind": "integer", "min": 1, "max": 200 }, "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "20", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "operationHistoryPerSubject": { "key": "operationHistoryPerSubject", "environment": "DEZFIL_OPERATION_HISTORY_PER_SUBJECT", "label": "Run history depth", "purpose": "Runs kept in each run history, such as a workflow step's; its latest success is always kept.", "defaultValue": 20, "unit": "runs", "parsing": "positive-integer", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "documentedDefault": "20", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": 20, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publicRateLimit": { "key": "publicRateLimit", "environment": "DEZFIL_PUBLIC_RATE_LIMIT", "label": "Requests per source", "purpose": "Requests one visitor may make to published maps, counted by network address across every published map.", "defaultValue": 60, "unit": "per 10 seconds", "write": { "kind": "integer", "min": 1, "max": 10000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "60", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 60, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "publicTileRateLimit": { "key": "publicTileRateLimit", "environment": "DEZFIL_PUBLIC_TILE_RATE_LIMIT", "label": "Tile requests per source", "purpose": "Tile requests one visitor may make to published maps, counted by network address across every published map.", "defaultValue": 600, "unit": "per 10 seconds", "write": { "kind": "integer", "min": 1, "max": 100000 }, "parsing": "positive", "kind": "number", "scope": "instance", "readBy": "admin", "changedBy": "admin", "documentedDefault": "600", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "value": 600, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantAutoCheck": { "key": "assistantAutoCheck", "environment": "DEZFIL_ASSISTANT_AUTO_CHECK", "kind": "boolean", "label": "Automatic map check", "purpose": "Check the rendered map after an assistant turn changes it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": true, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "dataDir": { "key": "dataDir", "environment": "DEZFIL_DATA_DIR", "kind": "path", "label": "Data directory", "purpose": "The single durable directory for tables, tiles and metadata.", "defaultValue": { "rule": "working-directory/data" }, "documentedDefault": "./data; /data in the container", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "/data", "source": "environment", "locked": true, "invalidOverride": false, "storedValue": null }, "secretKey": { "key": "secretKey", "environment": "DEZFIL_SECRET_KEY", "kind": "secret", "label": "Encryption key", "purpose": "The key that encrypts saved connection passwords and service addresses.", "defaultValue": { "rule": "key-file-or-generate" }, "documentedDefault": "generated", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "status": "not-yet-present" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "trustedProxies": { "key": "trustedProxies", "environment": "DEZFIL_TRUSTED_PROXIES", "kind": "list", "label": "Trusted proxies", "purpose": "The proxies whose forwarded visitor address, host, scheme and port Dezfil accepts.", "defaultValue": [], "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "sessionCookie": { "key": "sessionCookie", "environment": "DEZFIL_SESSION_COOKIE", "kind": "text", "label": "Session cookie name", "purpose": "Browser session cookie name, derived from the listening port unless overridden.", "defaultValue": { "rule": "listening-port" }, "documentedDefault": "port-based", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "dezfil_session", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "egressAllowlist": { "key": "egressAllowlist", "environment": "DEZFIL_EGRESS_ALLOWLIST", "kind": "list", "label": "Allowed destinations", "purpose": "Hosts on a private network that the server may reach.", "defaultValue": [], "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "objectStoreCredentials": { "key": "objectStoreCredentials", "environment": "DEZFIL_OBJECT_STORE_CREDENTIALS", "kind": "boolean", "label": "Object-store credentials", "purpose": "Read cloud storage links with the server's own credentials.", "defaultValue": false, "documentedDefault": "off", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": false, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "s3Endpoint": { "key": "s3Endpoint", "environment": "DEZFIL_S3_ENDPOINT", "kind": "address", "label": "S3 endpoint", "purpose": "The S3-compatible store that s3:// links are read from without the server's credentials.", "defaultValue": { "rule": "aws-bucket-endpoint" }, "documentedDefault": "AWS", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "rule": "aws-bucket-endpoint" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overpassUrl": { "key": "overpassUrl", "environment": "DEZFIL_OVERPASS_URL", "kind": "address", "label": "Overpass endpoint", "purpose": "Endpoint for OpenStreetMap imports.", "defaultValue": { "set": true, "origin": "https://overpass-api.de" }, "documentedDefault": "https://overpass-api.de/api/interpreter", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": true, "origin": "https://overpass-api.de" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "overtureS3Endpoint": { "key": "overtureS3Endpoint", "environment": "DEZFIL_OVERTURE_S3_ENDPOINT", "kind": "address", "label": "Overture endpoint", "purpose": "S3-compatible override for the public Overture bucket.", "defaultValue": { "set": false }, "documentedDefault": "unset, the public bucket", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "tippecanoe": { "key": "tippecanoe", "environment": "DEZFIL_TIPPECANOE", "kind": "path", "label": "Tile builder", "purpose": "The program that builds vector tiles.", "defaultValue": "tippecanoe", "documentedDefault": "tippecanoe", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "tippecanoe", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "basemapUrl": { "key": "basemapUrl", "environment": "DEZFIL_BASEMAP_URL", "kind": "address", "label": "Basemap address", "purpose": "A basemap style that Auto draws in both themes, in place of the built-in ones.", "defaultValue": { "rule": "built-in-basemap-for-theme" }, "documentedDefault": "built-in styles", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "rule": "built-in-basemap-for-theme" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "basemapAttribution": { "key": "basemapAttribution", "environment": "DEZFIL_BASEMAP_ATTRIBUTION", "kind": "text", "label": "Basemap credit", "purpose": "The credit maps show for the style DEZFIL_BASEMAP_URL names.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "satelliteUrl": { "key": "satelliteUrl", "environment": "DEZFIL_SATELLITE_URL", "kind": "address", "label": "Satellite template", "purpose": "Raster tile template enabling satellite imagery.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048, "placeholders": [ "{z}", "{x}", "{y}" ], "userInformation": "refused" }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "satelliteAttribution": { "key": "satelliteAttribution", "environment": "DEZFIL_SATELLITE_ATTRIBUTION", "kind": "text", "label": "Satellite credit", "purpose": "Credit line required by the imagery provider.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 160, "empty": "null" }, "value": null, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "geocoderUrl": { "key": "geocoderUrl", "environment": "DEZFIL_GEOCODER_URL", "kind": "address", "label": "Address finder", "purpose": "Nominatim-compatible endpoint for search and batch geocoding.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "isochroneUrl": { "key": "isochroneUrl", "environment": "DEZFIL_ISOCHRONE_URL", "kind": "address", "label": "Travel-time endpoint", "purpose": "Valhalla-compatible endpoint for travel-time areas.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048 }, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "templatesCatalogueUrl": { "key": "templatesCatalogueUrl", "environment": "DEZFIL_TEMPLATES_CATALOGUE", "kind": "address", "label": "Catalogue address", "purpose": "Where the template catalogue's index is read.", "defaultValue": { "set": true, "origin": "https://github.com" }, "documentedDefault": "https://github.com/Dezfil/templates/releases/latest/download/index.json", "scope": "instance", "readBy": "admin", "changedBy": "admin", "environmentTiming": "restart", "timing": "live", "secret": false, "editable": true, "write": { "kind": "address", "maxLength": 2048, "folder": "variable" }, "value": { "set": true, "origin": "https://github.com" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "anthropicApiKey": { "key": "anthropicApiKey", "environment": "ANTHROPIC_API_KEY", "kind": "secret", "label": "Anthropic credential", "purpose": "Enables the assistant with this provider.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "openaiApiKey": { "key": "openaiApiKey", "environment": "OPENAI_API_KEY", "kind": "secret", "label": "OpenAI credential", "purpose": "Enables the assistant with this provider.", "defaultValue": { "set": false }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": true, "editable": false, "value": { "set": false }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiProvider": { "key": "aiProvider", "environment": "DEZFIL_AI_PROVIDER", "kind": "choice", "label": "Assistant provider", "purpose": "Selects the provider when more than one credential is present.", "defaultValue": { "rule": "first-provider-with-key" }, "documentedDefault": "first key set", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModel": { "key": "aiModel", "environment": "DEZFIL_AI_MODEL", "kind": "text", "label": "Assistant model", "purpose": "Overrides the provider's default model.", "defaultValue": { "rule": "provider-default-model" }, "documentedDefault": "provider default", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": null, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModelsAnthropic": { "key": "aiModelsAnthropic", "environment": "DEZFIL_AI_MODELS_ANTHROPIC", "kind": "list", "label": "Anthropic model offer", "purpose": "Narrows and orders the catalogue; a set empty list offers only the default.", "defaultValue": { "rule": "effective-provider-catalogue" }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [ "claude-opus-5", "claude-fable-5", "claude-sonnet-5", "claude-haiku-4" ], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "aiModelsOpenai": { "key": "aiModelsOpenai", "environment": "DEZFIL_AI_MODELS_OPENAI", "kind": "list", "label": "OpenAI model offer", "purpose": "Narrows and orders the catalogue; a set empty list offers only the default.", "defaultValue": { "rule": "effective-provider-catalogue" }, "documentedDefault": "unset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": [ "gpt-6-astra", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-nova" ], "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "assistantOffer": { "key": "assistantOffer", "environment": "DEZFIL_ASSISTANT_OFFER", "kind": "choice", "label": "Assistant operation offer", "purpose": "With subset, the assistant starts with the page's own tools and looks up the rest; with full, it starts with every tool the page allows.", "defaultValue": "subset", "documentedDefault": "subset", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "subset", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "chromiumPath": { "key": "chromiumPath", "environment": "DEZFIL_CHROMIUM_PATH", "kind": "path", "label": "Image renderer", "purpose": "The headless browser that draws image exports and map pictures.", "defaultValue": "/usr/bin/chromium", "documentedDefault": "/usr/bin/chromium", "scope": "instance", "readBy": "admin", "changedBy": "deployment", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "/usr/bin/chromium", "source": "default", "locked": false, "invalidOverride": false, "storedValue": null }, "instanceName": { "key": "instanceName", "label": "Instance name", "purpose": "Name beside the wordmark and in browser titles.", "defaultValue": null, "documentedDefault": "unset", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 80, "empty": "null" }, "value": null, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "signInMessage": { "key": "signInMessage", "label": "Sign-in message", "purpose": "Optional message on the sign-in page.", "defaultValue": "", "documentedDefault": "empty", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 280, "empty": "null" }, "value": "", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "lostPasswordContact": { "key": "lostPasswordContact", "label": "Lost-password contact", "purpose": "Contact line for password recovery; empty uses the built-in line.", "defaultValue": "", "documentedDefault": "empty", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "text", "timing": "live", "secret": false, "editable": true, "write": { "kind": "text", "maxLength": 120, "empty": "null" }, "value": "", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "landingPage": { "key": "landingPage", "label": "Landing page", "purpose": "Preferred entry destination after sign-in.", "defaultValue": "home", "documentedDefault": "home", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "home", "projects", "maps", "workflows", "data", "sql" ] }, "value": "home", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.basemap": { "key": "newMap.basemap", "label": "Basemap", "purpose": "The basemap a new map starts on. Auto follows the theme; a basemap the instance no longer offers starts on Auto.", "defaultValue": "auto", "documentedDefault": "auto", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "auto", "dark", "light", "streets", "satellite" ] }, "value": "auto", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.latitude": { "key": "newMap.latitude", "label": "Starting latitude", "purpose": "The latitude a new map opens at.", "defaultValue": 40, "documentedDefault": "40", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": -85, "max": 85 }, "value": 40, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.longitude": { "key": "newMap.longitude", "label": "Starting longitude", "purpose": "The longitude a new map opens at.", "defaultValue": 0, "documentedDefault": "0", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": -180, "max": 180 }, "value": 0, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.zoom": { "key": "newMap.zoom", "label": "Starting zoom", "purpose": "The zoom a new map opens at.", "defaultValue": 1.3, "documentedDefault": "1.3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0, "max": 22 }, "value": 1.3, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newMap.legendCorner": { "key": "newMap.legendCorner", "label": "Legend corner", "purpose": "Where a new map's legend sits.", "defaultValue": "bottom-left", "documentedDefault": "bottom-left", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "top-left", "top-right", "bottom-left", "bottom-right" ] }, "value": "bottom-left", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.colorCycle": { "key": "newLayer.colorCycle", "label": "Color cycle", "purpose": "The palette whose colors new layers take in turn, drawn sketches included.", "defaultValue": "uber_viz_qualitative", "documentedDefault": "uber_viz_qualitative", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "uber_viz_qualitative", "bold", "tab10", "paired", "dark2", "set3" ] }, "value": "uber_viz_qualitative", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.pointOpacity": { "key": "newLayer.pointOpacity", "label": "Point opacity", "purpose": "How opaque a new points layer is drawn, unless it is created with a style.", "defaultValue": 72, "documentedDefault": "72", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 72, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.lineOpacity": { "key": "newLayer.lineOpacity", "label": "Line opacity", "purpose": "How opaque a new lines layer is drawn, unless it is created with a style.", "defaultValue": 95, "documentedDefault": "95", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 95, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.areaOpacity": { "key": "newLayer.areaOpacity", "label": "Area opacity", "purpose": "How opaque a new areas layer is drawn, unless it is created with a style.", "defaultValue": 50, "documentedDefault": "50", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 100 }, "unit": "%", "value": 50, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.lineWidth": { "key": "newLayer.lineWidth", "label": "Line width", "purpose": "How wide a new lines layer is drawn, unless it is created with a style.", "defaultValue": 2, "documentedDefault": "2", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0.5, "max": 50 }, "unit": "px", "value": 2, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "newLayer.pointRadius": { "key": "newLayer.pointRadius", "label": "Point radius", "purpose": "How large a new layer's points are drawn, unless it is created with a style.", "defaultValue": 3, "documentedDefault": "3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "decimal", "min": 0.5, "max": 100 }, "unit": "px", "value": 3, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.opens": { "key": "canvas.opens", "label": "Canvas opens", "purpose": "Whether a workflow canvas opens full screen or framed.", "defaultValue": "full", "documentedDefault": "full", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "full", "framed" ] }, "value": "full", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.minimap": { "key": "canvas.minimap", "label": "Canvas minimap", "purpose": "When a workflow canvas shows its minimap until the person chooses: auto shows it from six nodes.", "defaultValue": "auto", "documentedDefault": "auto", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "auto", "always", "never" ] }, "value": "auto", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "canvas.resultsBand": { "key": "canvas.resultsBand", "label": "Canvas results band", "purpose": "Whether a workflow canvas opens with its results band closed or open until the person chooses.", "defaultValue": "closed", "documentedDefault": "closed", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "closed", "open" ] }, "value": "closed", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "sqlConsole.textSize": { "key": "sqlConsole.textSize", "label": "SQL text size", "purpose": "The text size the SQL console's editor opens at.", "defaultValue": "12", "documentedDefault": "12", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "11", "12", "13", "14", "16" ] }, "unit": "px", "value": "12", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "sqlConsole.lineWrap": { "key": "sqlConsole.lineWrap", "label": "SQL line wrap", "purpose": "Whether the SQL console's editor wraps long lines.", "defaultValue": false, "documentedDefault": "off", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": false, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imageExport.width": { "key": "imageExport.width", "label": "Image starting width", "purpose": "The width a fresh image export card opens at.", "defaultValue": "1920", "documentedDefault": "1920", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1280", "1920", "2560" ] }, "unit": "px", "value": "1920", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imageExport.shape": { "key": "imageExport.shape", "label": "Image starting shape", "purpose": "The shape a fresh image export card opens at.", "defaultValue": "4:3", "documentedDefault": "4:3", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "16:9", "4:3", "1:1" ] }, "value": "4:3", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.sessionDays": { "key": "security.sessionDays", "label": "Stay signed in for", "purpose": "How long a session lasts after its last use. A session keeps the expiry it holds; its next use renews it by this length.", "defaultValue": "30", "documentedDefault": "30", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1", "7", "30", "90" ] }, "unit": "days", "value": "30", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.linkDays": { "key": "security.linkDays", "label": "Invite and reset links last", "purpose": "How long an invitation or a password reset link stays valid. A link keeps the lifetime it was issued with.", "defaultValue": "7", "documentedDefault": "7", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "1", "3", "7", "14" ] }, "unit": "days", "value": "7", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.failedPerAccount": { "key": "security.failedPerAccount", "label": "Failed sign-ins per account", "purpose": "Failed sign-ins for one account, within a fixed 15 minutes, before its next attempt pauses. Wrong current passwords on password and email changes pause those changes at the same count, counted apart. Never above the count per address.", "defaultValue": 5, "documentedDefault": "5", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 3, "max": 100 }, "unit": "per 15 minutes", "value": 5, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.failedPerAddress": { "key": "security.failedPerAddress", "label": "Failed sign-ins per address", "purpose": "Failed sign-ins from one network address, within a fixed 15 minutes, before its next attempt pauses. Never below the count per account.", "defaultValue": 20, "documentedDefault": "20", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 10, "max": 1000 }, "unit": "per 15 minutes", "value": 20, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "security.passwordMin": { "key": "security.passwordMin", "label": "Shortest password", "purpose": "The fewest characters a password set from now may have. Passwords set earlier keep signing in.", "defaultValue": 8, "documentedDefault": "8", "scope": "instance", "readBy": "public", "changedBy": "admin", "kind": "number", "timing": "live", "secret": false, "editable": true, "write": { "kind": "integer", "min": 8, "max": 64 }, "unit": "characters", "value": 8, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "tokens.create": { "key": "tokens.create", "label": "Who may create tokens", "purpose": "Whether every account or only admins may create API tokens. Tokens made earlier keep working.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "tokens.expiry": { "key": "tokens.expiry", "label": "New tokens expire after", "purpose": "The lifetime a new API token takes, from its creation. Tokens made earlier keep their own.", "defaultValue": "never", "documentedDefault": "never", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "never", "30d", "90d", "1y" ] }, "value": "never", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.publish": { "key": "publishing.publish", "label": "Who may publish", "purpose": "Whether every account, only admins or no one may publish a map or change a publication. Published maps stay public and can be unpublished.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins", "none" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.embedding": { "key": "publishing.embedding", "label": "Embedding on other sites", "purpose": "Which other sites may show a published page in a frame: any site, only the listed sites (at least one), or none.", "defaultValue": "any", "documentedDefault": "any", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "any", "listed", "off" ] }, "value": "any", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "publishing.embedSites": { "key": "publishing.embedSites", "label": "Listed sites", "purpose": "The sites that may show a published page in a frame while embedding is limited to listed sites; never empty while it is.", "defaultValue": [], "documentedDefault": "none", "scope": "instance", "readBy": "admin", "changedBy": "admin", "kind": "list", "timing": "live", "secret": false, "editable": true, "write": { "kind": "sites", "maxSites": 50 }, "value": [], "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "connections.create": { "key": "connections.create", "label": "Who may add database connections", "purpose": "Whether every account or only admins may add a database connection. Connections made earlier keep working.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "imports.links": { "key": "imports.links", "label": "Who may import from links", "purpose": "Whether every account or only admins may import from web addresses and cloud storage. Link datasets keep refreshing.", "defaultValue": "everyone", "documentedDefault": "everyone", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "choice", "timing": "live", "secret": false, "editable": true, "write": { "kind": "choice", "values": [ "everyone", "admins" ] }, "value": "everyone", "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.dark": { "key": "basemaps.dark", "label": "Dark", "purpose": "Whether Dark is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.light": { "key": "basemaps.light", "label": "Light", "purpose": "Whether Light is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.streets": { "key": "basemaps.streets", "label": "Streets", "purpose": "Whether Streets is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.satellite": { "key": "basemaps.satellite", "label": "Satellite", "purpose": "Whether Satellite is offered, while imagery is set up, where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "basemaps.singleMapStyles": { "key": "basemaps.singleMapStyles", "label": "Style addresses on single maps", "purpose": "Whether a map may take a style address the library does not offer. Off, such an address is refused on any map, for everyone, admins included; a map that holds one keeps it.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "templates.catalogue": { "key": "templates.catalogue", "label": "Use the catalogue", "purpose": "Whether the server reads the template catalogue: its list, its pictures and its downloads. Off, it reaches the catalogue for nothing; shipped and downloaded templates still open and copy.", "defaultValue": true, "documentedDefault": "on", "scope": "instance", "readBy": "signed-in", "changedBy": "admin", "kind": "boolean", "timing": "live", "secret": false, "editable": true, "write": { "kind": "switch" }, "value": true, "source": "default", "storedValue": null, "locked": false, "invalidOverride": false }, "port": { "key": "port", "environment": "PORT", "kind": "text", "label": "Listening port", "purpose": "Port used by the server and its internal API calls.", "defaultValue": { "rule": "runtime-port-or-request-origin" }, "documentedDefault": "3000 in the container", "scope": "platform", "readBy": "admin", "changedBy": "platform", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": "3000", "source": "environment", "locked": true, "invalidOverride": false, "storedValue": null }, "extensionDir": { "key": "extensionDir", "environment": "DUCKDB_EXTENSION_DIR", "kind": "path", "label": "Engine extensions", "purpose": "Location of the baked offline extension bundle.", "defaultValue": { "rule": "engine-default-extension-directory" }, "documentedDefault": "/app/duckdb-extensions in the container", "scope": "platform", "readBy": "admin", "changedBy": "platform", "environmentTiming": "restart", "timing": "next-start", "secret": false, "editable": false, "value": { "rule": "engine-default-extension-directory" }, "source": "default", "locked": false, "invalidOverride": false, "storedValue": null } }, "capacities": { "geocodeRows": 27, "isochroneOrigins": 13 }, "maxImageDimension": 4096, "version": "0.1.0", "startedAt": "2026-10-20T09:00:00.000Z", "warnings": [], "parts": { "query_engine": { "version": "1.5.4", "started": true, "extensions": [ "spatial", "h3", "json" ] }, "tile_builder": { "found": true, "version": null }, "image_renderer": { "found": false, "available": false, "imagesAtOnce": 2 }, "metadata_database": { "file": "metadata.sqlite" } }, "basemapStyles": [], "services": { "geocode": { "bytes": 0, "answers": 0, "budgetMb": 64 }, "isochrone": { "bytes": 0, "answers": 0, "budgetMb": 64 }, "overpass": { "bytes": 0, "answers": 0, "budgetMb": 2048 }, "overture": { "listed": false } } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/caches": { "delete": { "summary": "Clear service caches", "description": "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 cached answers only: with service, that one cache (geocode for the address finder, isochrone for travel time, overpass for OpenStreetMap); without it, all three. Settings, datasets, runs and the Overture release list are unchanged. An answer whose request began before the Clear is not kept, and a write already landing is waited for and then removed. Clearing an empty cache answers the same. Answers with the caches cleared. The embedded assistant asks for confirmation before calling on pages admitting writes; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "clear_service_caches", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "caches", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Clear cached service answers?", "consequence": "This removes cached answers only. The next request for each asks its service again; settings and data are unchanged.", "subject": { "path": null, "argument": "", "name": "" } }, "x-display": { "verb": "Cleared service caches" }, "x-confirm": true, "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "geocode", "isochrone", "overpass" ] }, "description": "The one cache to clear; omitted, all three." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearedServiceCaches" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/services/{service}/test": { "post": { "summary": "Test a service", "description": "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. Sends the service one fixed request at its address in effect, never one given here: geocode (the address finder) one search for a fixed place, isochrone (travel time) one area on foot round a fixed point for the shortest band, overpass (OpenStreetMap) the smallest Overpass query, overture a listing of the releases, s3 one request to the S3 address's root without credentials, satellite one fixed low-zoom tile (zoom 3, x 4, y 2) at the imagery's tile template within 10 seconds, passing when the answer is an image (a template carrying a user name or password is refused, with the sentence a save refuses it with, and nothing is sent), templates the template catalogue's index, read as a refresh reads it within the link import's time bound (DEZFIL_REMOTE_TIMEOUT_S), or from the folder DEZFIL_TEMPLATES_CATALOGUE names, passing with how many templates it lists, an index this server would refuse being unexpected_answer. It goes the way the service's own requests go: through the egress check, redirects included, and after the gap between requests for the address finder and travel time. It reaches outside this server and stores nothing: no setting changes and no cache is read or written, except that the Overture Test keeps the release list it finds, as Check now does. A second Test of a service while one runs gets the same answer from the same request. A stored address the instance's key no longer opens is refused with service_address_unreadable, as the service refuses it. While an admin has turned the template catalogue off (templates.catalogue), its Test is refused with 409 templates_catalogue_off and sends nothing. The embedded assistant asks for confirmation before calling; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "test_service", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [], "reachesOutside": true }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Send a test request to the {target} service?", "consequence": "This server sends one request to the service at its address in effect. Nothing is saved, except that a Test of Overture keeps the release list it finds.", "subject": { "path": null, "argument": "service", "name": "" } }, "x-display": { "verb": "Reached outside this server to test the {arg.service} service" }, "x-confirm": true, "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "overture", "s3", "satellite", "templates" ] }, "description": "The service to test: geocode, isochrone, overpass, overture, s3, satellite (the imagery's tile template) or templates (the template catalogue)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceTestAnswer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "overture", "s3", "satellite", "templates" ] }, "description": "The service to test: geocode, isochrone, overpass, overture, s3, satellite (the imagery's tile template) or templates (the template catalogue)." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/storage": { "get": { "summary": "Read how the data folder is used", "description": "Requires a current admin through cookie or bearer authentication, rechecked on every call. A cookie request must show it comes from this instance's own page, by an Origin that is this instance's, Sec-Fetch-Site same-origin or the X-Dezfil-Account header its pages send; one with none of them, or with another origin's Origin or a cross-site or same-site Sec-Fetch-Site, is refused. An admin bearer token calls directly. Responses, including refusals, are private, no-store. Walks the data folder and answers, for each kind of file, the bytes its files take and how many there are: tables (dataset files the metadata registers), tile_archives (archives with a tile record and what they were built from), service_caches (the three caches' answers), thumbnails (map card images), profile_pictures (each person's current picture), templates (downloaded templates, and the copies of an installed template's data the query engine reads), metadata_database (the database and its journal files), leftover_files (what the next restart's sweeps would remove: upload, download and tile scratch, staged project exports with their ownership records, table files no dataset or installed template uses, archives no layer uses, unfinished thumbnail writes, pictures that are no one's current picture; it includes work in progress) and other (the rest, such as the key file and the server's records); with every kind together and the free and total space on the folder's volume. Each file counts once, however many names it has. It takes names and sizes, which files the metadata references and which the installed templates' records name, opening no other file and following no link, and answers no name, owner, account, map, dataset, path or file name. One walk runs at a time: a read during a walk gets that walk's answer, and a read within 30 seconds of it gets the same answer, unless a service cache was cleared since the walk began: a Clear ends a walk under way at once, the reads already joined to it getting what it had counted, and a read after the Clear never gets a walk begun before it but joins one fresh walk. Every read's deadline is 10 seconds from its asking: the walk that answers it cuts every filesystem call and the disk's statistics by then and stops the reference read at the first of its slices of 200 rows to end past it. A walk stopped by its deadline or ended by a Clear gives each kind it had not finished as at least what it counted, finished false, and the disk as null when its statistics had not come. It changes nothing and sends nothing outside this server. The embedded assistant asks for confirmation before calling; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "read_storage", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Read how this server uses its data folder?", "consequence": "This server walks its data folder for sizes and counts, for at most 10 seconds. Nothing is saved and nothing is sent outside this server.", "subject": { "path": null, "argument": "", "name": "" } }, "x-display": { "verb": "Read how the data folder is used" }, "x-confirm": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageRead" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/parts/{part}/test": { "post": { "summary": "Test a part of this server", "description": "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. Runs one small fixed check on one part of this server as it is configured now, never one given here: data_folder writes and removes one empty file in the data folder, as the readiness check does, within 5 seconds; query_engine asks the engine that runs people's SQL one fixed spatial question with a known answer within 30 seconds, interrupting it a second before them, and starts a cold engine for it loading only the extensions already installed: it installs nothing, so without the spatial extension it answers not_found and leaves the engine for the next query to start, and a missing optional extension stays off until the next start; tile_builder asks the tile builder for its version, then builds a small archive from a few fixed points in a folder of its own under the tile scratch and removes it, within 30 seconds, beside any layer build, neither waiting behind one nor holding one up; a tile builder still running 3 seconds before the limit is asked to stop, ended outright if it has not 2 seconds later, and its folder removed once it is gone, all within the 30 seconds; image_renderer has the image renderer's browser photograph a small fixed picture of this server's own, from no map or data, and reads its mark's color back, within 10 seconds, only on an image slot free now with no image waiting: otherwise it answers busy at once, launching nothing, and an image asked while it runs waits for it as behind any image; its browser is closed, or ended, within those 10 seconds, and only then is its slot free again; metadata_database takes the metadata database's write lock, reads the schema's version and gives the lock back, writing nothing, answering busy when other work holds the lock past the database's 5-second wait. It changes no setting, leaves no file and sends nothing outside this server. A second Test of a part asked while one runs, its part's work still ending included, gets that run's answer. The embedded assistant asks for confirmation before calling; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "test_part", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Test the {target} part of this server?", "consequence": "This server runs one small fixed check on that part. Nothing is saved and nothing is sent outside this server.", "subject": { "path": null, "argument": "part", "name": "" } }, "x-display": { "verb": "Tested the {arg.part} part of this server" }, "x-confirm": true, "parameters": [ { "name": "part", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "data_folder", "query_engine", "tile_builder", "image_renderer", "metadata_database" ] }, "description": "The part to test: data_folder or query_engine or tile_builder or image_renderer or metadata_database." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartTestAnswer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "part", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "data_folder", "query_engine", "tile_builder", "image_renderer", "metadata_database" ] }, "description": "The part to test: data_folder or query_engine or tile_builder or image_renderer or metadata_database." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/basemaps": { "post": { "summary": "Add a style to the basemap library", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin through cookie or bearer authentication, rechecked inside the write on every call. Cookie requests require the same trusted Origin; an admin bearer token calls directly. Responses, including refusals, are private, no-store. Adds a MapLibre style by its address, for everyone choosing a basemap: the builder's picker lists it after the built-in styles, and a map that takes it keeps its own copy of the name, the address and the credit. The server reads the address once, now: first the egress policy's own check, so an address in loopback, private, link-local, metadata or other blocked space, or a name all of whose addresses resolve there, is refused with that check's sentence before anything is sent, unless DEZFIL_EGRESS_ALLOWLIST names it; then one request through the egress-governed client, redirects included, within 8 seconds and 2 MB. A valid style is kept with its sources' credit, else its host. Refused with 400 invalid_request, nothing kept: a name outside 1 to 60 characters, an address that is not http or https with a host or is longer than 2,048 characters, an address the library already holds, a 51st style, an answer that is not a MapLibre style, and a style that cannot be read now: there is no force, because an offered style must draw in the server's images too. No refusal repeats the address. Nothing reads the address again: no schedule and no recheck. Its address is public to whoever draws a map on it, published readers included. The embedded assistant asks for confirmation before calling on pages admitting writes; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "add_basemap_style", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "basemaps", "collection": true, "result": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Add {target} to the basemap library?", "consequence": "This server reads the style's address once to check it and take its credit, then offers it to everyone choosing a basemap. Its address is public to whoever draws a map on it.", "subject": { "path": null, "argument": "name", "name": "" } }, "x-display": { "verb": "Added the basemap style {subject}", "subject": { "resource": "basemaps", "result": "id", "name": [ "name" ] } }, "x-confirm": true, "requestBody": { "required": true, "x-byte-limit": 65536, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryStyleAdd" }, "example": { "name": "Harbour chart", "url": "https://tiles.example.org/styles/harbour/style.json" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryStyle" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/instance/basemaps/{id}": { "patch": { "summary": "Offer or hide a library style", "description": "At most 65,536 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current admin through cookie or bearer authentication, rechecked inside the write on every call. Cookie requests require the same trusted Origin; an admin bearer token calls directly. Responses, including refusals, are private, no-store. Sets whether an added style is offered where a basemap is chosen. Hidden, it leaves the builder's picker and the runtime configuration; maps that took it keep their copy and draw it. Answers the style as it is now; an unknown id answers 404 not_found. The embedded assistant asks for confirmation before calling on pages admitting writes; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "set_basemap_style_offered", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "basemaps", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Change whether {target} is offered?", "consequence": "Hidden, it leaves every basemap picker; maps that already took it keep it.", "subject": { "path": "/api/instance/settings", "argument": "id", "name": "name", "collection": "basemapStyles", "identity": "id" } }, "x-display": { "verb": "Set whether the basemap style {subject} is offered", "subject": { "resource": "basemaps", "argument": "id", "name": [ "name" ] } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The style's identity in the library." } ], "requestBody": { "required": true, "x-byte-limit": 65536, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryStyleOffered" }, "example": { "offered": false } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryStyle" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Remove a library style", "description": "Requires a current admin through cookie or bearer authentication, rechecked inside the write on every call. Cookie requests require the same trusted Origin; an admin bearer token calls directly. Responses, including refusals, are private, no-store. Removes an added style from the library. Maps that took it keep their copy of its name, address and credit and keep drawing it; nothing else changes. An unknown id answers 404 not_found. The embedded assistant asks for confirmation before calling on pages admitting writes; SQL and workflow assistants refuse this operation. MCP advertises that policy and adds no confirmation step.", "tags": [ "System" ], "x-tool": "remove_basemap_style", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "basemaps", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Remove {target} from the basemap library?", "consequence": "Maps that already took it keep their copy.", "subject": { "path": "/api/instance/settings", "argument": "id", "name": "name", "collection": "basemapStyles", "identity": "id" } }, "x-display": { "verb": "Removed the basemap style {subject}", "subject": { "resource": "basemaps", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The style's identity in the library." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryStyleRemoved" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The style's identity in the library." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates": { "get": { "summary": "List templates", "description": "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.", "tags": [ "Templates" ], "x-tool": "list_templates", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the templates" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Templates" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/refresh": { "post": { "summary": "Refresh the template catalogue", "description": "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.", "tags": [ "Templates" ], "x-tool": "refresh_templates", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [], "reachesOutside": true }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Reached outside this server to refresh the template catalogue" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/downloads": { "delete": { "summary": "Remove the downloaded templates", "description": "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.", "tags": [ "Templates" ], "x-tool": "remove_template_downloads", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "templates", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Remove every downloaded template from this server?", "consequence": "The downloads take {size}. Shipped templates and the copies people made stay as they are, and a removed template downloads again at its next open.", "subject": { "path": "/api/templates", "argument": "", "name": "", "facts": { "size": { "path": "downloads.bytes", "bytes": true, "fallback": "the space Storage shows for templates" } } } }, "x-display": { "verb": "Removed the downloaded templates" }, "x-confirm": true, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDownloads" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/{id}": { "get": { "summary": "Read a template", "description": "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.", "tags": [ "Templates" ], "x-tool": "get_template", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the template {subject}", "subject": { "resource": "templates", "argument": "id", "name": [ "title" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "The 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." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Templates" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "The 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." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/{id}/fetch": { "post": { "summary": "Fetch a template", "description": "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.", "tags": [ "Templates" ], "x-tool": "fetch_template", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "templates", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Download version {version} of {target}?", "consequence": "Its archive, {size}, comes from the template catalogue and is checked whole before it is installed on this server. Nothing is downloaded if that version is installed already.", "subject": { "path": "/api/templates/{id}", "argument": "id", "name": "title", "binds": { "argument": "version", "path": "version" }, "facts": { "size": { "path": "size", "bytes": true, "fallback": "of the size the catalogue lists" } } } }, "x-display": { "verb": "Fetched the template {subject}", "subject": { "resource": "templates", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "requestBody": { "x-byte-limit": 65536, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1, "description": "The version to fetch; without it, the one the template's card takes now." } }, "additionalProperties": false } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFetched" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/{id}/copy": { "post": { "summary": "Copy a template", "description": "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.", "tags": [ "Templates" ], "x-tool": "copy_template", "x-tool-input": { "closed": true }, "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "result": "project.id" }, { "resource": "maps", "collection": true, "result": "members.maps.*.id" }, { "resource": "layers", "collection": true }, { "resource": "recipes", "collection": true, "result": "members.recipes.*.id" }, { "resource": "tables", "collection": true, "result": "members.tables.*.id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Copy version {version} of {target} into a new project?", "consequence": "Its map, its workflow if it has one, and its datasets (an archive of {size}) become yours in a new project; the template stays as it is.", "subject": { "path": "/api/templates/{id}", "argument": "id", "name": "title", "binds": { "argument": "version", "path": "installed", "absent": "template_not_installed" }, "facts": { "size": { "path": "size", "bytes": true, "of": "version", "fallback": "the size the template lists" } } } }, "x-display": { "verb": "Copied the template into the project {subject}", "subject": { "resource": "projects", "result": "project.id", "name": [ "project.name" ] } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "requestBody": { "x-byte-limit": 65536, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new project's name, trimmed, 1 to 120 characters; without it, the template's title." }, "version": { "type": "integer", "minimum": 1, "description": "The installed version to copy; without it, the installed one." } }, "additionalProperties": false } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCopy" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/templates/{id}/picture": { "get": { "summary": "Read a template's picture", "description": "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.", "tags": [ "Templates" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "light", "dark" ] }, "description": "The theme's picture: light (the default) or dark." } ], "responses": { "200": { "description": "The picture.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Templates" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "light", "dark" ] }, "description": "The theme's picture: light (the default) or dark." } ], "responses": { "200": { "description": "The picture." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$" }, "description": "The template's id: lowercase letters, digits and hyphens, the same across its versions." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}/geometry": { "get": { "summary": "Inspect a dataset's geometry choices", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. For file uploads and URL imports only. SQL-save, workflow, PostGIS, OSM, Overture and sketch datasets refuse with 409 geometry_not_supported and a sentence. Unknown or reclaimed dataset identity answers 404 not_found; a stale artifact revision answers 409 input_changed. Column names are identifiers, never SQL expressions or file paths. Reads current stored schema, record, choice, opaque revision and candidates using the same first-1,000-row recognition and full safety evidence as CSV upload. Does not apply a proposal, fetch a source or invent legacy provenance. Repeated inspections reuse candidates while the artifact is unchanged. Historical consumed names and generated outputs are not new source columns.", "tags": [ "Tables" ], "x-tool": "inspect_table_geometry", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Inspected the geometry of the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "x-relevance": [ "builder", "sql", "workflow" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryInspection" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "put": { "summary": "Set or change a dataset's geometry", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. For file uploads and URL imports only. SQL-save, workflow, PostGIS, OSM, Overture and sketch datasets refuse with 409 geometry_not_supported and a sentence. Unknown or reclaimed dataset identity answers 404 not_found; a stale artifact revision answers 409 input_changed. Column names are identifiers, never SQL expressions or file paths. Original values and rows remain. WKT/EWKT, GeoJSON geometry objects, WKB hex/EWKB, validated H3 boundaries and x/y pairs from numeric or text-typed columns are supported. Pair values are read tolerantly per row on preview, first set, change and replay. Declared CRS wins: an explicit differing EPSG refuses with conflicting_crs; mixed/unknown declarations refuse. H3 and GeoJSON have inherent WGS84 and take no projection. Undeclared WKT/WKB/pairs assume WGS84 unless EPSG is explicit. Transformation produces WGS84 longitude/latitude. Under WGS84, mixed out-of-range rows are unreadable; only when no decoded nonempty row fits degrees does projection_required block application. Missing inputs do not count as unreadable. All-bad/empty inputs otherwise retain a geometry identity with null class and extent. Builds and re-measures an artifact, then publishes record and saved choice together. Retained sources permit repeated changes with one managed output. A first projection change is allowed on assumed native/consumed geometry; a further change without source values refuses with geometry_choice_invalid and source_unavailable. Last-run time, projects, dataset identity, layer SQL/style, undo and redo remain intact. Dependent tiles become stale; captured readers finish on old artifacts. A competing writer in the same table or URL group answers 409 geometry_in_flight. Malformed/unknown fields and incompatible types answer 400 invalid_request; missing columns answer 400 column_unavailable. Unusable choices answer 422 geometry_choice_invalid with issues. Post-commit cleanup failure does not reverse success. A saved manual geometry choice on a URL import replays against fresh source columns before automatic conversion, survives restart, and commits with the artifact and geometryRecord. Missing selected columns fail atomically with 400 column_unavailable; bad rows remain null geometries and are counted. Each container member keeps its own choice and the group downloads once and publishes together. Clear removes the override: the next refresh resumes automatic recognition, records its fresh result and resets geometry mode to unmodified. An unusable saved choice refuses atomically with 422 geometry_choice_invalid, including projection_required or conflicting_crs issues. A changed generation refuses with 409 input_changed.", "tags": [ "Tables" ], "x-tool": "set_table_geometry", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Set the geometry of the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryRequest" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryMutation" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Clear a dataset's generated geometry", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. For file uploads and URL imports only. SQL-save, workflow, PostGIS, OSM, Overture and sketch datasets refuse with 409 geometry_not_supported and a sentence. Unknown or reclaimed dataset identity answers 404 not_found; a stale artifact revision answers 409 input_changed. Column names are identifiers, never SQL expressions or file paths. Removes the managed output and applied record, retaining originals, identity, row count and last-run time. Repeated clear is a no-op; later set remains available. A clear that removes native/consumed geometry refuses with 422 geometry_choice_invalid and source_unavailable. History and layer SQL/style stay intact; dependent tiles become stale. Requires expectedRevision in the query. Competing edits/refreshes in the same provenance unit answer 409 geometry_in_flight. Clear removes a URL override; its next refresh runs automatic recognition and mode becomes unmodified.", "tags": [ "Tables" ], "x-tool": "clear_table_geometry", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Clear geometry from {target}?", "consequence": "This removes its generated geometry and saved geometry choice. Layers keep their definitions and refresh against the changed dataset.", "subject": { "path": "/api/catalogue/tables?names={name}", "argument": "name", "name": "name", "collection": "tables", "identity": "name" } }, "x-display": { "verb": "Cleared the geometry of the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "x-confirm": true, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." }, { "name": "expectedRevision", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Opaque revision returned by geometry inspection." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryMutation" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "409": { "description": "Error with a machine-readable code and human message." }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}/geometry/preview": { "post": { "summary": "Preview an explicit geometry choice", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. For file uploads and URL imports only. SQL-save, workflow, PostGIS, OSM, Overture and sketch datasets refuse with 409 geometry_not_supported and a sentence. Unknown or reclaimed dataset identity answers 404 not_found; a stale artifact revision answers 409 input_changed. Column names are identifiers, never SQL expressions or file paths. Original values and rows remain. WKT/EWKT, GeoJSON geometry objects, WKB hex/EWKB, validated H3 boundaries and x/y pairs from numeric or text-typed columns are supported. Pair values are read tolerantly per row on preview, first set, change and replay. Declared CRS wins: an explicit differing EPSG refuses with conflicting_crs; mixed/unknown declarations refuse. H3 and GeoJSON have inherent WGS84 and take no projection. Undeclared WKT/WKB/pairs assume WGS84 unless EPSG is explicit. Transformation produces WGS84 longitude/latitude. Under WGS84, mixed out-of-range rows are unreadable; only when no decoded nonempty row fits degrees does projection_required block application. Missing inputs do not count as unreadable. All-bad/empty inputs otherwise retain a geometry identity with null class and extent. No artifact, metadata, history, tile or saved-choice writes and no URL fetch. Returns the first 50 rows with corresponding feature ids and row outcomes, including null geometries; indexes belong only to the returned revision. Counts, geometry class, degree compatibility and extent are sampled from those first 50 rows, without extrapolation. CRS declarations are still checked across the full source column. Apply validates and counts the full input independently and may refuse a choice that the sample accepted. Map geometries are simplified for preview; text and geometry-valued grid cells longer than 512 characters end in an ellipsis after a 512-character excerpt. Original stored values are unchanged. A syntactically valid unusable projection or unavailable H3 returns 200 with canApply false and issues; unsupported ownership changes refuse with 422 and source_unavailable. Invalid JSON/unknown fields/types answer 400 invalid_request; missing columns answer 400 column_unavailable. The complete uncompressed UTF-8 JSON answer, including metadata, grid rows and map features together, is limited to 33,554,432 bytes (32 MiB); each non-geometry column value after excerpts, including nested values, to 2,097,152 bytes (2 MiB). Equality is admitted. Native geometry WKT excerpts and evaluated native map geometry count only toward the result ceiling. Source text and JSON remain non-geometry. Exceeding either fixed bound refuses the whole preview with HTTP 422 query_result_too_large and no partial sample. Preview is optional before apply.", "tags": [ "Tables" ], "x-tool": "preview_table_geometry", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Previewed a geometry choice for the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryRequest" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryPreview" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stored dataset SQL name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/geometry/projections": { "get": { "summary": "List geometry projections or resolve an EPSG code", "description": "The seven drawn projections in order: WGS 84, Web Mercator, ETRS89 / UTM 32N, ETRS89 / UTM 33N, ETRS89 / LAEA Europe, British National Grid, NAD83. The optional lookup accepts decimal digits with an EPSG: prefix, validates engine transformation support, and includes custom codes outside the shortlist. Custom entries return the bare EPSG code as name and null unit; curated names share recognition's label map. No query gives resolved null. Invalid syntax answers 400 invalid_request; unsupported codes answer 422 geometry_choice_invalid.", "tags": [ "Tables" ], "x-tool": "list_geometry_projections", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the geometry projections" }, "parameters": [ { "name": "epsg", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Numeric EPSG code, optionally prefixed EPSG:." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeometryProjections" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "epsg", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Numeric EPSG code, optionally prefixed EPSG:." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/health": { "get": { "summary": "Readiness check", "description": "Readiness reports whether socket provenance is installed, the data directory is usable, and, once a query has started the query engine that runs SQL, whether that engine can serve. Readiness starts no engine before a query does. A started engine is asked a trivial statement on its own connection, not behind any account's queries: a statement that fails reads unready, and one with no answer within 2 seconds reads ready, since a busy engine is not a dead one. An engine whose last start failed reads unready, and readiness starts it again at most once every 30 seconds, so an instance taken out of rotation recovers once the cause clears. Unready, the reason names storage or the query engine, never a path or the engine's own words.", "tags": [ "System" ], "x-tool": "check_health", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Checked the instance" }, "responses": { "200": { "description": "Ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "ready": { "summary": "Check that the instance is ready", "description": "Needs nothing: the check takes no sign-in.", "value": { "status": "ready" } } } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "The ingress preload, storage or the query engine is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthUnready" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Ready." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "The ingress preload, storage or the query engine is unavailable." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/config": { "get": { "summary": "Runtime client configuration", "description": "Instance-wide basemaps, built-in palettes, client limits, the defaults new maps, layers and screens start with, whether the template catalogue is in use, the rules every account follows and the shortest password, shared by every authenticated account. Includes deployment-configured basemap choices and provider availability, never server-side AI or geocoder credentials. Private, no-store.", "tags": [ "System" ], "x-tool": "get_config", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the instance configuration" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" }, "examples": { "newInstance": { "summary": "Read the values in effect", "description": "Needs a token. On a new instance, with its palettes trimmed to two of the twenty-three.", "value": { "basemapUrl": "https://tiles.openfreemap.org/styles/dark", "basemapOverrideUrl": null, "basemaps": [ { "key": "dark", "label": "Dark", "url": "https://tiles.openfreemap.org/styles/dark", "kind": "vector", "attribution": [ { "label": "© OpenMapTiles", "href": "https://openmaptiles.org" }, { "label": "© OpenStreetMap", "href": "https://www.openstreetmap.org/copyright" } ] }, { "key": "light", "label": "Light", "url": "https://tiles.openfreemap.org/styles/positron", "kind": "vector", "attribution": [ { "label": "© OpenMapTiles", "href": "https://openmaptiles.org" }, { "label": "© OpenStreetMap", "href": "https://www.openstreetmap.org/copyright" } ] }, { "key": "streets", "label": "Streets", "url": "https://tiles.openfreemap.org/styles/liberty", "kind": "vector", "attribution": [ { "label": "© OpenMapTiles", "href": "https://openmaptiles.org" }, { "label": "© OpenStreetMap", "href": "https://www.openstreetmap.org/copyright" } ] } ], "basemapStyles": [], "singleMapStyles": true, "palettes": [ { "name": "sunrise", "label": "Sunrise", "kind": "sequential", "group": "sequential", "colorblindSafe": false, "colors": [ "#355C7D", "#C06C84", "#F8B195" ] }, { "name": "bold", "label": "Bold", "kind": "categorical", "group": "qualitative", "colorblindSafe": false, "colors": [ "#7f3c8d", "#11a579", "#3969ac", "#f2b701", "#e73f74", "#80ba5a", "#e68310", "#008695", "#cf1c90", "#f97b72" ] } ], "renderCapFeatures": 250000, "previewRows": 1000, "geocoderConfigured": false, "defaults": { "newMap.basemap": "auto", "newMap.latitude": 40, "newMap.longitude": 0, "newMap.zoom": 1.3, "newMap.legendCorner": "bottom-left", "newLayer.colorCycle": "uber_viz_qualitative", "newLayer.pointOpacity": 72, "newLayer.lineOpacity": 95, "newLayer.areaOpacity": 50, "newLayer.lineWidth": 2, "newLayer.pointRadius": 3, "canvas.opens": "full", "canvas.minimap": "auto", "canvas.resultsBand": "closed", "sqlConsole.textSize": "12", "sqlConsole.lineWrap": false, "imageExport.width": "1920", "imageExport.shape": "4:3" }, "templates": { "catalogue": true }, "rules": { "tokens.create": "everyone", "tokens.expiry": "never", "publishing.publish": "everyone", "publishing.embedding": "any", "connections.create": "everyone", "imports.links": "everyone" }, "passwordMin": 8 } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/basemaps/satellite": { "get": { "summary": "The configured imagery style", "description": "A MapLibre style document for the imagery this instance configures, with the provider's credit. Its raster source names this instance's own tile address, `/api/basemaps/satellite/tiles/{z}/{x}/{y}{ratio}`, never the configured tile template: the server fetches each tile from the template, so the template and a key in it never leave the server. It answers signed-in accounts only; an anonymous request is refused. No imagery ships with the app, so an instance that configures none answers 404 and offers no imagery basemap, as does one whose tile template carries a user name or password. A stored template the instance's key no longer opens is refused with service_address_unreadable, never answered with another style. A published page's reader has the publication's own style address. Private, no-store.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "The style document.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No imagery is configured." }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "The style document." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No imagery is configured." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/basemaps/satellite/tiles/{z}/{x}/{y}": { "get": { "summary": "One tile of the configured imagery", "description": "Fetched now by the server from the tile template this instance configures and passed back, so the template and a key in it never leave the server. Use the tile address the imagery style names. Only the tile's z, x and y reach the template, each a whole number in plain decimal, z from 0 to 19 and x and y below 2 to the power of z, the row followed by @2x for a high-density tile or by nothing; anything else is refused with invalid_request before the imagery is asked. The template is filled from these alone as MapLibre fills a raster template: {z}, {x}, {y} (counted by the style source's scheme), {ratio} (@2x or nothing), {quadkey}, {prefix} and {bbox-epsg-3857}. No query, header or credential of the request goes with them. The fetch takes the egress policy at every hop, waits at most ten seconds and reads at most 4 MiB; only a whole PNG, JPEG, GIF, WebP or AVIF image passes back, with the type its bytes are, and no tile is stored. Every failure upstream answers imagery_unavailable, whose message says what went wrong and never the tile address or its key; a template carrying a user name or password is not drawn and answers the same. Private, no-store. An instance that configures no imagery answers 404 as the style does; a stored template the instance's key no longer opens is refused with service_address_unreadable. Signed-in accounts only; an anonymous request is refused and asks the imagery nothing. A published page's reader has the publication's own tile address.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "200": { "description": "The tile, as the imagery drew it.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No imagery is configured." }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "502": { "description": "imagery_unavailable: the imagery failed, or this instance's egress policy refused its address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Dezfil-Egress-Refused": { "description": "imagery where the egress policy refused the imagery's address, at its host or at a redirect; absent for every other failure. An image export that meets it refuses its image rather than make it without the imagery.", "schema": { "type": "string", "const": "imagery" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "200": { "description": "The tile, as the imagery drew it." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No imagery is configured." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "502": { "description": "imagery_unavailable: the imagery failed, or this instance's egress policy refused its address.", "headers": { "X-Dezfil-Egress-Refused": { "description": "imagery where the egress policy refused the imagery's address, at its host or at a redirect; absent for every other failure. An image export that meets it refuses its image rather than make it without the imagery.", "schema": { "type": "string", "const": "imagery" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Error with a machine-readable code and human message." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/palettes": { "get": { "summary": "List palettes", "description": "Shared by every authenticated account. The full palette offer: the curated catalogue plus every saved custom palette. Either kind's name works as `palette` in the fill operation.", "tags": [ "System" ], "x-tool": "list_palettes", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the palettes" }, "x-relevance": [ "builder" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaletteOffer" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Save a custom palette", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Every authenticated account may save a named gradient of ordered color stops. Instance-global: it appears in every map's picker and works in continuous and classified fills alike. Returns the saved palette with its assigned name.", "tags": [ "System" ], "x-tool": "create_palette", "x-effects": { "readOnly": false, "writes": [ { "resource": "palettes", "collection": true, "result": "name" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Saved the palette {subject}", "subject": { "resource": "palettes", "result": "name", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 60 }, "stops": { "type": "array", "minItems": 2, "maxItems": 16, "items": { "type": "object", "properties": { "color": { "type": "string", "description": "#rrggbb" }, "position": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "color", "position" ] } } }, "required": [ "label", "stops" ] }, "example": { "label": "Brand", "stops": [ { "color": "#f2f0e4", "position": 0 }, { "color": "#0d7d5c", "position": 1 } ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomPalette" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/palettes/{name}": { "delete": { "summary": "Delete a custom palette", "description": "Every authenticated account may remove any saved custom palette from the shared picker. Styles that used it keep rendering — their colors were baked in at classification time. Curated palettes cannot be deleted.", "tags": [ "System" ], "x-tool": "delete_palette", "x-effects": { "readOnly": false, "writes": [ { "resource": "palettes", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This removes the palette from the picker. Existing styled layers keep their colors.", "subject": { "path": "/api/palettes", "argument": "name", "name": "label", "collection": "custom", "identity": "name" } }, "x-display": { "verb": "Deleted the palette {subject}", "subject": { "resource": "palettes", "argument": "name" } }, "x-confirm": true, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Custom palette name." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Custom palette name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/settings": { "get": { "summary": "Workspace settings", "description": "The signed-in account's display name, per-screen view/sort preferences, how the SQL console's source list groups datasets and its look (color, contrast, typeface, background, corners, side menu and panels), plus the instance name shown beside the wordmark and in browser titles (null when unnamed). Cookie or bearer authentication is required. Responses, including refusals, are private, no-store.", "tags": [ "System" ], "x-tool": "get_settings", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read your settings" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSettings" }, "examples": { "newAccount": { "summary": "Read your own settings", "description": "Needs a token. A new account's settings.", "value": { "displayName": "Ana Diaz", "instanceName": null, "viewPrefs": {}, "sourceGrouping": "person", "look": { "color": "kelp", "contrast": "standard", "font": "inter", "background": "atlantic", "corners": "rounded", "rail": "hover", "panels": "glass", "transparency": "clear" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Update your settings", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Updates only the authenticated account's display name and preferences. Only admins can change instanceName. The entire patch is validated and authorized before any write; a forbidden or invalid field leaves every field unchanged. The look takes any of its picks; an unknown pick or value inside look refuses the patch, while an unknown field outside it is ignored. Cookie mutations require the same trusted Origin. Explicit bearer requests need no cookie or Origin. Responses, including refusals, are private, no-store.", "tags": [ "System" ], "x-tool": "update_settings", "x-effects": { "readOnly": false, "writes": [ { "resource": "settings", "collection": true }, { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated your settings" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "maxLength": 80, "description": "Your account display name." }, "instanceName": { "type": [ "string", "null" ], "maxLength": 80, "description": "Admin-only optional instance name. Empty, whitespace or null clears it; the instance is then unnamed." }, "viewPrefs": { "type": "object", "description": "Per-screen view preferences; slices merge into what is stored, and the read carries every slice written so far.", "properties": { "maps": { "type": "object", "description": "The Maps list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "edited", "created", "name" ] } } }, "data": { "type": "object", "description": "The Data page.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "updated", "name", "rows", "size" ] } } }, "workflows": { "type": "object", "description": "The workflows list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "edited", "created", "name" ] } } }, "projects": { "type": "object", "description": "The Projects list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "updated", "name", "largest" ] } } } } }, "sourceGrouping": { "type": "string", "enum": [ "person", "project" ], "default": "person", "description": "How the SQL console's source list groups datasets: by person (your own, then each other person's under their name and SQL name) or by project. Your own choice, never another account's; person until you choose otherwise." }, "look": { "type": "object", "additionalProperties": false, "description": "Any of your look's picks; the others stay as they are. A value outside a pick's choices, or a key that is not one of the picks, refuses the whole update: a bad value is named as look., an unknown key by its position.", "properties": { "color": { "type": "string", "enum": [ "kelp", "harbor", "heather", "slate" ], "default": "kelp", "description": "Color. The interface's tint: accents, primary buttons, active marks, focus and the background's ink. Never a data color." }, "contrast": { "type": "string", "enum": [ "standard", "more" ], "default": "standard", "description": "Contrast. Borders, dividers and quieter text; more makes them stronger in both themes." }, "font": { "type": "string", "enum": [ "inter", "system" ], "default": "inter", "description": "Typeface. The face of everything read: Inter, or the computer's own. Identifiers and values keep the mono face." }, "background": { "type": "string", "enum": [ "atlantic", "plain", "graticule", "hex" ], "default": "atlantic", "description": "Background. The texture behind the workspace and in the header bar; plain is none." }, "corners": { "type": "string", "enum": [ "rounded", "soft" ], "default": "rounded", "description": "Corners. Rounded edges of cards, fields, buttons and panels; soft is tighter." }, "rail": { "type": "string", "enum": [ "hover", "open", "icons" ], "default": "hover", "description": "Side menu. How the side menu opens: on a resting pointer or focus, always open with labels, or icons only." }, "panels": { "type": "string", "enum": [ "glass", "liquid", "paper" ], "default": "glass", "description": "Panels. How cards and panels are drawn: frosted glass, liquid glass with a light on its rim, or opaque paper with no blur." }, "transparency": { "type": "string", "enum": [ "clear", "medium", "firm" ], "default": "clear", "description": "Transparency. How much of the map shows through Liquid's cards and panels: clear, medium or firm. Only while Panels is Liquid." } } } } }, "examples": { "mapsAsList": { "summary": "Show the Maps page as a list, by name", "description": "Needs a token. The slice you send merges into what is stored.", "value": { "viewPrefs": { "maps": { "view": "list", "sort": "name" } } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSettings" }, "examples": { "mapsAsList": { "summary": "Show the Maps page as a list, by name", "description": "Needs a token. The slice you send merges into what is stored.", "value": { "displayName": "Ana Diaz", "instanceName": null, "viewPrefs": { "maps": { "view": "list", "sort": "name" } }, "sourceGrouping": "person", "look": { "color": "kelp", "contrast": "standard", "font": "inter", "background": "atlantic", "corners": "rounded", "rail": "hover", "panels": "glass", "transparency": "clear" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/openapi.json": { "get": { "summary": "This OpenAPI description", "description": "The same API reference for every authenticated account. Contains operation contracts, never private resource listings or credential values. Private, no-store.", "tags": [ "System" ], "x-tool": "get_api_description", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the API description" }, "responses": { "200": { "description": "The machine-readable API description.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "excerpt": { "summary": "Read this API description", "description": "Needs a token. An excerpt: the answer is the whole description, as this document.", "value": { "openapi": "3.1.0", "info": { "title": "Dezfil API", "version": "0.1.0" }, "paths": { "/api/query": { "post": { "summary": "Run read-only SQL", "requestBody": { "x-byte-limit": 16777216, "x-byte-error": "request_body_too_large" } } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "The machine-readable API description." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables": { "get": { "summary": "List tables", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. ", "tags": [ "Tables" ], "x-tool": "list_tables", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the datasets" }, "x-relevance": [ "builder", "sql", "workflow" ], "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableList" }, "examples": { "afterUpload": { "summary": "List your datasets", "description": "Needs a token. Lists world_cities, the dataset the upload made.", "value": [ { "geometryRecord": { "columns": [ "longitude", "latitude" ], "format": "pair", "signal": "name", "rule": "exact-pair", "crs": { "stance": "assumed", "srid": null, "label": "WGS 84 assumed" }, "unreadableCount": 0 }, "geometryCandidates": [ { "columns": [ "longitude", "latitude" ], "format": "pair", "signal": "name", "rule": "exact-pair", "strength": "strong", "sample": { "rows": 48, "nonNull": 48, "readable": 48 }, "crs": { "stance": "assumed", "srid": null, "label": "WGS 84 assumed" }, "degreeCompatible": true, "reasons": [], "applied": true, "sourceRetained": true, "orientations": [ { "lon": "longitude", "lat": "latitude" } ] } ], "id": "7d4b2e91-3f6a-4c58-8e12-9a0b5c6d7e2f", "name": "world_cities", "sourceFilename": "world-cities.csv", "format": "csv", "file": "tables/7d4b2e91-3f6a-4c58-8e12-9a0b5c6d7e2f.parquet", "geometryColumn": "geometry", "geometryType": "POINT", "crsAssumed": true, "headerSuspect": false, "rowCount": 48, "createdAt": "2026-10-20T09:00:01.283Z", "source": "upload", "sourceParams": null, "importedAt": "2026-10-20T09:00:01.283Z", "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "qualifiedName": "world_cities", "projectIds": [], "sizeBytes": 3839 } ] } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Upload a file as one or more tables", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. multipart/form-data with exactly one file part, named `file` — a request with several file parts, or a file under another field name, is refused without importing anything. To upload a batch, repeat the request once per file. Accepts GeoParquet, GeoJSON, CSV, Shapefile (as .zip), GeoPackage, and KML/KMZ. A container holding several spatial layers creates one table per layer; the answer enumerates them. Reception and processing each get the Data processing time limit captured when receiving begins, with separate deadlines. Changing the setting during receipt changes neither budget. No body byte for 60 seconds, including before the first byte, answers 408 upload_stalled. Reception or processing expiry answers 408 data_processing_timeout, naming the work and admitted limit. The first refusal is delivered without waiting for another byte or draining the body; the refused connection closes within five seconds. Incomplete reception cancels on departure and removes its partial file. Complete uploads continue processing after departure. CSV geometry recognition uses names first, in order: a text column named wkt/geometry/geom is parsed as WKT; lon/lat, lng/lat, long/lat, or longitude/latitude pairs become point geometry when each member is numeric or contains no non-blank values; when a member qualifies only by being blank, a numeric prefixed pair takes precedence. Empty and quoted-empty fields are blank; whitespace-only text is not. A row missing either member has null geometry. A prefixed pair (origin_lon/origin_lat, pickup_longitude/…) becomes the point when it is the origin pair or the only one. Safe prefixed x/y retains that name priority; bare x/y and easting/northing are weak candidates. Unsafe names yield to the next eligible name, then to content. A named WKT column with sampled non-null values but none readable stays weak with an unreadable reason and retains its source text; a strong content reading of that same column may apply instead. Content recognition samples the first 1,000 reader rows, excluding NULLs from each format's denominator. WKT/EWKT, GeoJSON geometry objects (not Features or FeatureCollections), WKB hex including EWKB SRIDs, and validated H3 cells are supported. An H3 cell becomes its boundary polygon; unavailable validation yields only an unvalidated weak hint. A content column is strong only when every sampled non-null value reads in that format, with at least one readable value. When some but not all read, it is weak with its sampled count. Strong ties use source column order. Content numeric pairs are always weak; unnamed pairs need at least 50% of complete sampled rows in a possible degree orientation, and ambiguous axes remain marked. The chosen mapping is checked over the entire input for finite longitude/x in [-180,180] and latitude/y in [-90,90], including every geometry vertex and values after the sample. A consistent declared CRS is reprojected to WGS84 under the file-ingest contract; conflicting declarations and untransformable SRIDs stay weak with reasons. Unknown declarations never become a WGS84 assumption. Undeclared degree-compatible WKT/WKB and eligible named pairs assume WGS84; GeoJSON and H3 are inherently WGS84 and declarations are not assumptions. Selected unreadable non-null values keep their rows with NULL geometry and a full-input unreadable count; missing inputs do not increment that count. Content roads retain source columns and add a distinct geometry column; named WKT keeps its replacement behavior. The geometryCandidates evidence retains alternatives, source identities, sample observations, axis roles, CRS and reasons. The geometryRecord identifies the applied choice, source CRS stance and full unreadable count, persisted for table inspection. Legacy records remain absent. Without an eligible mapping the CSV lands as a plain table with all source rows and columns and no CRS assumption. Local and URL CSV imports share these rules; refresh replaces automatic evidence with its artifact atomically, and failure keeps both old versions. A CSV whose detected column names betray a broken read: a name containing a comma (the header was never split), or most names numeric or blank (the first data row was taken as the header) imports with `headerSuspect: true`. The warning is advisory: it refuses nothing and changes nothing about recognition. MCP accepts at most 16,777,216 bytes for the entire JSON envelope, including base64. The raw file must be below 12 MiB, reduced by envelope and metadata overhead and by the configured upload cap. For canonical base64, subtract the serialized empty-content envelope bytes from 16,777,216, round down to whole groups of four, and allow three file bytes per group.", "tags": [ "Tables" ], "x-tool": "upload_table", "x-tool-input": { "multipart": { "field": "file", "filename": "filename", "content": "content_base64" } }, "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": [ "id", "tables.*.id" ] }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Uploaded a file" }, "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The project every created table joins — a query parameter because the body is the file itself. An unknown project refuses before the upload is received. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "MCP accepts at most 16,777,216 bytes for the entire JSON envelope, including base64. The raw file must be below 12 MiB, reduced by envelope and metadata overhead and by the configured upload cap. For canonical base64, subtract the serialized empty-content envelope bytes from 16,777,216, round down to whole groups of four, and allow three file bytes per group." } }, "required": [ "file" ] }, "examples": { "quickstart": { "summary": "Upload world-cities.csv", "description": "Needs a token and the file world-cities.csv: 48 cities with latitude and longitude columns. The form's one field, file, carries the file's bytes; the dataset takes its name from the file.", "value": { "file": "name,country,population,latitude,longitude\nTokyo,Japan,35676000,35.687,139.7495\nNew York,United States of America,19040000,40.7519,-73.982\nMexico City,Mexico,19028000,19.4444,-99.1329\nMumbai,India,18978000,19.0189,72.855\nSão Paulo,Brazil,18845000,-23.5567,-46.627\nShanghai,China,14987000,31.2184,121.4346\nKolkata,India,14787000,22.4969,88.3227\nDhaka,Bangladesh,12797394,23.725,90.4066\nBuenos Aires,Argentina,12795000,-34.6006,-58.3995\nLos Angeles,United States of America,12500000,33.9919,-118.1819\nCairo,Egypt,11893000,30.0519,31.248\nBeijing,China,11106000,39.9308,116.3863\nManila,Philippines,11100000,14.6061,120.9803\nMoscow,Russia,10452000,55.7541,37.6136\nIstanbul,Turkey,10061000,41.1069,29.0081\nParis,France,9904000,48.8686,2.3314\nSeoul,South Korea,9796000,37.5683,126.9978\nLagos,Nigeria,9466000,6.4452,3.3896\nJakarta,Indonesia,9125000,-6.1725,106.8275\nChicago,United States of America,8990000,41.8319,-87.752\nLondon,United Kingdom,8567000,51.5019,-0.1187\nLima,Peru,8012000,-12.0461,-77.052\nTehran,Iran,7873000,35.6739,51.4224\nKinshasa,Congo (Kinshasa),7843000,-4.3278,15.313\nBogota,Colombia,7772000,4.5984,-74.0853\nBangkok,Thailand,6704000,13.7519,100.5147\nSantiago,Chile,5720000,-33.4481,-70.669\nMadrid,Spain,5567000,40.402,-3.6853\nToronto,Canada,5213000,43.7019,-79.422\nSingapore,Singapore,5183700,1.295,103.8539\nLuanda,Angola,5172900,-8.8363,13.2325\nSydney,Australia,4630000,-33.9181,151.1832\nRiyadh,Saudi Arabia,4465000,24.6428,46.7708\nHanoi,Vietnam,4378000,21.0353,105.8481\nMelbourne,Australia,4170000,-37.8181,144.9731\nJohannesburg,South Africa,3435000,-26.1681,28.0281\nBerlin,Germany,3406000,52.5238,13.3996\nRome,Italy,3339000,41.8979,12.4813\nAthens,Greece,3242000,37.9853,23.7314\nCasablanca,Morocco,3181000,33.6019,-7.6183\nAddis Ababa,Ethiopia,3100000,9.0353,38.6981\nNairobi,Kenya,3010000,-1.2814,36.8147\nCaracas,Venezuela,2985000,10.5029,-66.919\nDakar,Senegal,2604000,14.7178,-17.4751\nTashkent,Uzbekistan,2184000,41.3136,69.293\nHavana,Cuba,2174000,23.1339,-82.3661\nAuckland,New Zealand,1377200,-36.8481,174.763\nStockholm,Sweden,1264000,59.3527,18.0954\n" }, "x-filenames": { "file": "world-cities.csv" } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" }, "examples": { "quickstart": { "summary": "Upload world-cities.csv", "description": "Needs a token and the file world-cities.csv: 48 cities with latitude and longitude columns. The form's one field, file, carries the file's bytes; the dataset takes its name from the file.", "value": { "id": "7d4b2e91-3f6a-4c58-8e12-9a0b5c6d7e2f", "sourceFilename": "world-cities.csv", "format": "csv", "file": "tables/7d4b2e91-3f6a-4c58-8e12-9a0b5c6d7e2f.parquet", "geometryColumn": "geometry", "geometryType": "POINT", "crsAssumed": true, "headerSuspect": false, "geometryRecord": { "columns": [ "longitude", "latitude" ], "format": "pair", "signal": "name", "rule": "exact-pair", "crs": { "stance": "assumed", "srid": null, "label": "WGS 84 assumed" }, "unreadableCount": 0 }, "geometryCandidates": [ { "columns": [ "longitude", "latitude" ], "format": "pair", "signal": "name", "rule": "exact-pair", "strength": "strong", "sample": { "rows": 48, "nonNull": 48, "readable": 48 }, "crs": { "stance": "assumed", "srid": null, "label": "WGS 84 assumed" }, "degreeCompatible": true, "reasons": [], "applied": true, "sourceRetained": true, "orientations": [ { "lon": "longitude", "lat": "latitude" } ] } ], "rowCount": 48, "createdAt": "2026-10-20T09:00:01.283Z", "source": "upload", "sourceParams": null, "importedAt": "2026-10-20T09:00:01.283Z", "name": "world_cities", "projectIds": [] } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/url": { "post": { "summary": "Import a remote file as one or more tables", "description": "At most 16,777,216 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. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Reads a remote Parquet, CSV, GeoJSON, Shapefile-zip, GeoPackage, or KML/KMZ file — https://, s3://, gs://, or az:// — and materializes it as GeoParquet tables (a snapshot, not a live link; one table per spatial layer for container formats). Private buckets use credentials configured in the server environment. The URL is stored as the tables' provenance, so the import can be re-run with the refresh operation.", "tags": [ "Tables" ], "x-tool": "import_table_from_url", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": [ "id", "tables.*.id" ] }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Imported a file from a URL" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Remote file URL (https/http/s3/gs/az) ending in a supported extension." }, "name": { "type": "string", "description": "Optional table name; derived from the URL when omitted." }, "projectId": { "type": [ "string", "null" ], "description": "The project every created table joins; omitted or null, unfiled. An unknown project refuses before the source is contacted. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } }, "required": [ "url" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture": { "post": { "summary": "Import Overture Maps data as a table", "description": "At most 16,777,216 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. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Reads one Overture theme (places, buildings, transportation, divisions, base, addresses) for a scope straight from the public S3 release and materializes it as a GeoParquet table. The scope is a named area (country, state, or a division found via the search operation) or a drawn shape (bbox or polygon ring). Semantics decide how a drawn or boundary area applies: \"within\" keeps only features entirely inside (the default for most themes), \"intersect\" also keeps edge-crossers (default for transportation and base). Divisions take a level (an Overture subtype, e.g. region, county — discover them via the levels operation) and exclude maritime areas. Places accept a category filter. The full set of import parameters is stored as provenance for refresh. Example: all states of Germany = {theme: \"divisions\", level: \"region\", scope: {type: \"country\", code: \"DE\"}}.", "tags": [ "Tables" ], "x-tool": "import_table_from_overture", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": "id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Imported Overture data as {subject}", "subject": { "resource": "tables", "result": "id", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "places", "buildings", "transportation", "divisions", "base", "addresses" ] }, "scope": { "$ref": "#/components/schemas/OvertureScope" }, "semantics": { "type": "string", "enum": [ "within", "intersect" ], "description": "How the area applies; defaulted per theme when omitted." }, "level": { "type": "string", "description": "Divisions only: the subtype to import (e.g. region, county, locality)." }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[west, south, east, north], WGS84 — legacy alternative to scope; imports as an intersect rectangle." }, "release": { "type": "string", "description": "Overture release (e.g. 2026-06-17.0); newest known when omitted." }, "category": { "type": "string", "description": "Places-only category filter." }, "name": { "type": "string", "description": "Optional table name." }, "projectId": { "type": [ "string", "null" ], "description": "The project every created table joins; omitted or null, unfiled. An unknown project refuses before the source is contacted. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } }, "required": [ "theme" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/count": { "post": { "summary": "Preview an Overture import's row count", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Counts what an import with the same body would land — same scope resolution, same filters — and returns the source query. Use it to sanity-check a selection before importing. With byLevel: true (divisions only) it returns every admin level's count under the scope in one call — the level picker's numbers — instead of a single count.", "tags": [ "Tables" ], "x-tool": "preview_overture_import", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Previewed an Overture import" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string" }, "scope": { "$ref": "#/components/schemas/OvertureScope" }, "semantics": { "type": "string", "enum": [ "within", "intersect" ] }, "level": { "type": "string" }, "byLevel": { "type": "boolean", "description": "Divisions only: return per-level scoped counts with samples instead of one number." }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "release": { "type": "string" }, "category": { "type": "string" } }, "required": [ "theme" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The count and the source query — or, with byLevel, the per-level counts (levels with zero matches are absent).", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "query": { "type": "string" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "subtype": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "samples": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/preview": { "post": { "summary": "Run an Overture query and return its features", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Runs exactly the query an import with the same body would run and returns the matching features as GeoJSON — capped by the render cap with truncation stated — so a selection can be inspected on a map before importing (the dialog's Run Query button). The answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built; above it the preview answers 422 render_bytes_exceeded with no partial result. The import is not held to that limit.", "tags": [ "Tables" ], "x-tool": "run_overture_query", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Ran an Overture query" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string" }, "scope": { "$ref": "#/components/schemas/OvertureScope" }, "semantics": { "type": "string", "enum": [ "within", "intersect" ] }, "level": { "type": "string" }, "release": { "type": "string" }, "category": { "type": "string" } }, "required": [ "theme" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The matching features, capped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturePreview" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/divisions/countries": { "get": { "summary": "List countries in Overture divisions", "description": "Countries present in a release's division data, by ISO code — the roots of the scope picker.", "tags": [ "Tables" ], "x-tool": "list_overture_countries", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed Overture countries" }, "parameters": [ { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Countries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[west, south, east, north] extent." } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Countries." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/divisions/levels": { "get": { "summary": "List a country's division levels", "description": "The admin levels that actually exist in a country's division data, with counts and sample names — Overture's vocabulary lands differently per country (German municipalities are one subtype, French communes another), so levels are discovered, never assumed.", "tags": [ "Tables" ], "x-tool": "list_overture_division_levels", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed Overture division levels" }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Levels, coarse to fine.", "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string" }, "country": { "type": "string" }, "levels": { "type": "array", "items": { "type": "object", "properties": { "subtype": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "samples": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Levels, coarse to fine." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/divisions/states": { "get": { "summary": "List a country's states", "description": "The country's state/region divisions with ISO 3166-2 codes — each is a scope: {type: \"state\", code}. Empty when the country has no region level.", "tags": [ "Tables" ], "x-tool": "list_overture_states", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed Overture states" }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "States, alphabetical.", "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string" }, "states": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[west, south, east, north] extent." } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "States, alphabetical." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/divisions/search": { "get": { "summary": "Find a division by name", "description": "Name search over a country's divisions (cities, municipalities, counties) for the typed city scope — matched against the division data itself, never a geocoder. The returned id is a scope: {type: \"division\", id}.", "tags": [ "Tables" ], "x-tool": "search_overture_divisions", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Searched Overture divisions" }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Name text; prefix matches rank first." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Ranked matches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subtype": { "type": "string" }, "kind": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[west, south, east, north] extent." } } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Two-letter ISO country code." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Name text; prefix matches rank first." }, { "name": "release", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Release; newest known when omitted." } ], "responses": { "200": { "description": "Ranked matches." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/osm": { "post": { "summary": "Import OpenStreetMap data as tables", "description": "At most 16,777,216 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. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Queries the configured Overpass endpoint and lands the result as GeoParquet tables split by geometry class (stem_points / stem_lines / stem_polygons, non-empty classes only) — one import group with one stored query, refreshed together. Provide selectors (tag filters like [\"amenity=restaurant\"]) with a bbox, or a raw OverpassQL query (the escape hatch; overpass-turbo's {{bbox}} is honoured). Either way the server applies its safety envelope (output format, timeout, size). Tags land as one JSON column plus promoted plain columns for name and the queried keys. Identical queries within the cache window do not re-hit the endpoint.", "tags": [ "Tables" ], "x-tool": "import_table_from_osm", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": "tables.*.id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Imported OpenStreetMap data" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selectors": { "type": "array", "items": { "type": "string" }, "description": "Tag selectors: \"key\" or \"key=value\" entries." }, "ql": { "type": "string", "description": "Raw OverpassQL (alternative to selectors); the safety envelope replaces any declared settings." }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[west, south, east, north], WGS84." }, "ring": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "description": "Drawn polygon [[lng, lat], …] (≤ 500 points) — alternative to bbox; becomes an Overpass poly filter." }, "geometry": { "type": "object", "description": "A GeoJSON Polygon or MultiPolygon (≤ 20,000 vertices) as the area — e.g. a feature from an existing table. Each part becomes an Overpass poly filter; holes apply in the post-fetch within filter. Takes precedence over ring/bbox." }, "semantics": { "type": "string", "enum": [ "within", "intersect" ], "description": "within keeps only features entirely inside the drawn shape (enforced server-side after geometry assembly — Overpass itself returns intersections); the default is intersect." }, "name": { "type": "string", "description": "Optional table-name stem." }, "projectId": { "type": [ "string", "null" ], "description": "The project every created table joins; omitted or null, unfiled. An unknown project refuses before the source is contacted. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created tables, one per non-empty geometry class.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tables": { "$ref": "#/components/schemas/TableList" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/osm/preview": { "post": { "summary": "Run an OSM query and return its features", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Runs exactly the Overpass fetch an import with the same body would run — same assembly and within filter — and returns the features as GeoJSON, capped by the render cap. The response is served from the query cache when possible, and a following import reuses it. The answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted while the features are assembled; above it the preview answers 422 render_bytes_exceeded with no partial result. The import is not held to that limit.", "tags": [ "Tables" ], "x-tool": "run_osm_query", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Ran an OpenStreetMap query" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "selectors": { "type": "array", "items": { "type": "string" } }, "ql": { "type": "string" }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "ring": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "geometry": { "type": "object", "description": "GeoJSON Polygon/MultiPolygon area (≤ 20,000 vertices)." }, "semantics": { "type": "string", "enum": [ "within", "intersect" ] }, "name": { "type": "string" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The matching features, capped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturePreview" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/overture/releases": { "get": { "summary": "List Overture releases", "description": "Available releases, newest first.", "tags": [ "Tables" ], "x-tool": "list_overture_releases", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed Overture releases" }, "responses": { "200": { "description": "Releases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "releases": { "type": "array", "items": { "type": "string" } }, "latest": { "type": "string" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Releases." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis": { "get": { "summary": "List PostGIS connections", "description": "Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Saved connections — passwords are write-only and never appear in any response.", "tags": [ "Connections" ], "x-tool": "list_postgis_connections", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the PostGIS connections" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PgConnectionList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create a PostGIS connection", "description": "At most 16,777,216 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. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Tests the connection first and saves only on success — nothing broken is ever stored. The password is encrypted at rest and never returned.", "tags": [ "Connections" ], "x-tool": "create_postgis_connection", "x-effects": { "readOnly": false, "writes": [ { "resource": "connections", "collection": true, "result": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Created the connection {subject}", "subject": { "resource": "connections", "result": "id", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "writeOnly": true, "description": "A Postgres URL or libpq key-value string. It is interpreted once and never stored or returned. SSL mode require maps to SSL required; prefer, disable and allow map to SSL not required (outgoing prefer, which may still negotiate TLS). Verify-ca, verify-full, unknown and conflicting repeated modes are refused before source contact, even with explicit fields. Identical repeats are accepted; empty modes are absent. Absent mode defaults to SSL required on create. Explicit fields override only a valid URL. Both string forms refuse unsupported protection requests before source contact or explicit-field overrides. Nonempty options, service and min_protocol_version are refused. Every occurrence is checked, with case-insensitive inventory names; encoding, repeats and URI fragments cannot hide a refusal. HTTP 400 invalid_request: This connection string uses the unsupported protection parameter channel_binding; Dezfil supports connection fields and SSL required or not required. The first refused parameter's canonical name replaces channel_binding; the existing SSL-mode refusal wins. Saved connections are not rechecked because their original string was never stored. See https://dezfil.io/docs/api/http-api/ (Connections) for parameter dispositions." }, "host": { "type": "string" }, "port": { "type": "integer", "default": 5432 }, "database": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "writeOnly": true, "description": "Write-only — never echoed back." }, "ssl": { "type": "boolean", "default": true } }, "required": [ "name" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created and tested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PgConnection" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Connections" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis/{id}": { "patch": { "summary": "Update a PostGIS connection", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Accepts any subset of editable fields. Connectivity changes are tested as a merged candidate before storage. A blank or omitted password keeps the stored password only when the host and port still identify the saved endpoint and the update does not turn SSL off. Changing the host or port, or turning SSL off, requires an entered password. Credentials and a submitted URL are never returned.", "tags": [ "Connections" ], "x-tool": "update_postgis_connection", "x-effects": { "readOnly": false, "writes": [ { "resource": "connections", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated the connection {subject}", "subject": { "resource": "connections", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "writeOnly": true, "description": "A Postgres URL or libpq key-value string. An individually supplied field wins over its valid URL part. SSL mode require maps to SSL required; prefer, disable and allow map to SSL not required (outgoing prefer, which may still negotiate TLS). Verify-ca, verify-full, unknown and conflicting repeated modes are refused before source contact, even with explicit fields. Identical repeats are accepted; empty modes are absent. Absent mode retains the saved SSL setting on edit. Both string forms refuse unsupported protection requests before source contact or explicit-field overrides. Nonempty options, service and min_protocol_version are refused. Every occurrence is checked, with case-insensitive inventory names; encoding, repeats and URI fragments cannot hide a refusal. HTTP 400 invalid_request: This connection string uses the unsupported protection parameter channel_binding; Dezfil supports connection fields and SSL required or not required. The first refused parameter's canonical name replaces channel_binding; the existing SSL-mode refusal wins. Saved connections are not rechecked because their original string was never stored. See https://dezfil.io/docs/api/http-api/ (Connections) for parameter dispositions." }, "host": { "type": "string" }, "port": { "type": "integer" }, "database": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "writeOnly": true, "description": "Write-only. Blank or omitted keeps the stored password." }, "ssl": { "type": "boolean", "description": "True requires SSL; false does not require it." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PgConnection" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a PostGIS connection", "description": "Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Imported snapshots stay intact; their refresh then reports the missing connection.", "tags": [ "Connections" ], "x-tool": "delete_postgis_connection", "x-effects": { "readOnly": false, "writes": [ { "resource": "connections", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "Imported snapshots remain. Their refresh will require a connection.", "subject": { "path": "/api/connections/postgis", "argument": "id", "name": "name", "collection": "", "identity": "id" } }, "x-display": { "verb": "Deleted the connection {subject}", "subject": { "resource": "connections", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis/{id}/test": { "post": { "summary": "Test a PostGIS connection", "description": "Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Reachability, authentication, and PostGIS presence — each failure is specific.", "tags": [ "Connections" ], "x-tool": "test_postgis_connection", "x-effects": { "readOnly": false, "writes": [ { "resource": "connections", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": true, "repeatability": "Identical calls may update retained working state and interact with external entities." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Tested the connection {subject}", "subject": { "resource": "connections", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PgConnection" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis/{id}/tables": { "get": { "summary": "List relations on a PostGIS connection", "description": "Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Lists importable tables, views, and materialized views with independent PostGIS-extension membership, geometry or geography facts, and honest planner-estimate states.", "tags": [ "Connections" ], "x-tool": "list_postgis_tables", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the relations of the connection {subject}", "subject": { "resource": "connections", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "200": { "description": "The source database's tables.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "schema": { "type": "string" }, "table": { "type": "string" }, "kind": { "type": "string", "enum": [ "table", "view", "materialized_view" ] }, "system": { "type": "boolean", "description": "True only for a relation that belongs to the PostGIS extension." }, "geometryColumn": { "type": [ "string", "null" ] }, "geometryType": { "type": [ "string", "null" ] }, "srid": { "type": [ "integer", "null" ] }, "spatialKind": { "type": [ "string", "null" ], "enum": [ "geometry", "geography", null ] }, "approxRows": { "type": [ "integer", "null" ], "minimum": 0, "description": "Omitted for a view, null for a never-analyzed table or materialized view, and numeric otherwise. Zero is a known estimate." } }, "required": [ "schema", "table", "kind", "system", "geometryColumn", "geometryType", "srid", "spatialKind" ] } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Connections" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "200": { "description": "The source database's tables." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis/{id}/preview": { "post": { "summary": "Preview a PostGIS relation", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Reads at most five rows from one saved connection and relation. The complete uncompressed UTF-8 JSON answer (columns and rows, excluding internal health) has a fixed 33,554,432-byte (32 MiB) ceiling; each non-geometry column value, including nested values and escaping, has a 2,097,152-byte (2 MiB) ceiling. Equality is admitted. Only source geometry/geography columns identified by source type, returned as WKT, are exempt from the cell ceiling. Text/JSON coordinates remain non-geometry. Excess refuses the whole answer with HTTP 422 query_result_too_large, without partial rows. The optional WHERE expression passes through the import guard and is applied to the preview. The caller cannot supply credentials, source SQL, or a row limit. Caller departure prevents later stages of this preview and discards late results (empty HTTP 499). Every source connection opened by the preview attachment has a 30-second per-statement ceiling; timeout answers HTTP 408 query_timeout. A departed caller's blocked source statement runs to that ceiling: the interrupt is observed between scan chunks and cannot reach a scan blocked in a libpq read. The aborted case's 35-second bound on responsive source and transport is met by the ceiling and is not evidence of interrupt propagation. The preview records nothing about the connection: neither its success nor any failure, cancellation or timeout changes the stored health, which answers for the last connection test, import or refresh. Connection tests, catalogue reads, imports and refreshes keep their existing limits.", "tags": [ "Connections" ], "x-tool": "preview_postgis_relation", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Previewed a relation of the connection {subject}", "subject": { "resource": "connections", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "schema": { "type": "string" }, "table": { "type": "string" }, "filter": { "type": "string", "description": "Optional WHERE expression evaluated on the source." } }, "required": [ "schema", "table" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The relation columns and up to five filtered source rows. Columns remain present when no row matches.", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "spatialKind": { "type": [ "string", "null" ], "enum": [ "geometry", "geography", null ] } }, "required": [ "name", "type", "spatialKind" ] } }, "rows": { "type": "array", "maxItems": 5, "items": { "type": "object", "additionalProperties": true } } }, "required": [ "columns", "rows" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "408": { "description": "query_timeout: The PostGIS source query took too long." }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "499": { "description": "The caller departed. Empty response." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/connections/postgis/{id}/snapshots": { "get": { "summary": "List snapshots for a PostGIS connection", "description": "Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Returns exactly the workspace tables whose stored provenance carries this connection id, including refresh and recipe facts.", "tags": [ "Connections" ], "x-tool": "list_postgis_snapshots", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the snapshots of the connection {subject}", "subject": { "resource": "connections", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "200": { "description": "The connection's workspace snapshots.", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshots": { "$ref": "#/components/schemas/TableList" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Connections" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "200": { "description": "The connection's workspace snapshots." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/imports/postgis": { "post": { "summary": "Import a PostGIS table as a snapshot", "description": "At most 16,777,216 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. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Materializes the table as a GeoParquet snapshot — read-only against the source, geometry normalized to WGS84 on the source side. An optional attribute filter and row limit narrow the import and become part of the stored import parameters, so refresh honours them. Live federation is deliberately not offered.", "tags": [ "Tables" ], "x-tool": "import_table_from_postgis", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": "id" }, { "resource": "connections", "collection": true, "argument": "connectionId" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Imported a PostGIS table as {subject}", "subject": { "resource": "tables", "result": "id", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string" }, "schema": { "type": "string" }, "table": { "type": "string" }, "name": { "type": "string", "description": "Optional table name." }, "filter": { "type": "string", "description": "Optional WHERE expression evaluated on the source." }, "limit": { "type": "integer", "description": "Optional row limit." }, "projectId": { "type": [ "string", "null" ], "description": "The project every created table joins; omitted or null, unfiled. An unknown project refuses before the source is contacted. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } }, "required": [ "connectionId", "schema", "table" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}/refresh": { "post": { "summary": "Refresh an imported table", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Re-runs the table's stored import (URL, Overture, and OSM imports) and replaces its data atomically. A failed refresh leaves the previous data fully intact. Dependent layers pick up the refreshed data on their next render. Overture tables accept an optional release (\"latest\" or a specific one) to move the stored import parameters — an explicit choice, never implicit. Refreshing any table of an OSM import group re-runs the stored query once (bypassing the cache) and updates every table of the group together. Refresh is single-flight per table (per group for OSM): while one runs, a second request answers 409 refresh_in_flight without starting another build; retry when the running refresh completes. A table deleted while its refresh runs answers 404 not_found and nothing is replaced. A saved manual geometry choice on a URL import replays against fresh source columns before automatic conversion, survives restart, and commits with the artifact and geometryRecord. Missing selected columns fail atomically with 400 column_unavailable; bad rows remain null geometries and are counted. Each container member keeps its own choice and the group downloads once and publishes together. Clear removes the override: the next refresh resumes automatic recognition, records its fresh result and resets geometry mode to unmodified. An unusable saved choice refuses atomically with 422 geometry_choice_invalid, including projection_required or conflicting_crs issues. A changed generation refuses with 409 input_changed.", "tags": [ "Tables" ], "x-tool": "refresh_table", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" }, { "resource": "connections", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": true, "repeatability": "Identical calls may update retained working state and interact with external entities." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Refreshed the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "requestBody": { "x-byte-limit": 16777216, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "release": { "type": "string", "description": "Overture only: \"latest\" or a release like 2026-06-17.0." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}/features": { "get": { "summary": "Read a table's features as GeoJSON", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. The table's features as a GeoJSON FeatureCollection, for drawing it as a reference layer (the import dialog's map legend and Select from Layer use this). A table that cannot draw — no geometry column, more features than the render cap, or a complete uncompressed answer over Bytes drawn per layer — returns ok:false with a plain-language reason and no features instead of an error. With sample=1 an over-cap table draws its first cap-many features and flags the response as sampled, unless that sample is itself over the byte limit.", "tags": [ "Tables" ], "x-tool": "get_table_features", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the features of the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "x-relevance": [ "builder", "sql", "workflow" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." }, { "name": "sample", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Draw a capped subset of an over-cap table instead of refusing; the response carries sampled + totalCount. A sample over Bytes drawn per layer is still refused." } ], "responses": { "200": { "description": "The features, or an honest refusal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "name": { "type": "string" }, "geometryType": { "type": [ "string", "null" ] }, "featureCount": { "type": "integer" }, "geojson": { "type": "object", "description": "FeatureCollection when ok; features carry a stable numeric id." }, "sampled": { "type": "boolean", "description": "True when a capped subset was drawn." }, "totalCount": { "type": "integer", "description": "The table's real row count when sampled." }, "reason": { "type": "string", "description": "Why the table cannot draw, when not ok." } }, "required": [ "ok", "name" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." }, { "name": "sample", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Draw a capped subset of an over-cap table instead of refusing; the response carries sampled + totalCount. A sample over Bytes drawn per layer is still refused." } ], "responses": { "200": { "description": "The features, or an honest refusal." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}/export": { "get": { "summary": "Download a table", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. The table as a file download: geoparquet streams the stored artifact byte-for-byte; geojson (spatial tables only) and csv (geometry as WKT) are converted on the fly. The response is an attachment named ..", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ], "default": "geoparquet" }, "description": "Download format; geoparquet when omitted." } ], "responses": { "200": { "description": "The file, as an attachment.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Unknown format, or GeoJSON asked of a non-spatial table." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ], "default": "geoparquet" }, "description": "Download format; geoparquet when omitted." } ], "responses": { "200": { "description": "The file, as an attachment." }, "400": { "description": "Unknown format, or GeoJSON asked of a non-spatial table." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/tables/{name}": { "get": { "summary": "Inspect a table", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Schema, row count, and a fifty-row preview. Preview text values, and the registered geometry column's WKT, longer than 512 characters show their first 512 characters followed by an ellipsis (…); other values, nested values, additional geometry columns, the schema, the row count and the stored data are never excerpted. The complete uncompressed UTF-8 JSON answer, including metadata, schema and envelope, is limited to 33,554,432 bytes (32 MiB); a non-geometry column value after excerpts, including nested values and escaping, to 2,097,152 bytes (2 MiB). Equality is admitted. Only the registered native geometry column, emitted as WKT, is exempt from the cell ceiling. Exceeding either bound refuses the whole inspection with HTTP 422 query_result_too_large, without partial data. The limits have no setting and do not apply to layer reads, dataset map features, file exports or owner deletion. A refused inspection leaves the dataset detail and its set-geometry panel unavailable.", "tags": [ "Tables" ], "x-tool": "inspect_table", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Inspected the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "x-relevance": [ "builder", "sql", "workflow" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableInspection" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a table", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. ", "tags": [ "Tables" ], "x-tool": "delete_table", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This deletes the dataset and its data. Layers that read it will lose their source.", "subject": { "path": "/api/catalogue/tables?names={name}", "argument": "name", "name": "name", "collection": "tables", "identity": "name" } }, "x-display": { "verb": "Deleted the dataset {subject}", "subject": { "resource": "tables", "argument": "name" } }, "x-confirm": true, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/operations": { "get": { "summary": "List the operations this instance offers", "description": "The instance-wide operation catalog, shared by every authenticated account: each verb's id, group, the input geometry it accepts, and its parameters. Read this to discover what may be passed to the run endpoint.", "tags": [ "Operations" ], "x-tool": "list_operations", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the operations" }, "x-relevance": [ "builder", "workflow" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationCatalog" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Operations" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/operations/run": { "post": { "summary": "Run an operation", "description": "At most 16,777,216 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. Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. Accepts one operation and answers **202** with a run, before the work is done; poll the run's own resource for its outcome. An accepted run outlives the request that started it. Closing the connection does not stop it.\n\nWhat is refused here, and what is reported on the run, is a fixed line. Refused immediately, minting no run: a malformed body, an unknown operation, SQL that is not an accepted read-only SELECT, an output name already taken, and a full queue. Reported on the run instead: SQL that parses but fails to bind or execute, a name taken between acceptance and commit, the engine memory budget, the execution budget, and a server stopped mid-run.\n\nSet dryRun to ask what the operation would produce without writing anything; a dry run is synchronous and mints no run.\n\nA parameter that names a dataset takes the caller's own dataset by its bare name, and another person's dataset the caller reaches by its qualified name, .; a dataset out of reach is refused exactly as one that does not exist.\n\nGive `writtenIn` when the parameters were written in a map's home or a workflow (a result previewed there and saved as a dataset, a tool previewing a layer's SQL): they are carried into the caller's own console, where a run reads its names, and the output is the caller's own dataset either way. Each dataset reference keeps the dataset it meant where it was written: a plain name of a dataset the destination's SQL home does not own, or whose name an output there takes, becomes .; an already qualified name stays as written; a workflow's own output becomes the dataset the caller's latest successful run of it made. Only those references change; the rest of the text is kept as written, and nothing where it came from is touched. A reference that cannot be carried (a dataset outside the caller's reach, an output the caller has not produced, a computed table name that would have to change) refuses the request with sql_error naming it, and nothing is written.\n\nOnly one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail. **sql_step** keeps the result of a read-only SELECT as a dataset: the escape hatch inside any recipe, and the way to save a query you already trust. A result with no geometry is an ordinary dataset, not a failure.\n\n**Measurements are ground metres.** A buffer's radius and a measured length are metres on the earth, at the latitude the data occupies, never degrees or metres on a map projection. They are measured in a transverse Mercator centred on the data's own extent, every input counted, and the output's provenance records it. Data too wide for that to hold within 1 % everywhere, or crossing the antimeridian, is **refused** for a distance with `measurement_crs_unavailable`, naming its width and extent; an **area** over the same data succeeds, because every area is measured in a global equal-area projection. An input whose coordinate system was assumed rather than declared is measured anyway and the answer says so, on the dry run, on the accepted run, and on the output.", "tags": [ "Operations" ], "x-tool": "run_operation", "x-effects": { "readOnly": false, "writes": [ { "resource": "runs", "collection": true, "result": "run.id" }, { "resource": "tables", "collection": true } ], "planningArgument": "dryRun" }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Ran the operation {arg.operation}", "planningVerb": "Planned the operation {arg.operation}" }, "x-relevance": [ "builder", "workflow" ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "An operation id from the catalog." }, "parameters": { "type": "object", "description": "The operation's own parameters, as the catalog describes them." }, "subject": { "type": "string", "description": "Groups this run with others in history, so 'when did this last succeed' has an answer across re-runs. Omitted, the run is its own subject." }, "dryRun": { "type": "boolean", "description": "Report what the run would produce and write nothing." }, "writtenIn": { "$ref": "#/components/schemas/WrittenIn", "description": "Where `parameters` were written, when not the caller's own console; they are carried into it." } }, "required": [ "operation", "parameters" ] }, "examples": { "saveAsDataset": { "summary": "Save a query's result as the dataset big_cities", "description": "Needs a token and the dataset world_cities. The run is accepted at once and writes big_cities when it finishes; read its outcome from the run.", "value": { "operation": "sql_step", "parameters": { "sql": "SELECT name, country, population, geometry FROM world_cities WHERE population > 10000000", "name": "big_cities" } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "What the run would produce; nothing written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDryRun" } } } }, "202": { "description": "Accepted; poll the run for its outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationRunEnvelope" }, "examples": { "saveAsDataset": { "summary": "Save a query's result as the dataset big_cities", "description": "Needs a token and the dataset world_cities. The run is accepted at once and writes big_cities when it finishes; read its outcome from the run.", "value": { "run": { "id": "e4a7c2b9-1f3d-4e6a-9c85-7b0d2f4a6e13", "operation": "sql_step", "state": "queued", "subject": { "kind": "run", "id": "e4a7c2b9-1f3d-4e6a-9c85-7b0d2f4a6e13" }, "parameters": { "sql": "SELECT name, country, population, geometry FROM world_cities WHERE population > 10000000", "name": "big_cities" }, "acceptedAt": "2026-10-20T09:00:01.494Z" } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/operations/runs": { "get": { "summary": "List operation runs", "description": "Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. Run history, newest first. Narrow to one subject to answer 'when did this last succeed'. A failed run never erases the successful one before it, so both are kept. History is bounded per subject, and a subject's most recent success is preserved even when the depth would otherwise drop it.", "tags": [ "Operations" ], "x-tool": "list_operation_runs", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the operation runs" }, "x-relevance": [ "workflow" ], "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only runs sharing this subject identity." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Most runs to return; newest first." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationRunList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Operations" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only runs sharing this subject identity." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Most runs to return; newest first." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/operations/runs/{id}": { "get": { "summary": "Read an operation run", "description": "Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. What a caller polls after the run endpoint accepted their operation. A succeeded run names its output dataset; a failed one carries a coded error. There is no completion percentage: a run reports when it started, and elapsed time follows from that.", "tags": [ "Operations" ], "x-tool": "get_operation_run", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the operation run {subject}", "subject": { "resource": "runs", "argument": "id" } }, "x-relevance": [ "workflow" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id.", "examples": { "saveAsDataset": { "summary": "Read the run that saved big_cities, once it finished", "value": "e4a7c2b9-1f3d-4e6a-9c85-7b0d2f4a6e13" } } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationRunEnvelope" }, "examples": { "saveAsDataset": { "summary": "Read the run that saved big_cities, once it finished", "description": "Needs a token and the run saving big_cities started. Until it finishes, its state is queued, then running: read it again until it is succeeded, failed or cancelled. A succeeded run names its dataset under output.", "value": { "run": { "id": "e4a7c2b9-1f3d-4e6a-9c85-7b0d2f4a6e13", "operation": "sql_step", "state": "succeeded", "subject": { "kind": "run", "id": "e4a7c2b9-1f3d-4e6a-9c85-7b0d2f4a6e13" }, "parameters": { "sql": "SELECT name, country, population, geometry FROM world_cities WHERE population > 10000000", "name": "big_cities" }, "acceptedAt": "2026-10-20T09:00:01.494Z", "startedAt": "2026-10-20T09:00:01.495Z", "finishedAt": "2026-10-20T09:00:01.503Z", "output": { "id": "c2e8f4a1-6b3d-4f97-a5c0-1d2e3f4a5b6c", "name": "big_cities" } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Operations" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/operations/runs/{id}/cancel": { "post": { "summary": "Cancel an operation run", "description": "Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. Stops a run for real: a queued one never starts, and a running one is interrupted in the engine rather than only in the record. A cancelled run leaves no dataset and no stranded file behind. Cancelling a run that has already finished is not an error. It answers the run unchanged, because 'make sure this is not running' is already true.", "tags": [ "Operations" ], "x-tool": "cancel_operation_run", "x-effects": { "readOnly": false, "writes": [ { "resource": "runs", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Cancelled the operation run {subject}", "subject": { "resource": "runs", "argument": "id" } }, "x-relevance": [ "workflow" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationRunEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes": { "get": { "summary": "List recipes", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Every recipe the caller reaches (their own, and every one filed in a project they own or belong to), each with its steps and their current conditions, what each step reads now, and a summary of the whole (its status and counts). A recipe is a workspace object like a dataset — not owned by a map, and outliving the layer that prompted it. `origin` narrows the answer to the workflows page's own (`workflow`) or the builder's one-step recipes (`builder`); unfiltered, both answer.", "tags": [ "Recipes" ], "x-tool": "list_recipes", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the workflows" }, "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "workflow", "builder" ] }, "description": "Which surface made the recipes wanted. Omitted, every recipe." }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create a recipe", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nA named, ordered list of steps. Dependencies may point only backwards, which is what keeps it authorable as a list and checkable without cycle detection at run time. The name is trimmed, must not be empty, and is at most 120 characters; two recipes may share one. `origin` says which surface is creating it — `workflow` (the default) or `builder`, the one-step Tools' invisible recipes — and never changes afterwards. Only workflows can be project members.", "tags": [ "Recipes" ], "x-tool": "create_recipe", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "result": "recipe.id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Created the workflow {subject}", "subject": { "resource": "recipes", "result": "recipe.id", "name": [ "recipe.name", "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "origin": { "type": "string", "enum": [ "workflow", "builder" ] }, "projectId": { "type": [ "string", "null" ], "description": "The project the new workflow joins; omitted or null, it starts unfiled. An unknown project refuses and creates nothing. Builder-origin recipes are refused project membership. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } }, "required": [ "name" ] }, "example": { "name": "Accidents near schools" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "workflow", "builder" ] }, "description": "Which surface made the recipes wanted. Omitted, every recipe." }, { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}": { "get": { "summary": "Read a recipe", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The recipe and every step in order, each with **all** the conditions true of it — broken, output missing, stale, never run, current — its stale causes with the input each came from, and its latest attempt as an ordinary run. The condition and the attempt are read together: fresh output with a failed latest attempt is a real and common combination.", "tags": [ "Recipes" ], "x-tool": "get_recipe", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Rename a recipe", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nThe same name rule as creation: trimmed, not empty, at most 120 characters, shared names allowed. Renaming moves the recipe's last-edited time, as adding, editing, reordering or removing a step does; running it does not.", "tags": [ "Recipes" ], "x-tool": "update_recipe", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeEnvelope" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a recipe", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Deletes the workflow, its steps, lineage and run records. **The datasets its steps produced remain in the workspace.** A recipe records how they were made; it does not own them.", "tags": [ "Recipes" ], "x-tool": "delete_recipe", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This deletes the workflow and its run records. Its output datasets remain in the workspace.", "subject": { "path": "/api/recipes/{id}", "argument": "id", "name": "recipe.name" } }, "x-display": { "verb": "Deleted the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDeleted" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/duplicate": { "post": { "summary": "Duplicate a recipe", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. A copy named \" copy\", a workflow, that has never run: the same steps in the same order under fresh ids, each from its active definition (a pending edit is not carried) with its layer provenance; every output renamed to a free name; every read of an original output redirected to the copy's, in named inputs and in SQL table references alike, with literals and comments untouched. The original and its datasets are unchanged. Refused (409) if the recipe changes while the copy is prepared, and (422) if a step's SQL cannot be rewritten to read the copy's outputs.", "tags": [ "Recipes" ], "x-tool": "duplicate_recipe", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "result": "recipe.id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Duplicated a workflow as {subject}", "subject": { "resource": "recipes", "result": "recipe.id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/dependencies": { "get": { "summary": "The datasets a workflow reads and writes", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Each step's references resolve to dataset identities in the workflow's SQL home within the caller's reach, the workflow's own outputs as the caller would run them, and each one is listed with its owner and the name the caller would type: a dataset the caller cannot reach is left out rather than named, and a same-named dataset of the caller's own never stands in for the home's. Memberships name the projects the caller reaches, and on the caller's own datasets every project they are in, one the caller no longer reaches included; producers only workflows the caller reaches, each marked with whether the caller owns it. The filing checklist's subject for a workflow: every registered dataset the workflow's current node definitions read (a pending edit over the active one) and every runner's recorded output of the workflow that the caller reaches, exactly once — a dataset both read and written appears once — with the same facts as a map's dependencies: source, row count, project memberships, the producing workflow, geometry column and sampled geometry type. A node whose definition cannot be analyzed fails the whole read with `dependencies_unresolved`; unlike the recipe read, which tolerates an unreadable node, this read never answers partially.", "tags": [ "Recipes" ], "x-tool": "get_workflow_dependencies", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the datasets of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDependencies" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/layout": { "get": { "summary": "Read a recipe's canvas layout", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The layout document: where each step and each source sits on the canvas, and the notes written around them. Stored beside the recipe, never inside it: nothing here changes what a run does or what a step reads. A recipe never arranged reads as the empty document with no write time. A read never names a step the recipe no longer has.", "tags": [ "Recipes" ], "x-tool": "get_recipe_layout", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the layout of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeLayoutEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "put": { "summary": "Replace a recipe's canvas layout", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nReplaces the whole document and answers with it as stored; there is no partial update, and `{}` is the empty document. A position for a step id the recipe does not have is dropped, not refused. Anything else wrong (a position that is not two finite numbers, more than 1,000 step positions, more than 1,000 source positions, a step or source key past 1,000 characters, a note missing a field, a colour outside the six, text past 4,000 characters, a non-positive size, a blank or duplicated note id, more than 100 notes) is refused whole (400) naming the first fault, and nothing is stored. A write that changes the document moves the recipe's last-edited time; one that stores what was already stored does not. Last write wins.", "tags": [ "Recipes" ], "x-tool": "set_recipe_layout", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Arranged the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeLayoutInput" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeLayoutEnvelope" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/steps": { "post": { "summary": "Add a step", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nAppends a step naming an operation from the catalog, its parameters, and the dataset it will produce.\n\n**The output's name**: stored in the registry's form; a blank or letterless name is refused in its own words; a name a registered table carries, or another step of this recipe declares or holds, is refused (`name_taken`) naming the holder. Another recipe's unrun declaration is no reservation. A step may be added unnamed; the run refuses a nameless one. **SQL the parser cannot read is accepted** with no present reads; the dry run and the run refuse it and say why.\n\nGive `fromLayerId` to author it from a layer: the step takes that layer's SQL **refined by its filters**, captured now and never re-read, so the step stays reproducible when the filters later change. Where the layer is drawn as hex bins, grid cells or origin–destination lines, the step consumes the **rows behind** those cells rather than the cells themselves, and the answer says so in `origin.substitutionNote`. Any layer the caller reaches can be captured, its SQL carried from its map's home into this workflow's context; one the caller does not reach answers as a missing one.\n\nGive `writtenIn` when the parameters were written elsewhere (a node copied from another workflow, the caller's console, a map): their dataset inputs and SQL are carried into this workflow's context, where this step's own output already takes its name. Each dataset reference keeps the dataset it meant where it was written: a plain name of a dataset the destination's SQL home does not own, or whose name an output there takes, becomes .; an already qualified name stays as written; a workflow's own output becomes the dataset the caller's latest successful run of it made. Only those references change; the rest of the text is kept as written, and nothing where it came from is touched. A reference that cannot be carried (a dataset outside the caller's reach, an output the caller has not produced, a computed table name that would have to change) refuses the request with sql_error naming it, and nothing is written.\n\nA step that would read its own output, or a later step's, is refused here rather than at run time.", "tags": [ "Recipes" ], "x-tool": "add_recipe_step", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Added a step to the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "An operation id from the catalog." }, "parameters": { "type": "object", "description": "The operation's own parameters, as the catalog describes them — including non-scalar ones, which are kept as sent." }, "fromLayerId": { "type": "string", "description": "Author from this layer: its filtered SQL is captured into the step's `sql` parameter, carried from the layer's map into this workflow." }, "writtenIn": { "$ref": "#/components/schemas/WrittenIn", "description": "Where `parameters` were written, when not in this workflow; they are carried into it." } }, "required": [ "operation" ] }, "example": { "operation": "spatial_join", "parameters": { "left": "boroughs", "right": "accidents", "predicate": "contains", "carry": [ { "aggregate": "count" } ], "name": "boroughs_with_accidents" } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeStepEnvelope" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/steps/{stepId}": { "get": { "summary": "Read a step", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. One step's definition, condition, stale causes, recorded inputs and latest attempt.", "tags": [ "Recipes" ], "x-tool": "get_recipe_step", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read a step of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeStepEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Edit a step", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\n**A change to a step that has already produced something is a proposal.** The step keeps meaning what its output was produced from until a run of the proposal succeeds; `applied` says which of the two happened — `active` for a step that had produced nothing, `proposed` otherwise. An edit that puts the active definition back clears the pending one and answers `active`.\n\n**Reading a later step's output orders the recipe rather than refusing**: the reader and everything depending on it move after the producer, other steps keep their places, the whole order is checked, and the edit and the order land together or not at all; a self-read is refused. **A produced output's name is frozen**; before the first run the name rule of adding applies. **SQL the parser cannot read is accepted** with no present reads. Refused (409) if the recipe changed while the edit was checked.", "tags": [ "Recipes" ], "x-tool": "update_recipe_step", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Edited a step of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parameters": { "type": "object" }, "fromLayerId": { "type": "string", "description": "Re-author from this layer, any the caller reaches: its filtered SQL is captured and carried from its map into this workflow." }, "writtenIn": { "$ref": "#/components/schemas/WrittenIn", "description": "Where `parameters` were written, when not in this workflow; they are carried into it as an add's are." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeStepEdited" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Remove a step", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. The step detaches: **the dataset it produced and its run history both survive**, and a step that reads that dataset goes on reading it as an ordinary workspace table. The answer says what is true: whether that dataset `exists`, was `deleted` since, or `never` was, and which steps read its name.", "tags": [ "Recipes" ], "x-tool": "remove_recipe_step", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Remove {target}?", "consequence": "This removes the node from its workflow. Existing output datasets and run history remain.", "subject": { "path": "/api/recipes/{id}/steps/{stepId}", "argument": "stepId", "name": "step.parameters.name" } }, "x-display": { "verb": "Removed a step from the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "x-confirm": true, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeStepRemoved" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/steps/{stepId}/proposal": { "delete": { "summary": "Discard a step's pending edit", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Puts the step back to its active definition — what its output was produced from — and changes nothing else. A step holding no pending edit is unchanged, and `discarded` says so.", "tags": [ "Recipes" ], "x-tool": "discard_recipe_step_edit", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Discarded a step's pending edit on the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeStepDiscarded" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/steps/{stepId}/move": { "post": { "summary": "Reorder a step", "description": "A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nMoves the step to a position, rewriting the ordinals densely. **The whole proposed ordering is checked**, not just the step that moved: dragging a producer downwards breaks its consumers rather than itself, and a reorder that would leave the recipe invalid is refused with nothing changed.", "tags": [ "Recipes" ], "x-tool": "move_recipe_step", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Moved a step of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ordinal": { "type": "integer", "description": "Zero-based position to move it to." } }, "required": [ "ordinal" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeEnvelope" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/steps/{stepId}/run": { "post": { "summary": "Run one step", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Answers **202** with one of the recipe's runs: a run of kind `single` with this one member, listed among the recipe's runs and read and cancelled through them; poll `/api/recipes/{id}/runs/{runId}` for its outcome. **This runs the step and nothing else** — carrying its dependents is the recipe-run endpoint's job.\n\nA re-run replaces the same runner's earlier output of the step **in place**, keeping the dataset's id and name, so every layer built on it keeps pointing at fresh data with no re-wiring; another runner's output is never touched. A failed re-run leaves the previous output intact and queryable.\n\n**What a caller may rely on.** The recipe's one-run-at-a-time rule applies: while a run is in flight this answers **409 `run_in_flight`** naming it. Ordinarily, a step the API cannot admit alone is refused before anything exists: no run, no attempt. Narrow exception: if the run was already listable and cancellation was accepted before that refusal, the cancelled run remains with the refusal member and no attempt. The run stays with the recipe after the step is removed.", "tags": [ "Recipes" ], "x-tool": "run_recipe_step", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" }, { "resource": "runs", "collection": true, "result": "run.id" }, { "resource": "tables", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Ran a step of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "202": { "description": "Accepted; poll the recipe run for its outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunStarted" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "The revision is stale (`stale_revision`), or a run is already in flight (`run_in_flight`, naming it); nothing started." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "stepId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Step id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/runs": { "get": { "summary": "List a recipe's runs", "description": "Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Every cascade this recipe has had, newest first, each durable and readable long after it finished.", "tags": [ "Recipes" ], "x-tool": "list_recipe_runs", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the runs of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Run a recipe, or a step and its dependents", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. **Request body bound.** At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Ordinary maximum-shape layout documents fit; escape-inflated keys and unbounded note ids can exceed the outer byte bound and are refused by design.\n\nOmit `fromStepId` to run the whole recipe from the beginning; give one to re-run that step and everything that reads it, in dependency order. A step starts only once every step it reads has succeeded, and one whose dependency failed is **not attempted** — reported `not_run`, minting no run at all, with the failure that stopped it named. Steps that do not depend on the failure still run.\n\n**Ask first with `plan: true`.** It answers what the request would carry and the editRevision paired with that definition, without starting anything. Starting requires that revision in X-Edit-Revision, including when planning awaits asynchronous work. A changed basis refuses with stale_revision before any run or output exists. `wide` is true for a run of the whole recipe and for a re-run that carries dependents, and false for the same request aimed at a step nothing reads. That is what the `when_wide` confirmation on this operation means — confirm the wide cases, not the leaf.\n\nA recipe run is **not** an operation run: it answers **202** with its own resource, which has its own outcome and contains the members' ordinary runs.\n\n**What a caller may rely on.** A recipe runs one run at a time: a start while one is in flight — this operation's or a single step's — answers **409 `run_in_flight`** naming the run, and two starts that race yield one run and one refusal. A start that names `members` — the step ids a confirmation listed, in order — starts exactly when the plan at start is that set in that order, and answers **409 `plan_changed`** otherwise, nothing started. This membership check accompanies the start revision check. Each member is read when admitted. Each attempted member's record carries its attempt — state, error, times, output — kept with the run after the step's own history is pruned; a member never attempted has none; every member keeps its step's operation and name after the step is removed.", "tags": [ "Recipes" ], "x-tool": "run_recipe", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" }, { "resource": "runs", "collection": true, "result": "run.id" }, { "resource": "tables", "collection": true } ], "planningArgument": "plan" }, "x-mcp": { "destructiveHint": true, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Run {target}?", "consequence": "This runs the listed nodes in order and creates or replaces their output datasets.", "subject": { "path": "/api/recipes/{id}", "argument": "id", "name": "recipe.name" } }, "x-display": { "verb": "Ran the workflow {subject}", "planningVerb": "Planned the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "x-confirm": "when_wide", "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal. Required to start; plan: true is a read and requires none." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "requestBody": { "x-byte-limit": 16777216, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromStepId": { "type": "string", "description": "Re-run this step and its dependents. Omitted, the whole recipe runs." }, "plan": { "type": "boolean", "description": "Report what would be carried, and whether that is wide, without starting anything." }, "members": { "type": "array", "items": { "type": "string" }, "description": "The step ids a confirmation listed, in order. Given, the run starts only when the plan at start is exactly that set in that order; otherwise 409 `plan_changed`." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "What this would carry; nothing started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunPlan" } } } }, "202": { "description": "Accepted; poll the recipe run for its outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunStarted" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "The revision is stale (`stale_revision`), a run is already in flight (`run_in_flight`, naming it), or the plan no longer matches the confirmed `members` (`plan_changed`); nothing started." }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/runs/{runId}": { "get": { "summary": "Read a recipe run", "description": "Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. Its own outcome — completed, partly completed, failed, cancelled or interrupted — every member with what became of it, and every dataset it produced. A member reported `not_run` carries **no** run id, because nothing was minted for it.", "tags": [ "Recipes" ], "x-tool": "get_recipe_run", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read a run of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe run id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunEnvelope" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Recipes" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe run id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe run id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/runs/{runId}/cancel": { "post": { "summary": "Cancel a recipe run", "description": "Standalone run records and subject histories are private to their initiating account, including for administrators. Standalone jobs retain their initiating owner before any output exists, after failure and after output deletion; contained jobs follow their workflow, read by everyone who reaches it and cancelled by their initiator or the workflow's owner. Unreached and missing run identities return not_found before cancellation or private content reads. Subject grouping, history pruning and output-name conflicts are account-local. Workers recheck account activity before preparation and at publication; an inactive owner's unfinished job fails with authentication_required and keeps no new output, and an input another account owns that is no longer within the runner's reach when the output commits refuses it with sql_error naming the input as written. Workflow runs, member attempts and retained outputs follow their workflow: everyone who reaches it reads its runs, with output links out of the caller's reach left out. Planning and starting a run are open to whoever may change the workflow's content (its owner, the project's owner and its editors); a viewer is refused with forbidden before anything is planned. A run is its runner's: it reads in the workflow's SQL home within the runner's reach, its outputs are created as the runner's own datasets, never replacing anyone else's, and are filed into the workflow's project as it stands when each output commits, when the runner may file there; a rerun replaces only the same runner's earlier output of that step, and a dataset of the runner's already holding the name is refused with name_taken. A run is cancelled by its initiator or the workflow's owner; an initiator who no longer reaches the workflow still cancels their own run by its identifier, answered 204 without the run. Administrators reach nothing more. Every referenced step and run must belong to the addressed workflow; unreached, missing and mixed-parent references return not_found before planning or execution. Account activity is checked after planning, at worker entry and at publication. At each output's commit the runner's permission and reach to every input are checked again: an input another account owns that the runner no longer reaches refuses that output with sql_error naming it as written, even though the step already read it; a runner who may no longer run the workflow (no longer its editor, or no longer reaching it after it was unfiled, moved, dissolved out of its project or transferred) completes the steps already admitted privately, into their own datasets, unfiled, leaving the workflow's recorded outputs, proposals and definitions unchanged, and no further step is admitted; the run records each outcome. A workflow moved or transferred while running files each output into its project as it stands at commit. Deactivation prevents further admission and publication, drains admitted work and retains already committed outputs and terminal attempts. Results remain owned after step or output deletion and independent job-history pruning. Restart marks unfinished runs interrupted without executing them again. One thing to stop, whatever it was in the middle of: what has not started never starts. Every member found running when cancellation is accepted is cancelled before any member settlement is awaited; only a member already terminal at acceptance stays finished, and its output stands. Running members are interrupted **in the engine**, not only in the record. The run's own outcome is then `cancelled`, written once the last in-flight member has settled. Cancelling one that has already finished is not an error.", "tags": [ "Recipes" ], "x-tool": "cancel_recipe_run", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" }, { "resource": "runs", "collection": true, "argument": "runId" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Cancelled a run of the workflow {subject}", "subject": { "resource": "recipes", "argument": "id", "name": [ "recipe.name", "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe run id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeRunEnvelope" } } } }, "204": { "description": "Cancelled for its initiator, who no longer reaches the workflow: the run is not shown." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe id." }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Recipe run id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/query": { "post": { "summary": "Run read-only SQL", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail. Named datasets resolve only within the caller's reach: a plain name, and its catalog-qualified forms, is the caller's own dataset; another person's dataset the caller reaches through a project is ., and the caller's own SQL name qualifies their own. Both hold in query()/query_table() expressions and nested SQL. Each evaluation uses fresh connection-local views on one shared hardened engine. Returns a capped preview plus the exact total row count. Geometry cells in the preview are WKT text by default; pass geometry: \"geojson\" to receive GeoJSON geometry objects instead. The complete UTF-8 JSON answer is limited to 33,554,432 bytes (32 MiB), and each non-geometry cell to 2,097,152 bytes (2 MiB), including JSON escaping. Equality is admitted. Native GEOMETRY columns, including CRS-qualified types, count toward the result limit only. Geometry-looking text and explicit WKT/GeoJSON text remain non-geometry. An oversized answer is refused in full with HTTP 422 query_result_too_large, without partial rows. These fixed limits do not change row limits, engine budgets or exports. A failing statement answers with the engine's message and, when the location maps to the submitted text, a 1-based line and column into the submitted SQL.", "tags": [ "Query" ], "x-tool": "run_sql", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Ran a query" }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sql": { "type": "string", "description": "Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail." }, "geometry": { "type": "string", "enum": [ "wkt", "geojson" ], "description": "How geometry columns travel in the preview. Default wkt." }, "writtenIn": { "$ref": "#/components/schemas/WrittenIn", "description": "Evaluate the SQL where it was written: in a map's SQL home, as its layers are, or in a workflow's context with its declared outputs as the caller runs them, always within the caller's reach. A name that binds nothing there, when the home is someone else's, is refused naming it, as a layer's would be. Omitted or console, the caller's own console." } }, "required": [ "sql" ] }, "examples": { "quickstart": { "summary": "Query the three largest cities", "description": "Needs a token and the dataset world_cities, which the upload makes.", "value": { "sql": "SELECT name, country, population FROM world_cities ORDER BY population DESC LIMIT 3" } }, "unknownTable": { "summary": "Query a dataset that does not exist", "description": "Needs a token. No dataset need exist: the answer is the error.", "value": { "sql": "SELECT * FROM no_such_dataset" } }, "valueTooLarge": { "summary": "Query one value over 2 MiB", "description": "Needs a token. No dataset need exist: the one value is over the size a value may have in an answer, so no row is returned.", "value": { "sql": "SELECT repeat('x', 3000000) AS value" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" }, "examples": { "quickstart": { "summary": "Query the three largest cities", "description": "Needs a token and the dataset world_cities, which the upload makes.", "value": { "columns": [ { "name": "name", "type": "VARCHAR" }, { "name": "country", "type": "VARCHAR" }, { "name": "population", "type": "BIGINT" } ], "rowCount": 3, "preview": [ { "name": "Tokyo", "country": "Japan", "population": "35676000" }, { "name": "New York", "country": "United States of America", "population": "19040000" }, { "name": "Mexico City", "country": "Mexico", "population": "19028000" } ], "previewTruncated": false, "runtimeMs": 4 } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unknownTable": { "summary": "Query a dataset that does not exist", "description": "Needs a token. No dataset need exist: the answer is the error.", "value": { "error": { "code": "sql_error", "message": "The query refers to an unknown table.", "position": { "line": 1, "column": 15 } } } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "valueTooLarge": { "summary": "Query one value over 2 MiB", "description": "Needs a token. No dataset need exist: the one value is over the size a value may have in an answer, so no row is returned.", "value": { "error": { "code": "query_result_too_large", "message": "The result is too large to return: more than 32 MB in total, or one non-geometry value over 2 MB. Select fewer rows or columns, or shorten the value." } } } } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/query/export": { "post": { "summary": "Download a query's full result", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. Every row the SQL produces — not the capped preview the query operation returns — as a file: csv, geoparquet (plain parquet when the result has no geometry), or geojson, which needs a geometry column and is refused with a coded reason otherwise. The first geometry column is the feature geometry; every other geometry column travels as WKT. Runs on the hardened read-only instance under the universal query bound — timeout, memory budget, and cancellation when the caller departs. The response is an attachment named .; through the agent tool it arrives as a base64 attachment envelope.", "tags": [ "Query" ], "x-tool": "export_sql_result", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": false } }, "x-display": { "verb": "Exported a query result" }, "x-relevance": [ "sql" ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sql": { "type": "string", "description": "Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail." }, "format": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "name": { "type": "string", "description": "Download name without extension. Default query_result." }, "prepare": { "type": "boolean", "description": "The page's road: write the file and answer a single-use ticket instead of the bytes; redeem it with GET within a minute. Leave unset to receive the attachment directly." } }, "required": [ "sql", "format" ] }, "examples": { "csv": { "summary": "Download a query's result as CSV", "description": "Needs a token and the dataset world_cities. The answer is the file largest_cities.csv, every row of the result.", "value": { "sql": "SELECT name, country, population FROM world_cities ORDER BY population DESC LIMIT 3", "format": "csv", "name": "largest_cities" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The file, as an attachment — or, with prepare, a JSON ticket {ticket, key, format}.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket", "key", "format" ], "properties": { "ticket": { "type": "string" }, "key": { "type": "string" }, "format": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] } } } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" }, "examples": { "csv": { "summary": "Download a query's result as CSV", "description": "Needs a token and the dataset world_cities. The answer is the file largest_cities.csv, every row of the result.", "value": "name,country,population\nTokyo,Japan,35676000\nNew York,United States of America,19040000\nMexico City,Mexico,19028000\n" } } } } }, "400": { "description": "Unknown format, GeoJSON without geometry, invalid SQL, or the bounded lane's coded errors." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "get": { "summary": "Redeem a prepared query-result download", "description": "Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. The second half of the page's download road: a ticket from a prepare call streams its file once as a native attachment, bound to the SQL key and format it was prepared for. Tickets expire after a minute; a redeemed, expired or mismatched ticket answers 410. Not an agent tool — agents call the POST directly.", "tags": [ "Query" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ticket the prepare call answered." }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The key the prepare call answered." }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "description": "The format the ticket was prepared for." } ], "responses": { "200": { "description": "The file, as an attachment.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "410": { "description": "The ticket is gone." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Query" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ticket the prepare call answered." }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The key the prepare call answered." }, { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "description": "The format the ticket was prepared for." } ], "responses": { "200": { "description": "The file, as an attachment." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "410": { "description": "The ticket is gone." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps": { "get": { "summary": "List maps", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. ", "tags": [ "Maps" ], "x-tool": "list_maps", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the maps" }, "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapList" }, "examples": { "quickstart": { "summary": "List the maps of a new account", "description": "Needs a token. A new account reaches no map yet.", "value": [] }, "afterQuickstart": { "summary": "List the maps once World cities exists", "description": "Needs a token. Lists the quickstart's map after its basemap changed and it was unpublished.", "value": [ { "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "World cities", "viewport": { "lng": 0, "lat": 40, "zoom": 1.3, "pitch": 0, "bearing": 0 }, "basemap": "light", "customBasemap": null, "basemapLayers": null, "note": null, "legendCorner": null, "legendOrder": null, "timeline": null, "widgets": [], "widgetsPublished": true, "publishToken": null, "publishedAt": null, "published": false, "createdAt": "2026-10-20T09:00:01.507Z", "updatedAt": "2026-10-20T09:00:01.530Z", "editRevision": "2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c", "lastChangedAt": "2026-10-20T09:00:01.530Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "projectId": null, "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "home": "ana_diaz", "layerCount": 1, "layerColors": [ "rgba(18, 147, 154, 1)" ], "pictureState": "waiting", "pictureVersion": null, "hasThumbnail": false, "thumbnailBasemap": null } ] } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create a map", "description": "At most 16,777,216 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. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Optionally filed into a project at birth: an unknown project refuses and creates nothing. A new map takes the instance's defaults for its basemap, starting view and legend corner (`defaults` in the runtime configuration).", "tags": [ "Maps" ], "x-tool": "create_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "result": "id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Created the map {subject}", "subject": { "resource": "maps", "result": "id", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "projectId": { "type": [ "string", "null" ], "description": "The project the new map joins; omitted or null, it starts unfiled. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one." } } }, "examples": { "quickstart": { "summary": "Create the map World cities", "description": "Needs a token. The answer's editRevision is what the next change to the map sends.", "value": { "name": "World cities" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapCreated" }, "examples": { "quickstart": { "summary": "Create the map World cities", "description": "Needs a token. The answer's editRevision is what the next change to the map sends.", "value": { "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "World cities", "viewport": { "lng": 0, "lat": 40, "zoom": 1.3 }, "basemap": null, "customBasemap": null, "basemapLayers": null, "note": null, "legendCorner": null, "legendOrder": null, "timeline": null, "widgets": [], "widgetsPublished": true, "publishToken": null, "publishedAt": null, "published": false, "createdAt": "2026-10-20T09:00:01.507Z", "updatedAt": "2026-10-20T09:00:01.507Z", "editRevision": "4f1c9a7e2b0d4c6e8a1f3b5d7c9e0a2b", "lastChangedAt": "2026-10-20T09:00:01.507Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "projectId": null, "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "home": "ana_diaz" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "project", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; \"none\" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects": { "get": { "summary": "List projects", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. Every project the caller reaches, its own and those shared with it, with its member counts (maps, workflows as workflow-origin recipes, datasets, published maps), its size total — `sizeComplete` is false when a member dataset's size is unknown, so the sum is honest about being partial — and when it last changed. Most recent first.", "tags": [ "Projects" ], "x-tool": "list_projects", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the projects" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create a project", "description": "At most 16,777,216 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. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. The name is trimmed, must not be empty, and is at most 120 characters; two projects may share one. `members` files initial members in the same act — one invalid member means nothing is created at all. Only workflows can be project members.", "tags": [ "Projects" ], "x-tool": "create_project", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "result": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Created the project {subject}", "subject": { "resource": "projects", "result": "id", "name": [ "name" ] } }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "members": { "$ref": "#/components/schemas/ProjectMemberChange" } }, "required": [ "name" ] }, "example": { "name": "Berlin mobility study" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreated" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}": { "get": { "summary": "Read a project", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. One project with its member counts and size. Its workflows are workflow-origin recipes.", "tags": [ "Projects" ], "x-tool": "get_project", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the project {subject}", "subject": { "resource": "projects", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Rename a project or edit its note", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. Renaming and the note follow the creation rules; a null note clears it. Membership is not edited here — that is the members operation.", "tags": [ "Projects" ], "x-tool": "update_project", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated the project {subject}", "subject": { "resource": "projects", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "note": { "type": [ "string", "null" ] } } }, "example": { "note": "Rings, catchments, lane density." } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a project", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. The set dissolves: memberships are removed and every map, workflow, dataset and artifact remains, unfiled unless another project holds it. The response says so explicitly.", "tags": [ "Projects" ], "x-tool": "delete_project", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This dissolves the project. Its maps, workflows and datasets remain.", "subject": { "path": "/api/projects/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Deleted the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Dissolved; contents remain.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "revisions": { "type": "array", "description": "Resulting revisions for each affected surviving map or workflow the caller still reaches, including withdrawn filings. Empty when none remain reachable.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "map", "workflow" ] }, "id": { "type": "string" }, "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "kind", "id", "editRevision" ] } } }, "required": [ "revisions" ] } ], "properties": { "deleted": { "type": "boolean" }, "contentsRemain": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "deleted", "contentsRemain", "message" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/members": { "get": { "summary": "Read a project's members", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. The composite: the project's maps, workflow-origin recipes and datasets, each in its ordinary listing shape and order. The response field remains `recipes`.", "tags": [ "Projects" ], "x-tool": "get_project_members", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the members of the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectMembers" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Change a project's members", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. One atomic change: adds and removes for maps, recipes and datasets together — everything applies or nothing does. Only workflows can be project members. Adding a map or eligible recipe moves it from any previous project; adding a dataset adds another membership; repeated adds are idempotent. Each part follows the filing rules, so a caller may add only their own resources, and a removal of what is not filed there changes nothing. An owner who no longer reaches the project may still withdraw their own resources from it; anyone else is answered as for an unknown project. Answers the updated composite as the caller reads it, empty for an owner who withdrew from a project they do not reach.", "tags": [ "Projects" ], "x-tool": "update_project_members", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Changed the members of the project {subject}", "subject": { "resource": "projects", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectMemberChange" }, "example": { "addMaps": [ "map-id" ], "expectedRevisions": { "map:map-id": "0123456789abcdef0123456789abcdef" }, "addTables": [ "table-id-1", "table-id-2" ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectMembersChanged" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/export": { "post": { "summary": "Export a project as one archive", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. A chosen subset of the project's members as one zip: datasets byte for byte as their stored GeoParquet artifacts — or, with datasetFormat, every dataset converted to GeoJSON or CSV, a dataset without geometry going as CSV under GeoJSON and the manifest naming each dataset's effective format — maps and workflows (workflow-origin recipes) as portable JSON projections (publication state, membership and runtime stripped; the workflow carries its canvas layout), and a versioned project.json manifest naming every included member. Every dataset has its own entry under the name the exporter types for it, its qualifiedName: the plain name for the exporter's own, . for another owner's, so two people's same-named datasets never collide; the manifest names each one's qualifiedName and owner and the exporter's SQL name (exportedBy). Map and workflow documents carry their SQL home, the account whose datasets their plain names mean. No connection facts travel. The archive is assembled and finalized before any success is claimed — a failed assembly is a coded refusal, never a truncated file. Refuses an unknown project, an empty selection, and any id that is not a current member. The response is an attachment named .zip; through the agent tool it arrives as a base64 attachment envelope. With prepare, a single-use ticket instead — the page's road; redeem it with GET within a minute.", "tags": [ "Projects" ], "x-tool": "export_project", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": false } }, "x-display": { "verb": "Exported the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maps": { "type": "array", "items": { "type": "string" }, "description": "Member map ids to include." }, "workflows": { "type": "array", "items": { "type": "string" }, "description": "Member workflow ids to include." }, "datasets": { "type": "array", "items": { "type": "string" }, "description": "Member dataset ids to include." }, "file": { "type": "string", "description": "Archive base name; normalized to file form, falling back to \"project\"." }, "prepare": { "type": "boolean", "description": "Answer a single-use ticket {ticket, key, filename, size} instead of the bytes." }, "datasetFormat": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ], "default": "geoparquet", "description": "One format for every dataset in the archive. Omitted or geoparquet: the stored artifact byte for byte. geojson: spatial datasets as GeoJSON, a dataset without geometry as CSV. csv: geometry as WKT text. The manifest records each dataset's effective format beside its file; the format version stays 1." } } }, "example": { "maps": [ "map-id" ], "datasets": [ "table-id" ], "file": "berlin-mobility-study" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The zip attachment — or, with prepare, the JSON ticket.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket", "key", "filename", "size" ], "properties": { "ticket": { "type": "string" }, "key": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "get": { "summary": "Redeem a prepared project export", "description": "Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. The second half of the page's download road: a ticket from a prepare call streams its finalized archive once as a native attachment. Tickets expire after a minute; a redeemed, expired or mismatched ticket answers 410 and the staged file is discarded. Not an agent tool — agents call the POST directly.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." }, { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ticket the prepare call answered." }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The key the prepare call answered." } ], "responses": { "200": { "description": "The zip attachment, once.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." }, { "name": "ticket", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The ticket the prepare call answered." }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The key the prepare call answered." } ], "responses": { "200": { "description": "The zip attachment, once." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/leave": { "post": { "summary": "Leave a project", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. An active viewer or editor may leave, including a frozen project. The credential supplies the departing member; there is no request body or member selector. Ends only that member's grant, with exactly the same reach loss as removal by the owner: exclusive reach ends on the next request, and the project disappears from lists and filters on the next read. Other grants and ownership remain. Owned work stays filed and shared, readable by its owner with the project's identity for withdrawal. Historical attribution stays named. Already admitted reads finish once; outputs recheck permission and input reach at commit, as after removal. Membership changes no edit revisions. No consent or notification is required, and the owner may add the person again normally. Answers only departure, never a roster. Missing and non-member projects both answer 404 not_found; owners answer 409 project_owner_cannot_leave. A repeated departure answers not_found.", "tags": [ "Projects" ], "x-tool": "leave_project", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Leave {target}?", "consequence": "You lose what this project gave you on your next request. What you created here stays yours and stays in the project. You still find it in your own lists.", "subject": { "path": "/api/projects/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Left the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDeparture" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/people": { "get": { "summary": "List a project's people", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. A project's people are its owner and its members, each member a viewer or an editor. The project's owner reads them all; anyone else who reaches the project reads the owner and themselves alone, with their own role. Adding a person, changing a role and removing a person are the project owner's alone: a member's attempt returns forbidden and an administrator gains nothing. A person is named by their SQL name. A change governs the person's reach on their next request, with no sign-out. Answers the owner first, then the members by name (to a member, themselves), each with their display name, SQL name and role, and marked deactivated while their account is: a deactivated member keeps their place with their grant inert until reactivation. Never an email or an account identity.", "tags": [ "Projects" ], "x-tool": "list_project_people", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the people of the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPeople" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Projects" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/people/{sqlName}": { "put": { "summary": "Give a person a role on a project", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. A project's people are its owner and its members, each member a viewer or an editor. The project's owner reads them all; anyone else who reaches the project reads the owner and themselves alone, with their own role. Adding a person, changing a role and removing a person are the project owner's alone: a member's attempt returns forbidden and an administrator gains nothing. A person is named by their SQL name. A change governs the person's reach on their next request, with no sign-out. Adds the person with the role, or changes the role they hold. Only an active account other than the project's owner can hold a role: the owner is never its own member (invalid_request), and a deactivated account, an invitation not yet redeemed and an unknown SQL name are refused alike with invalid_request and the sentence \"No active person has that SQL name.\" A viewer opens everything filed in the project; an editor can also change its maps and workflows and file their own work there. Answers the project's people as they now stand. While the owner's account is deactivated nobody can change the people.", "tags": [ "Projects" ], "x-tool": "set_project_person", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Change who can reach {target}?", "consequence": "The role applies on their next request: a viewer opens everything filed in the project, and an editor can also change its maps and workflows.", "subject": { "path": "/api/projects/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Gave {arg.sqlName} the {arg.role} role on the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." }, { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "viewer", "editor" ] } }, "required": [ "role" ] }, "example": { "role": "editor" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPeople" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Remove a person from a project", "description": "A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. A project's people are its owner and its members, each member a viewer or an editor. The project's owner reads them all; anyone else who reaches the project reads the owner and themselves alone, with their own role. Adding a person, changing a role and removing a person are the project owner's alone: a member's attempt returns forbidden and an administrator gains nothing. A person is named by their SQL name. A change governs the person's reach on their next request, with no sign-out. Takes the person off the project, a deactivated member included; removing someone who holds no role there changes nothing. Nothing the person owns is deleted, unfiled or reassigned. Answers the project's people as they now stand. While the owner's account is deactivated nobody can change the people.", "tags": [ "Projects" ], "x-tool": "remove_project_person", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Remove this person from {target}?", "consequence": "They lose what this project gave them on their next request. Nothing they own is deleted.", "subject": { "path": "/api/projects/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Removed {arg.sqlName} from the project {subject}", "subject": { "resource": "projects", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." }, { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPeople" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." }, { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/projects/{id}/transfer": { "post": { "summary": "Transfer a project to one of its members", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A project is reached by its owner and by its people, its viewers and editors. Lists, counts and member lists cover exactly the reached projects and everything filed in them, whoever owns it, and name each project's owner and the caller's role (owner, editor or viewer). Renaming, the note, dissolution, adding people, changing their roles, removing other people and its transfer are the owner's; a member may leave their own grant, including in a frozen project; administrators reach nothing more. Filing follows its own rules: adding a map, workflow or dataset needs the destination's permission (the project's owner, or an editor filing their own resource) and a project whose owner is active; the owner of a resource may always withdraw it from any project, member or not; the project's owner may remove anything filed in their project, which never deletes it or changes its owner. Unreached or missing references return the same not_found before changes or archive assembly; a reached project whose change the caller may not make returns forbidden and changes nothing. Compound changes are atomic. Deleting a project unfiles its contents without deleting artifacts or changing their owners. Anyone who reaches a project may export it, viewers included: a selection names members filed in it that the caller reaches, whoever owns them. Transfer is the only change of ownership any operation makes, and it is always the current owner's own act. The new owner is named by their SQL name and must be an active account. The owner's authority, the recipient, the ownership change and everything that moves with it commit together, or nothing changes. Datasets and connections have no transfer. Makes one of the project's active members its owner: the recipient leaves the member list and the previous owner becomes an editor. The project keeps its name, note, other people and contents, and everything filed in it keeps its own owner. The project owner's alone: a member's attempt returns forbidden. A recipient who is not an active member (a deactivated member, someone outside the project, an unknown SQL name, the owner) is refused with invalid_request, and nothing changes. While the owner's account is deactivated nobody can transfer it. Answers the project's identity and its new owner.", "tags": [ "Projects" ], "x-tool": "transfer_project", "x-effects": { "readOnly": false, "writes": [ { "resource": "projects", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Make someone else the owner of {target}?", "consequence": "They take over its people, sharing and deletion, and you stay on as an editor. Only they can give it back.", "subject": { "path": "/api/projects/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Transferred the project {subject} to {arg.to}", "subject": { "resource": "projects", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "description": "The new owner's SQL name." } }, "required": [ "to" ] }, "example": { "to": "ada" } } }, "x-byte-limit": 16777216, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transfer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/transfer": { "post": { "summary": "Transfer a map to someone who reaches it", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Transfer is the only change of ownership any operation makes, and it is always the current owner's own act. The new owner is named by their SQL name and must be an active account. The owner's authority, the recipient, the ownership change and everything that moves with it commit together, or nothing changes. Datasets and connections have no transfer. Makes another active person who already reaches the map its owner: the owner of the project it is filed in, or one of that project's people. An unfiled map is refused with invalid_request: file the map in a project first. The map keeps its SQL home, so its SQL means what it meant, and it keeps its layers, history, card images and its publication, which becomes the new owner's and renders with the new owner's reach: a dataset the new owner cannot reach fails on the link rather than drawing anything else. Anyone else who reaches it is refused with forbidden. A recipient who is deactivated, not yet redeemed, unknown, the owner, or does not reach it is refused with invalid_request, and nothing changes. Answers the map's identity and its new owner.", "tags": [ "Maps" ], "x-tool": "transfer_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Make someone else the owner of {target}?", "consequence": "Its publication, deletion and transfer become theirs, and its SQL home stays as it is. Only they can give it back.", "subject": { "path": "/api/maps/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Transferred the map {subject} to {arg.to}", "subject": { "resource": "maps", "argument": "id" } }, "x-relevance": [], "x-confirm": true, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "description": "The new owner's SQL name." } }, "required": [ "to" ] }, "example": { "to": "ada" } } }, "x-byte-limit": 16777216, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTransfer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/recipes/{id}/transfer": { "post": { "summary": "Transfer a workflow to someone who reaches it", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A workflow is reached by its owner and, while it is filed in a project, by that project's owner and people; its steps, layout and runs follow it. Results name the workflow's owner and SQL home and are read in that home within the caller's own reach: a reference the caller cannot reach is missing to them, named as written, and recorded lineage, output links and captured layer identities out of their reach are left out. Content changes are open to the owner, the project's owner and its editors; the SQL and dataset parameters anyone but the owner saves into a step must name only datasets within their own reach in the workflow's home, the workflow's declared outputs aside, else the save is refused with sql_error naming the reference as written and nothing changes. Deletion stays the owner's. Anyone who reaches a workflow may duplicate it into their own space: the copy keeps the workflow's SQL home and is filed in its project only when the duplicator may file there (its owner or an editor). Administrators reach nothing more. Unreached or missing workflows, steps, captured layers and project references return not_found before reading private contents or changing resources; a reached workflow whose change the caller may not make returns forbidden and changes nothing. A step's declared output name is taken when a dataset of that name is in the workflow's SQL home or in the declaring person's own space, and duplicate-name allocation considers the duplicator's own datasets and workflows and the datasets of the SQL home the copy keeps, both preserving the existing same-workflow conflict rules. Accepted changes recheck account activity and referenced-resource access at commit. Transfer is the only change of ownership any operation makes, and it is always the current owner's own act. The new owner is named by their SQL name and must be an active account. The owner's authority, the recipient, the ownership change and everything that moves with it commit together, or nothing changes. Datasets and connections have no transfer. Makes another active person who already reaches the workflow its owner: the owner of the project it is filed in, or one of that project's people. An unfiled workflow is refused with invalid_request: file the workflow in a project first. The workflow keeps its SQL home, so its SQL means what it meant, and it keeps its steps, layout and run history, while every run's outputs stay with the person who ran it. Anyone else who reaches it is refused with forbidden. A recipient who is deactivated, not yet redeemed, unknown, the owner, or does not reach it is refused with invalid_request, and nothing changes. Answers the workflow's identity and its new owner.", "tags": [ "Recipes" ], "x-tool": "transfer_workflow", "x-effects": { "readOnly": false, "writes": [ { "resource": "recipes", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Make someone else the owner of {target}?", "consequence": "Its deletion and transfer become theirs, and its SQL home and run history stay as they are. Only they can give it back.", "subject": { "path": "/api/recipes/{id}", "argument": "id", "name": "recipe.name" } }, "x-display": { "verb": "Transferred the workflow {subject} to {arg.to}", "subject": { "resource": "recipes", "argument": "id" } }, "x-relevance": [], "x-confirm": true, "parameters": [ { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "description": "The new owner's SQL name." } }, "required": [ "to" ] }, "example": { "to": "ada" } } }, "x-byte-limit": 16777216, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentTransfer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/accounts/search": { "get": { "summary": "Find people to share with", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. The directory of active people, for sharing a project: any signed-in account can find other active accounts by any part of their display name (case-insensitive, the query trimmed) or by their exact email (trimmed, case-insensitive), never by part of one. This is the one deliberate exception to account reads being admin-only, and it is minimal: each result carries the person's display name, SQL name and, while they have a picture, its pictureVersion, and nothing else, never an email, an admin flag or an account identity. Deactivated accounts and invitations not yet redeemed are never offered, nor the caller's own account, and nobody answers twice. An empty query answers nobody; at most 20 people answer, an exact email match first, then by display name. The SQL name is how the sharing operations name the person. Managing accounts stays admin-only.", "tags": [ "Accounts" ], "x-tool": "find_accounts", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Looked for people matching {arg.q}" }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 320 }, "description": "Part of a display name, or an exact email." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDirectory" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 320 }, "description": "Part of a display name, or an exact email." } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/account/picture": { "put": { "summary": "Set your picture", "description": "Requires a current cookie session or bearer token; a cookie-signed request needs the instance's Origin. Responses, including refusals, are private, no-store. It acts on the signed-in account's own picture, never another's, and an account whose deletion has been accepted is refused before anything is read. multipart/form-data with exactly one file part named `file`: a still JPEG, PNG or WebP image, recognised by its content whatever its name or declared type. The file is at most 10,485,760 bytes (10 MB, a fixed limit) and the whole body at most 65,536 bytes more, counted as they arrive whatever length is declared: one byte over answers 413 upload_too_large. An SVG, a GIF, an animated image, or one that is damaged or incomplete, answers 415 unsupported_image; more than 64 million pixels, read from the header before any pixel is decoded, 413 image_too_large. The body has 120 seconds to arrive: one still arriving then answers 408 data_processing_timeout, and one that sends no body byte for 60 seconds answers 408 upload_stalled. The first refusal is delivered without waiting for the rest of the body, and the refused connection closes within five seconds. A caller who leaves before the body is received changes nothing. Processing takes at most 20 seconds, waiting included, and runs one picture at a time on the instance with eight more waiting; past that, 503 operation_queue_full. The server keeps its own copy: turned the way its orientation says, the largest centred square scaled to 320 pixels, a WebP with transparency kept and every embedded record dropped. Writes to one account's picture take effect in the order they were admitted: a change overtaken by one admitted after it changes nothing and answers the account as it stands. A refusal or failure leaves the current picture. Answers the account, its new pictureVersion included. Through MCP the file travels as base64 in content_base64; a file of the full 10,485,760 bytes fits the 16,777,216-byte envelope.", "tags": [ "Accounts" ], "x-tool": "set_account_picture", "x-tool-input": { "multipart": { "field": "file", "filename": "filename", "content": "content_base64" } }, "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Set your picture" }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A still JPEG, PNG or WebP image of at most 10,485,760 bytes. Through MCP the file travels as base64 in content_base64; a file of the full 10,485,760 bytes fits the 16,777,216-byte envelope." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "408": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Remove your picture", "description": "Requires a current cookie session or bearer token; a cookie-signed request needs the instance's Origin. Responses, including refusals, are private, no-store. It acts on the signed-in account's own picture, never another's, and an account whose deletion has been accepted is refused before anything is read. Your initials stand in again; removing when there is no picture changes nothing. Writes to one account's picture take effect in the order they were admitted: a change overtaken by one admitted after it changes nothing and answers the account as it stands. Answers the account, without a pictureVersion.", "tags": [ "Accounts" ], "x-tool": "remove_account_picture", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Removed your picture" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/users/{id}/picture": { "delete": { "summary": "Remove a person's picture", "description": "Requires a current admin account through a cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Removes the account's picture, a deactivated account's included; its initials stand in again, and removing when there is none changes nothing. An admin removes a picture and never sets one: no operation sets another account's picture. An account whose deletion has been accepted, or an unknown one, answers 404 not_found, and a caller who is not an admin, or no longer one when the change commits, 403 forbidden; either way the picture stays. Writes to one account's picture take effect in the order they were admitted: a change overtaken by one admitted after it changes nothing and answers the account as it stands. Answers the account.", "tags": [ "Accounts" ], "x-tool": "remove_user_picture", "x-effects": { "readOnly": false, "writes": [ { "resource": "accounts", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Remove the picture of {target}?", "consequence": "Their initials show in its place. They can set a new picture themselves.", "subject": { "path": "/api/users", "argument": "id", "name": "name", "collection": "users", "identity": "id" } }, "x-display": { "verb": "Removed the picture of {subject}", "subject": { "resource": "accounts", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSession" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account's id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/accounts/{sqlName}/picture": { "get": { "summary": "Read a person's picture", "description": "Requires a current cookie session or bearer token. Any active account reads any person's current picture, with or without a shared project: the people the account, Users, directory, project people and owner reads name, a deactivated person included. The picture is a WebP, 320 pixels square, the server's own copy with no embedded records. `v` names the version a read gave: the current version is served, an earlier one answers 404, and without `v` the current picture is served. A person with no picture, under deletion or unknown answers the same 404. Every answer carries an entity tag of its bytes and `Cache-Control: private, no-cache`, so a client may keep it but asks again before each use; a request whose `If-None-Match` names the current tag is answered 304 without the bytes, after the same checks as a full read. Refusals are private, no-store. Agents receive the image as an attachment.", "tags": [ "Accounts" ], "x-tool": "read_account_picture", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": true } }, "x-display": { "verb": "Read the picture of {arg.sqlName}" }, "parameters": [ { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." }, { "name": "v", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The picture version a read gave (pictureVersion); absent reads the current picture." } ], "responses": { "200": { "description": "The picture, as an attachment.", "headers": { "ETag": { "description": "The entity tag of these bytes.", "schema": { "type": "string" } }, "Cache-Control": { "description": "private, no-cache", "schema": { "type": "string", "const": "private, no-cache" } }, "Content-Disposition": { "description": "attachment, named .webp", "schema": { "type": "string" } } }, "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "The picture is unchanged: its entity tag matches If-None-Match." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No picture at this address: none, an earlier version, a person under deletion or nobody by that SQL name (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Accounts" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." }, { "name": "v", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The picture version a read gave (pictureVersion); absent reads the current picture." } ], "responses": { "200": { "description": "The picture, as an attachment.", "headers": { "ETag": { "description": "The entity tag of these bytes.", "schema": { "type": "string" } }, "Cache-Control": { "description": "private, no-cache", "schema": { "type": "string", "const": "private, no-cache" } }, "Content-Disposition": { "description": "attachment, named .webp", "schema": { "type": "string" } } } }, "304": { "description": "The picture is unchanged: its entity tag matches If-None-Match." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No picture at this address: none, an earlier version, a person under deletion or nobody by that SQL name (not_found)." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "sqlName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person's SQL name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/icons/sanitize": { "post": { "summary": "Sanitize custom icon SVG", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Advisory pass of the custom-icon sanitizer: returns the accepted markup, whether anything changed, and a bounded report of dropped content (category and name). The layer write re-sanitizes — this exists so a picker or agent can preview the outcome. Not-SVG, oversize, and nothing-drawable inputs answer invalid_request.", "tags": [ "Layers" ], "x-tool": "sanitize_icon_svg", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Sanitized an icon" }, "x-relevance": [], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "svg": { "type": "string" } }, "required": [ "svg" ] }, "example": { "svg": "…" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SanitizedIcon" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/basemap/inspect": { "post": { "summary": "Inspect a custom basemap style URL", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. One bounded fetch through the egress policy, answering valid | not_style | unreachable | blocked with a summary and attribution preview. Advisory: the map write re-inspects before saving. Verdicts are 200s — a dead URL is a normal thing to ask about.", "tags": [ "Maps" ], "x-tool": "inspect_basemap_style", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Inspected a basemap style" }, "x-relevance": [], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "example": { "url": "https://tiles.example/styles/dark.json" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StyleInspection" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}": { "get": { "summary": "Read a map with its layers", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. ", "tags": [ "Maps" ], "x-tool": "get_map", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the map {subject}", "subject": { "resource": "maps", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id.", "examples": { "published": { "summary": "Read the published map with its layer", "value": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34" }, "notFound": { "summary": "Read a map that does not exist", "value": "no-such-map" } } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapWithLayers" }, "examples": { "published": { "summary": "Read the published map with its layer", "description": "Needs a token and the map World cities, published. The answer carries the editRevision the next change sends.", "value": { "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "World cities", "viewport": { "lng": 0, "lat": 40, "zoom": 1.3, "pitch": 0, "bearing": 0 }, "basemap": null, "customBasemap": null, "basemapLayers": null, "note": null, "legendCorner": null, "legendOrder": null, "timeline": null, "widgets": [], "widgetsPublished": true, "publishToken": "", "publishedAt": "2026-10-20T09:00:01.521Z", "published": true, "createdAt": "2026-10-20T09:00:01.507Z", "updatedAt": "2026-10-20T09:00:01.521Z", "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90", "lastChangedAt": "2026-10-20T09:00:01.521Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "layers": [ { "id": "9b1c4e7f-2a5d-4c83-8f06-3e7a1b9d5c20", "mapId": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "Big cities", "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000", "style": { "fill": { "type": "constant", "color": { "r": 18, "g": 147, "b": 154, "a": 1 } }, "fillOpacity": 0.72, "stroke": { "r": 12, "g": 16, "b": 24, "a": 1 }, "strokeOpacity": 0.85, "strokeWidth": 0, "pointRadius": 3, "opacity": 1 }, "visible": true, "tooltip": null, "popup": null, "publishedFields": null, "inLegend": true, "viz": { "type": "points" }, "filters": [], "legendTitle": null, "legendLabels": null, "legendAttrs": null, "ordinal": 0, "createdAt": "2026-10-20T09:00:01.515Z", "updatedAt": "2026-10-20T09:00:01.515Z", "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90", "lastChangedAt": "2026-10-20T09:00:01.521Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" } } ], "projectId": null, "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "home": "ana_diaz" } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "summary": "Read a map that does not exist", "description": "Needs a token. A map your account does not reach answers the same.", "value": { "error": { "code": "not_found", "message": "The requested resource was not found." } } } } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Update a map", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Any of name, viewport, basemap (dark | light | streets | satellite, or null for Auto — the builder follows the app theme; published views follow the publication's effective theme, unless a deployment override pins Auto), basemapLayers (per-group basemap visibility; null shows everything), legendCorner (null = bottom-left), legendOrder (the manual legend arrangement; null follows the layer panel), timeline (the docked playback timeline; null undocks), widgets (the ordered widget list, notes included), widgetsPublished (whether widgets ship with the published view), or layer order. The former `note` field retired into a note widget.", "tags": [ "Maps" ], "x-tool": "update_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" } ], "history": true }, "x-mcp": { "destructiveHint": true, "openWorldHint": true, "repeatability": "Identical calls may update retained working state and interact with external entities." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated the map {subject}", "subject": { "resource": "maps", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id.", "examples": { "lightBasemap": { "summary": "Change the map's basemap to Light", "value": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34" } } }, { "name": "X-Change-Group", "x-tool-name": "change_group", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\w-]{1,64}$" }, "description": "Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal. Required for any content field, including a no-op or content combined with viewport. Viewport-only writes need no revision and change no edit revision, history or attribution.", "examples": { "lightBasemap": { "summary": "Change the map's basemap to Light", "value": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90" } } } ], "requestBody": { "x-byte-limit": 16777216, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapUpdate" }, "examples": { "lightBasemap": { "summary": "Change the map's basemap to Light", "description": "Needs the map World cities with its newest editRevision, here the one reading the published map answered.", "value": { "basemap": "light" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapWithLayers" }, "examples": { "lightBasemap": { "summary": "Change the map's basemap to Light", "description": "Needs the map World cities with its newest editRevision, here the one reading the published map answered.", "value": { "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "World cities", "viewport": { "lng": 0, "lat": 40, "zoom": 1.3, "pitch": 0, "bearing": 0 }, "basemap": "light", "customBasemap": null, "basemapLayers": null, "note": null, "legendCorner": null, "legendOrder": null, "timeline": null, "widgets": [], "widgetsPublished": true, "publishToken": "", "publishedAt": "2026-10-20T09:00:01.521Z", "published": true, "createdAt": "2026-10-20T09:00:01.507Z", "updatedAt": "2026-10-20T09:00:01.529Z", "editRevision": "e7a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9", "lastChangedAt": "2026-10-20T09:00:01.529Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "layers": [ { "id": "9b1c4e7f-2a5d-4c83-8f06-3e7a1b9d5c20", "mapId": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "Big cities", "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000", "style": { "fill": { "type": "constant", "color": { "r": 18, "g": 147, "b": 154, "a": 1 } }, "fillOpacity": 0.72, "stroke": { "r": 12, "g": 16, "b": 24, "a": 1 }, "strokeOpacity": 0.85, "strokeWidth": 0, "pointRadius": 3, "opacity": 1 }, "visible": true, "tooltip": null, "popup": null, "publishedFields": null, "inLegend": true, "viz": { "type": "points" }, "filters": [], "legendTitle": null, "legendLabels": null, "legendAttrs": null, "ordinal": 0, "createdAt": "2026-10-20T09:00:01.515Z", "updatedAt": "2026-10-20T09:00:01.515Z", "editRevision": "e7a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9", "lastChangedAt": "2026-10-20T09:00:01.529Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" } } ], "projectId": null, "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "home": "ana_diaz" } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a map", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. ", "tags": [ "Maps" ], "x-tool": "delete_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" }, { "resource": "layers", "collection": true }, { "resource": "publications", "collection": true, "argument": "id" }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This deletes the map and its layers and stops its published link.", "subject": { "path": "/api/maps/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Deleted the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/picture/refresh": { "post": { "summary": "Refresh a map picture", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Ask the server to picture the saved drawing as its owner. The owner or a project Editor may ask; a Viewer receives forbidden. Repeated requests coalesce with pending work. The previous complete picture stays served. This changes no edit revision, history or Last edited timestamp and requires no edit revision. Answers queued after admission to the quiet wait, or unavailable when the renderer is absent. Basemap services may be contacted by the background attempt.", "tags": [ "Maps" ], "x-tool": "refresh_map_picture", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Requested a map picture" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "The renderer is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "const": "unavailable" }, "pictureState": { "type": "string", "const": "unavailable" } }, "required": [ "outcome", "pictureState" ] } } } }, "202": { "description": "Queued or coalesced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "const": "queued" }, "pictureState": { "type": "string", "const": "waiting" } }, "required": [ "outcome", "pictureState" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/thumbnail": { "get": { "summary": "Read a map's snapshot", "description": "History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The last complete PNG the server made for this map, the maps screen's card image. 404 while no picture is served. A map whose basemap follows the theme carries one image per theme: name the theme to read that one. The fallback order: the named theme's image, then the map's single image, then the other theme's; a request naming no theme answers the light image, then dark, then the single image. An image the reader may not be served (one that drew a dataset beyond their reach, or an unattributed one read by anyone but the owner) is passed over like a missing one; when none is left the answer is the same 404 as for a map with no image at all. The maps listing's `hasThumbnail` says beforehand whether there is one. Naming a shape or a width answers one of the sizes the server keeps of that picture, as WebP: the narrowest at least that wide, else the widest; a shape alone answers the widest. The sizes share one proportion, 968 by 494, which a card's box crops to its own; a picture kept earlier in two shapes answers the one named, and a width alone its card shape. A picture made before sizes were kept answers its PNG whatever is named. Every answer carries an entity tag of its bytes and `Cache-Control: private, no-cache`, so a client may keep it but asks again before each use; a request whose `If-None-Match` names the current tag is answered 304 without the bytes, after the same serving checks as a full read.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "light", "dark" ] }, "description": "The viewer's theme, \"light\" or \"dark\". Any other value is refused." }, { "name": "shape", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "card", "wide" ] }, "description": "The shape to answer. The server keeps every picture in one shape, which \"card\" and \"wide\" both name; a picture kept earlier in two shapes answers the one named until it is made again. Any other value is refused." }, { "name": "width", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "description": "The width in screen pixels the image will cover. Anything but a positive whole number is refused." } ], "responses": { "200": { "description": "The snapshot: the PNG, or with a shape or a width named, a kept size.", "headers": { "ETag": { "description": "The entity tag of these bytes.", "schema": { "type": "string" } }, "Cache-Control": { "description": "private, no-cache", "schema": { "type": "string", "const": "private, no-cache" } } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "The picture this reader is served is unchanged: its entity tag matches If-None-Match." }, "400": { "description": "A theme, shape or width the read does not take (invalid_request).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "put": { "summary": "Refuse a retired browser picture upload", "description": "History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Compatibility change: this operation no longer accepts browser pixels. An authorized owner receives 410 picture_upload_retired without the handler reading the body or changing any image. Use POST /api/maps/{id}/picture/refresh. Theme, cycle and revision query values do not restore the former operation.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "410": { "description": "Browser picture upload retired (picture_upload_retired).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "theme", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "light", "dark" ] }, "description": "The viewer's theme, \"light\" or \"dark\". Any other value is refused." }, { "name": "shape", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "card", "wide" ] }, "description": "The shape to answer. The server keeps every picture in one shape, which \"card\" and \"wide\" both name; a picture kept earlier in two shapes answers the one named until it is made again. Any other value is refused." }, { "name": "width", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "description": "The width in screen pixels the image will cover. Anything but a positive whole number is refused." } ], "responses": { "200": { "description": "The snapshot: the PNG, or with a shape or a width named, a kept size.", "headers": { "ETag": { "description": "The entity tag of these bytes.", "schema": { "type": "string" } }, "Cache-Control": { "description": "private, no-cache", "schema": { "type": "string", "const": "private, no-cache" } } } }, "304": { "description": "The picture this reader is served is unchanged: its entity tag matches If-None-Match." }, "400": { "description": "A theme, shape or width the read does not take (invalid_request)." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, PUT" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/widget-values": { "post": { "summary": "Read the map's widget values", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Every visible widget computed server-side over its layer's effective query, under an optional ephemeral selection set — cross-filter state that lives on the request and is never stored. Classic crossfilter semantics: a widget's own selection never filters itself. Also returns per-layer constrained/total row counts. A read, despite the POST — the body carries the selections. An optional draft widget previews an unsaved editor state: validated like a stored widget, it replaces its stored self by id (or joins as a new card) for this computation only — nothing is written.", "tags": [ "Maps" ], "x-tool": "read_widget_values", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the widget values of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-relevance": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "requestBody": { "x-byte-limit": 16777216, "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "$ref": "#/components/schemas/WidgetSelections" }, "draft": { "$ref": "#/components/schemas/MapWidget" } } }, "example": { "selections": [ { "widgetId": "w1", "kind": "exclude", "values": [ "Nordend" ] } ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetValues" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/search": { "get": { "summary": "Search the map", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. One search over the map's own data and, on request, places : visible layers matched by name, attribute values matched case-insensitively in genuine text columns of each visible layer's effective (filtered) result — one row per matching feature, at most 20 across layers, on the hardened read-only path — and every plausible reading of a pasted decimal coordinate pair. With `places=1` and a configured provider endpoint, Nominatim-compatible place results join, carrying the provider's attribution; unconfigured, the places group answers `unconfigured` and everything local still works. Value and place rows carry the geometry a client needs to fly or fit without a second request. Never builder actions.", "tags": [ "Maps" ], "x-tool": "search_map", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Searched the map {subject} for {arg.q}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The search text." }, { "name": "places", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Ask for places too — the submitted search. Omitted, the provider is never contacted (the per-keystroke path)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResults" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The search text." }, { "name": "places", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Ask for places too — the submitted search. Omitted, the provider is never contacted (the per-keystroke path)." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/dependencies": { "get": { "summary": "The datasets a map draws from", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Each layer's references resolve to dataset identities in the map's SQL home within the caller's reach, and each one is listed with its owner and the name the caller would type: a dataset the caller cannot reach is left out rather than named, and a same-named dataset of the caller's own never stands in for the map's. Memberships name the projects the caller reaches, and on the caller's own datasets every project they are in, one the caller no longer reaches included; producers only workflows the caller reaches, each marked with whether the caller owns it. The 14-A filing checklist's subject: every registered dataset used by at least one of the map's saved layers, exactly once, with its source, row count, project memberships, and the workflow-origin recipe that currently produces it (null otherwise), and its geometry column and sampled geometry type (both null for a non-spatial dataset; a column with no sampled type is still spatial). A layer whose statement cannot be analyzed fails the whole read with `dependencies_unresolved` — a partial answer never presents as a complete checklist.", "tags": [ "Maps" ], "x-tool": "get_map_dependencies", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the datasets of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapDependencies" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/duplicate": { "post": { "summary": "Duplicate a map", "description": "Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Full copy — viewport, basemap, note, legend, timeline dock, and every layer under fresh ids — named \" copy\", always an unpublished draft. Edit history does not carry over.", "tags": [ "Maps" ], "x-tool": "duplicate_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "result": "id" }, { "resource": "layers", "collection": true }, { "resource": "projects", "collection": true } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Duplicated a map as {subject}", "subject": { "resource": "maps", "result": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapWithLayers" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/history": { "get": { "summary": "Undo/redo availability", "description": "History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Whether the map currently has anything to undo or redo. Every qualifying change (style, viz, filters, names, visibility, layer add/delete, basemap, note, legend, layer order, timeline dock) lands on one per-map history, whoever made it; viewport moves, publish state, and a playing timeline do not.", "tags": [ "Maps" ], "x-tool": "get_history", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the undo state of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-relevance": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/History" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/undo": { "post": { "summary": "Undo the newest change", "description": "History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Reverts the latest step on the map's history. Consecutive edits in a group form a step, and an edit from outside the group between them starts a new one, so one turn's edits can span several steps. Grouping never crosses actors. Restores are verbatim: exactly the values stored before the change. Returns the refreshed map with fresh availability and a fresh editRevision; 409 invalid_request when there is nothing to undo, or 409 stale_revision when the seen revision is no longer current, including during SQL admission. Redo re-applies the stored change. A replay that would change a publication setting (the widget publication toggle or a layer's published fields) is the map owner's alone: anyone else is refused whole with forbidden, and nothing is restored.", "tags": [ "Maps" ], "x-tool": "undo_change", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" }, { "resource": "layers", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Undid a change on the map {subject}", "subject": { "resource": "maps", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapWithHistory" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/redo": { "post": { "summary": "Redo the newest undone change", "description": "History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Re-applies the most recently undone step exactly as it was stored. Consecutive edits in a group form a step, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. Any fresh edit after an undo discards the redo branch. Returns a fresh editRevision, never an older token even when values match. 409 invalid_request when there is nothing to redo, or 409 stale_revision when the seen revision is no longer current, including during SQL admission. A replay that would change a publication setting (the widget publication toggle or a layer's published fields) is the map owner's alone: anyone else is refused whole with forbidden, and nothing is restored.", "tags": [ "Maps" ], "x-tool": "redo_change", "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true, "argument": "id" }, { "resource": "layers", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Redid a change on the map {subject}", "subject": { "resource": "maps", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapWithHistory" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/sketches": { "get": { "summary": "List a map's sketch datasets", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. The sketch datasets drawn on this map, each with its table, owning layer and per-kind feature counts — what the builder's card copy and cascade confirmation read.", "tags": [ "Sketches" ], "x-tool": "list_map_sketches", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the sketches of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "The map's sketches.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "table": { "type": "string" }, "tableId": { "type": "string" }, "mapId": { "type": "string" }, "layerId": { "type": [ "string", "null" ] }, "rowCount": { "type": "integer" }, "counts": { "type": "object", "description": "Feature count per drawn kind." } }, "required": [ "table", "tableId", "mapId", "rowCount" ] } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Start a sketch with its first feature", "description": "At most 16,777,216 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. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. First commit of a draw session: mints the sketch dataset — named from the map's name plus _sketch, advancing a visible numeric suffix on collision — and its owning layer together, provenance recorded, no history step. The feature passes the same structural gate as every later commit: kind one of point, line, polygon, rectangle, circle, freehand; geometry the kind's GeoJSON family (polygon kinds are one closed ring, no holes); at most 10,000 vertices. Anyone who may change the map's content draws on it: the dataset is the drawer's own, filed into the map's project where the drawer may file, and the layer names it in the map's SQL home, qualified with the drawer's SQL name when that home is someone else's.", "tags": [ "Sketches" ], "x-tool": "create_sketch", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "result": "tableId" }, { "resource": "layers", "collection": true, "result": "layerId" }, { "resource": "maps", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Started a sketch on the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "object", "required": [ "kind", "geometry" ], "properties": { "kind": { "type": "string", "enum": [ "point", "line", "polygon", "rectangle", "circle", "freehand" ] }, "geometry": { "type": "object", "description": "GeoJSON Point, LineString or Polygon matching the kind." } } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "The minted sketch and resulting map editRevision.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "properties": { "table": { "type": "string" }, "tableId": { "type": "string" }, "layerId": { "type": "string" }, "layerName": { "type": "string" }, "featureId": { "type": "string" } }, "required": [ "table", "layerId", "featureId" ] } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Sketches" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "The map's sketches." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/sketches/{name}/features": { "get": { "summary": "Read a sketch's drawn features", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Every drawn feature with its stable id, kind and geometry — the identity the select tool and vertex handles use. The answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built; above it the read answers 422 render_bytes_exceeded with no partial result. Changes to the sketch are not held to that limit.", "tags": [ "Sketches" ], "x-tool": "get_sketch_features", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the features of the sketch {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "responses": { "200": { "description": "The features.", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "array" } }, "required": [ "features" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Append one drawn feature", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Commits one more shape into the session's dataset, under the same structural gate and vertex ceiling as the first. The dataset's id and name never change; the artifact is rewritten and every dependent layer's render refreshes. A sketch's features change only by its drawer, whatever the map's role grants; anyone else who reaches it is refused with forbidden.", "tags": [ "Sketches" ], "x-tool": "append_sketch_feature", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Added a feature to the sketch {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "object" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "The appended feature's id and the new count.", "content": { "application/json": { "schema": { "type": "object", "properties": { "featureId": { "type": "string" }, "rowCount": { "type": "integer" } }, "required": [ "featureId", "rowCount" ] } } } }, "400": { "description": "The feature failed the structural gate." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "The sketch vanished mid-flight; nothing written." }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Sketches" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "responses": { "200": { "description": "The features." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/sketches/{name}/features/{featureId}": { "patch": { "summary": "Move one vertex of a drawn polygon", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. The one permitted edit: move exactly one vertex of a polygon or freehand feature. Kind and vertex count are preserved; points, lines, rectangles and circles refuse; the moved ring passes the same structural gate as a fresh commit. Only the sketch's drawer moves a vertex.", "tags": [ "Sketches" ], "x-tool": "move_sketch_vertex", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Moved a vertex of the sketch {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." }, { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Drawn feature id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vertexIndex", "position" ], "properties": { "vertexIndex": { "type": "integer", "description": "Ring index, 0-based, excluding the closing position; moving index 0 moves the closure too." }, "position": { "type": "array", "description": "[longitude, latitude], in range." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The remaining row count after the feature change.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rowCount": { "type": "integer", "minimum": 0 } }, "required": [ "rowCount" ] } } } }, "400": { "description": "Bad index or out-of-range position." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "409": { "description": "Not a polygon-kind feature." }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete one drawn feature", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Removes exactly that row. The dataset keeps its id and name; deleting the last row leaves the empty dataset and its layer in place. Only the sketch's drawer deletes a feature.", "tags": [ "Sketches" ], "x-tool": "delete_sketch_feature", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Deleted a feature of the sketch {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." }, { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Drawn feature id." } ], "responses": { "200": { "description": "The remaining row count after the feature change.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rowCount": { "type": "integer", "minimum": 0 } }, "required": [ "rowCount" ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." }, { "name": "featureId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Drawn feature id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/sketches/{name}": { "delete": { "summary": "Delete a sketch and its owning layer — the cascade", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Only the sketch's drawer deletes it. On the drawer's own map it deletes the provenance-named owning layer, its bound widgets, the dataset, the artifact and the tile artifacts together; on someone else's map the dataset goes and the layer stays, failing by name, since deleting a dataset never changes another person's map. Deliberately not undoable: no history step is written and steps targeting the owner leave the timeline. Copies and other layers over the same table keep ordinary deletion behavior and enter the standing missing-table state.", "tags": [ "Sketches" ], "x-tool": "delete_sketch", "x-effects": { "readOnly": false, "writes": [ { "resource": "tables", "collection": true, "argument": "name" }, { "resource": "layers", "collection": true }, { "resource": "maps", "collection": true } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Deleted the sketch {subject}", "subject": { "resource": "tables", "argument": "name" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "responses": { "200": { "description": "Layer and dataset are gone. A changed surviving map carries its resulting editRevision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mapId": { "type": [ "string", "null" ] }, "layerId": { "type": [ "string", "null" ] }, "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "mapId", "layerId" ], "anyOf": [ { "properties": { "mapId": { "type": "string" } }, "required": [ "editRevision" ] }, { "properties": { "mapId": { "type": "null" } } } ] } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sketch table name." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/layers": { "get": { "summary": "List a map's layers", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. ", "tags": [ "Layers" ], "x-tool": "list_layers", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Listed the layers of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Create a layer from a SQL result", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. The SQL must return at least one geometry column. The first geometry column in select order is the primary geometry used for simple rendering; additional geometry columns are allowed. A default, publication-ready style is applied when none is provided: it takes the instance's defaults for new layers, the next color of the color cycle with the geometry's opacity, the line width and the point radius (`defaults` in the runtime configuration). A given style is kept as given.", "tags": [ "Layers" ], "x-tool": "create_layer", "x-effects": { "readOnly": false, "writes": [ { "resource": "layers", "collection": true, "result": "id" }, { "resource": "maps", "collection": true } ], "history": true }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Created the layer {subject}", "subject": { "resource": "layers", "result": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id.", "examples": { "quickstart": { "summary": "Add the layer Big cities", "value": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34" } } }, { "name": "X-Change-Group", "x-tool-name": "change_group", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\w-]{1,64}$" }, "description": "Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.", "examples": { "quickstart": { "summary": "Add the layer Big cities", "value": "4f1c9a7e2b0d4c6e8a1f3b5d7c9e0a2b" } } } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerCreate" }, "examples": { "quickstart": { "summary": "Add the layer Big cities", "description": "Needs the map World cities with the editRevision creating it answered, and the dataset world_cities. The layer draws the 15 cities of more than 10 million people.", "value": { "name": "Big cities", "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" }, "examples": { "quickstart": { "summary": "Add the layer Big cities", "description": "Needs the map World cities with the editRevision creating it answered, and the dataset world_cities. The layer draws the 15 cities of more than 10 million people.", "value": { "id": "9b1c4e7f-2a5d-4c83-8f06-3e7a1b9d5c20", "mapId": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", "name": "Big cities", "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000", "style": { "fill": { "type": "constant", "color": { "r": 18, "g": 147, "b": 154, "a": 1 } }, "fillOpacity": 0.72, "stroke": { "r": 12, "g": 16, "b": 24, "a": 1 }, "strokeOpacity": 0.85, "strokeWidth": 0, "pointRadius": 3, "opacity": 1 }, "visible": true, "tooltip": null, "popup": null, "publishedFields": null, "inLegend": true, "viz": { "type": "points" }, "filters": [], "legendTitle": null, "legendLabels": null, "legendAttrs": null, "ordinal": 0, "createdAt": "2026-10-20T09:00:01.515Z", "updatedAt": "2026-10-20T09:00:01.515Z", "editRevision": "c03e5b7d9f1a2c4e6b8d0f2a4c6e8b1d", "lastChangedAt": "2026-10-20T09:00:01.515Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}": { "get": { "summary": "Read a layer", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. ", "tags": [ "Layers" ], "x-tool": "get_layer", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the layer {subject}", "subject": { "resource": "layers", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "patch": { "summary": "Update a layer", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Any of name, sql, style, visibility, tooltip or popup fields (null = automatic), the published-field list (null = derived projection), legend inclusion, viz (points | hexbin | grid | heatmap — hexbin/grid aggregate server-side and get a fill over their aggregate value automatically), filters (applied before aggregation; [] removes them), or legend text overrides. Text labels live in the style's `label` member. When `sql` is changed, it must return at least one geometry column. The first geometry column in select order is the primary geometry used for simple rendering; additional geometry columns are allowed.", "tags": [ "Layers" ], "x-tool": "update_layer", "x-effects": { "readOnly": false, "writes": [ { "resource": "layers", "collection": true, "argument": "id" } ], "history": true }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Updated the layer {subject}", "subject": { "resource": "layers", "argument": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "X-Change-Group", "x-tool-name": "change_group", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\w-]{1,64}$" }, "description": "Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "requestBody": { "x-byte-limit": 16777216, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerUpdate" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Delete a layer", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Recorded on the undo timeline — an undo restores the layer whole. Removing one's own sketch layer also deletes its sketch dataset, wherever the map is; removing a layer that draws someone else's sketch leaves their dataset.", "tags": [ "Layers" ], "x-tool": "delete_layer", "x-effects": { "readOnly": false, "writes": [ { "resource": "layers", "collection": true, "argument": "id" }, { "resource": "maps", "collection": true }, { "resource": "tables", "collection": true } ], "history": true }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Delete {target}?", "consequence": "This removes the layer and its bound widgets. Your own sketch layer also deletes its sketch dataset.", "subject": { "path": "/api/layers/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Deleted the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "X-Change-Group", "x-tool-name": "change_group", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\w-]{1,64}$" }, "description": "Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "responses": { "200": { "description": "Deleted. The surviving map revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditRevisionResult" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, PATCH" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/duplicate": { "post": { "summary": "Duplicate a layer", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Full copy — SQL, style, viz, filters, tooltip, legend settings — with a suffixed name, stacked on top of the map's layer order.", "tags": [ "Layers" ], "x-tool": "duplicate_layer", "x-effects": { "readOnly": false, "writes": [ { "resource": "layers", "collection": true, "result": "id" }, { "resource": "maps", "collection": true } ], "history": true }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Duplicated a layer as {subject}", "subject": { "resource": "layers", "result": "id", "name": [ "name" ] } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "X-Change-Group", "x-tool-name": "change_group", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\w-]{1,64}$" }, "description": "Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way." }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal." } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/extent": { "post": { "summary": "A layer's current data extent", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. The bounding box of what the layer currently draws: its SQL, its stored filters, and any constraints stated in `dims` — the ranges, time windows and category selections a canvas enforces after the data is fetched. Answers `kind: \"extent\"` with `box` as [west, south, east, north], or `kind: \"empty\"` when the constraints leave nothing drawn. Empty is a normal outcome of filtering, not a failure. A client holding the layer's features whole can compute this itself; it exists for the case it cannot — a tiled layer, whose features never reach the client entire.", "tags": [ "Layers" ], "x-tool": "layer_extent", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the extent of the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "requestBody": { "x-byte-limit": 16777216, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dims": { "type": "array", "items": { "type": "object" }, "description": "Constraints in force beyond the layer's stored filters, in the canvas's dimension form." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The extent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerExtent" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/look": { "post": { "summary": "Look at a map: one bounded rendered image with its facts", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The model-facing check of a map: the map's stored state rendered through the same server-side road as the image export, at 1024 by 640 pixels, and answered as a PNG of at most 384 KiB together with the render's facts. The image is derived from that one render downwards through 768 by 480 and 512 by 320 when the byte bound is missed; still over it at 512 by 320 the answer is look_image_too_large and no image. The facts carry the render's identity, the bounded state identity of what the renderer actually drew (the map, the camera, the visible layers with a digest of their stored filters, the legend and the widgets, the appearance), the image's pixel and byte sizes, the source size, the attribution credited, the composition's truthful failures and any abandoned external requests, and the elapsed time. The appearance is an explicit input, light when absent; mapId names the map, and a call naming none answers look_target_missing. Read-only: the map's stored state stays as it is; the image is retained in process for GET /api/maps/look/{renderId} under documented bounds. Bounded by its own budget (30 s by default, DEZFIL_ASSISTANT_LOOK_TIMEOUT_S), queue wait, render and image preparation included; past it the answer is render_timeout. Without a renderer browser on the instance the answer is render_unavailable.", "tags": [ "Maps" ], "x-tool": "look_at_map", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "idempotentHint": false }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "json-image", "nativeImage": false } }, "x-display": { "verb": "Checked the map" }, "requestBody": { "x-byte-limit": 16777216, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mapId": { "type": "string", "description": "The map to look at. The assistant supplies the contextual map when the model names none; a headless call without one answers look_target_missing." }, "appearance": { "type": "string", "enum": [ "light", "dark" ], "description": "The theme to render with. Light when absent." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The image and the render's facts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapLook" } } } }, "400": { "description": "No map named (look_target_missing), or a malformed map id or appearance (invalid_request)." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such map (not_found)." }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "408": { "description": "The check's budget was exceeded (render_timeout)." }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The render failed or the renderer did not report what it drew (render_failed)." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/look/{renderId}": { "get": { "summary": "Read the retained image of a map check", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. Exactly the PNG a check handed the model, or the thumbnail derived from it at retention, as an attachment. Renders are retained in process under documented bounds, 256 renders and 96 MiB by default (DEZFIL_ASSISTANT_LOOK_RETENTION, DEZFIL_ASSISTANT_LOOK_RETENTION_MB), full images and thumbnails counted together, oldest evicted first, gone with the process. After eviction or a restart the answer is look_image_unavailable; this read renders nothing.", "tags": [ "Maps" ], "x-tool": "read_map_look_image", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": true } }, "x-display": { "verb": "Read the image of a map check" }, "x-relevance": [], "parameters": [ { "name": "renderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The render's identity from the check's facts." }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "thumbnail" ] }, "description": "full (the default) is the image the model was given; thumbnail is the 132 px wide derivation kept beside it." } ], "responses": { "200": { "description": "The PNG, as an attachment.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Evicted or gone with a restart (look_image_unavailable)." }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Maps" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "renderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The render's identity from the check's facts." }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "thumbnail" ] }, "description": "full (the default) is the image the model was given; thumbnail is the 132 px wide derivation kept beside it." } ], "responses": { "200": { "description": "The PNG, as an attachment." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Evicted or gone with a restart (look_image_unavailable)." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "renderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The render's identity from the check's facts." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/export/image": { "post": { "summary": "Render a map to a PNG image", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Server-side image export: the map rendered by the app's own client inside the instance's headless browser and screenshotted at exactly the definition's pixels — the same composition the builder's export card downloads, pixel-faithful by construction. Takes the documented ExportImageDefinition; answers the PNG as an attachment (agents receive it as the base64 attachment envelope). Bounded by the documented render budget and concurrency cap; renders stored map state — visible layers, stored filters — never builder-transient selections. Without a browser on the instance the operation answers render_unavailable; health is unaffected. When an external request outlives its bound, the request burst has settled and no app-origin request remains in flight, the relay ends its current sockets and refuses re-dials only to the stalled hosts for this render. Requests without a terminal event stay armed for another cut after the same bound. The whole render budget still applies. An image response carries x-dezfil-export-abandoned with the abandonment count and hosts (never paths), counting repeated cuts again. The server log names each abandonment as it happens.", "tags": [ "Maps" ], "x-tool": "export_map_image", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": true, "repeatability": "External entities and retained provider state may change between identical calls." }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": false } }, "x-display": { "verb": "Rendered the map {subject} to an image", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/ExportImageDefinition" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The PNG, as an attachment.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid definition (schema-validated)." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/export/{format}": { "get": { "summary": "Download a layer's effective result", "description": "Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. The layer's effective result as a file download: its SQL, then its stored filters, then OD/aggregation — exactly what the builder renders, so a stored filter is never dropped on the way out. Live widget selections and other transient view state never enter. The result's first geometry column is the feature geometry; every other geometry column travels as a WKT value beside it. Runs on the hardened read-only instance under the universal query bound — timeout, memory budget, and cancellation when the caller departs. The response is an attachment named .; through the agent tool it arrives as a base64 attachment envelope.", "tags": [ "Layers" ], "x-tool": "export_layer_data", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history", "binary": { "representation": "attachment", "nativeImage": false } }, "x-display": { "verb": "Exported the layer {subject} as {arg.format}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "description": "Download format: geoparquet, geojson, or csv (geometry as WKT)." } ], "responses": { "200": { "description": "The file, as an attachment.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Unknown format, invalid SQL, or the bounded lane's coded errors." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "description": "Download format: geoparquet, geojson, or csv (geometry as WKT)." } ], "responses": { "200": { "description": "The file, as an attachment." }, "400": { "description": "Unknown format, invalid SQL, or the bounded lane's coded errors." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "geoparquet", "geojson", "csv" ] }, "description": "Download format: geoparquet, geojson, or csv (geometry as WKT)." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/render": { "get": { "summary": "Render data for a layer", "description": "Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. The layer's effective result — its SQL refined by its filters, then aggregated by its viz (hexbin/grid cells expose value and count). Under the render cap the response is inline GeoJSON (mode: inline). A points-viz result over the cap is served as vector tiles instead (mode: tiled): tiles are prepared in the background — poll while `tiles.state` is `building`; when `ready`, `tiles.url` is a {z}/{x}/{y} template and bounds/zoom range describe the archive. Inline feature properties are the columns the layer and its map read: its style, label and label-priority fields, the filters the canvas applies, the docked timeline's field, the fields of the map's widgets on it, its explicit tooltip and pop-up fields or, while either list is automatic, the first eight columns, and a drawn sketch's feature_id and kind; other columns stay out, and the published field list plays no part. The inline answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built. Above it the layer takes the road it takes over the cap: a points-viz result is served as tiles, a result shipped without its live filters has them applied in the query and is answered inline if that fits, and anything else answers the errored state render_bytes_exceeded. A template's layer has no tile road. Errored states (deleted table, failed build, missing tiler, an aggregation over the cap, an answer over the byte limit) are returned as data, not an HTTP error.", "tags": [ "Layers" ], "x-tool": "render_layer", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Rendered the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerRender" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Render a computed layer under ephemeral selections", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. The settle lane for widget cross-filtering: re-render a hexbin, grid, cluster, or heatmap layer with a selection set folded into its query — cells re-bin and clusters recount, with zero writes. Selections are pre-resolved filters and pass the stored-filter validation; other viz types enforce selections client-side and reject this call.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "requestBody": { "x-byte-limit": 16777216, "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "type": "array", "items": { "$ref": "#/components/schemas/LayerFilter" } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerRender" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/slider-preview": { "get": { "summary": "Read bounded slider-preview input", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Read-only point input for an editing interaction. Discrete filters are applied; range/time filters are left for the client so a slider can narrow and widen. The response says whether it is exact or a stable bounded subset. It never changes the layer or its history and is not published. The answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built; above it the read answers 422 render_bytes_exceeded with no partial preview, and the layer's own render is unaffected.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SliderPreviewData" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/tiles/{z}/{x}/{y}": { "get": { "summary": "One vector tile of a tiled layer", "description": "Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Mapbox Vector Tile bytes for the archive built from the layer's effective result. Use the URL template from the render response (it carries a cache-busting version). A spot the archive does not cover returns 204 with no body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." } ], "responses": { "200": { "description": "The tile.", "content": { "application/vnd.mapbox-vector-tile": { "schema": { "type": "string", "format": "binary" } } } }, "204": { "description": "No tile at these coordinates." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." } ], "responses": { "200": { "description": "The tile." }, "204": { "description": "No tile at these coordinates." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/fields": { "get": { "summary": "A layer's non-geometry columns", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. `styling`: columns of the effective result, for fill and tooltip fields (an aggregated layer exposes exactly `value` and `count`). `filterable`: columns of the layer's own SQL result — what filters apply to.", "tags": [ "Layers" ], "x-tool": "list_layer_fields", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the fields of the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerFields" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/fields/{field}": { "get": { "summary": "A field's extent or distinct values", "description": "Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Seed data for a filter control: min/max and a binned distribution for numeric and time fields (time extents as ISO-8601 strings), distinct values (bounded, by frequency) for text. Computed on the layer's own result — the unfiltered extent, so a brush keeps a stable background. A distinct value longer than 2,097,152 bytes (2 MiB) as a JSON string refuses the answer with 422 query_result_too_large.", "tags": [ "Layers" ], "x-tool": "get_field_stats", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the statistics of {arg.field} on the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Field name from the layer's result." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldStats" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Layers" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Field name from the layer's result." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Field name from the layer's result." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/fill": { "post": { "summary": "Compute a data-driven paint", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Quantile, equal-interval, or natural (Fisher–Jenks, computed on a bounded sample) breaks for numeric attributes, distinct colors for categorical ones, or a `continuous` unclassed ramp: the attribute's domain resolved over the effective result with the palette's stops baked in (diverging palettes come back centered on the mean; clamp, log, and center are then style-level edits on the returned paint). Optional palette (curated or saved custom — see /api/palettes), class count, and reverse. Classification runs on the layer's effective result, so filters are respected and an aggregated layer classifies its `value` or `count`. Returns a paint to merge into the style — `fill`, or `strokeBy` for a data-driven outline — or into the viz fill of an aggregated layer. A category longer than 2,097,152 bytes (2 MiB) as a JSON string refuses the paint with 422 query_result_too_large.", "tags": [ "Layers" ], "x-tool": "compute_fill", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Computed a {arg.method} fill by {arg.attribute} on the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attribute": { "type": "string" }, "method": { "type": "string", "enum": [ "quantile", "equal", "natural", "categorical", "continuous" ] }, "palette": { "type": "string", "description": "Palette name from the catalogue or a saved custom palette; kind must match the method (numeric methods take sequential, diverging, and custom palettes, categorical takes qualitative)." }, "classes": { "type": "integer", "description": "Class count for numeric ramps (2-12)." }, "reversed": { "type": "boolean" } }, "required": [ "attribute", "method" ] }, "example": { "attribute": "population", "method": "quantile" } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillPaint" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/layers/{id}/scale": { "post": { "summary": "Compute a size scale", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. Resolve a numeric attribute's value range over the layer's effective result (filters respected) and map it onto an output range. Returns a scale to merge into the style — `pointRadiusBy` for point radius, `strokeWidthBy` for line width, or (with unit 'm') `heightBy` for polygon extrusion in meters. The sibling of the paint operation, for the size channels.", "tags": [ "Layers" ], "x-tool": "compute_scale", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Computed a size scale by {arg.attribute} on the layer {subject}", "subject": { "resource": "layers", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attribute": { "type": "string" }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Output values, smallest first — pixels (0-200) by default, meters (0-100000) with unit 'm'." }, "unit": { "type": "string", "enum": [ "px", "m" ], "description": "Output unit: px for sizes (default), m for the extrusion height channel." } }, "required": [ "attribute", "range" ] }, "example": { "attribute": "population", "range": [ 4, 28 ] } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SizeScale" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/publish": { "get": { "summary": "The active publication's authored settings", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The theme default and the viewer-controls checklist for the active publication. 204 when the map is not published — a state, not an error. A map record carries no publication state, so this is how an author surface reads back what it is about to change. The token is the map owner's alone: anyone else who reaches the map reads the settings without it.", "tags": [ "Publish" ], "x-tool": "get_publication_state", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the publication of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "The active publication's settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationState" } } } }, "204": { "description": "The map is not published." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "post": { "summary": "Publish a map", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Minting a publication and changing its theme or reader controls are the map owner's alone. Returns a stable, unguessable token. Idempotent while published. The optional `theme` (\"light\" | \"dark\") sets the published view's authored default: omitted on a first publication it records dark (existing callers keep their behavior); stated while already published it updates the stored default in place — the token never changes for a theme; omitted while published it changes nothing. The optional `viewerControls` sets which optional reader controls the publication exposes, on the same in-place rule: omitted it changes nothing, and on a publication that never stated one every control is on. Within a stated set an omitted member reads as enabled. The two settings are independent — stating one never rewrites the other. Unpublishing clears both with the token.", "tags": [ "Publish" ], "x-tool": "publish_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "publications", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Publish {target}?", "consequence": "Anyone with the link can view its published data.", "subject": { "path": "/api/maps/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Published the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id.", "examples": { "quickstart": { "summary": "Publish the map", "value": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34" } } }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.", "examples": { "quickstart": { "summary": "Publish the map", "value": "c03e5b7d9f1a2c4e6b8d0f2a4c6e8b1d" } } } ], "requestBody": { "x-byte-limit": 16777216, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "The authored default theme for readers." }, "viewerControls": { "$ref": "#/components/schemas/ViewerControls" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "201": { "description": "Published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishState" }, "examples": { "quickstart": { "summary": "Publish the map", "description": "Needs the map World cities with the editRevision adding the layer answered. The answer's token is the published link's: the map opens at /v/ for anyone with the link.", "value": { "token": "", "publishedAt": "2026-10-20T09:00:01.521Z", "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90", "lastChangedAt": "2026-10-20T09:00:01.521Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Unpublish a map", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The link stops resolving immediately. Revoking a publication is the map owner's alone.", "tags": [ "Publish" ], "x-tool": "unpublish_map", "x-effects": { "readOnly": false, "writes": [ { "resource": "publications", "collection": true, "argument": "id" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "repeatability": "Identical calls may update retained working state." }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Unpublish {target}?", "consequence": "Its published link will stop working.", "subject": { "path": "/api/maps/{id}", "argument": "id", "name": "name" } }, "x-display": { "verb": "Unpublished the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-confirm": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id.", "examples": { "unpublish": { "summary": "Stop sharing the map", "value": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34" } } }, { "name": "X-Edit-Revision", "x-tool-name": "expected_revision", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "description": "Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.", "examples": { "unpublish": { "summary": "Stop sharing the map", "value": "e7a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9" } } } ], "responses": { "200": { "description": "Unpublished. The surviving map revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditRevisionResult" }, "examples": { "unpublish": { "summary": "Stop sharing the map", "description": "Needs the published map World cities with its newest editRevision, here the one the basemap change answered. The published link stops working at once.", "value": { "editRevision": "2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c", "lastChangedAt": "2026-10-20T09:00:01.530Z", "lastChangedBy": { "name": "Ana Diaz", "sqlName": "ana_diaz" } } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "409": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "The active publication's settings." }, "204": { "description": "The map is not published." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/maps/{id}/published-fields": { "get": { "summary": "What each layer shares when this map is published", "description": "A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The shared-field statement: per layer, the effective published field set — fields marked `required` are what the published map cannot render without and publish regardless of any list — the mode (derived | list), and every field an explicit list could name. The publish surface renders exactly this; the wire carries exactly what it states. A layer whose SQL cannot resolve degrades to a per-layer error while the rest answer.", "tags": [ "Publish" ], "x-tool": "get_published_fields", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the published fields of the map {subject}", "subject": { "resource": "maps", "argument": "id" } }, "x-relevance": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedFieldsStatement" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Map id." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/publications/{token}": { "delete": { "summary": "Revoke a deactivated owner's publication", "description": "Requires a current admin through a cookie session or bearer token. Revokes only the supplied token when its owner is currently deactivated, checked in the same transaction as current admin authority. An active owner's token, an unknown token and a revoked token receive identical not_found responses with no change. This operation never reads or returns private map content or account identity, and grants no other access. Deactivation alone leaves existing links available; reactivation restores the owner's private access. Responses, including refusals, are private, no-store. Cookie mutations require the same trusted Origin.", "tags": [ "Publish" ], "x-tool": "revoke_inactive_publication", "x-effects": { "readOnly": false, "writes": [ { "resource": "publications", "collection": true, "argument": "token" } ] }, "x-mcp": { "destructiveHint": true, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-confirmation": { "target": "Revoke {target}?", "consequence": "The public link will stop working.", "subject": { "path": null, "argument": "token", "name": "" } }, "x-display": { "verb": "Revoked publication {subject}", "subject": { "resource": "publications", "argument": "token" } }, "x-relevance": [], "x-confirm": true, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The known publication token to revoke. This operation does not discover private maps.", "examples": { "deactivatedOwner": { "summary": "Take a deactivated account's published map offline", "value": "" } } } ], "responses": { "204": { "description": "Publication revoked. No content is returned.", "x-examples": { "deactivatedOwner": { "summary": "Take a deactivated account's published map offline", "description": "Needs an admin's token and the publish token of a map whose owner is deactivated: the end of the map's link, /v/. The answer has no body, and the link stops working at once. The account and the map stay." } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The known publication token to revoke. This operation does not discover private maps." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/catalogue/tables": { "get": { "summary": "Read the schema-only table catalogue", "description": "A dataset is reached by its owner and by the owner and people of every project it is filed in. Lists, schema discovery and counts cover exactly the reached datasets and name each one's owner and the name the caller would type for it: the plain name for the caller's own, . for another owner's. Another owner's dataset is shown without connection facts and without links to what the caller cannot reach: a PostGIS snapshot shows its origin kind, with neither its connection nor its remote schema and table. A bare dataset name in a path or parameter is the caller's own dataset. On dataset reads, features, downloads and operation parameters, another owner's dataset the caller reaches is addressed by its qualified name, and in a /api/tables path also by its identifier; changing one by any address answers forbidden. Datasets change, refresh and go only by their owner; administrators reach nothing more. Upload and sketch suffixes ignore other accounts' names. Unreached and missing datasets, maps and project references return not_found before source or artifact access; a refused change leaves resources unchanged. Refresh and geometry changes preserve the dataset's identity and owner and recheck account activity at commit. Names, stable identities, owners, the reached projects each dataset is filed in, recorded row counts and geometry facts with stored artifact column names and types. Reads metadata only, without evaluating row previews or healing geometry records. Recorded geometry identity is separate from the physical column type. Ordered by qualifiedName, the name the caller would type, which is unique within the caller's reach: two same-named datasets of different owners each appear exactly once. At most 32 tables and 64 columns per table per page. after continues tables; columnOffset continues columns for a named table. total counts matching tables, columnCount counts each table’s columns. Incomplete collections carry nextAfter or nextColumnOffset. A missing artifact fails the read instead of returning a false empty schema. Responses are bounded to 96 KiB; a response that cannot fit answers 422 catalogue_too_large so the caller can request fewer tables or columns. No artifact paths, source configuration, credentials, row samples or attachment bytes are returned.", "tags": [ "Tables" ], "x-tool": "read_table_catalogue", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read the table catalogue" }, "x-relevance": [ "builder", "sql", "workflow" ], "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Exclusive qualifiedName cursor from nextAfter.", "schema": { "type": "string" } }, { "name": "names", "in": "query", "required": false, "description": "Comma-separated exact names as the caller would type them (qualifiedName), at most 32: a plain name is the caller's own dataset, . another owner's. Missing or unreached names answer not_found.", "schema": { "type": "string" } }, { "name": "project", "in": "query", "required": false, "description": "Only this reached project's datasets, whoever owns them; none means the caller's own datasets filed in no project at all. An unknown or unreached project answers not_found.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Tables per page, 1 to 32; default 32.", "schema": { "type": "integer", "minimum": 1, "maximum": 32 }, "examples": { "firstPage": { "summary": "Read a page of one dataset with its columns", "value": 1 } } }, { "name": "columns", "in": "query", "required": false, "description": "Columns per table, 0 to 64; default 64. Zero returns identities and recorded facts with the column count.", "schema": { "type": "integer", "minimum": 0, "maximum": 64 } }, { "name": "columnOffset", "in": "query", "required": false, "description": "Zero-based column cursor, default 0.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCatalogue" }, "examples": { "firstPage": { "summary": "Read a page of one dataset with its columns", "description": "Needs a token, and the datasets world_cities and big_cities. nextAfter is the cursor for the next page: send it as after.", "value": { "tables": [ { "id": "c2e8f4a1-6b3d-4f97-a5c0-1d2e3f4a5b6c", "name": "big_cities", "qualifiedName": "big_cities", "owner": { "name": "Ana Diaz", "sqlName": "ana_diaz" }, "projectIds": [], "rowCount": 15, "geometryColumn": "geometry", "geometryType": "POINT", "crsAssumed": true, "columns": [ { "name": "name", "type": "VARCHAR" }, { "name": "country", "type": "VARCHAR" }, { "name": "population", "type": "BIGINT" }, { "name": "geometry", "type": "GEOMETRY('EPSG:4326')" } ], "columnCount": 4, "nextColumnOffset": null } ], "total": 2, "nextAfter": "big_cities" } } } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Tables" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Exclusive qualifiedName cursor from nextAfter.", "schema": { "type": "string" } }, { "name": "names", "in": "query", "required": false, "description": "Comma-separated exact names as the caller would type them (qualifiedName), at most 32: a plain name is the caller's own dataset, . another owner's. Missing or unreached names answer not_found.", "schema": { "type": "string" } }, { "name": "project", "in": "query", "required": false, "description": "Only this reached project's datasets, whoever owns them; none means the caller's own datasets filed in no project at all. An unknown or unreached project answers not_found.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Tables per page, 1 to 32; default 32.", "schema": { "type": "integer", "minimum": 1, "maximum": 32 } }, { "name": "columns", "in": "query", "required": false, "description": "Columns per table, 0 to 64; default 64. Zero returns identities and recorded facts with the column count.", "schema": { "type": "integer", "minimum": 0, "maximum": 64 } }, { "name": "columnOffset", "in": "query", "required": false, "description": "Zero-based column cursor, default 0.", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Success." }, "400": { "description": "Error with a machine-readable code and human message." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error with a machine-readable code and human message." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "422": { "description": "Error with a machine-readable code and human message." }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/runs": { "post": { "summary": "Reserve an assistant run", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Obtain a server-issued run identity bound to the authenticated account before sending a new message. Performs no model or product operation. Eight reserved, running or awaiting-confirmation runs share capacity; unused reservations expire after five minutes. Capacity refusal preserves occupied slots and points to GET /api/assistant/pending and DELETE /api/assistant/runs/{id} for recovery or release.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "assistant", "collection": true } ] }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRun" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/runs/{id}": { "get": { "summary": "Read assistant recovery state", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Run receipts and parked confirmations retain their initiating account through completion, failure and deletion of any output. Deactivation interrupts unfinished execution without retaining late provider content; reactivation restores access to the same private receipts. Only the reserving account can read or control this run; another account receives 404 assistant_run_unavailable. Read reserved, running, awaiting_confirmation, completed, interrupted, failed or unavailable state, received text, attempted actions, known outcomes and the original open pending action. No replay or continuation occurs. Unknown, evicted and pre-restart identities answer 404 assistant_run_unavailable. Only the newest 256 terminal receipts are retained, each at most 64 KiB; incomplete marks omitted text or arguments. Raw tool result bodies are never retained. Live recovery is bounded to 1 MiB, with oversized proposed actions refused before execution. provenance carries the model choice the run bound and, separately, the identities its completed provider responses reported, inside those same bounds.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRun" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "delete": { "summary": "Release an assistant reservation or abandon a pending turn", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Release an unused reservation (state becomes unavailable) or abandon an awaiting-confirmation turn (interrupted, pending action superseded). Neither starts model or tool work. Other states refuse with 409 assistant_run_state. Frees admission capacity; the old identity never starts new work.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "assistant", "collection": true, "argument": "id" } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRun" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "DELETE, GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/runs/{id}/cancel": { "post": { "summary": "Cancel active assistant execution", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Stops further admission and cancels an active provider or read-only tool request. A dispatched mutation settles to its known API outcome; an unknown outcome stays uncertain and is never re-executed. Accepted asynchronous jobs retain their own lifecycle and identity. Closing the execution stream has the same effect. Completed changes remain and an already parked confirmation stays recoverable. Closing a duplicate observer or recovery read cannot cancel the execution. Read the run again to observe settlement; this request does not wait for it.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "assistant", "collection": true, "argument": "id" } ] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRun" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Server-issued run identity" } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/pending": { "get": { "summary": "List open assistant confirmations", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Returns only the caller’s open pending actions (at most eight) with runId, server-issued pending id, original tool, exact arguments and confirmation words. Includes actions whose stream event was lost; read on pane mount. Pending actions have no wall-clock expiry. This read starts no work.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantPendingList" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant": { "get": { "summary": "Assistant status", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Whether the in-product assistant is enabled. When enabled, reports the resolved provider, model, step budget and whether the map is checked automatically after a turn that changed it, and every model a request may choose on this instance with that model's own effort levels. When not, reports the reason and how to enable it. The model credential is never included. Enablement is a deployment setting (an Anthropic or OpenAI API key); with none, this is a complete non-assistant instance and the surface is absent.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantStatus" }, "examples": { "enabled": { "summary": "Read the assistant's status on an instance with a key", "description": "Needs a token. The instance has an Anthropic key and the shipped model list.", "value": { "enabled": true, "provider": "anthropic", "model": "claude-opus-5", "models": [ { "id": "claude-opus-5", "name": "Opus 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" }, { "value": "xhigh", "label": "XHigh" }, { "value": "max", "label": "Max" } ] }, { "id": "claude-fable-5", "name": "Fable 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" }, { "value": "xhigh", "label": "XHigh" } ] }, { "id": "claude-sonnet-5", "name": "Sonnet 5", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" } ] }, { "id": "claude-haiku-4", "name": "Haiku 4", "efforts": [ { "value": "default", "label": "Default" }, { "value": "low", "label": "Low" }, { "value": "medium", "label": "Medium" }, { "value": "high", "label": "High" } ] } ], "catalogue": { "source": "shipped", "instance": "absent" }, "stepBudget": 20, "autoCheck": true } }, "notEnabled": { "summary": "Read the assistant's status on an instance without a key", "description": "Needs a token. The instance has no provider key, so the assistant is off.", "value": { "enabled": false, "reason": "No model credential is configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY (optionally DEZFIL_AI_PROVIDER and DEZFIL_AI_MODEL) and restart to enable the assistant." } } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/policy": { "get": { "summary": "Read a page's assistant policy and default offer", "description": "Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. For a page (builder, sql or workflow), the action policy its runs bind with, every operation that policy admits, the operations a run under that page is offered at its start (the page's relevant operations and the grounding reads, inside admission), and whether discovery is offered to reach the admitted operations the offer omits. Reports the same derivation the message route applies. Starts no work. A page outside the three answers 400 invalid_request.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "page", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "builder", "sql", "workflow" ] }, "description": "The page the run would carry as its context." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantPolicy" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "page", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "builder", "sql", "workflow" ] }, "description": "The page the run would carry as its context." } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/assistant/messages": { "post": { "summary": "Send a message to the assistant", "description": "At most 131,072 wire bytes; a larger body is refused with `assistant_submission_too_large` before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Reservations and pending actions are bound to their account. Every continuation reauthenticates that same account and uses its current permissions. A foreign run is unavailable; a foreign pending action is unknown. Grounding, subject reads, execution and automatic checks use the caller’s bearer-equivalent identity on every internal request. No credential is retained with a pending action. Every new message requires a runId from POST /api/assistant/runs. Unreserved requests refuse with 400 assistant_reservation_required before work. Unknown or evicted identities refuse with 404 assistant_run_unavailable. The first accepted submission binds its message, history, context and supersession. Identical concurrent or later submissions return an application/json AssistantRun snapshot without another exchange; changed input refuses with 409 assistant_run_conflict. Plain-English request; the assistant works through the same documented API these docs describe and streams its actions back as newline-delimited JSON events (application/x-ndjson): assistant text, tool calls and their results, confirmation prompts for destructive or publishing actions, and a terminal done/error. A confirm_required event pauses the run and carries a server-issued pending-action id; resolve it by posting a resolution referencing that id. Approval executes exactly the presented action once and the run continues where it paused, a decline skips it and the assistant finishes its turn. A pending action resolves at most once (409 pending_resolved on a repeat); a new message may name a pending action it supersedes (the implicit decline), after which resolution answers 409 pending_superseded. A hidden or unknown pending id cannot be resolved; naming one only to supersede it is a harmless no-op. Pending actions are working state, and bounded: after a container replacement resolution answers 404 pending_unknown and nothing re-runs; only a small number of reserved, running or parked runs share eight admission slots. A full instance refuses new reservations with assistant_capacity; live and pending runs are never silently evicted. Only unused reservations expire after five minutes. Pending turns have no wall-clock expiry and are recoverable through GET /api/assistant/pending. Release a reservation or abandon a pending turn with DELETE /api/assistant/runs/{id}. The resolved trace behind the 409 answers is bounded, so a sufficiently old repeat answers pending_unknown instead. The step budget spans the whole turn, pauses included. Submissions above 128 KiB refuse with assistant_submission_too_large before work. Terminal recovery keeps 256 receipts of at most 64 KiB; live recovery is at most 1 MiB per run and stops with assistant_recovery_limit before protected action data would exceed it. Returns 404 with assistant_disabled when no model credential is configured. The page action policy binds at the first accepted submission from the context's page and holds through the run's confirmation continuations: a builder context, and no context, admit every generated tool with its confirmation gates; a sql context and a workflow context admit only the operations that declare themselves read-only by their effects, the read-only query and the schema reads among them, and no operation that declares a write on any argument, conditional (plan or run) operations included; of the read-only ones they refuse any that reaches outside this server or asks for confirmation, a service's or a part's Test among them. The model is offered only what its run admits. A call outside the set, however it arrives, is refused before any product operation: its tool_result carries the documented error assistant_action_not_admitted and the run's receipt records the action as refused. A message may carry an optional choice of model and effort; GET /api/assistant reports what this instance offers. It binds with the rest of the submission at the first accepted one and holds through every continuation of the run; a choice on a resolution is ignored. A malformed choice, a model this instance does not offer, an effort the selected model does not offer and a named level for a model that has no levels of its own refuse with 400 assistant_choice_invalid, assistant_model_not_offered, assistant_effort_not_offered and assistant_effort_not_supported respectively, each before the run binds and before any provider call or product operation, leaving the reservation unbound and reusable. The run's receipt reports the pair it bound and, separately, the identities its completed provider responses named.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true }, { "resource": "layers", "collection": true }, { "resource": "tables", "collection": true }, { "resource": "publications", "collection": true }, { "resource": "recipes", "collection": true }, { "resource": "runs", "collection": true }, { "resource": "projects", "collection": true }, { "resource": "connections", "collection": true }, { "resource": "palettes", "collection": true }, { "resource": "settings", "collection": true }, { "resource": "caches", "collection": true }, { "resource": "basemaps", "collection": true }, { "resource": "templates", "collection": true }, { "resource": "assistant", "collection": true } ] }, "requestBody": { "x-byte-limit": 131072, "x-byte-error": "assistant_submission_too_large", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRequest" }, "example": { "runId": "server-issued-run-id", "message": "show me all parks within 500m of a station", "history": [] } } } }, "responses": { "200": { "description": "A stream of newline-delimited assistant events (application/x-ndjson).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRun" } }, "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/AssistantEvent" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/mcp": { "post": { "summary": "MCP endpoint", "description": "At most 16,777,216 wire bytes; a larger body is refused with `request_body_too_large` before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Model Context Protocol over the streamable HTTP transport, stateless. Supply an account API token in Authorization: Bearer on every request. Tools use the caller’s current permissions, including admin checks. Cookie callers use a short-lived server delegation tied to their session. Every internal hop rechecks current access; credentials never enter model input or retained confirmation state. Point a token-capable MCP client at this URL to get one tool per documented operation (the operation's x-tool name). External agents bring their own model; no server-side model credential is needed. The whole journey (upload, SQL, layer, style, publish) is completable through these tools.", "tags": [ "Agents" ], "x-tool": false, "x-effects": { "readOnly": false, "writes": [ { "resource": "maps", "collection": true }, { "resource": "layers", "collection": true }, { "resource": "tables", "collection": true }, { "resource": "publications", "collection": true }, { "resource": "recipes", "collection": true }, { "resource": "runs", "collection": true }, { "resource": "projects", "collection": true }, { "resource": "connections", "collection": true }, { "resource": "palettes", "collection": true }, { "resource": "settings", "collection": true }, { "resource": "caches", "collection": true }, { "resource": "basemaps", "collection": true }, { "resource": "templates", "collection": true }, { "resource": "assistant", "collection": true } ] }, "requestBody": { "x-byte-limit": 16777216, "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "A JSON-RPC 2.0 MCP message." }, "examples": { "createMap": { "summary": "Call the tool create_map", "description": "Needs a token. Send Accept: application/json, text/event-stream; the answer arrives as one server-sent event holding the JSON-RPC response, the tool's result in structuredContent.", "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_map", "arguments": { "name": "Field notes" } } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "JSON-RPC response, as application/json or text/event-stream.", "content": { "application/json": { "schema": { "type": "object", "description": "A JSON-RPC 2.0 MCP response." } }, "text/event-stream": { "schema": { "type": "string", "description": "The JSON-RPC 2.0 MCP response as server-sent events." }, "examples": { "createMap": { "summary": "Call the tool create_map", "description": "Needs a token. Send Accept: application/json, text/event-stream; the answer arrives as one server-sent event holding the JSON-RPC response, the tool's result in structuredContent.", "value": "event: message\ndata: {\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"{\\\"id\\\":\\\"6a3f8d20-4c1e-4b97-a2d5-8e9f0c1b3a74\\\",\\\"name\\\":\\\"Field notes\\\",\\\"viewport\\\":{\\\"lng\\\":0,\\\"lat\\\":40,\\\"zoom\\\":1.3},\\\"basemap\\\":null,\\\"customBasemap\\\":null,\\\"basemapLayers\\\":null,\\\"note\\\":null,\\\"legendCorner\\\":null,\\\"legendOrder\\\":null,\\\"timeline\\\":null,\\\"widgets\\\":[],\\\"widgetsPublished\\\":true,\\\"publishToken\\\":null,\\\"publishedAt\\\":null,\\\"published\\\":false,\\\"createdAt\\\":\\\"2026-10-20T09:00:02.875Z\\\",\\\"updatedAt\\\":\\\"2026-10-20T09:00:02.875Z\\\",\\\"editRevision\\\":\\\"9c41e07a5d2b4f8e8a6c1d3b7e05f2a4\\\",\\\"lastChangedAt\\\":\\\"2026-10-20T09:00:02.875Z\\\",\\\"lastChangedBy\\\":{\\\"name\\\":\\\"Ana Diaz\\\",\\\"sqlName\\\":\\\"ana_diaz\\\"},\\\"projectId\\\":null,\\\"owner\\\":{\\\"name\\\":\\\"Ana Diaz\\\",\\\"sqlName\\\":\\\"ana_diaz\\\"},\\\"home\\\":\\\"ana_diaz\\\"}\"}],\"structuredContent\":{\"result\":{\"id\":\"6a3f8d20-4c1e-4b97-a2d5-8e9f0c1b3a74\",\"name\":\"Field notes\",\"viewport\":{\"lng\":0,\"lat\":40,\"zoom\":1.3},\"basemap\":null,\"customBasemap\":null,\"basemapLayers\":null,\"note\":null,\"legendCorner\":null,\"legendOrder\":null,\"timeline\":null,\"widgets\":[],\"widgetsPublished\":true,\"publishToken\":null,\"publishedAt\":null,\"published\":false,\"createdAt\":\"2026-10-20T09:00:02.875Z\",\"updatedAt\":\"2026-10-20T09:00:02.875Z\",\"editRevision\":\"9c41e07a5d2b4f8e8a6c1d3b7e05f2a4\",\"lastChangedAt\":\"2026-10-20T09:00:02.875Z\",\"lastChangedBy\":{\"name\":\"Ana Diaz\",\"sqlName\":\"ana_diaz\"},\"projectId\":null,\"owner\":{\"name\":\"Ana Diaz\",\"sqlName\":\"ana_diaz\"},\"home\":\"ana_diaz\"},\"history\":null},\"isError\":false},\"jsonrpc\":\"2.0\",\"id\":1}\n\n" } } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}": { "get": { "summary": "Read a published view", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. The read-only view for a token: map, viewport, styled layers, and render data. The only data path a published page uses. Token ownership is checked before reuse and after assembly; responses are private and not stored so revocation cannot be bypassed by a browser or intermediary cache. Feature properties carry exactly each layer's effective published field set — the derived projection (style, label, tooltip/pop-up, live-filter, timeline and published-widget fields) or the author's explicit list plus the fields the map needs to render; hidden layers contribute no feature data.", "tags": [ "Publish" ], "x-tool": "view_published_map", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read a published map" }, "x-relevance": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedView" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "200": { "description": "Success." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down." }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/extent/{layerId}": { "post": { "summary": "A published layer's current data extent", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. At most 65,536 wire bytes. Excess answers 413 `request_body_too_large` before JSON parsing. Empty bodies keep their default selections. The published half of the extent capability: the bounding box of what the reader's current state leaves drawn. The reader never names a field — widget selections are keyed by widget id and resolve through the publication's stored widgets, and the timeline window's field comes from the map's own dock. A hidden layer or widget answers exactly as an unknown one does. Same shared reader rate limit as the other published lanes; `kind: \"empty\"` when nothing survives.", "tags": [ "Published" ], "x-tool": "published_layer_extent", "x-effects": { "readOnly": true, "writes": [] }, "x-mcp": { "destructiveHint": false, "openWorldHint": false, "idempotentHint": true }, "x-tool-output": { "envelope": "result-history" }, "x-display": { "verb": "Read a published layer's extent" }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the publication." } ], "requestBody": { "x-byte-limit": 65536, "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "type": "array", "items": { "type": "object" }, "description": "Widget selections, keyed by widget id — the same shape the widget-values lane accepts." }, "timeline": { "type": "object", "description": "The reader's timeline window: `min` and `max` time values, either nullable for an open end. The field is the map's docked one, never stated here." } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "The extent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerExtent" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the publication." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/widget-values": { "post": { "summary": "Widget values for a published view", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. At most 65,536 wire bytes. Excess answers 413 `request_body_too_large` before JSON parsing. Empty bodies keep their default selections. The live half of a published dashboard: the same batched computation as the builder path, under the published-view guarantees — the token must currently resolve, the map must ship widgets, selections pass stored-filter validation, and the anonymous viewer rate limit applies. Responses are private and never stored.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "requestBody": { "x-byte-limit": 65536, "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "$ref": "#/components/schemas/WidgetSelections" } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetValues" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/render/{layerId}": { "post": { "summary": "Re-render a published computed layer under selections", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. At most 65,536 wire bytes. Excess answers 413 `request_body_too_large` before JSON parsing. Empty bodies keep their default selections. The published settle lane: re-render one hexbin, grid, cluster, or heatmap layer under a reader's ephemeral selections — cells re-bin and clusters recount, read-only, with the same token checks and rate limit as other published reads. Selections may only reference fields the published surface declares — the layer's effective published field set, or a published widget's field; anything else answers 400 field_not_published before evaluation. Responses carry the effective set, and a hidden layer answers 404 like an absent one. Selection documents above 65,536 bytes are refused even when their filters meet the semantic count limits.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the published map." } ], "requestBody": { "x-byte-limit": 65536, "content": { "application/json": { "schema": { "type": "object", "properties": { "selections": { "type": "array", "items": { "$ref": "#/components/schemas/LayerFilter" } } } } } }, "x-byte-error": "request_body_too_large" }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerRender" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "413": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the published map." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "OPTIONS, POST" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/tiles/{layerId}/{z}/{x}/{y}": { "get": { "summary": "One vector tile of a published map's layer", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. Read-only under the publish token, in the tile-sized anonymous rate bucket. Only the layer's current ready server-shipped result is eligible; revocation, deletion, replacement, an inline transition, or a stale version returns the same clean not-found. Use the URL template the published view reports. Current tiles are private and must revalidate at the origin; a valid unchanged artifact may answer conditionally. A spot the current archive does not cover returns 204 with no body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the published map." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." }, { "name": "v", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Artifact version from the published view's URL template. When supplied, it must still be current." } ], "responses": { "200": { "description": "The tile.", "content": { "application/vnd.mapbox-vector-tile": { "schema": { "type": "string", "format": "binary" } } } }, "204": { "description": "No tile at these coordinates." }, "304": { "description": "The authorized current artifact matches If-None-Match." }, "404": { "description": "The publication or requested tile artifact is not current.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the published map." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." }, { "name": "v", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Artifact version from the published view's URL template. When supplied, it must still be current." } ], "responses": { "200": { "description": "The tile." }, "204": { "description": "No tile at these coordinates." }, "304": { "description": "The authorized current artifact matches If-None-Match." }, "404": { "description": "The publication or requested tile artifact is not current." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down." }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "layerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layer id within the published map." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/basemaps/satellite": { "get": { "summary": "The imagery style of a published map", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. The imagery style for a published page's reader, who is not signed in: the signed-in style's document, its raster source naming this publication's own tile address, `/api/published/{token}/basemaps/satellite/tiles/{z}/{x}/{y}{ratio}`, never the configured tile template. The published view's basemapUrl and the page's basemap switcher name this address. In the view budget. Served under the publish token only while the publication resolves, as its layer tiles are: a revoked or unknown token answers the same clean not_found, and so does a publication whose reader is not shown Satellite (the map is not on it, and its basemap switcher is off or no longer offers it). An instance with no imagery to draw now, none configured or a stored template its key no longer opens, answers 404 as the signed-in style does while none is configured. Private, no-store.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "200": { "description": "The style document.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "The publication is not current or does not show Satellite (not_found), or no imagery is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "200": { "description": "The style document." }, "404": { "description": "The publication is not current or does not show Satellite (not_found), or no imagery is configured." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down." }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } }, "/api/published/{token}/basemaps/satellite/tiles/{z}/{x}/{y}": { "get": { "summary": "One imagery tile of a published map", "description": "Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. Fetched now by the server from the tile template this instance configures and passed back, so the template and a key in it never leave the server. Use the tile address the imagery style names. Only the tile's z, x and y reach the template, each a whole number in plain decimal, z from 0 to 19 and x and y below 2 to the power of z, the row followed by @2x for a high-density tile or by nothing; anything else is refused with invalid_request before the imagery is asked. The template is filled from these alone as MapLibre fills a raster template: {z}, {x}, {y} (counted by the style source's scheme), {ratio} (@2x or nothing), {quadkey}, {prefix} and {bbox-epsg-3857}. No query, header or credential of the request goes with them. The fetch takes the egress policy at every hop, waits at most ten seconds and reads at most 4 MiB; only a whole PNG, JPEG, GIF, WebP or AVIF image passes back, with the type its bytes are, and no tile is stored. Every failure upstream answers imagery_unavailable, whose message says what went wrong and never the tile address or its key; a template carrying a user name or password is not drawn and answers the same. Private, no-store. In the tile budget. Served under the publish token only while the publication resolves, as its layer tiles are: a revoked or unknown token answers the same clean not_found, and so does a publication whose reader is not shown Satellite (the map is not on it, and its basemap switcher is off or no longer offers it). An instance with no imagery to draw now, none configured or a stored template its key no longer opens, answers 404 as the signed-in style does while none is configured. The token is checked again once the tile has come, so a publication revoked meanwhile passes nothing back.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "200": { "description": "The tile, as the imagery drew it.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The publication is not current or does not show Satellite (not_found), or no imagery is configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "imagery_unavailable: the imagery failed, or this instance's egress policy refused its address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-Dezfil-Egress-Refused": { "description": "imagery where the egress policy refused the imagery's address, at its host or at a redirect; absent for every other failure. An image export that meets it refuses its image rather than make it without the imagery.", "schema": { "type": "string", "const": "imagery" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "head": { "summary": "Read response headers", "description": "Automatic HEAD uses GET with no response body.", "tags": [ "Publish" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "200": { "description": "The tile, as the imagery drew it." }, "400": { "description": "Error with a machine-readable code and human message." }, "404": { "description": "The publication is not current or does not show Satellite (not_found), or no imagery is configured." }, "405": { "description": "Unsupported method. HEAD has no response body.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "429": { "description": "rate_limited: Too many requests. Please slow down." }, "502": { "description": "imagery_unavailable: the imagery failed, or this instance's egress policy refused its address.", "headers": { "X-Dezfil-Egress-Refused": { "description": "imagery where the egress policy refused the imagery's address, at its host or at a redirect; absent for every other failure. An image export that meets it refuses its image rather than make it without the imagery.", "schema": { "type": "string", "const": "imagery" } } } }, "503": { "description": "ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution." }, "504": { "description": "Error with a machine-readable code and human message." }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "options": { "summary": "Read allowed methods", "description": "Automatic OPTIONS returns no body and the Allow header. Authentication is required.", "tags": [ "System" ], "x-tool": false, "x-effects": { "readOnly": true, "writes": [] }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Publish token (22 characters)." }, { "name": "z", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile zoom, 0 to 19." }, { "name": "x", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile column, below 2 to the power of z." }, { "name": "y", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tile row, below 2 to the power of z, followed by @2x for a high-density tile." } ], "responses": { "204": { "description": "Allowed methods.", "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "401": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: the method is unsupported for this path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "description": "Exactly the documented methods for this path.", "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" } } } }, "503": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error with a machine-readable code and human message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "CookieSession": [] }, { "BearerToken": [] } ] } } }, "components": { "securitySchemes": { "CookieSession": { "type": "apiKey", "in": "cookie", "name": "dezfil_session", "description": "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." }, "BearerToken": { "type": "http", "scheme": "bearer", "description": "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." } }, "schemas": { "Account": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "sqlName": { "type": "string", "pattern": "^[a-z][a-z0-9_]{2,31}$", "description": "The account's SQL name, unique on the instance. Derived from the display name (else the email's local part, else the word user, with a number added on a collision or a name the query engine reserves) when the account is created or upgraded, and fixed thereafter: changing the name or email never changes it." }, "isAdmin": { "type": "boolean" }, "pictureVersion": { "type": "string", "description": "The version of the person's picture, present while they have one and new whenever it is replaced; absent while they have none, when their initials stand in. GET /api/accounts/{sqlName}/picture?v= reads it." }, "status": { "type": "string", "enum": [ "invited", "active", "deactivated" ] }, "isOriginal": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "lastSignInAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "sqlName", "isAdmin", "status", "isOriginal", "createdAt", "updatedAt", "lastSignInAt" ] }, "AccountSession": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": [ "account" ], "additionalProperties": false }, "AuthEntry": { "type": "object", "properties": { "instanceName": { "type": [ "string", "null" ] }, "signInMessage": { "type": "string", "maxLength": 280, "default": "" }, "lostPasswordContact": { "type": "string", "maxLength": 120, "default": "" }, "landingPage": { "type": "string", "enum": [ "home", "projects", "maps", "workflows", "data", "sql" ], "default": "home" }, "passwordMin": { "type": "integer", "minimum": 8, "maximum": 64, "description": "The fewest characters a password chosen on these screens needs: 8 for the first account, then the instance's shortest password, which admins set from 8 to 64." }, "setupRequired": { "type": "boolean" }, "prefillName": { "type": "string" } }, "required": [ "instanceName", "signInMessage", "lostPasswordContact", "landingPage", "passwordMin", "setupRequired" ], "additionalProperties": false }, "SignedOut": { "type": "object", "properties": { "signedOut": { "type": "boolean", "const": true } }, "required": [ "signedOut" ], "additionalProperties": false }, "Person": { "type": "object", "description": "A person a resource names where the app draws their face, such as its owner. The display name, the SQL name and the picture's version, never an email.", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string", "description": "The person's SQL name, the qualifier other people's SQL uses for their datasets." }, "pictureVersion": { "type": "string", "description": "The version of the person's picture, present while they have one and new whenever it is replaced; absent while they have none, when their initials stand in. GET /api/accounts/{sqlName}/picture?v= reads it." } }, "required": [ "name", "sqlName" ] }, "WrittenIn": { "type": "object", "description": "Where SQL or a dataset name was written: the context whose names it uses. console is the caller's own SQL console, where a plain name is the caller's own dataset; map is a map's SQL home, as its layers are read; workflow is a workflow's home with its declared outputs as the caller runs them. A map or workflow the caller does not reach answers as a missing one.", "properties": { "kind": { "type": "string", "enum": [ "console", "map", "workflow" ] }, "id": { "type": "string", "description": "The map or workflow; absent for console." } }, "required": [ "kind" ], "additionalProperties": false }, "ApiToken": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "revokedAt": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "description": "When the token stops working; null when it never expires. An expired token is refused with token_expired and stays listed until revoked." } }, "required": [ "id", "name", "createdAt", "lastUsedAt", "revokedAt", "expiresAt" ] }, "CreatedApiToken": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "revokedAt": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "description": "When the token stops working; null when it never expires. An expired token is refused with token_expired and stays listed until revoked." }, "secret": { "type": "string", "description": "Disclosed once. Store it securely before leaving this response." } }, "required": [ "id", "name", "createdAt", "lastUsedAt", "revokedAt", "expiresAt", "secret" ] }, "ApiTokens": { "type": "object", "additionalProperties": false, "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiToken" } } }, "required": [ "tokens" ] }, "PasswordChanged": { "type": "object", "additionalProperties": false, "properties": { "changed": { "type": "boolean", "const": true } }, "required": [ "changed" ] }, "TokenRevoked": { "type": "object", "additionalProperties": false, "properties": { "revoked": { "type": "boolean", "const": true } }, "required": [ "revoked" ] }, "AccountDeletionStatus": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "needs-retry", "completed" ] } }, "required": [ "id", "state" ] }, "AccountDeletionProgress": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "needs-retry" ] }, "admittedReads": { "type": "integer", "minimum": 0, "description": "Present while pending: the reads admitted before the deletion that it still waits on to settle." } }, "required": [ "id", "state" ] }, "PendingAccountDeletion": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "needs-retry" ] }, "account": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "isAdmin": { "type": "boolean" } }, "required": [ "id", "name", "email", "isAdmin" ] } }, "required": [ "id", "state", "account" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "state": { "type": "string", "const": "unreadable" } }, "required": [ "id", "state" ] } ] }, "AccountDeletionPreview": { "type": "object", "additionalProperties": false, "properties": { "account": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, "invited": { "type": "boolean" }, "totals": { "type": "object", "additionalProperties": false, "properties": { "maps": { "type": "integer", "minimum": 0 }, "datasets": { "type": "integer", "minimum": 0 }, "workflows": { "type": "integer", "minimum": 0 }, "projects": { "type": "integer", "minimum": 0 }, "connections": { "type": "integer", "minimum": 0 }, "publishedLinks": { "type": "integer", "minimum": 0 } }, "required": [ "maps", "datasets", "workflows", "projects", "connections", "publishedLinks" ] }, "people": { "type": "integer", "minimum": 0 }, "confirmation": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "account", "invited", "totals", "people", "confirmation" ] }, "AccountDeletionPreviewResult": { "anyOf": [ { "$ref": "#/components/schemas/AccountDeletionPreview" }, { "$ref": "#/components/schemas/AccountDeletionStatus" } ] }, "UserInvitationConflict": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "const": "email_taken" }, "message": { "type": "string" }, "accountId": { "type": "string" }, "canReactivate": { "type": "boolean" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Users": { "type": "object", "additionalProperties": false, "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "deletions": { "type": "array", "items": { "$ref": "#/components/schemas/PendingAccountDeletion" } } }, "required": [ "users", "deletions" ] }, "IssuedSignInLink": { "type": "object", "additionalProperties": false, "properties": { "account": { "$ref": "#/components/schemas/Account" }, "signInUrl": { "type": "string", "description": "One-time hand-over. The credential is in the fragment, never the query string." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "account", "signInUrl", "expiresAt" ] }, "InstanceSettingsPatch": { "type": "object", "additionalProperties": false, "properties": { "uploadMaxMb": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 102400, "description": "Largest upload. Size cap for one uploaded file. Null clears the stored value." }, "dataProcessingTimeoutS": { "type": [ "integer", "null" ], "minimum": 60, "maximum": 21600, "description": "Data processing time limit. Time to receive one upload, and, counted apart, time for one data processing job, such as an import. Null clears the stored value." }, "remoteMaxMb": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 102400, "description": "Largest link import. Size cap for a URL or object-store import. Null clears the stored value." }, "remoteTimeoutS": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 3600, "description": "Link import time limit. Time for one link import's whole download. Null clears the stored value." }, "overtureMaxKm2": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "Overture area. The largest area one Overture import of places may cover; other themes may cover more or less, by how dense they are. Null clears the stored value." }, "osmMaxKm2": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000, "description": "OpenStreetMap area. The largest area one OpenStreetMap import may cover. Null clears the stored value." }, "overpassTimeoutS": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 900, "description": "Overpass time limit. Time budget sent with every Overpass query. Null clears the stored value." }, "overpassCacheHours": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 720, "description": "Overpass cache freshness. How long an Overpass response stays fresh. Null clears the stored value." }, "queryTimeoutS": { "type": [ "integer", "null" ], "minimum": 5, "maximum": 600, "description": "Query time limit. Time for one query, whether the SQL people run, a layer, an inspection, a preview or a published map. Null clears the stored value." }, "previewRows": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 100000, "description": "Rows shown in results. Row cap for result previews. Null clears the stored value." }, "exportRenderTimeoutS": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 300, "description": "Time limit per image. Time for one image, its wait for a turn included. Null clears the stored value." }, "exportRenderConcurrency": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 8, "description": "Images at once. Images the server draws at the same time. Null clears the stored value." }, "geocodePaceMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 60000, "description": "Address finder pace. Minimum request gap; zero means no gap. Null clears the stored value." }, "geocodeMatchCacheHours": { "type": [ "integer", "null" ], "minimum": 24, "maximum": 8760, "description": "Address match freshness. How long matched addresses are cached. Null clears the stored value." }, "isochronePaceMs": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 60000, "description": "Travel-time pace. Minimum routing request gap; zero means no gap. Null clears the stored value." }, "isochroneRequestTimeoutS": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "Travel-time request limit. Deadline for one routing exchange. Null clears the stored value." }, "isochroneCacheHours": { "type": [ "integer", "null" ], "minimum": 24, "maximum": 8760, "description": "Travel-time cache freshness. How long complete routing answers are cached. Null clears the stored value." }, "geocodeRequestTimeoutS": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 120, "description": "Address request limit. Deadline for one geocoding exchange. Null clears the stored value." }, "operationTimeoutS": { "type": [ "integer", "null" ], "minimum": 30, "maximum": 7200, "description": "Time limit per run. Time for one tool run, not counting its wait for a turn. Null clears the stored value." }, "operationConcurrency": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 8, "description": "Operation runs at once. Tool runs at the same time; they share the engine that runs people's SQL. Null clears the stored value." }, "operationQueueMax": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200, "description": "Operation runs waiting. Tool runs that may wait for a turn. Null clears the stored value." }, "publicRateLimit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000, "description": "Requests per source. Requests one visitor may make to published maps, counted by network address across every published map. Null clears the stored value." }, "publicTileRateLimit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "Tile requests per source. Tile requests one visitor may make to published maps, counted by network address across every published map. Null clears the stored value." }, "s3Endpoint": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "S3 endpoint. The S3-compatible store that s3:// links are read from without the server's credentials. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_S3_ENDPOINT locks it." }, "overpassUrl": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "Overpass endpoint. Endpoint for OpenStreetMap imports. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_OVERPASS_URL locks it." }, "satelliteUrl": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "Satellite template. Raster tile template enabling satellite imagery. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. It must hold {z}, {x}, {y}; the save-time check reads it with each filled with a digit. It must carry no user name or password: the imagery is not drawn from such an address, so the key belongs in the path or the query. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_SATELLITE_URL locks it." }, "satelliteAttribution": { "type": [ "string", "null" ], "pattern": "^\\s*[\\s\\S]{0,160}\\s*$", "description": "Satellite credit. Credit line required by the imagery provider. Null clears the stored value. Text is trimmed before the 160-character limit; empty text clears to the default. A set DEZFIL_SATELLITE_ATTRIBUTION locks it." }, "geocoderUrl": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "Address finder. Nominatim-compatible endpoint for search and batch geocoding. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_GEOCODER_URL locks it." }, "isochroneUrl": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "Travel-time endpoint. Valhalla-compatible endpoint for travel-time areas. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_ISOCHRONE_URL locks it." }, "templatesCatalogueUrl": { "type": [ "string", "null" ], "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "Catalogue address. Where the template catalogue's index is read. Null clears the stored value. An http or https address with a host, at most 2048 characters once trimmed, kept as given. Write-only: it is stored encrypted with the instance's key and every read gives back its scheme and host alone, so a new key means sending the whole address again. A set DEZFIL_TEMPLATES_CATALOGUE locks it. Only DEZFIL_TEMPLATES_CATALOGUE may name a folder on the server instead; a folder is never taken here." }, "instanceName": { "type": [ "string", "null" ], "pattern": "^\\s*[\\s\\S]{0,80}\\s*$", "description": "Instance name. Name beside the wordmark and in browser titles. Null clears the stored value. Text is trimmed before the 80-character limit; empty text clears to the default." }, "signInMessage": { "type": [ "string", "null" ], "pattern": "^\\s*[\\s\\S]{0,280}\\s*$", "description": "Sign-in message. Optional message on the sign-in page. Null clears the stored value. Text is trimmed before the 280-character limit; empty text clears to the default." }, "lostPasswordContact": { "type": [ "string", "null" ], "pattern": "^\\s*[\\s\\S]{0,120}\\s*$", "description": "Lost-password contact. Contact line for password recovery; empty uses the built-in line. Null clears the stored value. Text is trimmed before the 120-character limit; empty text clears to the default." }, "landingPage": { "type": [ "string", "null" ], "enum": [ "home", "projects", "maps", "workflows", "data", "sql", null ], "description": "Landing page. Preferred entry destination after sign-in. Null clears the stored value." }, "newMap.basemap": { "type": [ "string", "null" ], "enum": [ "auto", "dark", "light", "streets", "satellite", null ], "description": "Basemap. The basemap a new map starts on. Auto follows the theme; a basemap the instance no longer offers starts on Auto. Null clears the stored value." }, "newMap.latitude": { "type": [ "number", "null" ], "minimum": -85, "maximum": 85, "description": "Starting latitude. The latitude a new map opens at. Null clears the stored value." }, "newMap.longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Starting longitude. The longitude a new map opens at. Null clears the stored value." }, "newMap.zoom": { "type": [ "number", "null" ], "minimum": 0, "maximum": 22, "description": "Starting zoom. The zoom a new map opens at. Null clears the stored value." }, "newMap.legendCorner": { "type": [ "string", "null" ], "enum": [ "top-left", "top-right", "bottom-left", "bottom-right", null ], "description": "Legend corner. Where a new map's legend sits. Null clears the stored value." }, "newLayer.colorCycle": { "type": [ "string", "null" ], "enum": [ "uber_viz_qualitative", "bold", "tab10", "paired", "dark2", "set3", null ], "description": "Color cycle. The palette whose colors new layers take in turn, drawn sketches included. Null clears the stored value." }, "newLayer.pointOpacity": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 100, "description": "Point opacity. How opaque a new points layer is drawn, unless it is created with a style. Null clears the stored value." }, "newLayer.lineOpacity": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 100, "description": "Line opacity. How opaque a new lines layer is drawn, unless it is created with a style. Null clears the stored value." }, "newLayer.areaOpacity": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 100, "description": "Area opacity. How opaque a new areas layer is drawn, unless it is created with a style. Null clears the stored value." }, "newLayer.lineWidth": { "type": [ "number", "null" ], "minimum": 0.5, "maximum": 50, "description": "Line width. How wide a new lines layer is drawn, unless it is created with a style. Null clears the stored value." }, "newLayer.pointRadius": { "type": [ "number", "null" ], "minimum": 0.5, "maximum": 100, "description": "Point radius. How large a new layer's points are drawn, unless it is created with a style. Null clears the stored value." }, "canvas.opens": { "type": [ "string", "null" ], "enum": [ "full", "framed", null ], "description": "Canvas opens. Whether a workflow canvas opens full screen or framed. Null clears the stored value." }, "canvas.minimap": { "type": [ "string", "null" ], "enum": [ "auto", "always", "never", null ], "description": "Canvas minimap. When a workflow canvas shows its minimap until the person chooses: auto shows it from six nodes. Null clears the stored value." }, "canvas.resultsBand": { "type": [ "string", "null" ], "enum": [ "closed", "open", null ], "description": "Canvas results band. Whether a workflow canvas opens with its results band closed or open until the person chooses. Null clears the stored value." }, "sqlConsole.textSize": { "type": [ "string", "null" ], "enum": [ "11", "12", "13", "14", "16", null ], "description": "SQL text size. The text size the SQL console's editor opens at. Null clears the stored value." }, "sqlConsole.lineWrap": { "type": [ "boolean", "null" ], "description": "SQL line wrap. Whether the SQL console's editor wraps long lines. Null clears the stored value." }, "imageExport.width": { "type": [ "string", "null" ], "enum": [ "1280", "1920", "2560", null ], "description": "Image starting width. The width a fresh image export card opens at. Null clears the stored value." }, "imageExport.shape": { "type": [ "string", "null" ], "enum": [ "16:9", "4:3", "1:1", null ], "description": "Image starting shape. The shape a fresh image export card opens at. Null clears the stored value." }, "security.sessionDays": { "type": [ "string", "null" ], "enum": [ "1", "7", "30", "90", null ], "description": "Stay signed in for. How long a session lasts after its last use. A session keeps the expiry it holds; its next use renews it by this length. Null clears the stored value." }, "security.linkDays": { "type": [ "string", "null" ], "enum": [ "1", "3", "7", "14", null ], "description": "Invite and reset links last. How long an invitation or a password reset link stays valid. A link keeps the lifetime it was issued with. Null clears the stored value." }, "security.failedPerAccount": { "type": [ "integer", "null" ], "minimum": 3, "maximum": 100, "description": "Failed sign-ins per account. Failed sign-ins for one account, within a fixed 15 minutes, before its next attempt pauses. Wrong current passwords on password and email changes pause those changes at the same count, counted apart. Never above the count per address. Null clears the stored value." }, "security.failedPerAddress": { "type": [ "integer", "null" ], "minimum": 10, "maximum": 1000, "description": "Failed sign-ins per address. Failed sign-ins from one network address, within a fixed 15 minutes, before its next attempt pauses. Never below the count per account. Null clears the stored value." }, "security.passwordMin": { "type": [ "integer", "null" ], "minimum": 8, "maximum": 64, "description": "Shortest password. The fewest characters a password set from now may have. Passwords set earlier keep signing in. Null clears the stored value." }, "tokens.create": { "type": [ "string", "null" ], "enum": [ "everyone", "admins", null ], "description": "Who may create tokens. Whether every account or only admins may create API tokens. Tokens made earlier keep working. Null clears the stored value." }, "tokens.expiry": { "type": [ "string", "null" ], "enum": [ "never", "30d", "90d", "1y", null ], "description": "New tokens expire after. The lifetime a new API token takes, from its creation. Tokens made earlier keep their own. Null clears the stored value." }, "publishing.publish": { "type": [ "string", "null" ], "enum": [ "everyone", "admins", "none", null ], "description": "Who may publish. Whether every account, only admins or no one may publish a map or change a publication. Published maps stay public and can be unpublished. Null clears the stored value." }, "publishing.embedding": { "type": [ "string", "null" ], "enum": [ "any", "listed", "off", null ], "description": "Embedding on other sites. Which other sites may show a published page in a frame: any site, only the listed sites (at least one), or none. Null clears the stored value." }, "publishing.embedSites": { "type": [ "array", "null" ], "maxItems": 50, "items": { "type": "string", "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/?#@\\\\\\s]+/?\\s*$" }, "description": "Listed sites. The sites that may show a published page in a frame while embedding is limited to listed sites; never empty while it is. Null clears the stored value. At most 50 sites, each http or https with a host and an optional port and nothing else. Each is kept as its scheme, host and port, a repeated site once; an empty list clears to the default." }, "connections.create": { "type": [ "string", "null" ], "enum": [ "everyone", "admins", null ], "description": "Who may add database connections. Whether every account or only admins may add a database connection. Connections made earlier keep working. Null clears the stored value." }, "imports.links": { "type": [ "string", "null" ], "enum": [ "everyone", "admins", null ], "description": "Who may import from links. Whether every account or only admins may import from web addresses and cloud storage. Link datasets keep refreshing. Null clears the stored value." }, "basemaps.dark": { "type": [ "boolean", "null" ], "description": "Dark. Whether Dark is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way. Null clears the stored value." }, "basemaps.light": { "type": [ "boolean", "null" ], "description": "Light. Whether Light is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way. Null clears the stored value." }, "basemaps.streets": { "type": [ "boolean", "null" ], "description": "Streets. Whether Streets is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Null clears the stored value." }, "basemaps.satellite": { "type": [ "boolean", "null" ], "description": "Satellite. Whether Satellite is offered, while imagery is set up, where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Null clears the stored value." }, "basemaps.singleMapStyles": { "type": [ "boolean", "null" ], "description": "Style addresses on single maps. Whether a map may take a style address the library does not offer. Off, such an address is refused on any map, for everyone, admins included; a map that holds one keeps it. Null clears the stored value." }, "templates.catalogue": { "type": [ "boolean", "null" ], "description": "Use the catalogue. Whether the server reads the template catalogue: its list, its pictures and its downloads. Off, it reaches the catalogue for nothing; shipped and downloaded templates still open and copy. Null clears the stored value." } } }, "InstanceSettings": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "uploadMaxMb": { "type": "object", "properties": { "key": { "const": "uploadMaxMb" }, "environment": { "const": "DEZFIL_UPLOAD_MAX_MB" }, "label": { "const": "Largest upload" }, "purpose": { "const": "Size cap for one uploaded file." }, "defaultValue": { "const": 5120 }, "unit": { "const": "MB" }, "write": { "const": { "kind": "integer", "min": 1, "max": 102400 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "5120" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "dataProcessingTimeoutS": { "type": "object", "properties": { "key": { "const": "dataProcessingTimeoutS" }, "environment": { "const": "DEZFIL_DATA_PROCESSING_TIMEOUT_S" }, "label": { "const": "Data processing time limit" }, "purpose": { "const": "Time to receive one upload, and, counted apart, time for one data processing job, such as an import." }, "defaultValue": { "const": 3600 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 60, "max": 21600 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "3600" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "remoteMaxMb": { "type": "object", "properties": { "key": { "const": "remoteMaxMb" }, "environment": { "const": "DEZFIL_REMOTE_MAX_MB" }, "label": { "const": "Largest link import" }, "purpose": { "const": "Size cap for a URL or object-store import." }, "defaultValue": { "const": 2048 }, "unit": { "const": "MB" }, "write": { "const": { "kind": "integer", "min": 1, "max": 102400 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "2048" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "remoteTimeoutS": { "type": "object", "properties": { "key": { "const": "remoteTimeoutS" }, "environment": { "const": "DEZFIL_REMOTE_TIMEOUT_S" }, "label": { "const": "Link import time limit" }, "purpose": { "const": "Time for one link import's whole download." }, "defaultValue": { "const": 300 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 10, "max": 3600 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "300" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overtureMaxKm2": { "type": "object", "properties": { "key": { "const": "overtureMaxKm2" }, "environment": { "const": "DEZFIL_OVERTURE_MAX_KM2" }, "label": { "const": "Overture area" }, "purpose": { "const": "The largest area one Overture import of places may cover; other themes may cover more or less, by how dense they are." }, "defaultValue": { "const": 25000 }, "unit": { "const": "km²" }, "write": { "const": { "kind": "integer", "min": 1, "max": 1000000 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "25000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "osmMaxKm2": { "type": "object", "properties": { "key": { "const": "osmMaxKm2" }, "environment": { "const": "DEZFIL_OSM_MAX_KM2" }, "label": { "const": "OpenStreetMap area" }, "purpose": { "const": "The largest area one OpenStreetMap import may cover." }, "defaultValue": { "const": 10000 }, "unit": { "const": "km²" }, "write": { "const": { "kind": "integer", "min": 1, "max": 1000000 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "10000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overpassTimeoutS": { "type": "object", "properties": { "key": { "const": "overpassTimeoutS" }, "environment": { "const": "DEZFIL_OVERPASS_TIMEOUT_S" }, "label": { "const": "Overpass time limit" }, "purpose": { "const": "Time budget sent with every Overpass query." }, "defaultValue": { "const": 60 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 10, "max": 900 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "60" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overpassMaxsizeMb": { "type": "object", "properties": { "key": { "const": "overpassMaxsizeMb" }, "environment": { "const": "DEZFIL_OVERPASS_MAXSIZE_MB" }, "label": { "const": "Overpass response budget" }, "purpose": { "const": "Response budget sent to Overpass; twice this aborts locally." }, "defaultValue": { "const": 512 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "512" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overpassCacheHours": { "type": "object", "properties": { "key": { "const": "overpassCacheHours" }, "environment": { "const": "DEZFIL_OVERPASS_CACHE_H" }, "label": { "const": "Overpass cache freshness" }, "purpose": { "const": "How long an Overpass response stays fresh." }, "defaultValue": { "const": 24 }, "unit": { "const": "hours" }, "write": { "const": { "kind": "integer", "min": 1, "max": 720 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "24" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overpassCacheMb": { "type": "object", "properties": { "key": { "const": "overpassCacheMb" }, "environment": { "const": "DEZFIL_OVERPASS_CACHE_MB" }, "label": { "const": "Overpass cache size" }, "purpose": { "const": "Cache size budget, evicted oldest first." }, "defaultValue": { "const": 2048 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "2048" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "queryTimeoutS": { "type": "object", "properties": { "key": { "const": "queryTimeoutS" }, "environment": { "const": "DEZFIL_QUERY_TIMEOUT_S" }, "label": { "const": "Query time limit" }, "purpose": { "const": "Time for one query, whether the SQL people run, a layer, an inspection, a preview or a published map." }, "defaultValue": { "const": 60 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 5, "max": 600 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "60" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "queryMemoryMb": { "type": "object", "properties": { "key": { "const": "queryMemoryMb" }, "environment": { "const": "DEZFIL_QUERY_MEMORY_MB" }, "label": { "const": "Engine memory" }, "purpose": { "const": "Memory the engine that runs people's SQL may use, shared by every query." }, "defaultValue": { "const": 2048 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "2048" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "trustedMemoryMb": { "type": "object", "properties": { "key": { "const": "trustedMemoryMb" }, "environment": { "const": "DEZFIL_TRUSTED_MEMORY_MB" }, "label": { "const": "Trusted engine memory" }, "purpose": { "const": "Memory the engine that imports and processes data may use; it may spill up to four times this to disk." }, "defaultValue": { "const": 3072 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "3072" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "previewRows": { "type": "object", "properties": { "key": { "const": "previewRows" }, "environment": { "const": "DEZFIL_PREVIEW_ROWS" }, "label": { "const": "Rows shown in results" }, "purpose": { "const": "Row cap for result previews." }, "defaultValue": { "const": 1000 }, "unit": { "const": "rows" }, "write": { "const": { "kind": "integer", "min": 10, "max": 100000 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "1000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "renderCapFeatures": { "type": "object", "properties": { "key": { "const": "renderCapFeatures" }, "environment": { "const": "DEZFIL_RENDER_CAP_FEATURES" }, "label": { "const": "Features drawn per layer" }, "purpose": { "const": "The most features a layer draws, and the count past which a points layer is drawn from tiles." }, "defaultValue": { "const": 250000 }, "unit": { "const": "features" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "250000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "renderCapBytes": { "type": "object", "properties": { "key": { "const": "renderCapBytes" }, "environment": { "const": "DEZFIL_RENDER_CAP_BYTES" }, "label": { "const": "Bytes drawn per layer" }, "purpose": { "const": "The largest answer one layer may draw from, in bytes of uncompressed JSON." }, "defaultValue": { "const": 134217728 }, "unit": { "const": "bytes" }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "134217728" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "sliderPreviewRows": { "type": "object", "properties": { "key": { "const": "sliderPreviewRows" }, "environment": { "const": "DEZFIL_SLIDER_PREVIEW_ROWS" }, "label": { "const": "Slider preview rows" }, "purpose": { "const": "Source points transferred for interactive slider previews." }, "defaultValue": { "const": 50000 }, "unit": { "const": "rows" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "50000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publishFreshnessS": { "type": "object", "properties": { "key": { "const": "publishFreshnessS" }, "environment": { "const": "DEZFIL_PUBLISH_FRESHNESS_S" }, "label": { "const": "Published freshness" }, "purpose": { "const": "Cache window for published views." }, "defaultValue": { "const": 30 }, "unit": { "const": "seconds" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "30" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "tileBuildTimeoutS": { "type": "object", "properties": { "key": { "const": "tileBuildTimeoutS" }, "environment": { "const": "DEZFIL_TILE_BUILD_TIMEOUT_S" }, "label": { "const": "Tile build time limit" }, "purpose": { "const": "Time budget for each background tile-build stage." }, "defaultValue": { "const": 600 }, "unit": { "const": "seconds" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "600" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "exportRenderTimeoutS": { "type": "object", "properties": { "key": { "const": "exportRenderTimeoutS" }, "environment": { "const": "DEZFIL_EXPORT_RENDER_TIMEOUT_S" }, "label": { "const": "Time limit per image" }, "purpose": { "const": "Time for one image, its wait for a turn included." }, "defaultValue": { "const": 90 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 10, "max": 300 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "90" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "exportRequestTimeoutS": { "type": "object", "properties": { "key": { "const": "exportRequestTimeoutS" }, "environment": { "const": "DEZFIL_EXPORT_REQUEST_TIMEOUT_S" }, "label": { "const": "Image request time limit" }, "purpose": { "const": "Deadline for each request made by the render page." }, "defaultValue": { "const": 20 }, "unit": { "const": "seconds" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "20" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "exportRenderConcurrency": { "type": "object", "properties": { "key": { "const": "exportRenderConcurrency" }, "environment": { "const": "DEZFIL_EXPORT_RENDER_CONCURRENCY" }, "label": { "const": "Images at once" }, "purpose": { "const": "Images the server draws at the same time." }, "defaultValue": { "const": 2 }, "unit": { "const": "renders" }, "write": { "const": { "kind": "integer", "min": 1, "max": 8 } }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "2" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "toolAttachmentMaxMb": { "type": "object", "properties": { "key": { "const": "toolAttachmentMaxMb" }, "environment": { "const": "DEZFIL_TOOL_ATTACHMENT_MAX_MB" }, "label": { "const": "Tool attachment size" }, "purpose": { "const": "The largest file a tool hands back to the assistant or an agent, such as an exported image." }, "defaultValue": { "const": 32 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "32" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantStepBudget": { "type": "object", "properties": { "key": { "const": "assistantStepBudget" }, "environment": { "const": "DEZFIL_ASSISTANT_STEP_BUDGET" }, "label": { "const": "Assistant steps" }, "purpose": { "const": "Maximum model and tool steps per request." }, "defaultValue": { "const": 20 }, "unit": { "const": "steps" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "20" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantLookTimeoutS": { "type": "object", "properties": { "key": { "const": "assistantLookTimeoutS" }, "environment": { "const": "DEZFIL_ASSISTANT_LOOK_TIMEOUT_S" }, "label": { "const": "Map check time limit" }, "purpose": { "const": "Time for one of the assistant's map checks, its wait for a turn included." }, "defaultValue": { "const": 30 }, "unit": { "const": "seconds" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "30" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantLookRetention": { "type": "object", "properties": { "key": { "const": "assistantLookRetention" }, "environment": { "const": "DEZFIL_ASSISTANT_LOOK_RETENTION" }, "label": { "const": "Retained map checks" }, "purpose": { "const": "Map check pictures kept in memory, oldest dropped first; a restart clears them." }, "defaultValue": { "const": 256 }, "unit": { "const": "images" }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "256" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantLookRetentionMb": { "type": "object", "properties": { "key": { "const": "assistantLookRetentionMb" }, "environment": { "const": "DEZFIL_ASSISTANT_LOOK_RETENTION_MB" }, "label": { "const": "Map check storage" }, "purpose": { "const": "Memory the kept map check pictures may take." }, "defaultValue": { "const": 96 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "96" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocodePaceMs": { "type": "object", "properties": { "key": { "const": "geocodePaceMs" }, "environment": { "const": "DEZFIL_GEOCODE_PACE_MS" }, "label": { "const": "Address finder pace" }, "purpose": { "const": "Minimum request gap; zero means no gap." }, "defaultValue": { "const": 1000 }, "unit": { "const": "milliseconds" }, "write": { "const": { "kind": "integer", "min": 0, "max": 60000 } }, "parsing": { "const": "non-negative" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "1000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocodeMatchCacheHours": { "type": "object", "properties": { "key": { "const": "geocodeMatchCacheHours" }, "environment": { "const": "DEZFIL_GEOCODE_MATCH_CACHE_HOURS" }, "label": { "const": "Address match freshness" }, "purpose": { "const": "How long matched addresses are cached." }, "defaultValue": { "const": 720 }, "unit": { "const": "hours" }, "write": { "const": { "kind": "integer", "min": 24, "max": 8760 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "720" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocodeNoMatchCacheHours": { "type": "object", "properties": { "key": { "const": "geocodeNoMatchCacheHours" }, "environment": { "const": "DEZFIL_GEOCODE_NO_MATCH_CACHE_HOURS" }, "label": { "const": "Unmatched address freshness" }, "purpose": { "const": "How long no-match answers are cached." }, "defaultValue": { "const": 24 }, "unit": { "const": "hours" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "24" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocodeCacheMb": { "type": "object", "properties": { "key": { "const": "geocodeCacheMb" }, "environment": { "const": "DEZFIL_GEOCODE_CACHE_MB" }, "label": { "const": "Address cache size" }, "purpose": { "const": "Size budget for cached geocoding answers." }, "defaultValue": { "const": 64 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "64" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "isochronePaceMs": { "type": "object", "properties": { "key": { "const": "isochronePaceMs" }, "environment": { "const": "DEZFIL_ISOCHRONE_PACE_MS" }, "label": { "const": "Travel-time pace" }, "purpose": { "const": "Minimum routing request gap; zero means no gap." }, "defaultValue": { "const": 1000 }, "unit": { "const": "milliseconds" }, "write": { "const": { "kind": "integer", "min": 0, "max": 60000 } }, "parsing": { "const": "non-negative" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "1000" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "isochroneRequestTimeoutS": { "type": "object", "properties": { "key": { "const": "isochroneRequestTimeoutS" }, "environment": { "const": "DEZFIL_ISOCHRONE_REQUEST_TIMEOUT_S" }, "label": { "const": "Travel-time request limit" }, "purpose": { "const": "Deadline for one routing exchange." }, "defaultValue": { "const": 20 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 1, "max": 120 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "20" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "isochroneCacheHours": { "type": "object", "properties": { "key": { "const": "isochroneCacheHours" }, "environment": { "const": "DEZFIL_ISOCHRONE_CACHE_HOURS" }, "label": { "const": "Travel-time cache freshness" }, "purpose": { "const": "How long complete routing answers are cached." }, "defaultValue": { "const": 168 }, "unit": { "const": "hours" }, "write": { "const": { "kind": "integer", "min": 24, "max": 8760 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "168" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "isochroneCacheMb": { "type": "object", "properties": { "key": { "const": "isochroneCacheMb" }, "environment": { "const": "DEZFIL_ISOCHRONE_CACHE_MB" }, "label": { "const": "Travel-time cache size" }, "purpose": { "const": "Size budget for cached routing answers." }, "defaultValue": { "const": 64 }, "unit": { "const": "MB" }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "64" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocodeRequestTimeoutS": { "type": "object", "properties": { "key": { "const": "geocodeRequestTimeoutS" }, "environment": { "const": "DEZFIL_GEOCODE_REQUEST_TIMEOUT_S" }, "label": { "const": "Address request limit" }, "purpose": { "const": "Deadline for one geocoding exchange." }, "defaultValue": { "const": 10 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 1, "max": 120 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "10" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "operationTimeoutS": { "type": "object", "properties": { "key": { "const": "operationTimeoutS" }, "environment": { "const": "DEZFIL_OPERATION_TIMEOUT_S" }, "label": { "const": "Time limit per run" }, "purpose": { "const": "Time for one tool run, not counting its wait for a turn." }, "defaultValue": { "const": 600 }, "unit": { "const": "seconds" }, "write": { "const": { "kind": "integer", "min": 30, "max": 7200 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "600" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "operationConcurrency": { "type": "object", "properties": { "key": { "const": "operationConcurrency" }, "environment": { "const": "DEZFIL_OPERATION_CONCURRENCY" }, "label": { "const": "Operation runs at once" }, "purpose": { "const": "Tool runs at the same time; they share the engine that runs people's SQL." }, "defaultValue": { "const": 1 }, "unit": { "const": "runs" }, "write": { "const": { "kind": "integer", "min": 1, "max": 8 } }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "1" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "operationQueueMax": { "type": "object", "properties": { "key": { "const": "operationQueueMax" }, "environment": { "const": "DEZFIL_OPERATION_QUEUE_MAX" }, "label": { "const": "Operation runs waiting" }, "purpose": { "const": "Tool runs that may wait for a turn." }, "defaultValue": { "const": 20 }, "unit": { "const": "runs" }, "write": { "const": { "kind": "integer", "min": 1, "max": 200 } }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "20" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "operationHistoryPerSubject": { "type": "object", "properties": { "key": { "const": "operationHistoryPerSubject" }, "environment": { "const": "DEZFIL_OPERATION_HISTORY_PER_SUBJECT" }, "label": { "const": "Run history depth" }, "purpose": { "const": "Runs kept in each run history, such as a workflow step's; its latest success is always kept." }, "defaultValue": { "const": 20 }, "unit": { "const": "runs" }, "parsing": { "const": "positive-integer" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "documentedDefault": { "const": "20" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publicRateLimit": { "type": "object", "properties": { "key": { "const": "publicRateLimit" }, "environment": { "const": "DEZFIL_PUBLIC_RATE_LIMIT" }, "label": { "const": "Requests per source" }, "purpose": { "const": "Requests one visitor may make to published maps, counted by network address across every published map." }, "defaultValue": { "const": 60 }, "unit": { "const": "per 10 seconds" }, "write": { "const": { "kind": "integer", "min": 1, "max": 10000 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "60" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publicTileRateLimit": { "type": "object", "properties": { "key": { "const": "publicTileRateLimit" }, "environment": { "const": "DEZFIL_PUBLIC_TILE_RATE_LIMIT" }, "label": { "const": "Tile requests per source" }, "purpose": { "const": "Tile requests one visitor may make to published maps, counted by network address across every published map." }, "defaultValue": { "const": 600 }, "unit": { "const": "per 10 seconds" }, "write": { "const": { "kind": "integer", "min": 1, "max": 100000 } }, "parsing": { "const": "positive" }, "kind": { "const": "number" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "documentedDefault": { "const": "600" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "label", "purpose", "defaultValue", "unit", "write", "parsing", "kind", "scope", "readBy", "changedBy", "documentedDefault", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantAutoCheck": { "type": "object", "properties": { "key": { "const": "assistantAutoCheck" }, "environment": { "const": "DEZFIL_ASSISTANT_AUTO_CHECK" }, "kind": { "const": "boolean" }, "label": { "const": "Automatic map check" }, "purpose": { "const": "Check the rendered map after an assistant turn changes it." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "dataDir": { "type": "object", "properties": { "key": { "const": "dataDir" }, "environment": { "const": "DEZFIL_DATA_DIR" }, "kind": { "const": "path" }, "label": { "const": "Data directory" }, "purpose": { "const": "The single durable directory for tables, tiles and metadata." }, "defaultValue": { "const": { "rule": "working-directory/data" } }, "documentedDefault": { "const": "./data; /data in the container" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "secretKey": { "type": "object", "properties": { "key": { "const": "secretKey" }, "environment": { "const": "DEZFIL_SECRET_KEY" }, "kind": { "const": "secret" }, "label": { "const": "Encryption key" }, "purpose": { "const": "The key that encrypts saved connection passwords and service addresses." }, "defaultValue": { "const": { "rule": "key-file-or-generate" } }, "documentedDefault": { "const": "generated" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": true }, "editable": { "const": false }, "value": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "environment", "data-directory", "not-yet-present" ] } }, "required": [ "status" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "trustedProxies": { "type": "object", "properties": { "key": { "const": "trustedProxies" }, "environment": { "const": "DEZFIL_TRUSTED_PROXIES" }, "kind": { "const": "list" }, "label": { "const": "Trusted proxies" }, "purpose": { "const": "The proxies whose forwarded visitor address, host, scheme and port Dezfil accepts." }, "defaultValue": { "const": [] }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "sessionCookie": { "type": "object", "properties": { "key": { "const": "sessionCookie" }, "environment": { "const": "DEZFIL_SESSION_COOKIE" }, "kind": { "const": "text" }, "label": { "const": "Session cookie name" }, "purpose": { "const": "Browser session cookie name, derived from the listening port unless overridden." }, "defaultValue": { "const": { "rule": "listening-port" } }, "documentedDefault": { "const": "port-based" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "egressAllowlist": { "type": "object", "properties": { "key": { "const": "egressAllowlist" }, "environment": { "const": "DEZFIL_EGRESS_ALLOWLIST" }, "kind": { "const": "list" }, "label": { "const": "Allowed destinations" }, "purpose": { "const": "Hosts on a private network that the server may reach." }, "defaultValue": { "const": [] }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "objectStoreCredentials": { "type": "object", "properties": { "key": { "const": "objectStoreCredentials" }, "environment": { "const": "DEZFIL_OBJECT_STORE_CREDENTIALS" }, "kind": { "const": "boolean" }, "label": { "const": "Object-store credentials" }, "purpose": { "const": "Read cloud storage links with the server's own credentials." }, "defaultValue": { "const": false }, "documentedDefault": { "const": "off" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "s3Endpoint": { "type": "object", "properties": { "key": { "const": "s3Endpoint" }, "environment": { "const": "DEZFIL_S3_ENDPOINT" }, "kind": { "const": "address" }, "label": { "const": "S3 endpoint" }, "purpose": { "const": "The S3-compatible store that s3:// links are read from without the server's credentials." }, "defaultValue": { "const": { "rule": "aws-bucket-endpoint" } }, "documentedDefault": { "const": "AWS" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048 } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overpassUrl": { "type": "object", "properties": { "key": { "const": "overpassUrl" }, "environment": { "const": "DEZFIL_OVERPASS_URL" }, "kind": { "const": "address" }, "label": { "const": "Overpass endpoint" }, "purpose": { "const": "Endpoint for OpenStreetMap imports." }, "defaultValue": { "const": { "set": true, "origin": "https://overpass-api.de" } }, "documentedDefault": { "const": "https://overpass-api.de/api/interpreter" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048 } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "overtureS3Endpoint": { "type": "object", "properties": { "key": { "const": "overtureS3Endpoint" }, "environment": { "const": "DEZFIL_OVERTURE_S3_ENDPOINT" }, "kind": { "const": "address" }, "label": { "const": "Overture endpoint" }, "purpose": { "const": "S3-compatible override for the public Overture bucket." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset, the public bucket" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "tippecanoe": { "type": "object", "properties": { "key": { "const": "tippecanoe" }, "environment": { "const": "DEZFIL_TIPPECANOE" }, "kind": { "const": "path" }, "label": { "const": "Tile builder" }, "purpose": { "const": "The program that builds vector tiles." }, "defaultValue": { "const": "tippecanoe" }, "documentedDefault": { "const": "tippecanoe" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemapUrl": { "type": "object", "properties": { "key": { "const": "basemapUrl" }, "environment": { "const": "DEZFIL_BASEMAP_URL" }, "kind": { "const": "address" }, "label": { "const": "Basemap address" }, "purpose": { "const": "A basemap style that Auto draws in both themes, in place of the built-in ones." }, "defaultValue": { "const": { "rule": "built-in-basemap-for-theme" } }, "documentedDefault": { "const": "built-in styles" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemapAttribution": { "type": "object", "properties": { "key": { "const": "basemapAttribution" }, "environment": { "const": "DEZFIL_BASEMAP_ATTRIBUTION" }, "kind": { "const": "text" }, "label": { "const": "Basemap credit" }, "purpose": { "const": "The credit maps show for the style DEZFIL_BASEMAP_URL names." }, "defaultValue": { "const": null }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "satelliteUrl": { "type": "object", "properties": { "key": { "const": "satelliteUrl" }, "environment": { "const": "DEZFIL_SATELLITE_URL" }, "kind": { "const": "address" }, "label": { "const": "Satellite template" }, "purpose": { "const": "Raster tile template enabling satellite imagery." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048, "placeholders": [ "{z}", "{x}", "{y}" ], "userInformation": "refused" } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." }, "userInformation": { "const": true, "description": "The template in effect carries a user name or password, never given here. The imagery is not drawn from such an address." } }, "required": [ "set", "origin", "userInformation" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "satelliteAttribution": { "type": "object", "properties": { "key": { "const": "satelliteAttribution" }, "environment": { "const": "DEZFIL_SATELLITE_ATTRIBUTION" }, "kind": { "const": "text" }, "label": { "const": "Satellite credit" }, "purpose": { "const": "Credit line required by the imagery provider." }, "defaultValue": { "const": null }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "text", "maxLength": 160, "empty": "null" } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "geocoderUrl": { "type": "object", "properties": { "key": { "const": "geocoderUrl" }, "environment": { "const": "DEZFIL_GEOCODER_URL" }, "kind": { "const": "address" }, "label": { "const": "Address finder" }, "purpose": { "const": "Nominatim-compatible endpoint for search and batch geocoding." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048 } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "isochroneUrl": { "type": "object", "properties": { "key": { "const": "isochroneUrl" }, "environment": { "const": "DEZFIL_ISOCHRONE_URL" }, "kind": { "const": "address" }, "label": { "const": "Travel-time endpoint" }, "purpose": { "const": "Valhalla-compatible endpoint for travel-time areas." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048 } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "templatesCatalogueUrl": { "type": "object", "properties": { "key": { "const": "templatesCatalogueUrl" }, "environment": { "const": "DEZFIL_TEMPLATES_CATALOGUE" }, "kind": { "const": "address" }, "label": { "const": "Catalogue address" }, "purpose": { "const": "Where the template catalogue's index is read." }, "defaultValue": { "const": { "set": true, "origin": "https://github.com" } }, "documentedDefault": { "const": "https://github.com/Dezfil/templates/releases/latest/download/index.json" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "address", "maxLength": 2048, "folder": "variable" } }, "value": { "oneOf": [ { "type": "object", "properties": { "set": { "const": false } }, "required": [ "set" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "origin": { "type": "string", "description": "Scheme and host only, including the port when set. No user information, path, query or fragment." } }, "required": [ "set", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "unreadable": { "const": true } }, "required": [ "set", "unreadable" ], "additionalProperties": false }, { "type": "object", "properties": { "set": { "const": true }, "folder": { "const": true, "description": "The variable names a folder on this server, read as files under the same checks; its path is never given." } }, "required": [ "set", "folder" ], "additionalProperties": false }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "anthropicApiKey": { "type": "object", "properties": { "key": { "const": "anthropicApiKey" }, "environment": { "const": "ANTHROPIC_API_KEY" }, "kind": { "const": "secret" }, "label": { "const": "Anthropic credential" }, "purpose": { "const": "Enables the assistant with this provider." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": true }, "editable": { "const": false }, "value": { "type": "object", "properties": { "set": { "type": "boolean" } }, "required": [ "set" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "openaiApiKey": { "type": "object", "properties": { "key": { "const": "openaiApiKey" }, "environment": { "const": "OPENAI_API_KEY" }, "kind": { "const": "secret" }, "label": { "const": "OpenAI credential" }, "purpose": { "const": "Enables the assistant with this provider." }, "defaultValue": { "const": { "set": false } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": true }, "editable": { "const": false }, "value": { "type": "object", "properties": { "set": { "type": "boolean" } }, "required": [ "set" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "aiProvider": { "type": "object", "properties": { "key": { "const": "aiProvider" }, "environment": { "const": "DEZFIL_AI_PROVIDER" }, "kind": { "const": "choice" }, "label": { "const": "Assistant provider" }, "purpose": { "const": "Selects the provider when more than one credential is present." }, "defaultValue": { "const": { "rule": "first-provider-with-key" } }, "documentedDefault": { "const": "first key set" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "aiModel": { "type": "object", "properties": { "key": { "const": "aiModel" }, "environment": { "const": "DEZFIL_AI_MODEL" }, "kind": { "const": "text" }, "label": { "const": "Assistant model" }, "purpose": { "const": "Overrides the provider's default model." }, "defaultValue": { "const": { "rule": "provider-default-model" } }, "documentedDefault": { "const": "provider default" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "aiModelsAnthropic": { "type": "object", "properties": { "key": { "const": "aiModelsAnthropic" }, "environment": { "const": "DEZFIL_AI_MODELS_ANTHROPIC" }, "kind": { "const": "list" }, "label": { "const": "Anthropic model offer" }, "purpose": { "const": "Narrows and orders the catalogue; a set empty list offers only the default." }, "defaultValue": { "const": { "rule": "effective-provider-catalogue" } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "aiModelsOpenai": { "type": "object", "properties": { "key": { "const": "aiModelsOpenai" }, "environment": { "const": "DEZFIL_AI_MODELS_OPENAI" }, "kind": { "const": "list" }, "label": { "const": "OpenAI model offer" }, "purpose": { "const": "Narrows and orders the catalogue; a set empty list offers only the default." }, "defaultValue": { "const": { "rule": "effective-provider-catalogue" } }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "assistantOffer": { "type": "object", "properties": { "key": { "const": "assistantOffer" }, "environment": { "const": "DEZFIL_ASSISTANT_OFFER" }, "kind": { "const": "choice" }, "label": { "const": "Assistant operation offer" }, "purpose": { "const": "With subset, the assistant starts with the page's own tools and looks up the rest; with full, it starts with every tool the page allows." }, "defaultValue": { "const": "subset" }, "documentedDefault": { "const": "subset" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "chromiumPath": { "type": "object", "properties": { "key": { "const": "chromiumPath" }, "environment": { "const": "DEZFIL_CHROMIUM_PATH" }, "kind": { "const": "path" }, "label": { "const": "Image renderer" }, "purpose": { "const": "The headless browser that draws image exports and map pictures." }, "defaultValue": { "const": "/usr/bin/chromium" }, "documentedDefault": { "const": "/usr/bin/chromium" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "deployment" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "instanceName": { "type": "object", "properties": { "key": { "const": "instanceName" }, "label": { "const": "Instance name" }, "purpose": { "const": "Name beside the wordmark and in browser titles." }, "defaultValue": { "const": null }, "documentedDefault": { "const": "unset" }, "scope": { "const": "instance" }, "readBy": { "const": "public" }, "changedBy": { "const": "admin" }, "kind": { "const": "text" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "text", "maxLength": 80, "empty": "null" } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "signInMessage": { "type": "object", "properties": { "key": { "const": "signInMessage" }, "label": { "const": "Sign-in message" }, "purpose": { "const": "Optional message on the sign-in page." }, "defaultValue": { "const": "" }, "documentedDefault": { "const": "empty" }, "scope": { "const": "instance" }, "readBy": { "const": "public" }, "changedBy": { "const": "admin" }, "kind": { "const": "text" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "text", "maxLength": 280, "empty": "null" } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "lostPasswordContact": { "type": "object", "properties": { "key": { "const": "lostPasswordContact" }, "label": { "const": "Lost-password contact" }, "purpose": { "const": "Contact line for password recovery; empty uses the built-in line." }, "defaultValue": { "const": "" }, "documentedDefault": { "const": "empty" }, "scope": { "const": "instance" }, "readBy": { "const": "public" }, "changedBy": { "const": "admin" }, "kind": { "const": "text" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "text", "maxLength": 120, "empty": "null" } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "landingPage": { "type": "object", "properties": { "key": { "const": "landingPage" }, "label": { "const": "Landing page" }, "purpose": { "const": "Preferred entry destination after sign-in." }, "defaultValue": { "const": "home" }, "documentedDefault": { "const": "home" }, "scope": { "const": "instance" }, "readBy": { "const": "public" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "home", "projects", "maps", "workflows", "data", "sql" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newMap.basemap": { "type": "object", "properties": { "key": { "const": "newMap.basemap" }, "label": { "const": "Basemap" }, "purpose": { "const": "The basemap a new map starts on. Auto follows the theme; a basemap the instance no longer offers starts on Auto." }, "defaultValue": { "const": "auto" }, "documentedDefault": { "const": "auto" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "auto", "dark", "light", "streets", "satellite" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newMap.latitude": { "type": "object", "properties": { "key": { "const": "newMap.latitude" }, "label": { "const": "Starting latitude" }, "purpose": { "const": "The latitude a new map opens at." }, "defaultValue": { "const": 40 }, "documentedDefault": { "const": "40" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "decimal", "min": -85, "max": 85 } }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newMap.longitude": { "type": "object", "properties": { "key": { "const": "newMap.longitude" }, "label": { "const": "Starting longitude" }, "purpose": { "const": "The longitude a new map opens at." }, "defaultValue": { "const": 0 }, "documentedDefault": { "const": "0" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "decimal", "min": -180, "max": 180 } }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newMap.zoom": { "type": "object", "properties": { "key": { "const": "newMap.zoom" }, "label": { "const": "Starting zoom" }, "purpose": { "const": "The zoom a new map opens at." }, "defaultValue": { "const": 1.3 }, "documentedDefault": { "const": "1.3" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "decimal", "min": 0, "max": 22 } }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newMap.legendCorner": { "type": "object", "properties": { "key": { "const": "newMap.legendCorner" }, "label": { "const": "Legend corner" }, "purpose": { "const": "Where a new map's legend sits." }, "defaultValue": { "const": "bottom-left" }, "documentedDefault": { "const": "bottom-left" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "top-left", "top-right", "bottom-left", "bottom-right" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.colorCycle": { "type": "object", "properties": { "key": { "const": "newLayer.colorCycle" }, "label": { "const": "Color cycle" }, "purpose": { "const": "The palette whose colors new layers take in turn, drawn sketches included." }, "defaultValue": { "const": "uber_viz_qualitative" }, "documentedDefault": { "const": "uber_viz_qualitative" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "uber_viz_qualitative", "bold", "tab10", "paired", "dark2", "set3" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.pointOpacity": { "type": "object", "properties": { "key": { "const": "newLayer.pointOpacity" }, "label": { "const": "Point opacity" }, "purpose": { "const": "How opaque a new points layer is drawn, unless it is created with a style." }, "defaultValue": { "const": 72 }, "documentedDefault": { "const": "72" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 10, "max": 100 } }, "unit": { "const": "%" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.lineOpacity": { "type": "object", "properties": { "key": { "const": "newLayer.lineOpacity" }, "label": { "const": "Line opacity" }, "purpose": { "const": "How opaque a new lines layer is drawn, unless it is created with a style." }, "defaultValue": { "const": 95 }, "documentedDefault": { "const": "95" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 10, "max": 100 } }, "unit": { "const": "%" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.areaOpacity": { "type": "object", "properties": { "key": { "const": "newLayer.areaOpacity" }, "label": { "const": "Area opacity" }, "purpose": { "const": "How opaque a new areas layer is drawn, unless it is created with a style." }, "defaultValue": { "const": 50 }, "documentedDefault": { "const": "50" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 10, "max": 100 } }, "unit": { "const": "%" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.lineWidth": { "type": "object", "properties": { "key": { "const": "newLayer.lineWidth" }, "label": { "const": "Line width" }, "purpose": { "const": "How wide a new lines layer is drawn, unless it is created with a style." }, "defaultValue": { "const": 2 }, "documentedDefault": { "const": "2" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "decimal", "min": 0.5, "max": 50 } }, "unit": { "const": "px" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "newLayer.pointRadius": { "type": "object", "properties": { "key": { "const": "newLayer.pointRadius" }, "label": { "const": "Point radius" }, "purpose": { "const": "How large a new layer's points are drawn, unless it is created with a style." }, "defaultValue": { "const": 3 }, "documentedDefault": { "const": "3" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "decimal", "min": 0.5, "max": 100 } }, "unit": { "const": "px" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "canvas.opens": { "type": "object", "properties": { "key": { "const": "canvas.opens" }, "label": { "const": "Canvas opens" }, "purpose": { "const": "Whether a workflow canvas opens full screen or framed." }, "defaultValue": { "const": "full" }, "documentedDefault": { "const": "full" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "full", "framed" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "canvas.minimap": { "type": "object", "properties": { "key": { "const": "canvas.minimap" }, "label": { "const": "Canvas minimap" }, "purpose": { "const": "When a workflow canvas shows its minimap until the person chooses: auto shows it from six nodes." }, "defaultValue": { "const": "auto" }, "documentedDefault": { "const": "auto" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "auto", "always", "never" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "canvas.resultsBand": { "type": "object", "properties": { "key": { "const": "canvas.resultsBand" }, "label": { "const": "Canvas results band" }, "purpose": { "const": "Whether a workflow canvas opens with its results band closed or open until the person chooses." }, "defaultValue": { "const": "closed" }, "documentedDefault": { "const": "closed" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "closed", "open" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "sqlConsole.textSize": { "type": "object", "properties": { "key": { "const": "sqlConsole.textSize" }, "label": { "const": "SQL text size" }, "purpose": { "const": "The text size the SQL console's editor opens at." }, "defaultValue": { "const": "12" }, "documentedDefault": { "const": "12" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "11", "12", "13", "14", "16" ] } }, "unit": { "const": "px" }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "sqlConsole.lineWrap": { "type": "object", "properties": { "key": { "const": "sqlConsole.lineWrap" }, "label": { "const": "SQL line wrap" }, "purpose": { "const": "Whether the SQL console's editor wraps long lines." }, "defaultValue": { "const": false }, "documentedDefault": { "const": "off" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "imageExport.width": { "type": "object", "properties": { "key": { "const": "imageExport.width" }, "label": { "const": "Image starting width" }, "purpose": { "const": "The width a fresh image export card opens at." }, "defaultValue": { "const": "1920" }, "documentedDefault": { "const": "1920" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "1280", "1920", "2560" ] } }, "unit": { "const": "px" }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "imageExport.shape": { "type": "object", "properties": { "key": { "const": "imageExport.shape" }, "label": { "const": "Image starting shape" }, "purpose": { "const": "The shape a fresh image export card opens at." }, "defaultValue": { "const": "4:3" }, "documentedDefault": { "const": "4:3" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "16:9", "4:3", "1:1" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "security.sessionDays": { "type": "object", "properties": { "key": { "const": "security.sessionDays" }, "label": { "const": "Stay signed in for" }, "purpose": { "const": "How long a session lasts after its last use. A session keeps the expiry it holds; its next use renews it by this length." }, "defaultValue": { "const": "30" }, "documentedDefault": { "const": "30" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "1", "7", "30", "90" ] } }, "unit": { "const": "days" }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "security.linkDays": { "type": "object", "properties": { "key": { "const": "security.linkDays" }, "label": { "const": "Invite and reset links last" }, "purpose": { "const": "How long an invitation or a password reset link stays valid. A link keeps the lifetime it was issued with." }, "defaultValue": { "const": "7" }, "documentedDefault": { "const": "7" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "1", "3", "7", "14" ] } }, "unit": { "const": "days" }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "security.failedPerAccount": { "type": "object", "properties": { "key": { "const": "security.failedPerAccount" }, "label": { "const": "Failed sign-ins per account" }, "purpose": { "const": "Failed sign-ins for one account, within a fixed 15 minutes, before its next attempt pauses. Wrong current passwords on password and email changes pause those changes at the same count, counted apart. Never above the count per address." }, "defaultValue": { "const": 5 }, "documentedDefault": { "const": "5" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 3, "max": 100 } }, "unit": { "const": "per 15 minutes" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "security.failedPerAddress": { "type": "object", "properties": { "key": { "const": "security.failedPerAddress" }, "label": { "const": "Failed sign-ins per address" }, "purpose": { "const": "Failed sign-ins from one network address, within a fixed 15 minutes, before its next attempt pauses. Never below the count per account." }, "defaultValue": { "const": 20 }, "documentedDefault": { "const": "20" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 10, "max": 1000 } }, "unit": { "const": "per 15 minutes" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "security.passwordMin": { "type": "object", "properties": { "key": { "const": "security.passwordMin" }, "label": { "const": "Shortest password" }, "purpose": { "const": "The fewest characters a password set from now may have. Passwords set earlier keep signing in." }, "defaultValue": { "const": 8 }, "documentedDefault": { "const": "8" }, "scope": { "const": "instance" }, "readBy": { "const": "public" }, "changedBy": { "const": "admin" }, "kind": { "const": "number" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "integer", "min": 8, "max": 64 } }, "unit": { "const": "characters" }, "value": { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "unit", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "tokens.create": { "type": "object", "properties": { "key": { "const": "tokens.create" }, "label": { "const": "Who may create tokens" }, "purpose": { "const": "Whether every account or only admins may create API tokens. Tokens made earlier keep working." }, "defaultValue": { "const": "everyone" }, "documentedDefault": { "const": "everyone" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "everyone", "admins" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "tokens.expiry": { "type": "object", "properties": { "key": { "const": "tokens.expiry" }, "label": { "const": "New tokens expire after" }, "purpose": { "const": "The lifetime a new API token takes, from its creation. Tokens made earlier keep their own." }, "defaultValue": { "const": "never" }, "documentedDefault": { "const": "never" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "never", "30d", "90d", "1y" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publishing.publish": { "type": "object", "properties": { "key": { "const": "publishing.publish" }, "label": { "const": "Who may publish" }, "purpose": { "const": "Whether every account, only admins or no one may publish a map or change a publication. Published maps stay public and can be unpublished." }, "defaultValue": { "const": "everyone" }, "documentedDefault": { "const": "everyone" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "everyone", "admins", "none" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publishing.embedding": { "type": "object", "properties": { "key": { "const": "publishing.embedding" }, "label": { "const": "Embedding on other sites" }, "purpose": { "const": "Which other sites may show a published page in a frame: any site, only the listed sites (at least one), or none." }, "defaultValue": { "const": "any" }, "documentedDefault": { "const": "any" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "any", "listed", "off" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "publishing.embedSites": { "type": "object", "properties": { "key": { "const": "publishing.embedSites" }, "label": { "const": "Listed sites" }, "purpose": { "const": "The sites that may show a published page in a frame while embedding is limited to listed sites; never empty while it is." }, "defaultValue": { "const": [] }, "documentedDefault": { "const": "none" }, "scope": { "const": "instance" }, "readBy": { "const": "admin" }, "changedBy": { "const": "admin" }, "kind": { "const": "list" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "sites", "maxSites": 50 } }, "value": { "anyOf": [ { "type": "array", "maxItems": 50, "items": { "type": "string", "pattern": "^https?://[a-z0-9.-]+(?::[0-9]{1,5})?$" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "array", "maxItems": 50, "items": { "type": "string", "pattern": "^https?://[a-z0-9.-]+(?::[0-9]{1,5})?$" } }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "connections.create": { "type": "object", "properties": { "key": { "const": "connections.create" }, "label": { "const": "Who may add database connections" }, "purpose": { "const": "Whether every account or only admins may add a database connection. Connections made earlier keep working." }, "defaultValue": { "const": "everyone" }, "documentedDefault": { "const": "everyone" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "everyone", "admins" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "imports.links": { "type": "object", "properties": { "key": { "const": "imports.links" }, "label": { "const": "Who may import from links" }, "purpose": { "const": "Whether every account or only admins may import from web addresses and cloud storage. Link datasets keep refreshing." }, "defaultValue": { "const": "everyone" }, "documentedDefault": { "const": "everyone" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "choice" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "choice", "values": [ "everyone", "admins" ] } }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemaps.dark": { "type": "object", "properties": { "key": { "const": "basemaps.dark" }, "label": { "const": "Dark" }, "purpose": { "const": "Whether Dark is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemaps.light": { "type": "object", "properties": { "key": { "const": "basemaps.light" }, "label": { "const": "Light" }, "purpose": { "const": "Whether Light is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it. Auto keeps following the theme with it either way." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemaps.streets": { "type": "object", "properties": { "key": { "const": "basemaps.streets" }, "label": { "const": "Streets" }, "purpose": { "const": "Whether Streets is offered where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemaps.satellite": { "type": "object", "properties": { "key": { "const": "basemaps.satellite" }, "label": { "const": "Satellite" }, "purpose": { "const": "Whether Satellite is offered, while imagery is set up, where a basemap is chosen: the builder's picker, a published page's switcher and the Maps tab. Off, choosing it anew is refused; a map already on it keeps it." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "basemaps.singleMapStyles": { "type": "object", "properties": { "key": { "const": "basemaps.singleMapStyles" }, "label": { "const": "Style addresses on single maps" }, "purpose": { "const": "Whether a map may take a style address the library does not offer. Off, such an address is refused on any map, for everyone, admins included; a map that holds one keeps it." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "templates.catalogue": { "type": "object", "properties": { "key": { "const": "templates.catalogue" }, "label": { "const": "Use the catalogue" }, "purpose": { "const": "Whether the server reads the template catalogue: its list, its pictures and its downloads. Off, it reaches the catalogue for nothing; shipped and downloaded templates still open and copy." }, "defaultValue": { "const": true }, "documentedDefault": { "const": "on" }, "scope": { "const": "instance" }, "readBy": { "const": "signed-in" }, "changedBy": { "const": "admin" }, "kind": { "const": "boolean" }, "timing": { "const": "live" }, "secret": { "const": false }, "editable": { "const": true }, "write": { "const": { "kind": "switch" } }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, { "type": "null" } ] } }, "required": [ "key", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "kind", "timing", "secret", "editable", "write", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "port": { "type": "object", "properties": { "key": { "const": "port" }, "environment": { "const": "PORT" }, "kind": { "const": "text" }, "label": { "const": "Listening port" }, "purpose": { "const": "Port used by the server and its internal API calls." }, "defaultValue": { "const": { "rule": "runtime-port-or-request-origin" } }, "documentedDefault": { "const": "3000 in the container" }, "scope": { "const": "platform" }, "readBy": { "const": "admin" }, "changedBy": { "const": "platform" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false }, "extensionDir": { "type": "object", "properties": { "key": { "const": "extensionDir" }, "environment": { "const": "DUCKDB_EXTENSION_DIR" }, "kind": { "const": "path" }, "label": { "const": "Engine extensions" }, "purpose": { "const": "Location of the baked offline extension bundle." }, "defaultValue": { "const": { "rule": "engine-default-extension-directory" } }, "documentedDefault": { "const": "/app/duckdb-extensions in the container" }, "scope": { "const": "platform" }, "readBy": { "const": "admin" }, "changedBy": { "const": "platform" }, "environmentTiming": { "const": "restart" }, "timing": { "const": "next-start" }, "secret": { "const": false }, "editable": { "const": false }, "value": { "anyOf": [ { "type": [ "string", "null" ] }, { "type": "object", "properties": { "rule": { "type": "string" } }, "required": [ "rule" ], "additionalProperties": false } ] }, "source": { "type": "string", "enum": [ "environment", "stored", "default" ] }, "locked": { "type": "boolean" }, "invalidOverride": { "type": "boolean" }, "storedValue": { "type": "null" } }, "required": [ "key", "environment", "kind", "label", "purpose", "defaultValue", "documentedDefault", "scope", "readBy", "changedBy", "environmentTiming", "timing", "secret", "editable", "value", "source", "locked", "invalidOverride", "storedValue" ], "additionalProperties": false } }, "required": [ "uploadMaxMb", "dataProcessingTimeoutS", "remoteMaxMb", "remoteTimeoutS", "overtureMaxKm2", "osmMaxKm2", "overpassTimeoutS", "overpassMaxsizeMb", "overpassCacheHours", "overpassCacheMb", "queryTimeoutS", "queryMemoryMb", "trustedMemoryMb", "previewRows", "renderCapFeatures", "renderCapBytes", "sliderPreviewRows", "publishFreshnessS", "tileBuildTimeoutS", "exportRenderTimeoutS", "exportRequestTimeoutS", "exportRenderConcurrency", "toolAttachmentMaxMb", "assistantStepBudget", "assistantLookTimeoutS", "assistantLookRetention", "assistantLookRetentionMb", "geocodePaceMs", "geocodeMatchCacheHours", "geocodeNoMatchCacheHours", "geocodeCacheMb", "isochronePaceMs", "isochroneRequestTimeoutS", "isochroneCacheHours", "isochroneCacheMb", "geocodeRequestTimeoutS", "operationTimeoutS", "operationConcurrency", "operationQueueMax", "operationHistoryPerSubject", "publicRateLimit", "publicTileRateLimit", "assistantAutoCheck", "dataDir", "secretKey", "trustedProxies", "sessionCookie", "egressAllowlist", "objectStoreCredentials", "s3Endpoint", "overpassUrl", "overtureS3Endpoint", "tippecanoe", "basemapUrl", "basemapAttribution", "satelliteUrl", "satelliteAttribution", "geocoderUrl", "isochroneUrl", "templatesCatalogueUrl", "anthropicApiKey", "openaiApiKey", "aiProvider", "aiModel", "aiModelsAnthropic", "aiModelsOpenai", "assistantOffer", "chromiumPath", "instanceName", "signInMessage", "lostPasswordContact", "landingPage", "newMap.basemap", "newMap.latitude", "newMap.longitude", "newMap.zoom", "newMap.legendCorner", "newLayer.colorCycle", "newLayer.pointOpacity", "newLayer.lineOpacity", "newLayer.areaOpacity", "newLayer.lineWidth", "newLayer.pointRadius", "canvas.opens", "canvas.minimap", "canvas.resultsBand", "sqlConsole.textSize", "sqlConsole.lineWrap", "imageExport.width", "imageExport.shape", "security.sessionDays", "security.linkDays", "security.failedPerAccount", "security.failedPerAddress", "security.passwordMin", "tokens.create", "tokens.expiry", "publishing.publish", "publishing.embedding", "publishing.embedSites", "connections.create", "imports.links", "basemaps.dark", "basemaps.light", "basemaps.streets", "basemaps.satellite", "basemaps.singleMapStyles", "templates.catalogue", "port", "extensionDir" ], "additionalProperties": false }, "capacities": { "type": "object", "properties": { "geocodeRows": { "type": "integer", "minimum": 1 }, "isochroneOrigins": { "type": "integer", "minimum": 0 } }, "required": [ "geocodeRows", "isochroneOrigins" ], "additionalProperties": false }, "maxImageDimension": { "type": "integer", "const": 4096 }, "version": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Effective timeout relationship mismatches, including deployment overrides. These do not block unrelated edits." }, "parts": { "type": "object", "properties": { "query_engine": { "type": "object", "properties": { "version": { "type": [ "string", "null" ], "description": "The engine library's version number." }, "started": { "type": "boolean", "description": "Whether the engine that runs people's SQL has started; the read never starts it." }, "extensions": { "type": "array", "items": { "type": "string", "enum": [ "spatial", "h3", "json" ] }, "description": "The extensions the started engine loaded, in load order; empty before it starts." } }, "required": [ "version", "started", "extensions" ], "additionalProperties": false }, "tile_builder": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Whether an executable file is where the tile builder's setting points (a bare name looked up on the search path), by a file check alone." }, "version": { "type": [ "string", "null" ], "description": "The tile builder's version number once this server has run it, else null." } }, "required": [ "found", "version" ], "additionalProperties": false }, "image_renderer": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Whether an executable file is where the image renderer's browser setting points (a bare name looked up on the search path), by a file check alone." }, "available": { "type": "boolean", "description": "Whether the picture service can use the renderer: an executable is found and no launch refusal is awaiting the next startup or hourly look. This read launches nothing and does not clear a refusal." }, "imagesAtOnce": { "type": "integer", "minimum": 1, "description": "Images at once in effect." } }, "required": [ "found", "available", "imagesAtOnce" ], "additionalProperties": false }, "metadata_database": { "type": "object", "properties": { "file": { "type": "string", "description": "The metadata database's file name, without its folder." } }, "required": [ "file" ], "additionalProperties": false } }, "required": [ "query_engine", "tile_builder", "image_renderer", "metadata_database" ], "additionalProperties": false, "description": "Each part of this server as System's Status shows it, read without creating an engine, launching a browser or running any program." }, "basemapStyles": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/LibraryStyle" }, "description": "The basemap library, oldest first, hidden styles included." }, "services": { "type": "object", "properties": { "geocode": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "Bytes the cached answers take in the data folder." }, "answers": { "type": "integer", "minimum": 0, "description": "How many answers the cache holds." }, "budgetMb": { "type": "number", "minimum": 0, "description": "The cache's size budget in MB, as its variable gives it; the oldest answers go first past it." } }, "required": [ "bytes", "answers", "budgetMb" ], "additionalProperties": false, "description": "The address finder's cached answers." }, "isochrone": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "Bytes the cached answers take in the data folder." }, "answers": { "type": "integer", "minimum": 0, "description": "How many answers the cache holds." }, "budgetMb": { "type": "number", "minimum": 0, "description": "The cache's size budget in MB, as its variable gives it; the oldest answers go first past it." } }, "required": [ "bytes", "answers", "budgetMb" ], "additionalProperties": false, "description": "Travel time's cached answers." }, "overpass": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "Bytes the cached answers take in the data folder." }, "answers": { "type": "integer", "minimum": 0, "description": "How many answers the cache holds." }, "budgetMb": { "type": "number", "minimum": 0, "description": "The cache's size budget in MB, as its variable gives it; the oldest answers go first past it." } }, "required": [ "bytes", "answers", "budgetMb" ], "additionalProperties": false, "description": "OpenStreetMap's cached answers." }, "overture": { "description": "The Overture release list this process keeps: how many releases, the newest and when it was listed, or listed false before any listing succeeded. The pinned releases offered through an outage are never kept.", "oneOf": [ { "type": "object", "properties": { "listed": { "const": false } }, "required": [ "listed" ], "additionalProperties": false }, { "type": "object", "properties": { "listed": { "const": true }, "releases": { "type": "integer", "minimum": 1 }, "newest": { "type": "string" }, "listedAt": { "type": "string", "format": "date-time" } }, "required": [ "listed", "releases", "newest", "listedAt" ], "additionalProperties": false } ] } }, "required": [ "geocode", "isochrone", "overpass", "overture" ], "additionalProperties": false, "description": "What the services keep on this instance, read from the data folder and this process without asking any service." } }, "required": [ "settings", "capacities", "maxImageDimension", "version", "startedAt", "warnings", "parts", "basemapStyles", "services" ], "additionalProperties": false }, "ClearedServiceCaches": { "type": "object", "properties": { "cleared": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "geocode", "isochrone", "overpass" ] }, "description": "The caches emptied." } }, "required": [ "cleared" ], "additionalProperties": false }, "ServiceTestAnswer": { "description": "A service's Test: passed, with the milliseconds the service took to answer (Overture: how many releases its listing names and the newest; templates: how many templates the catalogue's index lists, with the milliseconds), or failed with one reason: not_set_up (no address), refused (the egress rules refused it, or the satellite tile template carries a user name or password; message is the refusal's sentence), unreachable (nothing answered), timed_out (no answer within the service's time limit), status (an answer with that status) or unexpected_answer (an answer, but not as the service gives one). Never the service's body, its address or a key.", "oneOf": [ { "type": "object", "properties": { "service": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "s3", "satellite" ] }, "result": { "const": "passed" }, "milliseconds": { "type": "integer", "minimum": 0, "description": "How long the service took to answer, once the request was sent." } }, "required": [ "service", "result", "milliseconds" ], "additionalProperties": false }, { "type": "object", "properties": { "service": { "const": "templates" }, "result": { "const": "passed" }, "templates": { "type": "integer", "minimum": 0, "description": "How many templates the catalogue's index lists that this server reads." }, "milliseconds": { "type": "integer", "minimum": 0, "description": "How long the catalogue took to answer with its index, once the request was sent." } }, "required": [ "service", "result", "templates", "milliseconds" ], "additionalProperties": false }, { "type": "object", "properties": { "service": { "const": "overture" }, "result": { "const": "passed" }, "releases": { "type": "integer", "minimum": 1, "description": "How many releases the listing names; kept as the list the Overture pane offers." }, "newest": { "type": "string", "description": "The newest release." } }, "required": [ "service", "result", "releases", "newest" ], "additionalProperties": false }, { "type": "object", "properties": { "service": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "overture", "s3", "satellite", "templates" ], "description": "The service tested." }, "result": { "const": "failed" }, "reason": { "const": "refused" }, "message": { "type": "string", "description": "The refusal's sentence: the egress check's, or the one a save refuses a satellite tile template carrying a user name or password with." } }, "required": [ "service", "result", "reason", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "service": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "overture", "s3", "satellite", "templates" ], "description": "The service tested." }, "result": { "const": "failed" }, "reason": { "const": "status" }, "status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "The status the service answered with." } }, "required": [ "service", "result", "reason", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "service": { "type": "string", "enum": [ "geocode", "isochrone", "overpass", "overture", "s3", "satellite", "templates" ], "description": "The service tested." }, "result": { "const": "failed" }, "reason": { "type": "string", "enum": [ "not_set_up", "unreachable", "timed_out", "unexpected_answer" ] } }, "required": [ "service", "result", "reason" ], "additionalProperties": false } ] }, "StorageRead": { "type": "object", "properties": { "kinds": { "type": "object", "properties": { "tables": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Dataset files the metadata registers." }, "tile_archives": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Tile archives with a tile record, and what they were built from." }, "service_caches": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "The three service caches' answers." }, "thumbnails": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Map card images and their evidence." }, "profile_pictures": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Each person's current picture." }, "templates": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Downloaded templates, and the copies of an installed template's data the query engine reads, a file with two names counted once." }, "metadata_database": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "The metadata database and its journal files." }, "leftover_files": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "What the next restart's sweeps would remove: upload, download and tile scratch, staged project exports with their ownership records, table files no dataset or installed template uses, archives no layer uses and their evidence, unfinished thumbnail writes, pictures that are no one's current picture with their ownership records. It includes work in progress." }, "other": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "Everything else in the data folder, such as the key file and the server's records." } }, "required": [ "tables", "tile_archives", "service_caches", "thumbnails", "profile_pictures", "templates", "metadata_database", "leftover_files", "other" ], "additionalProperties": false }, "total": { "type": "object", "properties": { "bytes": { "type": "integer", "minimum": 0, "description": "The bytes the files take." }, "files": { "type": "integer", "minimum": 0, "description": "How many files." }, "finished": { "type": "boolean", "description": "False when the walk stopped at its limit before it had seen every such file: the bytes and files are then at least these." } }, "required": [ "bytes", "files", "finished" ], "additionalProperties": false, "description": "What the data folder holds: every kind together." }, "disk": { "description": "Free and total bytes on the data folder's volume, or null when the system would not say within the read's 10 seconds.", "oneOf": [ { "type": "object", "properties": { "free": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "free", "total" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kinds", "total", "disk" ], "additionalProperties": false, "description": "What the data folder holds, by kind (tables, tile_archives, service_caches, thumbnails, profile_pictures, templates, metadata_database, leftover_files, other). Never a name, an owner, an account, a map, a dataset, a path or a file name." }, "PartTestAnswer": { "description": "A part's Test: passed, with the milliseconds the check took, or failed with one reason: not_found (a program, or the spatial extension, is not where its setting points), busy (the part is busy with other work), timed_out (no answer within the Test's own limit) or failed. Never a path, a program's output or an error's words.", "oneOf": [ { "type": "object", "properties": { "part": { "type": "string", "enum": [ "data_folder", "query_engine", "tile_builder", "image_renderer", "metadata_database" ], "description": "The part tested." }, "result": { "const": "passed" }, "milliseconds": { "type": "integer", "minimum": 0, "description": "How long the check took." } }, "required": [ "part", "result", "milliseconds" ], "additionalProperties": false }, { "type": "object", "properties": { "part": { "type": "string", "enum": [ "data_folder", "query_engine", "tile_builder", "image_renderer", "metadata_database" ], "description": "The part tested." }, "result": { "const": "failed" }, "reason": { "type": "string", "enum": [ "not_found", "busy", "timed_out", "failed" ] } }, "required": [ "part", "result", "reason" ], "additionalProperties": false } ] }, "LibraryStyle": { "type": "object", "properties": { "id": { "type": "string", "description": "The style's identity in the library." }, "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The name a person choosing a basemap sees." }, "url": { "type": "string", "description": "The style's address, public to whoever draws a map on it, as a map's own style address is." }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" }, "offered": { "type": "boolean", "description": "Whether the style is offered where a basemap is chosen. Hidden, maps already on a copy of it keep it." }, "addedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "url", "attribution", "offered", "addedAt" ], "additionalProperties": false, "description": "A style in the basemap library." }, "LibraryStyleAdd": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^\\s*\\S[\\s\\S]{0,59}\\s*$", "description": "1 to 60 characters once trimmed." }, "url": { "type": "string", "pattern": "^\\s*[Hh][Tt][Tt][Pp][Ss]?://[^/\\\\?#\\s]", "description": "An http or https MapLibre style address with a host, at most 2,048 characters once trimmed, kept as given." } }, "required": [ "name", "url" ], "additionalProperties": false }, "LibraryStyleOffered": { "type": "object", "properties": { "offered": { "type": "boolean", "description": "True offers the style where a basemap is chosen; false hides it." } }, "required": [ "offered" ], "additionalProperties": false }, "LibraryStyleRemoved": { "type": "object", "properties": { "removed": { "const": true } }, "required": [ "removed" ], "additionalProperties": false }, "TemplateSource": { "type": "object", "properties": { "name": { "type": "string", "description": "Who published the data." }, "licence": { "type": "string", "description": "The licence's identifier, as SPDX writes it." }, "credit": { "type": "string", "description": "The credit text the source asks for, word for word." } }, "required": [ "name", "licence", "credit" ], "additionalProperties": false }, "TemplateCard": { "type": "object", "properties": { "id": { "type": "string", "description": "The template's id, the same across its versions." }, "kind": { "type": "string", "enum": [ "map", "workflow" ], "description": "A finished map, or a workflow example with its result map." }, "version": { "type": "integer", "minimum": 1, "description": "The version an open or a copy begun now takes: the newest the catalogue lists, unless the installed one is as new." }, "title": { "type": "string", "description": "The template's title." }, "question": { "type": "string", "description": "The question it answers, in a line." }, "place": { "type": "string", "description": "Where its data is." }, "tags": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "First map", "Time", "Analysis", "3D", "Big data", "Widgets", "Flows" ] }, "description": "One to three tags from a closed list." }, "dataDate": { "type": "string", "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$", "description": "The data's date: a year, a month or a day." }, "sources": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/TemplateSource" }, "description": "Every source of its data, with its licence and the credit it asks for." }, "steps": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The step's id in the template's workflow." }, "operation": { "type": "string", "description": "The operation it runs, by its id in the operation catalogue." }, "output": { "type": "string", "description": "The name of the dataset it makes." }, "reads": { "type": "array", "items": { "type": "string" }, "description": "The names it reads: datasets of the template and earlier steps' outputs, never anything outside the template." } }, "required": [ "id", "operation", "output", "reads" ], "additionalProperties": false }, "description": "A workflow example's steps in their order, as its workflow holds them, so its graph can be drawn before it is downloaded; null for a map template." }, "origin": { "type": "string", "enum": [ "shipped", "catalogue" ], "description": "shipped: in this instance's image, working with no network; catalogue: listed by the template catalogue." }, "installed": { "type": [ "integer", "null" ], "minimum": 1, "description": "The version installed on this server (shipped or downloaded), or null." }, "listed": { "type": [ "integer", "null" ], "minimum": 1, "description": "The newest version the catalogue's last list names, or null." }, "present": { "type": "boolean", "description": "Whether version is installed; false means its first open or copy downloads it." }, "size": { "type": "integer", "minimum": 0, "description": "The version's archive size in bytes, as transferred." }, "picture": { "type": "string", "enum": [ "kept", "not_kept", "too_large" ], "description": "kept: GET /api/templates/{id}/picture answers it; not_kept: the catalogue's picture could not be read, or the pictures kept for one list reached their 64 MB first; too_large: the catalogue's picture was over its 2 MB bound and refused (template_picture_too_large)." } }, "required": [ "id", "kind", "version", "title", "question", "place", "tags", "dataDate", "sources", "steps", "origin", "installed", "listed", "present", "size", "picture" ], "additionalProperties": false, "description": "One template as its card draws it." }, "TemplateDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "The template's id, the same across its versions." }, "kind": { "type": "string", "enum": [ "map", "workflow" ], "description": "A finished map, or a workflow example with its result map." }, "version": { "type": "integer", "minimum": 1, "description": "The version an open or a copy begun now takes: the newest the catalogue lists, unless the installed one is as new." }, "title": { "type": "string", "description": "The template's title." }, "question": { "type": "string", "description": "The question it answers, in a line." }, "place": { "type": "string", "description": "Where its data is." }, "tags": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "First map", "Time", "Analysis", "3D", "Big data", "Widgets", "Flows" ] }, "description": "One to three tags from a closed list." }, "dataDate": { "type": "string", "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$", "description": "The data's date: a year, a month or a day." }, "sources": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/TemplateSource" }, "description": "Every source of its data, with its licence and the credit it asks for." }, "steps": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The step's id in the template's workflow." }, "operation": { "type": "string", "description": "The operation it runs, by its id in the operation catalogue." }, "output": { "type": "string", "description": "The name of the dataset it makes." }, "reads": { "type": "array", "items": { "type": "string" }, "description": "The names it reads: datasets of the template and earlier steps' outputs, never anything outside the template." } }, "required": [ "id", "operation", "output", "reads" ], "additionalProperties": false }, "description": "A workflow example's steps in their order, as its workflow holds them, so its graph can be drawn before it is downloaded; null for a map template." }, "origin": { "type": "string", "enum": [ "shipped", "catalogue" ], "description": "shipped: in this instance's image, working with no network; catalogue: listed by the template catalogue." }, "installed": { "type": [ "integer", "null" ], "minimum": 1, "description": "The version installed on this server (shipped or downloaded), or null." }, "listed": { "type": [ "integer", "null" ], "minimum": 1, "description": "The newest version the catalogue's last list names, or null." }, "present": { "type": "boolean", "description": "Whether version is installed; false means its first open or copy downloads it." }, "size": { "type": "integer", "minimum": 0, "description": "The version's archive size in bytes, as transferred." }, "picture": { "type": "string", "enum": [ "kept", "not_kept", "too_large" ], "description": "kept: GET /api/templates/{id}/picture answers it; not_kept: the catalogue's picture could not be read, or the pictures kept for one list reached their 64 MB first; too_large: the catalogue's picture was over its 2 MB bound and refused (template_picture_too_large)." }, "howMade": { "type": "object", "properties": { "question": { "type": "string", "description": "The question in full." }, "datasets": { "type": "array", "items": { "type": "object", "properties": { "dataset": { "type": "string", "description": "A dataset of the template." }, "source": { "type": "string", "description": "The source it came from." }, "made": { "type": "string", "description": "How it was made, in a line." } }, "required": [ "dataset", "source", "made" ], "additionalProperties": false } }, "styling": { "type": "array", "items": { "type": "string" }, "description": "The styling choices, a line each." } }, "required": [ "question", "datasets", "styling" ], "additionalProperties": false }, "contents": { "anyOf": [ { "$ref": "#/components/schemas/TemplateContents" }, { "type": "null" } ], "description": "What the version holds, once it is installed on this server (shipped, or downloaded and whole by its record); null while it is not, or when its files do not read. POST /api/templates/{id}/fetch installs a listed version." } }, "required": [ "id", "kind", "version", "title", "question", "place", "tags", "dataDate", "sources", "steps", "origin", "installed", "listed", "present", "size", "picture", "howMade", "contents" ], "additionalProperties": false, "description": "One template: its card, how it is made, and what its version holds once installed." }, "TemplateDataset": { "type": "object", "properties": { "id": { "type": "string", "description": "Its id as a template's dataset or bundled result, never a stored dataset's: no dataset operation answers it." }, "name": { "type": "string", "description": "The name the template's SQL and steps read it by." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Its rows, as measured when the version was installed." }, "geometryColumn": { "type": [ "string", "null" ], "description": "Its geometry column, or null for a table without geometry." }, "geometryType": { "type": [ "string", "null" ], "description": "Its geometry type as measured, or null." } }, "required": [ "id", "name", "rowCount", "geometryColumn", "geometryType" ], "additionalProperties": false, "description": "A dataset of an installed template version, or a step's bundled result." }, "TemplateContents": { "type": "object", "properties": { "mapId": { "type": "string", "description": "The template map's id. GET /api/maps/{id} reads the map with its layers' SQL and styles, and the layer render and widget-value operations answer its layers, as for a map one may only view; nothing writes it." }, "revision": { "type": "string", "description": "The version's revision, from its archive's checksum; the same for as long as the version is installed." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the template's map was made, as it was published." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the template's map last changed before it was published." }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateDataset" }, "description": "The template's own datasets." }, "workflow": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "The workflow's name." }, "steps": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The step's id in the template's workflow." }, "operation": { "type": "string", "description": "The operation it runs, by its id in the operation catalogue." }, "parameters": { "type": "object", "description": "Its parameters as the workflow holds them, its output's name among them, as a workflow's step is defined." }, "output": { "$ref": "#/components/schemas/TemplateDataset" }, "reads": { "type": "array", "items": { "type": "string" }, "description": "The names it reads: the template's datasets and earlier steps' outputs." } }, "required": [ "id", "operation", "parameters", "output", "reads" ], "additionalProperties": false }, "description": "The steps in their order, each with the bundled result it came with as its output; a template's workflow never runs." }, "layout": { "type": "object", "properties": { "steps": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LayoutPosition" }, "description": "A position per step, keyed by step id." }, "sources": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LayoutPosition" }, "description": "A position per dataset read, keyed by its name." }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutNote" }, "description": "The canvas's notes, in their order." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the arrangement was last written before the version was published; null for one with nothing placed, which the canvas arranges itself." } }, "required": [ "steps", "sources", "notes", "updatedAt" ], "additionalProperties": false } }, "required": [ "name", "steps", "layout" ], "additionalProperties": false }, { "type": "null" } ], "description": "A workflow example's workflow: its steps with their parameters and its saved canvas arrangement; null for a map template." } }, "required": [ "mapId", "revision", "createdAt", "updatedAt", "datasets", "workflow" ], "additionalProperties": false, "description": "What an installed template version holds, read from this server: its map's id, its datasets and a workflow example's workflow." }, "TemplateCatalogueState": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "listed", "empty", "not_read", "off", "unreachable", "slow", "refused" ], "description": "listed: the last read listed templates; empty: it listed none this server reads; not_read: no read since this process started or since the address or the switch changed; off: an admin turned the catalogue off; unreachable: nothing answered; slow: no answer within the link import's time bound; refused: see reason." }, "host": { "type": [ "string", "null" ], "description": "The catalogue's scheme and host, never its path or query; null for a folder or an address this server cannot read." }, "folder": { "type": "boolean", "description": "True when DEZFIL_TEMPLATES_CATALOGUE names a folder on this server; its path is never given." }, "readAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the kept list was read; null before any read." }, "reason": { "type": [ "string", "null" ], "enum": [ "status", "egress_blocked", "service_address_unreadable", "template_index_too_large", "template_index_invalid", "template_index_repeats_id", "template_address_outside", null ], "description": "Why it was refused: status (the catalogue answered with the status below), egress_blocked (the egress rules), service_address_unreadable (a saved address the instance's key no longer opens), template_index_too_large (over 1 MB), template_index_invalid (not an index this server reads), template_index_repeats_id (an id twice) or template_address_outside (an archive or picture address outside the catalogue's origin or folder). Null unless the state is refused." }, "status": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599, "description": "The status the catalogue answered with; null unless the reason is status." }, "message": { "type": "string", "description": "Only for template_index_invalid, a plain-text reason naming the first offending field and its entry's zero-based position and id when available, with names limited to 120 characters and no other index values." } }, "required": [ "state", "host", "folder", "readAt", "reason", "status" ], "additionalProperties": false, "description": "Where the template catalogue stands for this list." }, "TemplateFetched": { "type": "object", "properties": { "id": { "type": "string", "description": "The template's id." }, "version": { "type": "integer", "minimum": 1, "description": "The version fetched: the one the request named, else the one its card took." }, "size": { "type": "integer", "minimum": 0, "description": "Its archive's size in bytes, as transferred." }, "downloaded": { "type": "boolean", "description": "True when this call downloaded and installed it, or joined the download that did; false when it was installed already and nothing was sent." } }, "required": [ "id", "version", "size", "downloaded" ], "additionalProperties": false, "description": "A template's version, installed on this server." }, "TemplateCopy": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "members": { "$ref": "#/components/schemas/ProjectMembers" } }, "required": [ "project", "members" ], "additionalProperties": false, "description": "The project a copy made, with its members: the copied map, the copied workflow of a workflow example, and the copied datasets." }, "TemplateDownloads": { "type": "object", "properties": { "versions": { "type": "integer", "minimum": 0, "description": "How many downloaded versions." }, "bytes": { "type": "integer", "minimum": 0, "description": "The bytes their folders take in the data folder." } }, "required": [ "versions", "bytes" ], "additionalProperties": false, "description": "What the downloaded templates hold on this server, which DELETE /api/templates/downloads frees. Shipped templates and copies are not among them." }, "TemplateList": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateCard" }, "description": "Shipped templates first, in the image's order; then the catalogue's entries in its index's order, a shipped id winning over an entry naming it; then downloaded templates the kept list does not name." }, "catalogue": { "$ref": "#/components/schemas/TemplateCatalogueState" }, "downloads": { "$ref": "#/components/schemas/TemplateDownloads" } }, "required": [ "templates", "catalogue", "downloads" ], "additionalProperties": false }, "ExportImageDefinition": { "type": "object", "description": "An image export, fully resolved: exact output pixels (the aspect is entailed), the camera, how large the map is drawn, bounded placement and a size step for every element, the included widgets, an optional title, and an optional basemap override for this image alone. The builder's export card edits exactly this and the server renderer consumes exactly this, so the two roads cannot drift.", "additionalProperties": false, "required": [ "viewport", "size", "legend", "widgets", "title", "appearance" ], "properties": { "mapScale": { "type": "number", "minimum": 0.25, "maximum": 16, "description": "Output pixels per composition pixel: how large the map itself is drawn. A smaller value lays the map out across more composition pixels, so its labels, roads and symbols take a smaller share of the image: the look of a screenshot of a very large screen. Output width is then only density: a wider image is the same picture more sharply. Required, unless the deprecated name overlayScale is given instead." }, "overlayScale": { "type": "number", "minimum": 0.25, "maximum": 16, "description": "Deprecated name for mapScale, accepted so definitions written before the rename keep rendering. Give one or the other." }, "widgetSize": { "type": "string", "enum": [ "xs", "s", "m", "l" ], "description": "How large the widget rail is drawn. Absent means m." }, "credit": { "type": "object", "additionalProperties": false, "required": [ "corner", "size" ], "description": "Where the basemap attribution sits and how large. It has no visibility: the basemap licence requires it in every image, and it never renders below a legible floor whatever the step. Absent means bottom-right at m.", "properties": { "corner": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ] }, "size": { "type": "string", "enum": [ "xs", "s", "m", "l" ] } } }, "basemapLayers": { "type": [ "object", "null" ], "additionalProperties": false, "description": "The basemap layer groups THIS image draws: resolved, not a difference from the map's stored choice, so the definition renders the same tomorrow as today. A missing key means visible. Null means every group is visible; absence means the map's own stored choice. Vector styles only: imagery has no groups to hide.", "properties": { "labels": { "type": "boolean" }, "roads": { "type": "boolean" }, "borders": { "type": "boolean" }, "buildings": { "type": "boolean" }, "water": { "type": "boolean" }, "land": { "type": "boolean" } } }, "appearance": { "type": "string", "enum": [ "light", "dark" ], "description": "The author's active theme at export: captured state, so the server renders exactly what the card's client capture always exported implicitly." }, "viewport": { "type": "object", "additionalProperties": false, "required": [ "lng", "lat", "zoom", "pitch", "bearing" ], "properties": { "lng": { "type": "number", "minimum": -540, "maximum": 540 }, "lat": { "type": "number", "minimum": -85.051129, "maximum": 85.051129 }, "zoom": { "type": "number", "minimum": 0, "maximum": 24 }, "pitch": { "type": "number", "minimum": 0, "maximum": 60, "description": "Degrees; 0 = flat." }, "bearing": { "type": "number", "minimum": -360, "maximum": 360, "description": "Degrees; 0 = north-up." } } }, "size": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "type": "integer", "minimum": 480, "maximum": 4096, "description": "At least the width a legible basemap credit needs: an image too narrow to carry its attribution is refused, not exported without it." }, "height": { "type": "integer", "minimum": 64, "maximum": 4096 } } }, "legend": { "type": "object", "additionalProperties": false, "required": [ "visible", "corner", "size" ], "properties": { "visible": { "type": "boolean" }, "corner": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ] }, "size": { "type": "string", "enum": [ "xs", "s", "m", "l" ] } } }, "widgets": { "type": "array", "items": { "type": "string" }, "description": "Ids of the included widgets, in rail order." }, "title": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "text", "size" ], "properties": { "text": { "type": "string", "maxLength": 200 }, "size": { "type": "string", "enum": [ "xs", "s", "m", "l" ] } } } } }, "MapLookState": { "type": "object", "description": "The bounded state identity a check's image is attributed to: what the renderer actually drew, declared by the render page itself, never a later read of the map.", "required": [ "map", "camera", "layers", "legend", "widgets", "appearance", "digest" ], "properties": { "map": { "type": "string" }, "camera": { "type": "object", "required": [ "lng", "lat", "zoom", "pitch", "bearing" ], "properties": { "lng": { "type": "number" }, "lat": { "type": "number" }, "zoom": { "type": "number" }, "pitch": { "type": "number" }, "bearing": { "type": "number" } } }, "layers": { "type": "array", "description": "The visible layers drawn, each with a digest of the stored filters applied.", "items": { "type": "object", "required": [ "id", "filters" ], "properties": { "id": { "type": "string" }, "filters": { "type": "string" } } } }, "legend": { "type": "object", "required": [ "visible", "corner", "order" ], "properties": { "visible": { "type": "boolean" }, "corner": { "type": "string" }, "order": { "type": "array", "items": { "type": "string" } } } }, "widgets": { "type": "array", "items": { "type": "string" } }, "appearance": { "type": "string", "enum": [ "light", "dark" ] }, "digest": { "type": "string", "description": "A digest of the identity above." } } }, "MapLookRender": { "type": "object", "description": "A check's facts: everything but the image bytes, which never enter an event or a receipt.", "required": [ "id", "mapId", "mapName", "appearance", "state", "image", "source", "attribution", "composition", "elapsedMs" ], "properties": { "id": { "type": "string", "description": "The render's identity, minted per check." }, "mapId": { "type": "string" }, "mapName": { "type": "string" }, "appearance": { "type": "string", "enum": [ "light", "dark" ] }, "state": { "$ref": "#/components/schemas/MapLookState" }, "image": { "type": "object", "required": [ "width", "height", "bytes" ], "properties": { "width": { "type": "integer" }, "height": { "type": "integer" }, "bytes": { "type": "integer" } }, "description": "The size the image was answered at and its byte count." }, "source": { "type": "object", "required": [ "width", "height" ], "properties": { "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "The settled render's size, from which smaller sizes are derived." }, "attribution": { "type": "string", "description": "The basemap credit the render carried." }, "composition": { "type": "object", "required": [ "failures", "abandoned" ], "properties": { "failures": { "type": "array", "items": { "type": "string" }, "description": "Truthful failures composed into the image: a failed layer, failed widget values." }, "abandoned": { "type": "array", "items": { "type": "string" }, "description": "One host entry per external request abandonment, including repeated cuts of requests with no terminal event." } } }, "elapsedMs": { "type": "integer" } } }, "RecordedMapLookState": { "type": "object", "description": "The bounded state identity a check's image is attributed to: what the renderer actually drew, declared by the render page itself, never a later read of the map. In a terminal recovery record the detail lists layers, widgets and the legend's order may be absent: the record was compacted past them and the detail was not kept. An absent list is not an empty one, which means a map with nothing of that kind drawn.", "required": [ "map", "camera", "legend", "appearance", "digest" ], "properties": { "map": { "type": "string" }, "camera": { "type": "object", "required": [ "lng", "lat", "zoom", "pitch", "bearing" ], "properties": { "lng": { "type": "number" }, "lat": { "type": "number" }, "zoom": { "type": "number" }, "pitch": { "type": "number" }, "bearing": { "type": "number" } } }, "layers": { "type": "array", "description": "The visible layers drawn, each with a digest of the stored filters applied.", "items": { "type": "object", "required": [ "id", "filters" ], "properties": { "id": { "type": "string" }, "filters": { "type": "string" } } } }, "legend": { "type": "object", "required": [ "visible", "corner" ], "properties": { "visible": { "type": "boolean" }, "corner": { "type": "string" }, "order": { "type": "array", "items": { "type": "string" } } } }, "widgets": { "type": "array", "items": { "type": "string" } }, "appearance": { "type": "string", "enum": [ "light", "dark" ] }, "digest": { "type": "string", "description": "A digest of the identity above." } } }, "RecordedMapLookRender": { "type": "object", "description": "A check's facts: everything but the image bytes, which never enter an event or a receipt. As recorded in a recovery receipt, whose state may have been compacted.", "required": [ "id", "mapId", "mapName", "appearance", "state", "image", "source", "attribution", "composition", "elapsedMs" ], "properties": { "id": { "type": "string", "description": "The render's identity, minted per check." }, "mapId": { "type": "string" }, "mapName": { "type": "string" }, "appearance": { "type": "string", "enum": [ "light", "dark" ] }, "state": { "$ref": "#/components/schemas/RecordedMapLookState" }, "image": { "type": "object", "required": [ "width", "height", "bytes" ], "properties": { "width": { "type": "integer" }, "height": { "type": "integer" }, "bytes": { "type": "integer" } }, "description": "The size the image was answered at and its byte count." }, "source": { "type": "object", "required": [ "width", "height" ], "properties": { "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "The settled render's size, from which smaller sizes are derived." }, "attribution": { "type": "string", "description": "The basemap credit the render carried." }, "composition": { "type": "object", "required": [ "failures", "abandoned" ], "properties": { "failures": { "type": "array", "items": { "type": "string" }, "description": "Truthful failures composed into the image: a failed layer, failed widget values." }, "abandoned": { "type": "array", "items": { "type": "string" }, "description": "One host entry per external request abandonment, including repeated cuts of requests with no terminal event." } } }, "elapsedMs": { "type": "integer" } } }, "MapLook": { "type": "object", "required": [ "render", "image" ], "properties": { "render": { "$ref": "#/components/schemas/MapLookRender" }, "image": { "type": "object", "required": [ "content_type", "width", "height", "bytes", "content_base64" ], "properties": { "content_type": { "type": "string", "enum": [ "image/png" ] }, "width": { "type": "integer" }, "height": { "type": "integer" }, "bytes": { "type": "integer" }, "content_base64": { "type": "string", "description": "The PNG, byte for byte." } } } } }, "OvertureScope": { "type": "object", "description": "Where an Overture import applies. One of: {type: \"country\", code: \"DE\"} · {type: \"state\", code: \"DE-HE\"} · {type: \"division\", id} (an id from the division search) · {type: \"bbox\", bbox: [w, s, e, n]} · {type: \"polygon\", ring: [[lng, lat], …]} (≤ 500 points) · {type: \"feature\", geometry} (a GeoJSON Polygon/MultiPolygon, ≤ 20,000 vertices — e.g. a feature from an existing table). Named scopes are exact and view-independent; an optional label is kept as provenance.", "properties": { "type": { "type": "string", "enum": [ "country", "state", "division", "bbox", "polygon", "feature" ] }, "code": { "type": "string", "description": "country/state: ISO 3166-1 alpha-2 or 3166-2 code." }, "id": { "type": "string", "description": "division: the Overture division id." }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "ring": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "geometry": { "type": "object", "description": "feature: a GeoJSON Polygon or MultiPolygon, parts and holes intact." }, "label": { "type": "string", "description": "Display name, stored as provenance." } }, "required": [ "type" ] }, "FeaturePreview": { "type": "object", "description": "A Run Query result: the features the matching import would land, capped by the render cap and bounded by Bytes drawn per layer.", "properties": { "geojson": { "type": "object", "description": "GeoJSON FeatureCollection." }, "featureCount": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when more features matched than the cap." }, "cap": { "type": "integer" } }, "required": [ "geojson", "featureCount", "truncated", "cap" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "picture_upload_retired", "setting_locked", "project_owner_cannot_leave", "method_not_allowed", "authentication_required", "invalid_credentials", "account_deactivated", "setup_complete", "weak_password", "email_taken", "self_change_refused", "account_not_deactivated", "deletion_in_progress", "deletion_unreadable", "deletion_changed", "last_admin", "forbidden", "invalid_link", "token_expired", "rule_refused", "current_password_required", "authentication_busy", "ingress_unavailable", "geometry_not_supported", "geometry_choice_invalid", "geometry_in_flight", "unsupported_format", "unsupported_image", "image_too_large", "upload_too_large", "archive_too_large", "remote_fetch_failed", "remote_fetch_abandoned", "remote_too_large", "remote_timeout", "egress_blocked", "imagery_unavailable", "area_too_large", "name_taken", "not_refreshable", "dependencies_unresolved", "export_failed", "refresh_in_flight", "connection_failed", "connection_password_required", "malformed_file", "request_body_too_large", "mcp_read_failed", "mcp_transport_failed", "mcp_response_invalid", "stale_revision", "invalid_request", "not_found", "sql_rejected", "sql_error", "query_timeout", "engine_memory_exceeded", "data_processing_timeout", "request_timeout", "upload_stalled", "render_bytes_exceeded", "query_memory_exceeded", "query_result_too_large", "tile_build_timeout", "render_cap_exceeded", "tiler_unavailable", "tile_build_failed", "render_unavailable", "render_timeout", "render_failed", "look_target_missing", "look_image_too_large", "look_image_unavailable", "attachment_too_large", "operation_timeout", "operation_queue_full", "run_in_flight", "plan_changed", "operation_interrupted", "input_changed", "geocoder_unconfigured", "geocoder_failed", "isochrone_unconfigured", "isochrone_failed", "service_address_unreadable", "basemap_not_offered", "measurement_crs_unavailable", "operation_superseded", "widget_layer_missing", "column_unavailable", "field_not_published", "catalogue_not_published", "selection_incompatible", "rate_limited", "catalogue_too_large", "assistant_reservation_required", "assistant_run_unavailable", "assistant_run_conflict", "assistant_capacity", "assistant_run_state", "assistant_submission_too_large", "assistant_recovery_limit", "assistant_plan_unavailable", "assistant_action_uncertain", "assistant_action_interrupted", "assistant_action_not_admitted", "assistant_choice_invalid", "assistant_model_not_offered", "assistant_effort_not_offered", "assistant_effort_not_supported", "assistant_context_invalid", "assistant_context_too_large", "assistant_context_unavailable", "assistant_disabled", "assistant_auth", "assistant_provider", "pending_unknown", "pending_resolved", "pending_superseded", "invalid_sketch_feature", "not_a_sketch", "feature_not_found", "vertex_move_refused", "sketch_gone", "map_not_found", "template_not_listed", "templates_catalogue_off", "template_archive_too_large", "template_checksum_mismatch", "template_unpacked_too_large", "template_malformed", "template_entry_escapes", "template_members_mismatch", "template_format_unsupported", "template_invalid", "template_forbidden", "template_picture_too_large", "template_licence_refused", "template_credit_missing", "template_reference_outside", "template_record_mismatch", "template_not_installed", "template_reference_unbound", "internal" ] }, "message": { "type": "string" }, "retryAfter": { "type": "integer", "minimum": 1, "description": "Seconds before retry after a login limit or temporary authentication capacity refusal." }, "retryAt": { "type": "string", "format": "date-time", "description": "When a login limit permits another attempt." }, "rule": { "type": "string", "enum": [ "tokens.create", "publishing.publish", "connections.create", "imports.links" ], "description": "The instance rule that refused a rule_refused request, keyed as PATCH /api/instance/settings takes it." }, "setting": { "type": "string", "enum": [ "basemaps.dark", "basemaps.light", "basemaps.streets", "basemaps.satellite", "basemaps.singleMapStyles" ], "description": "The switch that refused a basemap_not_offered request: the one hiding the basemap it chose, or basemaps.singleMapStyles for a style address the basemap library does not offer, keyed as PATCH /api/instance/settings takes it." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/GeometryIssue" }, "description": "Geometry-choice refusal reasons, when applicable." }, "position": { "type": "object", "description": "Where a sql_error sits in the submitted SQL, 1-based, when the engine reported it. Absent otherwise.", "properties": { "line": { "type": "integer" }, "column": { "type": "integer" } }, "required": [ "line", "column" ] } }, "required": [ "code", "message" ] } } }, "Health": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ready" ] } } }, "HealthUnready": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "enum": [ "unready" ] }, "reason": { "type": "string", "enum": [ "An unexpected server error occurred.", "The query engine that runs SQL is not answering." ] } } }, "DependencyDataset": { "type": "object", "description": "One dataset a map or workflow depends on — the facts both filing checklists carry.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifiedName": { "type": "string", "description": "The name the caller would type: the plain name for the caller's own dataset, . for another owner's." }, "owner": { "$ref": "#/components/schemas/Person" }, "owned": { "type": "boolean", "description": "True when the caller owns the dataset: a filing checklist offers only these. Another person's dependency is listed as not the caller's to add." }, "source": { "type": "string" }, "rowCount": { "type": "integer" }, "projectIds": { "type": "array", "items": { "type": "string" }, "description": "Every project the dataset is in that the caller reaches, and for the caller's own dataset every project it is in, one they no longer reach included; order carries no meaning." }, "geometryColumn": { "type": [ "string", "null" ], "description": "The geometry column; null for a non-spatial dataset." }, "geometryType": { "type": [ "string", "null" ], "description": "The sampled geometry type; null when there is no column or nothing was sampled — a column with no sampled type is still spatial." }, "producer": { "type": [ "object", "null" ], "description": "The workflow-origin recipe a run of which recorded this dataset as its output, when the caller reaches that workflow; null otherwise.", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "owned": { "type": "boolean", "description": "True when the caller owns the workflow and so may file it." } } } }, "required": [ "id", "name", "qualifiedName", "owner", "owned", "source", "rowCount", "projectIds", "geometryColumn", "geometryType", "producer" ] }, "MapDependencies": { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "datasets": { "type": "array", "description": "The distinct registered datasets the map's layers read, alphabetical by the name the caller would type.", "items": { "$ref": "#/components/schemas/DependencyDataset" } } }, "required": [ "datasets" ] }, "WorkflowDependencies": { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "datasets": { "type": "array", "description": "The distinct registered datasets the workflow reads and writes, every runner's recorded output the caller reaches included, alphabetical by the name the caller would type.", "items": { "$ref": "#/components/schemas/DependencyDataset" } } }, "required": [ "datasets" ] }, "WorkspaceSettings": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The authenticated account's display name." }, "instanceName": { "type": [ "string", "null" ], "description": "The instance's optional name: shown beside the wordmark and as the browser-title tail. Null when the instance is unnamed." }, "viewPrefs": { "type": "object", "description": "Per-screen view preferences; slices merge into what is stored, and the read carries every slice written so far.", "properties": { "maps": { "type": "object", "description": "The Maps list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "edited", "created", "name" ] } } }, "data": { "type": "object", "description": "The Data page.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "updated", "name", "rows", "size" ] } } }, "workflows": { "type": "object", "description": "The workflows list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "edited", "created", "name" ] } } }, "projects": { "type": "object", "description": "The Projects list.", "properties": { "view": { "type": "string", "enum": [ "grid", "list" ] }, "sort": { "type": "string", "enum": [ "updated", "name", "largest" ] } } } } }, "sourceGrouping": { "type": "string", "enum": [ "person", "project" ], "default": "person", "description": "How the SQL console's source list groups datasets: by person (your own, then each other person's under their name and SQL name) or by project. Your own choice, never another account's; person until you choose otherwise." }, "look": { "type": "object", "additionalProperties": false, "description": "Your look, every pick at its kept value or its default; a kept value this version no longer offers reads as its default. It follows you to every browser you sign in to; published pages and exported images keep the default look.", "properties": { "color": { "type": "string", "enum": [ "kelp", "harbor", "heather", "slate" ], "default": "kelp", "description": "Color. The interface's tint: accents, primary buttons, active marks, focus and the background's ink. Never a data color." }, "contrast": { "type": "string", "enum": [ "standard", "more" ], "default": "standard", "description": "Contrast. Borders, dividers and quieter text; more makes them stronger in both themes." }, "font": { "type": "string", "enum": [ "inter", "system" ], "default": "inter", "description": "Typeface. The face of everything read: Inter, or the computer's own. Identifiers and values keep the mono face." }, "background": { "type": "string", "enum": [ "atlantic", "plain", "graticule", "hex" ], "default": "atlantic", "description": "Background. The texture behind the workspace and in the header bar; plain is none." }, "corners": { "type": "string", "enum": [ "rounded", "soft" ], "default": "rounded", "description": "Corners. Rounded edges of cards, fields, buttons and panels; soft is tighter." }, "rail": { "type": "string", "enum": [ "hover", "open", "icons" ], "default": "hover", "description": "Side menu. How the side menu opens: on a resting pointer or focus, always open with labels, or icons only." }, "panels": { "type": "string", "enum": [ "glass", "liquid", "paper" ], "default": "glass", "description": "Panels. How cards and panels are drawn: frosted glass, liquid glass with a light on its rim, or opaque paper with no blur." }, "transparency": { "type": "string", "enum": [ "clear", "medium", "firm" ], "default": "clear", "description": "Transparency. How much of the map shows through Liquid's cards and panels: clear, medium or firm. Only while Panels is Liquid." } }, "required": [ "color", "contrast", "font", "background", "corners", "rail", "panels", "transparency" ] } }, "required": [ "displayName", "instanceName", "viewPrefs", "sourceGrouping", "look" ] }, "Config": { "type": "object", "properties": { "basemapUrl": { "type": "string", "description": "The deployment default style (override or dark)." }, "basemapOverrideUrl": { "type": [ "string", "null" ], "description": "The deployment basemap override, when set — it pins Auto maps in both themes." }, "basemaps": { "type": "array", "description": "The selectable basemap styles.", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "dark", "light", "streets", "satellite" ] }, "label": { "type": "string" }, "url": { "type": "string" }, "kind": { "type": "string", "enum": [ "vector", "imagery" ], "description": "Vector styles carry the toggleable content groups (basemapLayers); imagery is a photo — groups don't apply." }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" } } } }, "basemapStyles": { "type": "array", "description": "The styles an admin added to the basemap library and offers, oldest first, chosen by their id; hidden ones are left out.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The style's identity in the library." }, "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The name a person choosing a basemap sees." }, "url": { "type": "string", "description": "The style's address, public to whoever draws a map on it, as a map's own style address is." }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" } }, "required": [ "id", "name", "url", "attribution" ], "additionalProperties": false, "description": "A style an admin added to the library by its address, offered where a basemap is chosen. A map that takes it keeps its own copy of the name, the address and the credit." } }, "singleMapStyles": { "type": "boolean", "description": "Whether a map may take a style address the basemap library does not offer (the basemaps.singleMapStyles setting). Off, such an address is refused with basemap_not_offered when a map write or an undo or redo would newly put it on a map; a map that holds one keeps it." }, "palettes": { "type": "array", "description": "The palette catalogue for data-driven fills, grouped for browsing and flagged colorblind-safe where the upstream source designates it.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "sequential", "categorical" ] }, "group": { "type": "string", "enum": [ "sequential", "diverging", "qualitative" ], "description": "Browsing group; diverging palettes classify as kind \"sequential\" (same methods, steps, reverse)." }, "colorblindSafe": { "type": "boolean" }, "colors": { "type": "array", "items": { "type": "string" } }, "levels": { "type": "object", "description": "Published per-class-count colors (ColorBrewer sets); a k-class fill uses these exact colors when present." } } } }, "renderCapFeatures": { "type": "integer" }, "previewRows": { "type": "integer" }, "geocoderConfigured": { "type": "boolean", "description": "Whether a place-search provider endpoint is configured. The endpoint URL itself never leaves the server." }, "defaults": { "type": "object", "additionalProperties": false, "required": [ "newMap.basemap", "newMap.latitude", "newMap.longitude", "newMap.zoom", "newMap.legendCorner", "newLayer.colorCycle", "newLayer.pointOpacity", "newLayer.lineOpacity", "newLayer.areaOpacity", "newLayer.lineWidth", "newLayer.pointRadius", "canvas.opens", "canvas.minimap", "canvas.resultsBand", "sqlConsole.textSize", "sqlConsole.lineWrap", "imageExport.width", "imageExport.shape" ], "description": "What new things start with on this instance, keyed and valued as PATCH /api/instance/settings takes them: every key with its effective value. A new map takes the newMap values and a new layer created without a style the newLayer values; the workflow canvas, the SQL console and a fresh image export card take theirs as they open. Admins change them, and nothing that already exists changes with them. A basemap the instance no longer offers reads as auto.", "properties": { "newMap.basemap": { "type": "string", "enum": [ "auto", "dark", "light", "streets", "satellite" ], "description": "Basemap. The basemap a new map starts on. Auto follows the theme; a basemap the instance no longer offers starts on Auto." }, "newMap.latitude": { "type": "number", "minimum": -85, "maximum": 85, "description": "Starting latitude. The latitude a new map opens at." }, "newMap.longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Starting longitude. The longitude a new map opens at." }, "newMap.zoom": { "type": "number", "minimum": 0, "maximum": 22, "description": "Starting zoom. The zoom a new map opens at." }, "newMap.legendCorner": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ], "description": "Legend corner. Where a new map's legend sits." }, "newLayer.colorCycle": { "type": "string", "enum": [ "uber_viz_qualitative", "bold", "tab10", "paired", "dark2", "set3" ], "description": "Color cycle. The palette whose colors new layers take in turn, drawn sketches included." }, "newLayer.pointOpacity": { "type": "integer", "minimum": 10, "maximum": 100, "description": "Point opacity (%). How opaque a new points layer is drawn, unless it is created with a style." }, "newLayer.lineOpacity": { "type": "integer", "minimum": 10, "maximum": 100, "description": "Line opacity (%). How opaque a new lines layer is drawn, unless it is created with a style." }, "newLayer.areaOpacity": { "type": "integer", "minimum": 10, "maximum": 100, "description": "Area opacity (%). How opaque a new areas layer is drawn, unless it is created with a style." }, "newLayer.lineWidth": { "type": "number", "minimum": 0.5, "maximum": 50, "description": "Line width (px). How wide a new lines layer is drawn, unless it is created with a style." }, "newLayer.pointRadius": { "type": "number", "minimum": 0.5, "maximum": 100, "description": "Point radius (px). How large a new layer's points are drawn, unless it is created with a style." }, "canvas.opens": { "type": "string", "enum": [ "full", "framed" ], "description": "Canvas opens. Whether a workflow canvas opens full screen or framed." }, "canvas.minimap": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "Canvas minimap. When a workflow canvas shows its minimap until the person chooses: auto shows it from six nodes." }, "canvas.resultsBand": { "type": "string", "enum": [ "closed", "open" ], "description": "Canvas results band. Whether a workflow canvas opens with its results band closed or open until the person chooses." }, "sqlConsole.textSize": { "type": "string", "enum": [ "11", "12", "13", "14", "16" ], "description": "SQL text size (px). The text size the SQL console's editor opens at." }, "sqlConsole.lineWrap": { "type": "boolean", "description": "SQL line wrap. Whether the SQL console's editor wraps long lines." }, "imageExport.width": { "type": "string", "enum": [ "1280", "1920", "2560" ], "description": "Image starting width (px). The width a fresh image export card opens at." }, "imageExport.shape": { "type": "string", "enum": [ "16:9", "4:3", "1:1" ], "description": "Image starting shape. The shape a fresh image export card opens at." } } }, "templates": { "type": "object", "required": [ "catalogue" ], "additionalProperties": false, "properties": { "catalogue": { "type": "boolean", "description": "Whether the template catalogue is in use (the templates.catalogue setting). Off, the server reads it for nothing; shipped and downloaded templates still open and copy." } } }, "rules": { "type": "object", "additionalProperties": false, "required": [ "tokens.create", "tokens.expiry", "publishing.publish", "publishing.embedding", "connections.create", "imports.links" ], "description": "The rules every signed-in account follows, keyed and valued as PATCH /api/instance/settings takes them. Admins change them.", "properties": { "tokens.create": { "type": "string", "enum": [ "everyone", "admins" ], "description": "Whether every account or only admins may create API tokens. Tokens made earlier keep working." }, "tokens.expiry": { "type": "string", "enum": [ "never", "30d", "90d", "1y" ], "description": "The lifetime a new API token takes, from its creation. Tokens made earlier keep their own." }, "publishing.publish": { "type": "string", "enum": [ "everyone", "admins", "none" ], "description": "Whether every account, only admins or no one may publish a map or change a publication. Published maps stay public and can be unpublished." }, "publishing.embedding": { "type": "string", "enum": [ "any", "listed", "off" ], "description": "Which other sites may show a published page in a frame: any site, only the listed sites (at least one), or none." }, "connections.create": { "type": "string", "enum": [ "everyone", "admins" ], "description": "Whether every account or only admins may add a database connection. Connections made earlier keep working." }, "imports.links": { "type": "string", "enum": [ "everyone", "admins" ], "description": "Whether every account or only admins may import from web addresses and cloud storage. Link datasets keep refreshing." } } }, "passwordMin": { "type": "integer", "minimum": 8, "maximum": 64, "description": "The instance's shortest password: the fewest characters a password set from now may have, from 8 to 64. Admins change it; passwords set earlier keep signing in." } } }, "SearchResults": { "type": "object", "description": "The grouped map-search answer. `places` is present only when asked for, `refusedLayers` only when a layer's values were refused.", "required": [ "layers", "values", "coordinates" ], "properties": { "layers": { "type": "array", "description": "Visible layers whose names match.", "items": { "type": "object", "required": [ "layerId", "name", "viz" ], "properties": { "layerId": { "type": "string" }, "name": { "type": "string" }, "viz": { "type": "string", "description": "The layer's visualization type." } } } }, "values": { "type": "array", "description": "Matching features, one row each, at most 20. Point features carry `point`; lines and polygons carry an interior `anchor` and `bounds` [minLng, minLat, maxLng, maxLat].", "items": { "type": "object", "required": [ "layerId", "layerName", "field", "value" ], "properties": { "layerId": { "type": "string" }, "layerName": { "type": "string" }, "field": { "type": "string" }, "value": { "type": "string" }, "point": { "type": "array", "items": { "type": "number" } }, "anchor": { "type": "array", "items": { "type": "number" } }, "bounds": { "type": "array", "items": { "type": "number" } } } } }, "refusedLayers": { "type": "array", "description": "Visible layers whose matching values were refused: one of them is longer than 2,097,152 bytes (2 MiB) as a JSON string, the ceiling for one value. Such a layer answers no value rows; the others answer as usual. Each entry carries the error and errorCode a failed widget carries (query_result_too_large). Other layer failures contribute nothing and are not listed.", "items": { "type": "object", "required": [ "layerId", "layerName", "error", "errorCode" ], "properties": { "layerId": { "type": "string" }, "layerName": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string", "description": "One of the documented error codes." } } } }, "coordinates": { "type": "array", "description": "Every plausible reading of a pasted decimal pair — both when both are valid.", "items": { "type": "object", "required": [ "reading", "lat", "lng" ], "properties": { "reading": { "type": "string", "enum": [ "latlon", "lonlat" ] }, "lat": { "type": "number" }, "lng": { "type": "number" } } } }, "places": { "type": "object", "description": "The places group's answer: `ok` with results and the provider's attribution, `unconfigured`, or `failed` with a sanitized message (never the provider URL).", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "ok", "unconfigured", "failed" ] }, "attribution": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "required": [ "name", "lng", "lat" ], "properties": { "name": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "lng": { "type": "number" }, "lat": { "type": "number" }, "bounds": { "type": "array", "items": { "type": "number" } } } } } } } } }, "OperationCatalog": { "type": "object", "description": "The verbs this instance offers, as data. An agent discovers what it may ask the run endpoint for by reading this rather than by knowing the verbs in advance — which is why every field a caller needs in order to build a legal request is declared here.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "group": { "type": "string" }, "label": { "type": "string" }, "symbol": { "type": "string", "description": "Glyph name a picker draws beside the label — presentation metadata, stable per verb, from the app's shared icon set." }, "blurb": { "type": "string", "description": "One plain-text line for pickers. `description` is the reference text; this is the working surface's sentence." }, "description": { "type": "string" }, "inputs": { "type": "array", "description": "The datasets this verb takes and what each is for. A verb with two inputs has two that are not interchangeable — a spatial join's left and right mean different things, and the output's geometry comes from one of them. A verb that declares none takes its input from whatever its own SQL names, which is a different thing from taking no input at all.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "string", "enum": [ "any", "none", "point", "line", "polygon" ] }, "description": "Geometry classes this particular input accepts. \"none\" is the opposite of \"any\": it admits only a table without geometry, which is what a verb that writes a geometry column onto every row takes." }, "required": { "type": "boolean" } } } }, "accepts": { "type": "array", "items": { "type": "string", "enum": [ "any", "none", "point", "line", "polygon" ] }, "description": "Input geometry classes the operation accepts overall; \"any\" includes a table with no geometry, and \"none\" admits only one." }, "requires": { "type": "array", "items": { "type": "string", "enum": [ "geocoder", "isochrone" ] }, "description": "What this instance must be configured with for the verb to run at all. A verb that declares none always runs." }, "availability": { "type": "object", "description": "Whether *this* instance can run the verb, resolved when the catalog is served rather than declared — an operator who configures a provider changes the answer without changing a verb. A verb with no requirement answers available.", "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "description": "Why not, when it cannot — one sentence a reader can act on, naming the setting that is missing." } } }, "outputGeometry": { "type": "object", "description": "Where the result's geometry comes from. A verb that fixes its class regardless of input declares it; one that passes geometry through names the input it comes from; one whose result must be inspected says so.", "properties": { "kind": { "type": "string", "enum": [ "probed", "none", "from_input", "fixed" ] }, "input": { "type": "string" }, "geometry": { "type": "string", "enum": [ "point", "line", "polygon" ] } } }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "min": { "type": "number", "description": "Hard lower bound, where the verb has one." }, "max": { "type": "number", "description": "Hard upper bound, where the verb has one." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "enum", "enum_list", "field", "column_list", "field_list", "number_list" ], "description": "`enum` is one value from `options`; `enum_list` is several, as a list. They are distinct because a caller told `enum` where a list is required has been given the wrong shape. `field` is one column of the named input; `column_list` is several columns, as names; `field_list` is several **aggregate specifications** — `{aggregate, field, as}` — and sending one shape where the other is expected is refused." }, "required": { "type": "boolean" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" }, "description": "The permitted values for an enum or enum list, fixed by the operation's own contract rather than by whatever the engine happens to offer. On a `field_list` these are the aggregates that parameter accepts, which differ between verbs." }, "aliasable": { "type": "boolean", "description": "Whether a carried value may be given a name of its own. A summary's aggregates cannot, and an editor offering the field would produce a name the operation ignores." }, "requiredWhen": { "type": "object", "description": "What makes this parameter required, when it is not always — a distance is needed only for a within-distance relationship. Declared so a caller knows before it sends rather than after the refusal.", "properties": { "parameter": { "type": "string" }, "equals": { "type": "string" } } }, "relevantWhen": { "type": "object", "description": "When this parameter is part of the question at all — absent means always; present, it only applies while the named parameter holds one of these values. A distance is no part of an \"intersects\" question. Distinct from requiredWhen: a parameter can be used without being required. A value sent for an inapplicable parameter is ignored or refused by the operation's own admission, so callers should omit it.", "properties": { "parameter": { "type": "string" }, "oneOf": { "type": "array", "items": { "type": "string" } } } }, "ofInput": { "type": "string", "description": "Which input a field parameter names a column of." }, "fieldType": { "type": "string", "enum": [ "text", "number" ], "description": "The kind of column a field parameter may name, when the verb needs one kind. Declared so a caller offers or sends a column that can work rather than learning from a refusal; admission checks the same rule." }, "minItems": { "type": "number", "description": "For a number_list: the fewest items the list takes." }, "maxItems": { "type": "number", "description": "For a number_list: the most items the list takes — the isochrone's four bands is the protocol's own maximum." }, "itemMin": { "type": "number", "description": "For a number_list: the floor every item must clear." }, "itemInteger": { "type": "boolean", "description": "For a number_list: items must be whole numbers." }, "itemsUnique": { "type": "boolean", "description": "For a number_list: duplicate items are refused — each band is asked once." }, "unit": { "type": "string", "enum": [ "metres", "minutes" ], "description": "Present when the value is not a bare number: `metres` is a **ground measurement** — metres on the earth, at the latitude the data occupies, never degrees and never metres on a map projection; a caller that ignores this and sends the geometry's own units gets a buffer five hundred degrees wide. `minutes` is travel time: the number the user typed is the number on the wire, no conversion exists." }, "default": { "description": "The value used when the parameter is omitted." } } } } } } } } }, "OperationMeasurement": { "type": "object", "description": "Where a run measured. A buffer whose record does not name its measurement CRS is not reproducible — the same operation with the same parameters can produce a different geometry under a later strategy, and nothing would explain the difference.", "properties": { "crs": { "type": "object", "description": "The CRS each kind of measurement happened in, keyed by kind. A distance is measured in a transverse Mercator centred on the data's own extent, recorded as its PROJ definition; an area in a global equal-area projection, recorded as its EPSG code.", "additionalProperties": { "type": "string" } }, "fallback": { "type": "boolean", "description": "True when a measurement was made in a global projection rather than a local one, so a number measured globally is never read back as one measured locally." }, "assumedCrs": { "type": "array", "items": { "type": "string" }, "description": "Inputs whose WGS84 was assumed rather than declared. The measurement is only as trustworthy as that assumption." } } }, "OperationDryRun": { "type": "object", "description": "The answer to dryRun: what the operation would produce, with nothing written.", "properties": { "operation": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal facts to read before committing to the run — today, that a measured input's coordinate system was assumed rather than declared. Said here so a caller learns it *before* running, not after." }, "measurement": { "$ref": "#/components/schemas/OperationMeasurement" }, "dryRun": { "type": "object", "properties": { "rowCount": { "type": "integer" }, "geometryColumn": { "type": [ "string", "null" ] }, "geometryType": { "type": [ "string", "null" ], "description": "The class the registered dataset would carry, in the same words an imported table holding that geometry does." }, "geometry": { "type": "string", "enum": [ "none", "undetermined", "classified" ], "description": "Which of the three answers this is. 'none' — the result has no geometry column and would be a table, not a mappable layer. 'undetermined' — it has one but no geometries to classify. 'classified' — geometryType names its class. A null geometryType alone cannot tell the first two apart." } } } } }, "OperationRun": { "type": "object", "description": "One run of an operation. The same shape in every state, so a queued run and a finished one are read the same way.\n\nFields that have not happened yet are absent rather than present and empty: a queued run carries no startedAt, and a run that has not succeeded carries no output. There is deliberately no completion percentage — the engine's own progress signal is unreachable from the hardened query instance, and it would describe one statement of a run made of several. Show elapsed time from startedAt instead.", "properties": { "id": { "type": "string", "description": "Identifies this run, distinct from its output." }, "operation": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ], "description": "The last three are terminal and never change again. A cancelled run carries no error: the user's own choice is not a fault." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal facts to read before trusting the answer — today, that a measured input's coordinate system was assumed rather than declared. Present on the answer that accepts a run; the durable record is the output's own provenance, so a polled run does not repeat it." }, "subject": { "type": "object", "description": "What groups this run with others in history. 'client' when the caller supplied the identity, 'run' when the run is its own subject.", "properties": { "kind": { "type": "string", "enum": [ "run", "client", "step" ] }, "id": { "type": "string" } } }, "parameters": { "type": "object", "description": "The parameters this run was accepted with." }, "acceptedAt": { "type": "string" }, "startedAt": { "type": "string", "description": "Absent until the run leaves the queue." }, "finishedAt": { "type": "string", "description": "Absent until the run reaches a terminal state." }, "output": { "type": "object", "description": "The dataset the run wrote, by id and by name. Present only on a succeeded run.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "disclosure": { "type": "object", "description": "What this run asked, for a run whose answers came from a **provider** rather than the engine — the endpoint's host and path, the parameters that affected the answers, the address-normalization version, and how many distinct questions were answered from the cache and how many from the wire. It stands in place of the SQL an in-engine run records, and it belongs to *this* run: a later re-run of the same step publishes its own. The endpoint's query string, where a key travels, is never included. Absent on a run that asked nobody.", "additionalProperties": true }, "error": { "type": "object", "description": "Present only on a failed run.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "OperationRunEnvelope": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/OperationRun" } } }, "OperationRunList": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/OperationRun" } } } }, "StaleCause": { "type": "object", "description": "Why a step's output no longer reflects what it was made from. **Every active cause is reported**, each naming the input it came from: a step can read a refreshed table *and* sit downstream of a re-run step at once, and discarding one to show the other would leave this unable to say why.", "properties": { "reason": { "type": "string", "enum": [ "source_changed", "upstream_stale", "upstream_re_ran" ] }, "tableId": { "type": "string" }, "tableName": { "type": "string" }, "producedByStepId": { "type": "string", "description": "The step that produces that table, when one does." } } }, "RecipeStep": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string" }, "recipeId": { "type": "string" }, "ordinal": { "type": "integer" }, "operation": { "type": "string" }, "parameters": { "type": "object", "description": "What the step means now — what its output was produced from. Non-scalar parameters are kept as sent." }, "summary": { "type": "string", "description": "One line describing what this step does, composed from the operation and its active parameters — \"500 m around stations\". Served so every surface and every agent reads the same sentence rather than composing its own; it describes what the step means now, never a proposal awaiting a run." }, "proposedParameters": { "type": [ "object", "null" ], "description": "An edit awaiting a successful run; null when there is none." }, "output": { "type": [ "object", "null" ], "description": "The output of the run this view describes: the caller's own latest output of the step when they have one, else the workflow owner's, each runner's output being their own dataset. The step's conditions, inputs and last success describe the same run. Shown when the caller reaches the dataset; one since deleted only to its runner and the workflow's owner. Null when neither has produced one or the caller does not reach it.", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "runner": { "$ref": "#/components/schemas/ResourceOwner", "description": "The person whose run produced it." }, "runId": { "type": [ "string", "null" ], "description": "The workflow run that produced it, when recorded." }, "jobId": { "type": [ "string", "null" ], "description": "The step's attempt that produced it, when recorded." } } }, "condition": { "type": "string", "enum": [ "broken", "output_missing", "output_unavailable", "stale", "never_run", "current" ], "description": "The first condition true of it, in the order broken, output missing, output unavailable, stale, never run, current — un-runnable before un-current, because offering a re-run that cannot succeed tells the user the wrong thing. `output_missing`: the output of the run described was deleted. `output_unavailable`: that output exists but is outside the caller's reach (the workflow owner's, shown to a caller with no output of their own); it is named nowhere." }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "**Every** condition true of it. Conditions coexist: a step can have lost both an input and its output." }, "causes": { "type": "array", "items": { "$ref": "#/components/schemas/StaleCause" } }, "missingInputs": { "type": "array", "description": "What it lost, when it is broken — with the id and name it recorded, which is how the row explains itself after a deletion. `throughStepId` is set when the break arrived from a producer upstream rather than from this step's own input. Conditions are read within the caller's reach: an input the caller cannot reach is missing to them, named as written, and for a caller whose own space is not the workflow's SQL home it carries `message`, the sentence a resource evaluation gives, the same for a hidden and a nonexistent dataset.", "items": { "type": "object", "properties": { "tableId": { "type": "string" }, "tableName": { "type": "string" }, "throughStepId": { "type": "string" }, "message": { "type": "string" } } } }, "origin": { "type": [ "object", "null" ], "description": "Where a layer-authored step's SQL came from, including `substitutionNote` when the layer aggregated and the step took the rows behind the cells instead. The map and layer it names are left out when the caller does not reach that map." }, "inputs": { "type": "array", "description": "The tables this step read when it last published — from the parse of the SQL that ran, never a scan of its text. Only the ones the caller reaches, and, to the workflow's owner, ones since deleted.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "reads": { "type": "array", "items": { "type": "string" }, "description": "What the step would read on its next run: its pending definition's reads when it holds one, its active definition's otherwise — named inputs, or the tables its SQL names — before any run and whether or not those tables exist. Present tense; `inputs` is the recorded past." }, "latestAttempt": { "oneOf": [ { "$ref": "#/components/schemas/OperationRun" }, { "type": "null" } ], "description": "Its most recent run, in one of the five job states. Read together with the condition and never instead of it." }, "lastSuccessAt": { "type": [ "string", "null" ] }, "templateResult": { "type": [ "object", "null" ], "properties": { "template": { "type": "string", "description": "The template's id." }, "version": { "type": "integer", "minimum": 1, "description": "The version copied." } }, "required": [ "template", "version" ], "description": "Set when the output this step's view describes is a template's bundled result that came with a copy of the template (its dataset's source is `template`). No run of this workflow made it, so `lastSuccessAt` is null and the output names no job or run. The step's first run replaces it, and this is null from then on." } } }, "Recipe": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string", "enum": [ "workflow", "builder" ], "description": "Which surface made it: the workflows page lists `workflow`; the builder's one-step Tools make `builder`. Fixed at creation." }, "projectId": { "type": [ "string", "null" ], "description": "The project this workflow is in: on the caller's own workflow always, a project they no longer reach included (they withdraw it with PATCH /api/projects/{id}/members), and on anyone else's the project through which the caller reaches it; null = in no project." }, "owner": { "$ref": "#/components/schemas/Person", "description": "The workflow's owner." }, "home": { "type": "string", "description": "The SQL name of the workflow's SQL home: the account whose datasets its plain table names mean, whoever reads or runs it." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "When it was last edited: rename, or a step added, edited, reordered or removed. A run is not an edit, and neither is a refused change. Strictly increasing." }, "summary": { "$ref": "#/components/schemas/RecipeSummary" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeStep" } } }, "required": [ "owner", "home" ] }, "RecipeSummary": { "type": "object", "description": "The recipe's one-line state, computed by the server so the workflows page and an agent read the same classification. The first status that applies wins; a step in more than one condition counts once, in the status shown.", "properties": { "nodes": { "type": "integer", "description": "Steps in the recipe." }, "sources": { "type": "integer", "description": "Distinct tables read that no step of this recipe produces." }, "liveOutputs": { "type": "integer", "description": "Outputs whose dataset currently exists — what deleting the recipe leaves behind." }, "status": { "type": "string", "enum": [ "empty", "cannot_run", "in_progress", "failed", "run_again", "never_run", "partly_never_run", "up_to_date" ], "description": "In precedence: `empty` (no steps); `cannot_run` (a step is broken); `in_progress` (a latest attempt queued or running); `failed` (a latest attempt failed); `run_again` (an output deleted or stale, or a pending edit); `never_run` (no step has an output); `partly_never_run` (some have none); `up_to_date`. A cancelled attempt alone changes nothing." }, "count": { "type": "integer", "description": "How many steps the status counts; 0 for empty and up to date." } } }, "RecipeEnvelope": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "recipe": { "$ref": "#/components/schemas/Recipe" } } }, "RecipeList": { "type": "object", "properties": { "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/Recipe" } } } }, "RecipeStepEnvelope": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "step": { "$ref": "#/components/schemas/RecipeStep" } } }, "RecipeStepEdited": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "step": { "$ref": "#/components/schemas/RecipeStep" }, "applied": { "type": "string", "enum": [ "active", "proposed" ], "description": "`active` changed what the step means; `proposed` is waiting on a successful run of it." } } }, "RecipeStepRemoved": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "removed": { "type": "string" }, "output": { "type": [ "object", "null" ], "description": "The step's output, by its recorded identity; null for a step that declared none.", "properties": { "name": { "type": "string" }, "state": { "type": "string", "enum": [ "exists", "deleted", "never" ], "description": "`exists`: the dataset remains; `deleted`: it was produced but has since been deleted; `never`: the step never produced one." } } }, "readers": { "type": "array", "description": "The recipe's other steps whose present reads name the output.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "label": { "type": "string" } } } }, "outputsRemain": { "type": "boolean", "description": "True only when the dataset exists." }, "message": { "type": "string" } } }, "RecipeStepDiscarded": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "step": { "$ref": "#/components/schemas/RecipeStep" }, "discarded": { "type": "boolean", "description": "Whether a pending edit was there to discard." } } }, "LayoutPosition": { "type": "object", "description": "Canvas units at the canvas's natural zoom.", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] }, "LayoutNote": { "type": "object", "description": "A layout-only annotation: no reads, no output, no state, no place in a run. Nothing in the recipe refers to it.", "properties": { "id": { "type": "string", "description": "Chosen by the writer; unique within the document." }, "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number", "description": "Positive." }, "h": { "type": "number", "description": "Positive." }, "color": { "type": "string", "enum": [ "yellow", "green", "blue", "pink", "purple", "grey" ] }, "text": { "type": "string", "description": "Markdown, at most 4,000 characters, stored verbatim. The canvas reads a `label:` line in a leading `---` block as the note's label; the API interprets nothing." } }, "required": [ "id", "x", "y", "w", "h", "color", "text" ] }, "RecipeLayoutInput": { "type": "object", "description": "The whole document. An absent map or list is the empty one.", "properties": { "steps": { "type": "object", "description": "A position per step, keyed by step id.", "maxProperties": 1000, "propertyNames": { "maxLength": 1000 }, "additionalProperties": { "$ref": "#/components/schemas/LayoutPosition" } }, "sources": { "type": "object", "description": "A position per source, keyed by table name. A source may be positioned that no step reads yet: a loose table on the canvas lives only here.", "maxProperties": 1000, "propertyNames": { "maxLength": 1000 }, "additionalProperties": { "$ref": "#/components/schemas/LayoutPosition" } }, "notes": { "type": "array", "description": "At most 100, in the writer's order.", "items": { "$ref": "#/components/schemas/LayoutNote" } } } }, "RecipeLayout": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] }, { "$ref": "#/components/schemas/RecipeLayoutInput" }, { "type": "object", "properties": { "updatedAt": { "type": [ "string", "null" ], "description": "When the document was last written; null for one never written." } } } ] }, "RecipeLayoutEnvelope": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] } ], "type": "object", "properties": { "layout": { "$ref": "#/components/schemas/RecipeLayout" } } }, "RecipeDeleted": { "type": "object", "properties": { "deleted": { "type": "string" }, "outputsRemain": { "type": "boolean", "description": "Always true: a recipe's datasets survive its deletion." }, "message": { "type": "string" } } }, "RecipeRunAttempt": { "type": "object", "description": "What became of a member's attempt: the job's state, error, times and output, composed from the live job while it is in flight — so `queued` is told from `running` — and kept with the run once it settles, so the run still says why a member failed after the node's own history is pruned. A member never attempted (`not_run`, or refused at admission) has none.", "properties": { "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "acceptedAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ] }, "output": { "type": [ "object", "null" ], "description": "Null when the caller does not reach the dataset.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } }, "RecipeRunMember": { "type": "object", "properties": { "stepId": { "type": "string" }, "ordinal": { "type": "integer" }, "operation": { "type": [ "string", "null" ], "description": "The node's operation when the run was planned, kept with the run after the node is removed." }, "name": { "type": [ "string", "null" ], "description": "The name the node was called by when the run was planned — its dataset's, or the one it declared — kept after the node is removed." }, "output": { "type": [ "object", "null" ], "description": "The dataset this member published; null until it has.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "attempt": { "oneOf": [ { "$ref": "#/components/schemas/RecipeRunAttempt" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "not_run" ], "description": "`not_run` is the member's own condition and never a job state: nothing was minted for it." }, "jobId": { "type": [ "string", "null" ], "description": "The operation run this member minted; null for `not_run`." }, "stoppedBy": { "type": [ "string", "null" ], "description": "What stopped it — the step id of the member whose failure blocked it, or a coded reason." }, "stoppedReason": { "type": [ "string", "null" ], "description": "The server's own sentence for that stop, where there is one — for a member refused before any job existed, this is the only field that names *which* input was missing or which parameter was out of range. `stoppedBy` carries a code, a blocking step id or `cancelled`, none of which a reader can act on by itself." } } }, "RecipeRun": { "type": "object", "description": "A recipe run is **not** an operation run. An operation run names exactly one output; this may produce several, none, or a mix of succeeded and never-attempted members — so it has its own outcome and *contains* runs rather than being one.", "properties": { "id": { "type": "string" }, "recipeId": { "type": "string" }, "kind": { "type": "string", "enum": [ "run_all", "from_step", "single" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "completed", "partly_completed", "failed", "cancelled", "interrupted", null ], "description": "Null while it is still going. `interrupted` is how a run the server stopped mid-flight settles — it always reaches a terminal outcome, and nothing is resumed." }, "cancelled": { "type": "boolean" }, "startedAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeRunMember" } }, "outputs": { "type": "array", "description": "Every dataset this run produced: its runner's own.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "runner": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } } }, "RecipeRunEnvelope": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/RecipeRun" } } }, "RecipeRunList": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeRun" } } } }, "RecipeRunStarted": { "type": "object", "required": [ "run", "editRevision" ], "properties": { "run": { "$ref": "#/components/schemas/RecipeRun" }, "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } } }, "RecipeRunPlan": { "type": "object", "required": [ "plan", "editRevision" ], "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "plan": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "run_all", "from_step", "single" ] }, "wide": { "type": "boolean", "description": "True when this would carry other steps with it. The `when_wide` confirmation is about exactly this." }, "members": { "type": "array", "items": { "type": "string" } } } } } }, "GeometryCrs": { "type": "object", "properties": { "stance": { "type": "string", "enum": [ "assumed", "inherent", "declared", "unknown", "conflicting" ] }, "srid": { "type": [ "integer", "null" ], "description": "Declared source SRID, or 4326 for inherent WGS84. Null when absent or unresolved." }, "label": { "type": "string", "description": "Source CRS short name for the record sentence; artifacts always hold WGS84 coordinates." } }, "required": [ "stance", "srid", "label" ] }, "GeometrySample": { "type": "object", "properties": { "rows": { "type": "integer", "minimum": 0, "maximum": 1000 }, "nonNull": { "type": "integer", "minimum": 0, "description": "Non-NULL inputs, or complete pairs, in the sampled reader rows." }, "readable": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sampled readable inputs. Null when an optional validator is unavailable, never an invented zero." } }, "required": [ "rows", "nonNull", "readable" ] }, "GeometryCandidate": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 2 }, "format": { "type": "string", "enum": [ "wkt", "geojson", "wkb", "h3", "pair" ] }, "signal": { "type": "string", "enum": [ "name", "content" ] }, "rule": { "type": "string", "enum": [ "wkt-name", "exact-pair", "prefixed-pair", "content" ] }, "crs": { "$ref": "#/components/schemas/GeometryCrs" }, "strength": { "type": "string", "enum": [ "strong", "weak" ] }, "sample": { "$ref": "#/components/schemas/GeometrySample" }, "degreeCompatible": { "type": [ "boolean", "null" ], "description": "Whether retained source coordinates fit degree ranges: full-input evidence for decoded geometry and eligible name matches, sampled evidence for numeric hints. A declared projected source may be false while its transformed output safely applies. Null for unvalidated hints." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons preventing automatic use, including partial readability, unsafe placement, CRS conflicts, unavailable H3 or numeric/axis ambiguity." }, "orientations": { "type": "array", "description": "Possible longitude/x and latitude/y roles; two entries mean ambiguous axes.", "items": { "type": "object", "properties": { "lon": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "lon", "lat" ] } }, "applied": { "type": "boolean" }, "sourceRetained": { "type": "boolean", "description": "False when a selected named-WKT source was replaced. Its original name is historical evidence, not a selectable stored column." } }, "required": [ "columns", "format", "signal", "rule", "crs", "strength", "sample", "degreeCompatible", "reasons", "applied", "sourceRetained" ] }, "GeometryRecord": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 2 }, "format": { "type": "string", "enum": [ "wkt", "geojson", "wkb", "h3", "pair" ] }, "crs": { "$ref": "#/components/schemas/GeometryCrs" }, "signal": { "type": "string", "enum": [ "name", "content", "manual" ] }, "rule": { "type": "string", "enum": [ "wkt-name", "exact-pair", "prefixed-pair", "content", "manual" ] }, "unreadableCount": { "type": "integer", "minimum": 0, "description": "Unreadable non-NULL selected inputs over the full input, not the recognition sample. Missing pair members are not unreadable." } }, "required": [ "columns", "format", "signal", "rule", "crs", "unreadableCount" ] }, "GeometryChoice": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "wkt", "geojson", "wkb", "h3", "pair" ] }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 2, "uniqueItems": true }, "epsg": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "format", "columns" ], "additionalProperties": false, "description": "One exact source column, or two distinct numeric or text-typed coordinate columns in x/y order for pair. Numeric text is read tolerantly per row on preview, first set, change and URL replay. Non-null unreadable pairs keep null geometry and are counted; either missing member is a missing input. H3 and GeoJSON forbid epsg. Omission honors declared/inherent CRS, otherwise assumes WGS84. An explicit EPSG is a user declaration; a differing existing declaration refuses. The first projection correction on native/consumed assumed geometry names the stored geometry column and its historical format (wkb without one), with epsg. No further correction is available without retained source values.", "if": { "properties": { "format": { "const": "pair" } } }, "then": { "properties": { "columns": { "minItems": 2, "maxItems": 2 } } }, "else": { "properties": { "columns": { "minItems": 1, "maxItems": 1 } } }, "not": { "properties": { "format": { "enum": [ "h3", "geojson" ] } }, "required": [ "epsg" ] } }, "GeometryRequest": { "type": "object", "properties": { "expectedRevision": { "type": "string", "minLength": 1, "description": "Opaque token binding table identity and artifact generation. Do not interpret or construct it." }, "choice": { "$ref": "#/components/schemas/GeometryChoice" } }, "required": [ "expectedRevision", "choice" ], "additionalProperties": false }, "GeometryIssue": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "projection_required", "unsupported_projection", "h3_unavailable", "unknown_crs", "conflicting_crs", "source_unavailable" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "GeometryInspection": { "type": "object", "properties": { "tableId": { "type": "string" }, "revision": { "type": "string", "minLength": 1, "description": "Opaque token binding table identity and artifact generation. Do not interpret or construct it." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false } }, "geometryColumn": { "type": [ "string", "null" ] }, "geometryRecord": { "anyOf": [ { "$ref": "#/components/schemas/GeometryRecord" }, { "type": "null" } ] }, "currentChoice": { "anyOf": [ { "$ref": "#/components/schemas/GeometryChoice" }, { "type": "null" } ], "description": "A replayable retained choice, including reconstructable automatic recognition; null for a historical consumed source. Its presence alone does not mean a manual override is stored." }, "mode": { "type": "string", "enum": [ "unmodified", "set", "cleared" ], "description": "Unmodified means no manual override. Clear removes the override; the next URL refresh resets mode to unmodified and records its fresh automatic recognition." }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/GeometryCandidate" } } }, "required": [ "tableId", "revision", "columns", "geometryColumn", "geometryRecord", "currentChoice", "mode", "candidates" ], "additionalProperties": false }, "GeometryPreview": { "type": "object", "properties": { "tableId": { "type": "string" }, "revision": { "type": "string", "minLength": 1, "description": "Opaque token binding table identity and artifact generation. Do not interpret or construct it." }, "choice": { "$ref": "#/components/schemas/GeometryChoice" }, "canApply": { "type": "boolean" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/GeometryIssue" } }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 50, "description": "Number of sampled rows, the first 50 source rows at most; not the dataset total." }, "unreadableCount": { "type": "integer", "minimum": 0, "description": "Unreadable inputs in the first 50 sampled rows, excluding missing values." }, "geometryType": { "type": [ "string", "null" ], "description": "Geometry class in the first 50 sampled rows." }, "extent": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "WGS84 bounds of the first 50 sampled rows before map simplification; null without placeable nonempty sample geometry." }, "degreeCompatible": { "type": [ "boolean", "null" ], "description": "The first 50 sampled rows' decoded nonempty source coordinates before transformation: true if every row fits degrees, false if any does not, null when none has coordinates." }, "sample": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "values": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "readable", "missing", "unreadable", "projection-required" ] } }, "required": [ "index", "values", "status" ], "additionalProperties": false }, "maxItems": 50 }, "features": { "type": "object", "properties": { "type": { "type": "string", "const": "FeatureCollection" }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "Feature" }, "id": { "type": "integer", "minimum": 0 }, "geometry": { "type": [ "object", "null" ], "additionalProperties": true }, "properties": { "type": "object", "additionalProperties": false } }, "required": [ "type", "id", "geometry", "properties" ], "additionalProperties": false }, "maxItems": 50 } }, "required": [ "type", "features" ], "additionalProperties": false } }, "required": [ "rows", "features" ], "additionalProperties": false } }, "required": [ "tableId", "revision", "choice", "canApply", "issues", "rowCount", "unreadableCount", "geometryType", "extent", "degreeCompatible", "sample" ], "additionalProperties": false }, "GeometryMutation": { "type": "object", "properties": { "table": { "$ref": "#/components/schemas/Table" }, "revision": { "type": "string", "minLength": 1, "description": "Opaque token binding table identity and artifact generation. Do not interpret or construct it." }, "currentChoice": { "anyOf": [ { "$ref": "#/components/schemas/GeometryChoice" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "unmodified", "set", "cleared" ], "description": "Unmodified means no manual override. Clear removes the override; the next URL refresh resets mode to unmodified and records its fresh automatic recognition." }, "extent": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "Full WGS84 west, south, east, north bounds; null without a placeable nonempty geometry." } }, "required": [ "table", "revision", "currentChoice", "mode", "extent" ], "additionalProperties": false }, "GeometryProjection": { "type": "object", "properties": { "epsg": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "unit": { "type": [ "string", "null" ], "enum": [ "degrees", "metres", null ] } }, "required": [ "epsg", "name", "unit" ], "additionalProperties": false }, "GeometryProjections": { "type": "object", "properties": { "projections": { "type": "array", "items": { "$ref": "#/components/schemas/GeometryProjection" } }, "resolved": { "anyOf": [ { "$ref": "#/components/schemas/GeometryProjection" }, { "type": "null" } ] } }, "required": [ "projections", "resolved" ], "additionalProperties": false }, "Table": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifiedName": { "type": "string", "description": "The name the caller would type for this dataset: its plain name when it is the caller's own, . when it is another owner's, which tells two same-named datasets apart. Present on every listing and read." }, "owner": { "$ref": "#/components/schemas/Person", "description": "The dataset's owner. Present on every listing and read." }, "sourceFilename": { "type": [ "string", "null" ], "description": "The file this table arrived as. Null for a derived table, whose output never was a file, and, to anyone but its owner, for a PostGIS snapshot, whose remote schema and table belong to its owner's connection." }, "format": { "type": "string", "enum": [ "geoparquet", "geojson", "csv", "shapefile", "geopackage", "kml" ] }, "geometryColumn": { "type": [ "string", "null" ] }, "geometryType": { "type": [ "string", "null" ] }, "geometryRecord": { "anyOf": [ { "$ref": "#/components/schemas/GeometryRecord" }, { "type": "null" } ], "description": "Applied automatic CSV recognition or a manual file/URL geometry choice. Null after clear or recognition without a choice; legacy absence is preserved until geometry is set." }, "geometryCandidates": { "type": "array", "items": { "$ref": "#/components/schemas/GeometryCandidate" }, "description": "Automatic CSV recognition evidence. Manual geometry edits clear this stored sample; GET geometry recomputes current candidates. Legacy absence is preserved until a correction." }, "crsAssumed": { "type": "boolean" }, "headerSuspect": { "type": "boolean", "description": "True when a CSV's detected column names betrayed a broken read: a name containing a comma (the header was never split), or most names numeric or blank (the first data row was taken as the header). Advisory only — the import succeeded and nothing is blocked. Always false for non-CSV sources and derived tables; a refresh recomputes it." }, "rowCount": { "type": "integer" }, "createdAt": { "type": "string" }, "source": { "type": "string", "enum": [ "upload", "url", "overture", "osm", "postgis", "operation", "sketch", "template" ], "description": "Which source created the table; \"operation\" for a table an operation produced; \"sketch\" for a table drawn on a map — its sourceParams carry mapId, mapName and layerId; \"template\" for a dataset a copy of a template made — its sourceParams carry the template's id (`template`) and the `version` it was copied from. A template's dataset is never refreshed: the copy is the caller's to change." }, "sourceParams": { "type": [ "object", "null" ], "description": "As stored for the caller's own dataset. For another owner's, null when it would name a connection (a PostGIS snapshot shows its source kind and nothing more) or a map the caller does not reach. For another owner's derived dataset, `inputs` lists only the inputs the caller reaches; its `sql` and `parameters` are as stored. Parameters that re-run the import (e.g. { url }); null for single-file uploads. Container-format tables also record { layer, group? } — the source layer and, for multi-layer imports, the shared group id; for uploads these describe provenance only, since uploads are never refreshable. For a derived table this records the operation that produced it (`operation`, the catalogue's identifier), its parameters, the SQL that ran (`sql`), its inputs by id as well as by name (`inputs`), and when it ran (`ranAt`); the inspection resolves those inputs into its own `inputs` field. A table produced by an operation that asked a **provider** carries a `disclosure` — the request it made: the endpoint's host and path (`endpoint`, null when none was recorded) and the request's other recorded facts, each operation's own — and **no `sql` at all**: its statement names a private staging path, and an absence is a better contract than a redaction that must never miss. The disclosure's endpoint is host and path only; the query string, where a key travels, is never recorded anywhere. A reader may rely on these fields as the durable provenance of the dataset: the workflow canvas's Provenance tab shows them and recomputes nothing." }, "importedAt": { "type": [ "string", "null" ], "description": "When this table's data was last produced — the import's last run, or for a derived table the run that wrote it." }, "inputs": { "type": [ "array", "null" ], "description": "For a derived table: the inputs its run recorded, resolved by the id each was recorded under. An input whose id no longer exists reads as missing — never as whatever now carries its name. Resolved within the caller's reach: the dataset's owner reads an input they no longer reach as missing, exactly as a deleted one; anyone else reads only the inputs they reach.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "The name recorded when the run happened." }, "currentName": { "type": "string", "description": "The name that id carries now, if it exists." }, "missing": { "type": "boolean" }, "nameReclaimed": { "type": "boolean", "description": "The recorded name now belongs to a different table." } } } }, "sizeBytes": { "type": [ "integer", "null" ], "description": "Size of the stored GeoParquet artifact in bytes; present on listings and inspections, null if the file is missing." }, "projectIds": { "type": "array", "items": { "type": "string" }, "description": "The projects this dataset is in that the caller reaches, and for the caller's own dataset every project it is in, one they no longer reach included (they withdraw it with PATCH /api/projects/{id}/members); empty = in no project. A dataset can be in several; the order carries no meaning." } } }, "TableList": { "type": "array", "items": { "$ref": "#/components/schemas/Table" } }, "ImportResult": { "description": "An import answer. Single-table formats answer with the created table alone. Container formats (Shapefile zip, GeoPackage, KML/KMZ) can hold several layers: the answer is then the first created table plus `tables` — every table the import created, one per spatial layer — and `skipped`, the members that did not become tables and why.", "allOf": [ { "$ref": "#/components/schemas/Table" }, { "type": "object", "properties": { "tables": { "$ref": "#/components/schemas/TableList" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "reason": { "type": "string" } } } } } } ] }, "PgConnection": { "type": "object", "description": "A saved PostGIS connection. Passwords are write-only and never appear here.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "database": { "type": "string" }, "username": { "type": "string" }, "ssl": { "type": "boolean" }, "createdAt": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "failing", "no_postgis", "not_checked_lately", "never_checked" ], "description": "Derived from the persisted last use. Connected becomes not_checked_lately at seven days." }, "lastCheckedAt": { "type": [ "string", "null" ] }, "lastCheckError": { "type": [ "string", "null" ], "description": "A credential-free failure sentence." }, "serverVersion": { "type": [ "string", "null" ] }, "postgisVersion": { "type": [ "string", "null" ], "description": "The most recently observed PostGIS version, or null when none has been observed or PostGIS was absent." } } }, "PgConnectionList": { "type": "array", "items": { "$ref": "#/components/schemas/PgConnection" } }, "TableInspection": { "allOf": [ { "$ref": "#/components/schemas/Table" }, { "type": "object", "properties": { "columns": { "$ref": "#/components/schemas/ColumnList" }, "preview": { "type": "array", "items": { "type": "object" } } } } ] }, "ColumnList": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "QueryResult": { "type": "object", "properties": { "columns": { "$ref": "#/components/schemas/ColumnList" }, "rowCount": { "type": "integer" }, "preview": { "type": "array", "items": { "type": "object" } }, "previewTruncated": { "type": "boolean" }, "runtimeMs": { "type": "integer" } } }, "LegendCorner": { "type": [ "string", "null" ], "enum": [ "top-left", "top-right", "bottom-left", "bottom-right", null ], "description": "Where the map legend sits, on the builder canvas and the published view alike. Null means bottom-left — the historical position. Overlays sharing a corner stack." }, "LegendOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The manual legend arrangement: layer ids in legend order, top first. Null means automatic — the legend follows the layer panel's top-to-bottom order. A write must list exactly the map's current layer ids (no misses, no strangers, no doubles) or null to return to automatic; anything else is rejected unchanged. Layers added later enter at the top until the next manual write." }, "BasemapAttribution": { "type": "array", "description": "The active basemap's credit lines, rendered on the builder canvas and the published view; a line with an href renders as a link.", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } }, "required": [ "label" ] } }, "CustomBasemap": { "type": [ "object", "null" ], "description": "A per-map custom basemap style: the MapLibre style URL, its optional display name, and the attribution snapshot captured server-side at save time — the credit that stays truthful when the style itself cannot be read later.", "properties": { "url": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" } }, "required": [ "url", "name", "attribution" ] }, "SanitizedIcon": { "type": "object", "description": "The custom-icon sanitizer's answer: the accepted markup (byte-identical to the input when nothing needed removing), whether anything changed, the bounded drop report, and the aspect ratio the renderer derives its raster box from.", "properties": { "svg": { "type": "string" }, "changed": { "type": "boolean" }, "dropped": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "element", "attribute", "declaration" ] }, "name": { "type": "string" } }, "required": [ "kind", "name" ] } }, "aspect": { "type": "number" } }, "required": [ "svg", "changed", "dropped", "aspect" ] }, "StyleInspection": { "type": "object", "description": "The advisory verdict on a custom basemap style URL. valid carries the style's name, layer and source counts, and normalized attribution; the other verdicts carry a worded detail. unreachable and blocked can still be saved with force — every reader's browser fetches the style itself.", "properties": { "verdict": { "type": "string", "enum": [ "valid", "not_style", "unreachable", "blocked" ] }, "name": { "type": [ "string", "null" ] }, "layerCount": { "type": "number" }, "sourceCount": { "type": "number" }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" }, "detail": { "type": "string" } }, "required": [ "verdict" ] }, "BasemapLayers": { "type": [ "object", "null" ], "description": "Per-group basemap visibility: labels, roads, borders, buildings, water, land. A missing group is visible; false hides that group on the builder canvas and the published view, on every vector basemap style — imagery (satellite) has no groups, so toggles are inert there and the imagery itself is never hidden. Null means everything is visible.", "properties": { "labels": { "type": "boolean" }, "roads": { "type": "boolean" }, "borders": { "type": "boolean" }, "buildings": { "type": "boolean" }, "water": { "type": "boolean" }, "land": { "type": "boolean" } } }, "MapNote": { "type": [ "object", "null" ], "description": "The map's one optional info box, shown in a map corner on the builder canvas and the published view. The body supports a safe formatting subset — bold, italic, links, lists, paragraphs; raw HTML renders as plain text and links open in a new tab. Null means no box.", "properties": { "title": { "type": [ "string", "null" ], "description": "Optional heading (max 120 characters)." }, "body": { "type": "string", "description": "The text (max 4,000 characters)." }, "corner": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ], "description": "Placement; defaults to top-right." } }, "required": [ "body" ] }, "Viewport": { "type": "object", "description": "The map camera: pitch 0 to 60 degrees, latitude -85.051129 to 85.051129 degrees, zoom -2 to 24, all finite and inclusive. Out-of-range submissions are refused. Accepted cameras render as stored, except coverage moves a center nearer a pole than half the canvas height toward the equator and raises zoom below log2(canvas height / 512), accounting for view padding. Older stored cameras read clamped to these bounds without a write. The viewport is one whole camera: omitted pitch and bearing store zero (flat and north-up).", "properties": { "lng": { "type": "number" }, "lat": { "type": "number", "minimum": -85.051129, "maximum": 85.051129 }, "zoom": { "type": "number", "minimum": -2, "maximum": 24 }, "pitch": { "type": "number", "minimum": 0, "maximum": 60 }, "bearing": { "type": "number", "minimum": -360, "maximum": 360 } } }, "MapTimeline": { "type": [ "object", "null" ], "description": "The map's docked playback timeline — at most one per map. It names the layer whose time filter is expanded into the map-docked widget with playback; the window itself stays that layer's timerange filter. The layer must be non-aggregated (points/heatmap draw real features; hex/grid cells are aggregated server-side and cannot animate) and must already carry a timerange filter on the field. Null means no timeline is docked.", "properties": { "layerId": { "type": "string", "description": "A layer of this map." }, "field": { "type": "string", "description": "The temporal field — must match one of the layer's timerange filters." }, "speed": { "type": "number", "description": "Sweep-speed multiplier (0.25–32); 1 crosses the extent at the base rate. Defaults to 1." } }, "required": [ "layerId", "field" ] }, "MapWidget": { "type": "object", "description": "One dashboard card: a formula (headline aggregate), category (top 5 + Other ranking; clicking a row EXCLUDES it), histogram (distribution with a brushable range), or note (authored title + body, no data). Data types are computed server-side over their layer's effective query. field is the aggregated/grouping/binned field (null for a count formula and for notes); agg is count | sum | avg | min | max (category ranking allows count | sum | avg; histogram and note ignore it — send count); aggField is the field a category sum/avg ranks by (null otherwise); unit/note/format are formula presentation (note doubles as a note widget's body); layerId is null exactly for notes.", "properties": { "id": { "type": "string", "description": "Unique within the map." }, "type": { "type": "string", "enum": [ "formula", "category", "histogram", "note" ] }, "layerId": { "type": [ "string", "null" ], "description": "The layer the widget reads — and the only layer its selection filters. Null for notes." }, "title": { "type": "string", "description": "Card heading (≤ 60)." }, "field": { "type": [ "string", "null" ] }, "agg": { "type": "string", "enum": [ "count", "sum", "avg", "min", "max" ] }, "aggField": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ], "description": "Formula: text after the number (≤ 20)." }, "note": { "type": [ "string", "null" ], "description": "Formula: caption under the number; note widget: the body (≤ 2000)." }, "format": { "type": [ "string", "null" ], "enum": [ "compact", "percent", "percent2", "integer", "decimal1", "decimal2", null ], "description": "Formula number formatting; null = automatic." }, "visible": { "type": "boolean" } }, "required": [ "id", "type", "layerId", "title", "field", "agg", "aggField", "unit", "note", "format", "visible" ] }, "WidgetList": { "type": "array", "items": { "$ref": "#/components/schemas/MapWidget" }, "description": "The map's widgets, in rail order (at most 12)." }, "WidgetSelections": { "type": "array", "description": "Ephemeral cross-filter state: at most one entry per widget — {widgetId, kind: 'exclude', values} names a category widget's DEACTIVATED categories (all categories are active by default; Other and unlisted categories stay); {widgetId, kind: 'range', min, max} is a histogram brush (null bounds are open-ended). The filtered field resolves from the stored widget, never the request. Selections live on the request and are never stored.", "items": { "type": "object", "properties": { "widgetId": { "type": "string" }, "kind": { "type": "string", "enum": [ "exclude", "range" ] }, "values": { "type": "array", "items": { "type": "string" } }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "widgetId", "kind" ] } }, "WidgetValues": { "type": "object", "description": "Batched widget values. Each entry answers for one visible widget: formula {value, baseline} (baseline = the selection-free value), category {categories: [{value, n}], other} (top 5; other is the rollup or null), histogram {domain, bins} (domain from the selection-free query so bars shrink in place). A widget whose layer is gone or whose query failed answers {id, error, errorCode} — the rest keep working, and truth surfaces key their prose on errorCode (widget_layer_missing, query_timeout, sql_error, …) while error keeps the detail. layers carries per-layer constrained/total row counts.", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "formula", "category", "histogram" ] }, "value": { "type": [ "number", "null" ] }, "baseline": { "type": [ "number", "null" ] }, "categories": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "n": { "type": "number" } } } }, "other": { "type": [ "number", "null" ] }, "domain": { "type": [ "object", "null" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "bins": { "type": "array", "items": { "type": "integer" } }, "error": { "type": "string" }, "errorCode": { "type": "string", "description": "Machine-readable reason when error is present; one of the documented error codes." } }, "required": [ "id" ] } }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layerId": { "type": "string" }, "count": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "layerId", "count", "total" ] } } }, "required": [ "widgets", "layers" ] }, "ResourceOwner": { "type": "object", "description": "A person a resource names: its owner, or the account whose SQL home it is. The display name and the SQL name, never an email.", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string", "description": "The person's SQL name, the qualifier other people's SQL uses for their datasets." } }, "required": [ "name", "sqlName" ] }, "MapPresence": { "type": "object", "description": "What every map read and listing carries beyond the stored map, the same for the caller's own maps as for maps shared with them. Never part of the published view.", "properties": { "projectId": { "type": [ "string", "null" ], "description": "The project this map is in: on the caller's own map always, a project they no longer reach included (they withdraw it with PATCH /api/projects/{id}/members), and on anyone else's the project through which the caller reaches it; null = in no project." }, "owner": { "$ref": "#/components/schemas/Person", "description": "The map's owner." }, "home": { "type": "string", "description": "The SQL name of the map's SQL home: the account whose datasets its plain table names mean, whoever reads it. Fixed at creation; duplication and transfer keep it." } }, "required": [ "projectId", "owner", "home" ] }, "MapCreated": { "allOf": [ { "$ref": "#/components/schemas/Map" }, { "$ref": "#/components/schemas/MapPresence" } ] }, "Map": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "viewport": { "$ref": "#/components/schemas/Viewport" }, "basemap": { "type": [ "string", "null" ], "description": "dark | light | streets | satellite; null is Auto — the builder follows the app theme (a deployment basemap override pins it), and published views render the deployment default." }, "customBasemap": { "$ref": "#/components/schemas/CustomBasemap", "description": "The map's custom basemap style; null = none. When set it wins over the key in every surface; the key survives underneath and returns when this clears." }, "basemapLayers": { "$ref": "#/components/schemas/BasemapLayers" }, "note": { "$ref": "#/components/schemas/MapNote", "description": "Legacy: always null — the map's old note field migrated into a note widget. Kept for pre-migration undo images." }, "legendCorner": { "$ref": "#/components/schemas/LegendCorner" }, "legendOrder": { "$ref": "#/components/schemas/LegendOrder" }, "timeline": { "$ref": "#/components/schemas/MapTimeline" }, "widgets": { "$ref": "#/components/schemas/WidgetList" }, "widgetsPublished": { "type": "boolean", "description": "Whether widgets ship with the published view." }, "publishToken": { "type": [ "string", "null" ], "description": "The published link's token, the map owner's alone: null to anyone else who reaches the map, and null while unpublished. Handing the link out is publishing, which stays the owner's act." }, "publishedAt": { "type": [ "string", "null" ] }, "published": { "type": "boolean", "description": "Whether a publication is live, for everyone who reaches the map; `publishedAt` says since when." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "MapOverview": { "allOf": [ { "$ref": "#/components/schemas/Map" }, { "type": "object", "properties": { "projectId": { "type": [ "string", "null" ], "description": "The project this map is in: on the caller's own map always, a project they no longer reach included, and on anyone else's the project through which the caller reaches it; null = in no project. Never part of the published view." }, "layerCount": { "type": "integer" }, "layerColors": { "type": "array", "items": { "type": "string" }, "description": "One representative CSS color per layer, in draw order — what the maps screen renders as layer dots." }, "pictureState": { "type": "string", "enum": [ "current", "waiting", "failed", "unsupported", "unavailable" ], "description": "The server picture work state. It names no dataset or private reason, even when this reader cannot be served the picture." }, "pictureVersion": { "type": [ "string", "null" ], "description": "An opaque version of the served picture for the image URL v parameter. Changes when a new complete picture lands, including data-only and requested refreshes. Null when no picture is served." }, "hasThumbnail": { "type": "boolean", "description": "Whether the map has a card image the caller is served: GET /api/maps/{id}/thumbnail answers one. False until the server first pictures the map, and while every image it has drew a dataset beyond the caller's reach. A card asks for the image only when this is true." }, "thumbnailBasemap": { "type": [ "object", "null" ], "description": "The basemap that card image was drawn on, recorded when the image was saved: the style's address, its kind, whether the map's own style (a library or single-map style) drew it rather than one of the instance's, and the credit it claimed then. A page of card images credits their basemaps from it, so an image keeps its credit when the map, the imagery or the instance's styles change, until the map is captured again. Null while hasThumbnail is false, and for an image that recorded none (one saved before images recorded it, or a picture of a template on Satellite, whose template names no imagery), which is credited by the map's basemap now.", "properties": { "url": { "type": "string" }, "kind": { "type": "string", "enum": [ "vector", "imagery" ] }, "custom": { "type": "boolean" }, "attribution": { "$ref": "#/components/schemas/BasemapAttribution" } }, "required": [ "url", "kind", "custom", "attribution" ] } } }, { "$ref": "#/components/schemas/MapPresence" } ] }, "MapList": { "type": "array", "items": { "$ref": "#/components/schemas/MapOverview" } }, "Project": { "type": "object", "description": "An optional named set over maps, workflows and datasets, with its member counts and size composed in. Workflows are workflow-origin recipes.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "description": "When the set itself last changed: its name, note or membership. A member's own edits do not advance it." }, "mapCount": { "type": "integer" }, "publishedMapCount": { "type": "integer" }, "recipeCount": { "type": "integer", "description": "The project's workflow-origin recipes. The field name stays `recipeCount` for wire compatibility." }, "tableCount": { "type": "integer" }, "sizeBytes": { "type": "integer", "description": "The sum of the member datasets' known artifact sizes." }, "sizeComplete": { "type": "boolean", "description": "False when a member dataset's size is unknown — the sum is partial and says so." }, "owner": { "$ref": "#/components/schemas/Person", "description": "The project's owner." }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ], "description": "How the caller stands to the project: its owner, or one of its people. A project with any role but owner is one shared with the caller." } }, "required": [ "id", "name", "note", "owner", "role", "createdAt", "updatedAt", "mapCount", "publishedMapCount", "recipeCount", "tableCount", "sizeBytes", "sizeComplete" ] }, "ProjectList": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "ProjectCreated": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "type": "object", "properties": { "revisions": { "type": "array", "description": "Resulting revisions for each affected surviving map or workflow the caller still reaches, including withdrawn filings. Empty when none remain reachable.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "map", "workflow" ] }, "id": { "type": "string" }, "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "kind", "id", "editRevision" ] } } }, "required": [ "revisions" ] } ] }, "ProjectMembersChanged": { "allOf": [ { "$ref": "#/components/schemas/ProjectMembers" }, { "type": "object", "properties": { "revisions": { "type": "array", "description": "Resulting revisions for each affected surviving map or workflow the caller still reaches, including withdrawn filings. Empty when none remain reachable.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "map", "workflow" ] }, "id": { "type": "string" }, "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "kind", "id", "editRevision" ] } } }, "required": [ "revisions" ] } ] }, "ProjectMembers": { "type": "object", "description": "A project's members, each kind in its ordinary listing shape. Project workflows are workflow-origin recipes.", "properties": { "maps": { "$ref": "#/components/schemas/MapList" }, "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/Recipe" }, "description": "The project's workflow-origin recipes; the field name stays `recipes` for wire compatibility." }, "tables": { "$ref": "#/components/schemas/TableList" } }, "required": [ "maps", "recipes", "tables" ] }, "ProjectMemberChange": { "type": "object", "description": "One atomic membership change: adds and removes together — all applied or none. Ids name existing objects; one unknown id changes nothing. Only workflows can be project members.", "properties": { "expectedRevisions": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "description": "Required for every named map and workflow, including no-op adds or removals. Keys are map: or workflow:; values are the editRevision paired with the caller’s read. Missing or malformed values answer 400; any stale value refuses the whole change with 409 stale_revision. Datasets need no revision." }, "addMaps": { "type": "array", "items": { "type": "string" } }, "removeMaps": { "type": "array", "items": { "type": "string" } }, "addRecipes": { "type": "array", "items": { "type": "string" }, "description": "Recipe ids to add. Only workflows can be project members." }, "removeRecipes": { "type": "array", "items": { "type": "string" } }, "addTables": { "type": "array", "items": { "type": "string" } }, "removeTables": { "type": "array", "items": { "type": "string" } } } }, "ProjectDeparture": { "type": "object", "additionalProperties": false, "properties": { "left": { "type": "boolean", "enum": [ true ] } }, "required": [ "left" ] }, "ProjectPerson": { "type": "object", "description": "One of a project's people: never an email or an account identity.", "properties": { "name": { "type": "string", "description": "The person's display name." }, "sqlName": { "type": "string", "description": "The person's SQL name, which names them on every sharing operation." }, "pictureVersion": { "type": "string", "description": "The version of the person's picture, present while they have one and new whenever it is replaced; absent while they have none, when their initials stand in. GET /api/accounts/{sqlName}/picture?v= reads it." }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ] }, "deactivated": { "type": "boolean", "description": "The account is deactivated: a member's grant is inert until reactivation, and the owner can remove them." } }, "required": [ "name", "sqlName", "role", "deactivated" ] }, "DirectoryPerson": { "type": "object", "additionalProperties": false, "description": "A person the directory offers: their display name, their SQL name and their picture's version, nothing else.", "properties": { "name": { "type": "string", "description": "The person's display name." }, "sqlName": { "type": "string", "description": "The person's SQL name, which names them on every sharing operation." }, "pictureVersion": { "type": "string", "description": "The version of the person's picture, present while they have one and new whenever it is replaced; absent while they have none, when their initials stand in. GET /api/accounts/{sqlName}/picture?v= reads it." } }, "required": [ "name", "sqlName" ] }, "AccountDirectory": { "type": "object", "properties": { "accounts": { "type": "array", "maxItems": 20, "description": "An exact email match first, then by display name.", "items": { "$ref": "#/components/schemas/DirectoryPerson" } } }, "required": [ "accounts" ] }, "DocumentTransfer": { "allOf": [ { "$ref": "#/components/schemas/Transfer" } ], "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Resulting revision, present only while the caller still reaches the transferred document." } } }, "Transfer": { "type": "object", "description": "A completed transfer: the resource's identity and its new owner.", "properties": { "id": { "type": "string" }, "owner": { "$ref": "#/components/schemas/Person", "description": "The new owner." } }, "required": [ "id", "owner" ] }, "ProjectPeople": { "type": "object", "properties": { "people": { "type": "array", "description": "The owner first, then the members by name.", "items": { "$ref": "#/components/schemas/ProjectPerson" } } }, "required": [ "people" ] }, "MapWithLayers": { "allOf": [ { "$ref": "#/components/schemas/Map" }, { "type": "object", "properties": { "projectId": { "type": [ "string", "null" ], "description": "The project this map is in: on the caller's own map always, a project they no longer reach included, and on anyone else's the project through which the caller reaches it; null = in no project. Detail reads carry it; the published surfaces never do." } } }, { "$ref": "#/components/schemas/MapPresence" }, { "type": "object", "properties": { "layers": { "$ref": "#/components/schemas/LayerList" } } } ] }, "MapUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "viewport": { "$ref": "#/components/schemas/Viewport" }, "basemap": { "type": [ "string", "null" ], "description": "dark | light | streets | satellite; null returns the map to Auto (follows the app theme in the builder; published views use the deployment default)." }, "customBasemap": { "type": [ "object", "null" ], "description": "Set or replace the map's custom basemap style; null removes it and reveals the stored key again. The server inspects the URL before saving: a valid style saves with its attribution snapshot; unreachable or policy-blocked URLs save only with force: true (every reader's browser fetches the style itself, so they may still work); non-style URLs never save. { libraryStyle } takes a style the instance's basemap library offers, by its id (GET /api/config lists them as basemapStyles): the map keeps its own copy of the style's name, address and credit, nothing is fetched, and hiding or removing the style later changes no map. A hidden or unknown id is refused. While the basemaps.singleMapStyles setting is off, a url the library does not offer is refused with basemap_not_offered, before it is read, unless the map already holds it.", "anyOf": [ { "required": [ "url" ] }, { "required": [ "libraryStyle" ] } ], "properties": { "libraryStyle": { "type": "string", "description": "A basemap library style's id; given alone, without url, name or force." }, "url": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "Display name for the picker tile; absent shows the URL's hostname." }, "force": { "type": "boolean", "description": "Save despite an unreachable or blocked verdict." } } }, "basemapLayers": { "$ref": "#/components/schemas/BasemapLayers" }, "legendCorner": { "$ref": "#/components/schemas/LegendCorner" }, "legendOrder": { "$ref": "#/components/schemas/LegendOrder" }, "timeline": { "$ref": "#/components/schemas/MapTimeline" }, "widgets": { "$ref": "#/components/schemas/WidgetList" }, "widgetsPublished": { "type": "boolean", "description": "Whether widgets ship with the published view. A publication setting: only the map's owner changes it, and anyone else's write that would change it is refused whole with forbidden." }, "layerOrder": { "type": "array", "items": { "type": "string" }, "description": "All the map's layer ids, bottom to top — the draw order." } } }, "HistoryTarget": { "type": [ "object", "null" ], "properties": { "eligible": { "type": "boolean", "description": "Whether the caller may replay the entire target under current edit, SQL and publication rules." }, "reason": { "type": [ "string", "null" ], "description": "The refusal reason, or null when eligible." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "map", "layer" ] }, "targetId": { "type": "string" }, "op": { "type": "string", "enum": [ "add", "update", "delete" ] }, "createdAt": { "type": "string", "format": "date-time" }, "author": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "scope", "targetId", "op", "author", "createdAt" ] } } }, "required": [ "eligible", "reason", "steps" ] }, "History": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "description": "Undo/redo availability on the map's timeline.", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "canUndo": { "type": "boolean" }, "canRedo": { "type": "boolean" }, "undoTarget": { "$ref": "#/components/schemas/HistoryTarget" }, "redoTarget": { "$ref": "#/components/schemas/HistoryTarget" } }, "required": [ "canUndo", "canRedo", "undoTarget", "redoTarget" ] }, "MapWithHistory": { "allOf": [ { "$ref": "#/components/schemas/MapWithLayers" }, { "type": "object", "properties": { "history": { "$ref": "#/components/schemas/History" } }, "required": [ "history" ] } ] }, "FillPaint": { "type": "object", "description": "A color paint, serving the fill and the data-driven outline: {type: 'constant', color} · categorical {attribute, palette, map: [{value, color}], other} · ramp {type: 'quantile', attribute, palette, method: quantile|equal|natural|custom, breaks, colors, optional classes} (breaks strictly ascending, one fewer than colors) · continuous {type: 'continuous', attribute, palette, domain: [low, high], stops, optional clamp: [low, high], log, center, positions, reversed} (values interpolate smoothly along the stops over the domain; clamp narrows the effective domain, values outside take the end colors; log needs a strictly positive effective domain; center splits the ramp for diverging reads and starts at the mean when a diverging palette is applied). Colors are {r, g, b, a}. Computed breaks come back as nice rounded values. To set custom class boundaries, write the ramp with method: 'custom', your breaks, and baseMethod naming the method they derived from (quantile|equal|natural) — a later class-count change recomputes from it. When a low-cardinality result can realize fewer visible classes, classes remembers the requested count.", "properties": { "type": { "type": "string" } } }, "CustomPalette": { "type": "object", "description": "A saved custom palette: a named gradient of ordered color stops, instance-global, usable wherever palettes are offered (continuous and classified). Styles reference it by name but bake resolved colors in, so deleting a palette never breaks a map that used it.", "properties": { "name": { "type": "string", "description": "Stable id, assigned on save; use as `palette`." }, "label": { "type": "string", "maxLength": 60 }, "stops": { "type": "array", "minItems": 2, "maxItems": 16, "items": { "type": "object", "properties": { "color": { "type": "string", "description": "#rrggbb" }, "position": { "type": "number", "minimum": 0, "maximum": 1, "description": "0–1, non-decreasing across the stops." } }, "required": [ "color", "position" ] } } }, "required": [ "name", "label", "stops" ] }, "PaletteOffer": { "type": "object", "description": "Everything the palette picker offers: the curated catalogue and the saved custom palettes.", "properties": { "curated": { "type": "array", "items": { "type": "object" } }, "custom": { "type": "array", "items": { "$ref": "#/components/schemas/CustomPalette" } } }, "required": [ "curated", "custom" ] }, "SizeScale": { "type": "object", "description": "Numeric attribute → pixel-size mapping. `domain` is the attribute's value range (low, high) over the effective result, resolved server-side; `range` is the output in pixels (smallest, largest). Point radius maps area-honestly (square root of the value); line width maps linearly. Features with a missing or non-numeric value draw at the smallest size.", "properties": { "attribute": { "type": "string" }, "domain": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "attribute", "domain", "range" ] }, "Aggregate": { "type": "object", "description": "What each cell shows: {fn: 'count'}, or {fn: 'sum' | 'avg' | 'min' | 'max', attribute} over a numeric attribute.", "properties": { "fn": { "type": "string", "enum": [ "count", "sum", "avg", "min", "max" ] }, "attribute": { "type": "string" } }, "required": [ "fn" ] }, "Viz": { "type": "object", "description": "How the layer's result is drawn. `points` (default) draws the raw features. `hexbin` and `grid` aggregate points into cells server-side — results beyond the render cap stay renderable; cells expose `value` and `count`, colored by the viz `fill` (assigned automatically when omitted). `heatmap` draws point density. `arc` and `line` draw each row as an origin→destination pair from the mapped endpoints — arc as a curved swing with an adjustable height, line straight; the path's source color and width ride the style's stroke channels, and `targetColor` blends toward the destination. `icon` draws points as a glyph from the curated bundled set — size rides the style's point-radius channel, color its fill channel, fixed or by attribute. `cluster` aggregates points client-side into count-labeled bubbles by a pixel radius; zooming in dissolves them; clicking a bubble zooms toward where it breaks apart. Non-point layers keep simple rendering. hexbin/grid may carry `elevation`: cells extrude by an aggregate — count, or a function over a numeric field — so color and height can encode different things; the aggregate's range is resolved server-side and maps linearly onto [0, height] meters. Absent = flat, exactly as before.", "properties": { "type": { "type": "string", "enum": [ "points", "hexbin", "grid", "heatmap", "arc", "line", "icon", "cluster" ] }, "cellKm": { "type": "number", "description": "hexbin/grid: cell edge length in **web-mercator** kilometres — a length on the map projection, not a ground distance. Web mercator stretches by 1/cos(latitude), so a 1.2 km cell covers about 730 m of ground at 52°N and about 410 m at 70°N. Any value 0.02-1000 (hexbin: hexagon edge; grid: square edge). Every other distance in this API — a buffer radius, a measured length — is ground metres." }, "aggregate": { "$ref": "#/components/schemas/Aggregate" }, "fill": { "$ref": "#/components/schemas/FillPaint" }, "elevation": { "type": "object", "description": "hexbin/grid cell extrusion. height = the tallest prism in meters (100-20000); domain is resolved server-side — send aggregate and height only.", "properties": { "aggregate": { "$ref": "#/components/schemas/Aggregate" }, "height": { "type": "number", "minimum": 100, "maximum": 20000 }, "domain": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } }, "required": [ "aggregate", "height" ] }, "radiusPx": { "type": "number", "description": "heatmap: kernel radius in pixels (1-200). cluster: clustering radius in pixels (20-120)." }, "intensity": { "type": "number", "description": "heatmap: intensity multiplier (0.1-10)." }, "weight": { "type": [ "string", "null" ], "description": "heatmap: numeric attribute weighting each point; null = 1." }, "origin": { "$ref": "#/components/schemas/OdEndpoint" }, "dest": { "$ref": "#/components/schemas/OdEndpoint" }, "height": { "type": "number", "description": "arc: swing relative to the endpoint distance (0.1-2)." }, "targetColor": { "type": "object", "description": "arc/line: destination end of the color gradient as {r, g, b, a}; omit for one fixed color." }, "glyph": { "type": "string", "description": "icon: the glyph name from the curated Maki subset (e.g. 'cafe', 'parking', 'marker')." }, "customSvg": { "type": [ "string", "null" ], "description": "icon: sanitized custom SVG markup; when present it wins over the glyph, tinted by the fill channel like any glyph. Writes pass through the sanitizer — scripts, event handlers and references are stripped and reported (preview via /api/icons/sanitize); not-SVG, oversize (256 KB), and nothing-drawable inputs answer invalid_request. Null clears back to the glyph." }, "color": { "description": "cluster: 'fixed' paints the style's fill color; an Aggregate ({fn} or {fn, attribute}) colors bubbles on a sequential ramp over the current view's values." }, "showCounts": { "type": "boolean", "description": "cluster: draw the count label on each bubble." } }, "required": [ "type" ] }, "OdEndpoint": { "type": [ "object", "null" ], "description": "One arc/line endpoint: a geometry column of the layer's result ({kind: 'geometry', field}) or a pair of numeric longitude/latitude columns ({kind: 'lonlat', lon, lat}). Null = not yet mapped; the layer asks instead of rendering. The fields endpoint lists `geometryColumns`; numeric columns come from `filterable`.", "properties": { "kind": { "type": "string", "enum": [ "geometry", "lonlat" ] }, "field": { "type": "string" }, "lon": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "kind" ] }, "LayerFilter": { "type": "object", "description": "A structured refinement of the layer's result, applied before aggregation. Range: {field, kind: 'range', min, max} (numbers; a null bound is open-ended). Time range: {field, kind: 'timerange', min, max} (ISO-8601 strings, e.g. '2021-03-01' or '2021-03-01T08:30:00'; for date/timestamp fields). Value set: {field, kind: 'values', values} (an empty set matches nothing); with exclude: true the set inverts — keep everything EXCEPT these values (NULL rows drop, as SQL's NOT IN decides).", "properties": { "field": { "type": "string" }, "kind": { "type": "string", "enum": [ "range", "timerange", "values" ] }, "exclude": { "type": "boolean", "description": "values kind only: invert the set." }, "min": { "type": [ "number", "string", "null" ], "description": "Number for range, ISO-8601 string for timerange." }, "max": { "type": [ "number", "string", "null" ], "description": "Number for range, ISO-8601 string for timerange." }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "field", "kind" ] }, "FieldStats": { "type": "object", "description": "A field's extent and distribution (numeric and time fields) or distinct values (text; bounded, by frequency), for seeding filter controls and the ramp's distribution. Time extents are ISO-8601 strings. On an aggregated (hex/grid) layer, `value` and `count` answer over the effective query — the same values classification sees.", "properties": { "field": { "type": "string" }, "kind": { "type": "string", "enum": [ "numeric", "time", "text" ] }, "numeric": { "type": "boolean" }, "min": { "type": [ "number", "string", "null" ], "description": "Number for numeric, ISO-8601 string for time." }, "max": { "type": [ "number", "string", "null" ], "description": "Number for numeric, ISO-8601 string for time." }, "mean": { "type": [ "number", "null" ], "description": "Arithmetic mean; numeric fields only." }, "bins": { "type": "array", "items": { "type": "integer" }, "description": "Row counts over equal bins across [min, max] — the distribution histogram behind a range brush. Empty when the extent is missing or a single value." }, "values": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } }, "required": [ "field", "kind", "numeric" ] }, "Style": { "type": "object", "additionalProperties": false, "description": "A layer's full visual definition. Constant channels plus data-driven ones: `strokeBy` drives the outline color like `fill` drives the fill; `pointRadiusBy` and `strokeWidthBy` drive the sizes. Absent data-driven members mean the constant siblings apply.", "properties": { "fill": { "$ref": "#/components/schemas/FillPaint" }, "fillOpacity": { "type": "number", "description": "0-1 fill translucency; 1 = opaque. Colors are solid — the sliders own alpha. Default 1." }, "stroke": { "type": "object", "description": "Constant outline color {r, g, b, a}." }, "strokeOpacity": { "type": "number", "description": "0-1 multiplier on the stroke alpha. Default 1." }, "strokeWidth": { "type": "number" }, "pointRadius": { "type": "number" }, "opacity": { "type": "number" }, "strokeBy": { "$ref": "#/components/schemas/FillPaint", "description": "Data-driven outline color; overrides `stroke` when present." }, "pointRadiusBy": { "$ref": "#/components/schemas/SizeScale", "description": "Data-driven point radius; overrides `pointRadius`." }, "strokeWidthBy": { "$ref": "#/components/schemas/SizeScale", "description": "Data-driven line/outline width; overrides `strokeWidth`." }, "heightBy": { "$ref": "#/components/schemas/SizeScale", "description": "Polygon extrusion by attribute: the domain maps linearly onto meters (range up to 100000; resolve with the scale operation, unit 'm'). Omit for flat." }, "label": { "type": "object", "description": "Text labels on the layer; omit for none. On a simple-feature layer set `attribute` to the column whose value labels each feature (points at the point, lines and polygons at an interior anchor). On an aggregated hex/grid layer omit `attribute` — each cell labels itself with its aggregate value, compactly formatted. Heatmaps cannot be labeled.", "properties": { "attribute": { "type": "string", "description": "Label source column; omit on aggregated layers." }, "size": { "type": "number", "description": "Text size, 1-72; 12 is a good default. On simple layers this is screen pixels. On hex/grid layers it scales the label's proportion of its cell — cell labels zoom with the map, like the cells themselves." }, "color": { "type": "object", "description": "Text color {r, g, b, a}. Pick against the basemap: white reads well on dark styles and imagery, a dark color on light styles." }, "haloWidth": { "type": "number", "description": "Halo rim behind the text, 0 (none) to 3 (widest). Replaced the legacy `halo` boolean: stored maps migrate on read; writes stating the boolean answer invalid_request." }, "haloColor": { "type": "object", "description": "Halo color {r, g, b, a}." }, "weight": { "type": "string", "enum": [ "normal", "bold" ], "description": "Absent = normal." }, "anchor": { "type": "string", "description": "One of the nine compass positions plus center, relative to the feature's anchor point; absent = center." }, "offsetX": { "type": "number", "description": "Pixels, -50 to 50; +x right. Absent = 0." }, "offsetY": { "type": "number", "description": "Pixels, -50 to 50; +y down. Absent = 0." }, "rotation": { "type": "number", "description": "Degrees, -180 to 180, counter-clockwise positive. Absent = 0." }, "textCase": { "type": "string", "enum": [ "as-is", "upper", "lower" ], "description": "Applied before truncation. Absent = as-is." }, "maxChars": { "type": [ "number", "null" ], "description": "Truncate to N code points with an ellipsis (not counted), 1 to 80; null/absent = no truncation." }, "density": { "type": "number", "description": "Collision-culling density, 0 sparse to 1 dense; absent = 0.5. Table-backed layers only — tiled layers are exempt from thinning." }, "zoomFloor": { "type": [ "number", "null" ], "description": "Show labels from this whole zoom level (0-24); null/absent = no floor." }, "priorityField": { "type": [ "string", "null" ], "description": "Numeric column ranking which labels survive the cap and collisions (higher wins; nulls last); null/absent = stable feature order. Published maps carry the column's values." }, "cap": { "type": [ "number", "null" ], "description": "Draw at most N labels (1-10000), after ranking; null/absent = no cap." } }, "required": [ "size", "color", "haloWidth", "haloColor" ] } } }, "Layer": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string" }, "mapId": { "type": "string" }, "name": { "type": "string" }, "sql": { "type": "string", "description": "Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail." }, "style": { "$ref": "#/components/schemas/Style" }, "visible": { "type": "boolean" }, "tooltip": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Fields shown in the hover tooltip; null = automatic." }, "popup": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Fields shown in the click pop-up; null = automatic." }, "publishedFields": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The author's explicit published-field list; null = the derived minimal projection (style, label, tooltip/pop-up, live-filter, timeline and published-widget fields). Published responses carry exactly the effective set; fields the published map needs to render are always published, whatever this lists." }, "inLegend": { "type": "boolean", "description": "Whether the layer contributes to the legend." }, "viz": { "$ref": "#/components/schemas/Viz" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/LayerFilter" }, "description": "Refinements applied before aggregation; the SQL stays the source of truth and [] restores it exactly." }, "legendTitle": { "type": [ "string", "null" ], "description": "Legend title override; null = the layer name." }, "legendLabels": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Per-entry legend label overrides; null entries (and null itself) keep the automatic labels." }, "legendAttrs": { "type": [ "object", "null" ], "description": "Per-channel legend attribute-name overrides, keyed by channel (fill, stroke, radius, width). Three states per channel: a missing key (and null itself) keeps the automatic attribute name, a string overrides it, and a null value hides that channel's attribute line. An override drops automatically when its channel's driving attribute changes." }, "ordinal": { "type": "integer" } } }, "LayerList": { "type": "array", "items": { "$ref": "#/components/schemas/Layer" } }, "LayerCreate": { "type": "object", "properties": { "name": { "type": "string" }, "sql": { "type": "string", "description": "Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail." }, "style": { "$ref": "#/components/schemas/Style" }, "writtenIn": { "$ref": "#/components/schemas/WrittenIn", "description": "Where sql was written, when not in this map: the caller's console (a dataset's \"Add to a map\" too), another map or a workflow. The SQL is carried into this map's SQL home and the layer stores the carried text. Each dataset reference keeps the dataset it meant where it was written: a plain name of a dataset the destination's SQL home does not own, or whose name an output there takes, becomes .; an already qualified name stays as written; a workflow's own output becomes the dataset the caller's latest successful run of it made. Only those references change; the rest of the text is kept as written, and nothing where it came from is touched. A reference that cannot be carried (a dataset outside the caller's reach, an output the caller has not produced, a computed table name that would have to change) refuses the request with sql_error naming it, and nothing is written. Omitted, the SQL is this map's own, read in its home as every saved layer is." } }, "required": [ "sql" ] }, "LayerUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "sql": { "type": "string", "description": "Only one read-only SELECT over named datasets is accepted. File readers, file-relation shorthand and engine path or definition discovery are refused before binding with sql_rejected, including nested SQL and computed targets. File-referencing PROJ coordinate definitions are also refused before native projection use, including computed or per-row values; EPSG identifiers and inline definitions without files remain supported. Unknown tables receive the same sql_error whether hidden or nonexistent, without catalogue suggestions. Engine errors do not expose filesystem paths or internal statements; input positions are retained when available. Existing saved SQL is retained unchanged; affected saved and published queries fail." }, "style": { "$ref": "#/components/schemas/Style" }, "visible": { "type": "boolean" }, "tooltip": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 32, "description": "Fields shown in the hover tooltip (up to 32, each an existing result column); null = automatic." }, "popup": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 32, "description": "Fields shown in the click pop-up (up to 32, each an existing result column); null = automatic. Independent of tooltip — a tooltip often wants one field, a pop-up several." }, "publishedFields": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 32, "description": "Explicit published-field list (up to 32, each an existing result column); null restores the derived minimal projection. The functional core — fields the published map needs to render, label, filter and cross-filter — publishes regardless of this list. A publication setting: only the map's owner changes it, and anyone else's write that would change it is refused whole with forbidden." }, "inLegend": { "type": "boolean" }, "viz": { "$ref": "#/components/schemas/Viz" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/LayerFilter" } }, "legendTitle": { "type": [ "string", "null" ] }, "legendLabels": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] } }, "legendAttrs": { "type": [ "object", "null" ], "description": "Per-channel legend attribute-name overrides (fill, stroke, radius, width → short string, or null to hide that channel's attribute line); null = all automatic." } } }, "PublishedFieldsStatement": { "type": "object", "description": "Per-layer statement of the effective published field set.", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layerId": { "type": "string" }, "name": { "type": "string" }, "hidden": { "type": "boolean", "description": "A hidden layer shares nothing — it is absent from the published surface entirely; its statement carries an empty field set." }, "mode": { "type": "string", "enum": [ "derived", "list" ], "description": "derived = the minimal projection; list = the author's explicit published-field list." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean", "description": "The published map cannot render without it; no list can remove it." } } } }, "available": { "type": "array", "items": { "type": "string" }, "description": "Every field an explicit list could name. Empty on aggregated layers, whose computed columns are the whole wire." }, "list": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The author's raw explicit list, verbatim (null = derived). Editors write against this, never against the effective set." }, "error": { "type": "string", "description": "Present when this layer's fields cannot be resolved; the other layers still answer." } } } } } }, "LayerRender": { "type": "object", "properties": { "layerId": { "type": "string" }, "ok": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "inline", "tiled" ], "description": "inline carries the GeoJSON itself; tiled points at served vector tiles (a points-viz result over the render cap or Bytes drawn per layer)." }, "geojson": { "type": "object", "description": "Inline GeoJSON. Feature properties are the columns the audience reads: on a builder render, what the layer and its map use; on a published render, the effective published field set. Non-point features carry a reserved __anchor property — an interior [lng, lat] that labels anchor on; it never shows in tooltips or pop-ups." }, "featureCount": { "type": "integer" }, "geometryType": { "type": [ "string", "null" ], "enum": [ "POINT", "LINESTRING", "POLYGON", "MIXED", null ], "description": "Canonical geometry family of the effective render result, independent of inline or tiled delivery. Multi-geometry variants collapse into their simple family; null means the result is empty or its family is unknown." }, "tiles": { "$ref": "#/components/schemas/LayerTiles" }, "liveFiltered": { "type": "boolean", "description": "True when the data ships without the layer's live filters (range/time filters on non-aggregated layers) — the builder canvas enforces them client-side, so slider and playback moves never refetch. Absent when every filter is already applied in the SQL." }, "error": { "type": "object", "description": "Present when ok is false: why the layer cannot render right now. code is one of the documented error codes (query_timeout, sql_error, render_cap_exceeded, render_bytes_exceeded, tiler_unavailable, tile_build_failed, …) and is what truth surfaces present; message carries the detail. Both builder and published viewer show an errored layer as a visible failed state, never as silent absence.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "SliderPreviewData": { "type": "object", "description": "Bounded point input for transient builder slider previews. `exact` is false when `geojson` is a stable subset of the source rows. This response is never durable layer state.", "properties": { "layerId": { "type": "string" }, "exact": { "type": "boolean" }, "sourceCount": { "type": "integer" }, "sampledCount": { "type": "integer" }, "budget": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "numeric", "time", "text" ] } }, "required": [ "name", "kind" ] } }, "geojson": { "type": "object" } }, "required": [ "layerId", "exact", "sourceCount", "sampledCount", "budget", "fields", "geojson" ] }, "LayerTiles": { "type": "object", "description": "How a tiled layer stands. While `building`, poll the render endpoint. When `ready`, `url` is a {z}/{x}/{y} tile URL template (with a cache-busting version parameter), and bounds ([west, south, east, north]) with the zoom range describe the archive. A failed build reports as an errored layer instead.", "properties": { "state": { "type": "string", "enum": [ "building", "ready" ] }, "url": { "type": "string" }, "bounds": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 }, "minZoom": { "type": "integer" }, "maxZoom": { "type": "integer" }, "builtAt": { "type": "string" } }, "required": [ "state" ] }, "FieldList": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "numeric": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "numeric", "time", "text" ], "description": "The field's family: numeric, time (date/timestamp columns), or text. Decides the matching filter kind." } } } }, "LayerFields": { "type": "object", "properties": { "styling": { "$ref": "#/components/schemas/FieldList" }, "filterable": { "$ref": "#/components/schemas/FieldList" }, "geometryColumns": { "type": "array", "items": { "type": "string" }, "description": "Geometry columns of the layer's own SQL result, in SELECT order — what arc/line endpoints can map to." } } }, "LayerExtent": { "type": "object", "description": "A layer's current data extent. `empty` is a distinct outcome from a failure: filtering everything away is a normal thing to do.", "properties": { "kind": { "type": "string", "enum": [ "extent", "empty" ] }, "box": { "type": "array", "items": { "type": "number" }, "description": "[west, south, east, north]; absent when empty." } } }, "EditRevisionResult": { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." } }, "required": [ "editRevision" ] }, "PublishState": { "allOf": [ { "type": "object", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "editRevision", "lastChangedAt", "lastChangedBy" ] } ], "type": "object", "properties": { "token": { "type": "string" }, "publishedAt": { "type": "string" } } }, "ViewerControls": { "type": "object", "description": "Which optional reader controls a publication exposes. Zoom and point-north are never listed: a published map a reader cannot navigate reads as broken, so they are not the author's to remove. Every member defaults to true.", "properties": { "tilt": { "type": "boolean", "description": "The 3D tilt toggle." }, "fit": { "type": "boolean", "description": "The fit-to-data button." }, "theme": { "type": "boolean", "description": "The reader's light/dark toggle." }, "basemap": { "type": "boolean", "description": "The basemap picker." }, "coords": { "type": "boolean", "description": "The cursor coordinate readout in the attribution strip." } } }, "PublicationState": { "type": "object", "description": "An active publication's authored settings.", "properties": { "editRevision": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Opaque durable revision paired with this document state. Camera and derived writes do not change it." }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last accepted covered change, independent of camera and cache clocks." }, "lastChangedBy": { "description": "A named actor has display and fixed SQL names. { deleted: true } explicitly identifies a deleted actor and carries no names or profile fields. Null explicitly means unknown. Never inferred from ownership.", "oneOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "sqlName": { "type": "string" } }, "required": [ "name", "sqlName" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false }, { "type": "null" } ] }, "token": { "type": "string", "description": "The published link's token, the map owner's alone: absent for anyone else who reaches the map." }, "publishedAt": { "type": "string" }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "viewerControls": { "$ref": "#/components/schemas/ViewerControls" } } }, "PublishedView": { "type": "object", "properties": { "name": { "type": "string" }, "viewport": { "$ref": "#/components/schemas/Viewport" }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "The authored default theme: the mode the publisher stated or was composing in when the map was published. Publications made before this field existed read dark until published anew. A reader may switch locally for the current page load only (the remembered per-link override was retired); the switch never changes this value, and the next load starts from it again." }, "basemapUrl": { "type": "string", "description": "Resolved basemap style URL for the authored theme — the published page's first render uses exactly this." }, "basemapForTheme": { "type": [ "object", "null" ], "description": "Non-null when the basemap follows the effective theme (a genuine Auto with no deployment override): the style URL for each mode (`light`, `dark`), so a reader theme switch swaps styles without another round trip. Null for an explicit basemap or an overridden Auto. In the builder every explicit basemap stays fixed in both themes; on the published viewer the Dark and Light styles are excepted, and the reader's theme control moves them as a pair — they are the two modes. Streets and Satellite stay fixed there too." }, "basemapKey": { "type": [ "string", "null" ], "enum": [ "dark", "light", "streets", "satellite", null ], "description": "The authored basemap choice; null = Auto. The reader's picker marks its card from this and resolves a return to Auto — the resolved URL alone cannot say whether Auto or an explicit style sharing that URL was authored. Note the published Dark/Light exception described on `basemapForTheme`: a reader's theme control moves those two as a pair." }, "customBasemap": { "$ref": "#/components/schemas/CustomBasemap", "description": "The map's custom basemap style; null = none. When set, basemapUrl is its URL in both themes, the attribution is its saved snapshot, and the reader's picker marks no built-in card — a reader who switches to one has no way back within the load." }, "basemapPinned": { "type": "boolean", "description": "Whether this deployment pins Auto in both themes. A reader's theme switch leaves a pinned Auto alone; an explicit reader pick still applies for that page load." }, "basemapKind": { "type": "string", "enum": [ "vector", "imagery" ], "description": "The resolved style's kind — group toggles act on vector styles only." }, "basemapAttribution": { "$ref": "#/components/schemas/BasemapAttribution" }, "basemapLayers": { "$ref": "#/components/schemas/BasemapLayers" }, "note": { "$ref": "#/components/schemas/MapNote" }, "legendCorner": { "$ref": "#/components/schemas/LegendCorner" }, "legendOrder": { "$ref": "#/components/schemas/LegendOrder" }, "timeline": { "type": [ "object", "null" ], "description": "The docked playback timeline, resolved for the viewer: layerId, field, speed, the settled window, the field's full extent (ISO-8601), and its histogram bins. Null when no timeline is docked or the dock no longer resolves." }, "layers": { "type": "array", "items": { "type": "object" }, "description": "Each layer carries its style, render data, and `liveFilters`: resolved range/time filters the render shipped without — the viewer enforces their settled ranges client-side." }, "widgets": { "$ref": "#/components/schemas/WidgetList", "description": "The map's visible widgets, present when the map ships widgets — the viewer reads values through the published widget-values call. Empty when the toggle is off or no widget resolves." }, "viewerControls": { "$ref": "#/components/schemas/ViewerControls", "description": "Which optional reader controls this publication exposes. A publication that never stated a set reports every control on." } } }, "TableCatalogue": { "type": "object", "required": [ "tables", "total", "nextAfter" ], "properties": { "total": { "type": "integer" }, "nextAfter": { "type": [ "string", "null" ] }, "tables": { "type": "array", "maxItems": 32, "items": { "type": "object", "required": [ "id", "name", "qualifiedName", "owner", "projectIds", "rowCount", "geometryColumn", "geometryType", "crsAssumed", "columns", "columnCount", "nextColumnOffset" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifiedName": { "type": "string", "description": "The name the caller would type: the plain name for the caller's own dataset, . for another owner's." }, "owner": { "$ref": "#/components/schemas/Person" }, "projectIds": { "type": "array", "items": { "type": "string" }, "description": "The projects this dataset is filed in that the caller owns or belongs to, and for the caller's own dataset every project it is filed in, one they no longer reach included (they withdraw it with PATCH /api/projects/{id}/members); never another person's membership in a project the caller does not reach. Identities only; the projects listing names those the caller reaches." }, "rowCount": { "type": "integer" }, "geometryColumn": { "type": [ "string", "null" ] }, "geometryType": { "type": [ "string", "null" ] }, "crsAssumed": { "type": "boolean" }, "columnCount": { "type": "integer" }, "nextColumnOffset": { "type": [ "integer", "null" ] }, "columns": { "type": "array", "maxItems": 64, "items": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } } } } } }, "AssistantContext": { "description": "Optional page grounding, at most 64 KiB of UTF-8 JSON. Omission makes no page claim. Unknown fields, malformed snapshots and incompatible object ownership refuse before work with assistant_context_invalid; oversized context answers 413 assistant_context_too_large. Server-owned identities are checked against this instance. SQL is an exact browser-submitted snapshot, not a draft write, execution or approval. A table preview is not a last execution.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "page", "mapId", "selectedLayerId" ], "properties": { "page": { "const": "builder" }, "mapId": { "type": "string", "minLength": 1 }, "selectedLayerId": { "type": [ "string", "null" ], "minLength": 1 }, "appearance": { "type": "string", "enum": [ "light", "dark" ], "description": "The builder's resolved theme, so an automatic map check renders the appearance the person is looking at. Absent means light." } } }, { "type": "object", "additionalProperties": false, "properties": { "page": { "const": "sql" }, "draft": { "type": "string" }, "selection": { "type": [ "string", "null" ] }, "lastExecution": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "sql": { "type": "string" }, "result": { "$ref": "#/components/schemas/AssistantSqlResultSummary" } }, "required": [ "sql", "result" ] }, { "type": "object", "additionalProperties": false, "properties": { "sql": { "type": "string" }, "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "sql", "error" ] } ] } }, "required": [ "page", "draft", "selection", "lastExecution" ] }, { "type": "object", "additionalProperties": false, "properties": { "page": { "const": "workflow" }, "recipeId": { "type": "string", "minLength": 1 }, "selectedStepId": { "type": [ "string", "null" ], "minLength": 1 }, "lastRunId": { "type": [ "string", "null" ], "minLength": 1 } }, "required": [ "page", "recipeId", "selectedStepId", "lastRunId" ] } ] }, "AssistantSqlResultSummary": { "type": "object", "additionalProperties": false, "properties": { "totalRows": { "type": "integer", "minimum": 0 }, "returnedRows": { "type": "integer", "minimum": 0 }, "truncated": { "type": "boolean" }, "columns": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } }, "elapsedMs": { "type": "number", "minimum": 0 } }, "required": [ "totalRows", "returnedRows", "truncated", "columns", "elapsedMs" ], "description": "The result of this exact executed SQL. Returned rows cannot exceed total rows. No row samples are submitted as automatic grounding." }, "AssistantEffects": { "type": "object", "required": [ "readOnly", "writes" ], "properties": { "readOnly": { "type": "boolean" }, "writes": { "type": "array", "items": { "type": "object", "required": [ "resource", "ids", "collection" ], "properties": { "resource": { "type": "string", "enum": [ "maps", "layers", "tables", "publications", "recipes", "runs", "projects", "connections", "palettes", "settings", "caches", "basemaps", "templates", "assistant" ] }, "ids": { "type": "array", "items": { "type": "string" } }, "collection": { "type": "boolean", "description": "True when a narrower identity cannot be established." } } } } } }, "AssistantConfirmation": { "type": "object", "required": [ "target", "consequence" ], "properties": { "target": { "type": "string" }, "consequence": { "type": "string" } } }, "AssistantSubject": { "type": "object", "required": [ "resource" ], "description": "The subject of an action as resolved when it happened: its resource, its identity when the call or response named one, and its display name when one was carried. A later rename or deletion does not change it.", "properties": { "resource": { "type": "string", "enum": [ "maps", "layers", "tables", "publications", "recipes", "runs", "projects", "connections", "palettes", "settings", "caches", "basemaps", "templates", "assistant" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "AssistantHistory": { "type": "object", "required": [ "mapId", "group" ], "description": "Where a change qualifies for a map's history: the map and the change group the turn stamped. A turn may touch several maps and a manual edit during a pause splits its steps, so a group is the turn's marker, never a claim that it is one currently undoable step.", "properties": { "mapId": { "type": "string" }, "group": { "type": "string" } } }, "AssistantObservation": { "type": "object", "required": [ "state" ], "description": "The observation attached to a map check: a separate fact recorded when the model's subsequent text arrived, never a change to the check's outcome. awaited: the check settled and the text has not come; captured: text holds the first subsequent sentence, at most 240 characters cut at a word boundary, and at is where in the run's text it begins; silent: the turn completed with no subsequent text; interrupted: no text will come, reason says why (cancelled, exhausted, failed); unavailable: the terminal compaction dropped the detail. Absence of this object on a check that did not succeed means the check produced no image.", "properties": { "state": { "type": "string", "enum": [ "awaited", "captured", "silent", "interrupted", "unavailable" ] }, "text": { "type": "string" }, "at": { "type": "integer", "minimum": 0 }, "reason": { "type": "string", "enum": [ "cancelled", "exhausted", "failed" ] } } }, "AssistantAction": { "type": "object", "required": [ "id", "tool", "status" ], "description": "A known attempted action, never a raw tool-result body. Effects describe possible resources. Status distinguishes success, accepted asynchronous work (jobId), refusal and uncertainty. Additive facts recorded when the action happened: elapsedMs measures the dispatch alone, never a gate's wait; history names the map and change group of a qualifying change and is absent for excluded ones; decision says how a resolution settled a gated call; omitted marks an action whose arguments the terminal compaction dropped, so unavailable detail is never shown as empty. Missing text is covered by the receipt's incomplete flag. A map check carries render, its facts without bytes, observation, the separate later fact with its lifecycle, and automatic when the loop scheduled it itself. A terminal compaction may have dropped the render's detail lists, which is why this render's state has them optional while the check's own response does not.", "properties": { "id": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object" }, "status": { "type": "string", "enum": [ "attempted", "succeeded", "refused", "uncertain", "accepted" ] }, "effects": { "$ref": "#/components/schemas/AssistantEffects" }, "jobId": { "type": "string" }, "label": { "type": "string", "description": "The record's line for the action, composed from the operation's declared display when it happened." }, "subject": { "$ref": "#/components/schemas/AssistantSubject" }, "elapsedMs": { "type": "integer", "minimum": 0 }, "history": { "$ref": "#/components/schemas/AssistantHistory" }, "decision": { "type": "string", "enum": [ "approved", "declined" ] }, "omitted": { "type": "boolean", "enum": [ true ] }, "render": { "$ref": "#/components/schemas/RecordedMapLookRender" }, "observation": { "$ref": "#/components/schemas/AssistantObservation" }, "automatic": { "type": "boolean", "enum": [ true ] } } }, "AssistantConfirmationRecord": { "type": "object", "required": [ "id", "runId", "tool", "decision" ], "description": "A settled confirmation, kept in the receipt when its pending representation goes: the exact action and the words as presented, with the decision. Approved and declined settle through a resolution; superseded through a newer message naming it or a release. Approval's outcome is the action's own record entry, failure included.", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object" }, "confirmation": { "$ref": "#/components/schemas/AssistantConfirmation" }, "effects": { "$ref": "#/components/schemas/AssistantEffects" }, "decision": { "type": "string", "enum": [ "approved", "declined", "superseded" ] }, "callId": { "type": "string", "description": "The tool-call id the gate held; absent from the actions when the continuation stopped before the call ran." }, "omitted": { "type": "boolean", "enum": [ true ], "description": "The terminal compaction dropped this gate's arguments; the decision and the words stand." } } }, "AssistantPendingAction": { "type": "object", "required": [ "id", "runId", "tool", "args" ], "description": "Exact open action, bound to the original run and target. A confirmation resolution uses id, while recovery uses runId. Confirmation words remain those presented when the action parked.", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object" }, "confirmation": { "$ref": "#/components/schemas/AssistantConfirmation" }, "effects": { "$ref": "#/components/schemas/AssistantEffects" }, "callId": { "type": "string", "description": "The tool-call id the gate holds: the action it runs as on approval, so a settled gate can be matched with its action or seen to have run as none." } } }, "AssistantModelChoice": { "type": "object", "required": [ "id", "name", "efforts" ], "description": "A model a request may choose on this instance. The effort levels are that model's own, in its provider's own words as Dezfil knows them: there is no shared scale, and no equivalence of computational work across models or providers is claimed. Every model offers the entry \"default\": the provider's own no-choice behavior, which is what a request with no effort resolves to. A model Dezfil knows no levels for offers that entry alone, which states what Dezfil supports and never that the provider lacks the capability. This list is exactly the accepted set: every value here is accepted for this model, and no other value is.", "properties": { "id": { "type": "string", "description": "The identity a request names in choice.model." }, "name": { "type": "string", "description": "A display name; an identity with no display name reads as itself." }, "efforts": { "type": "array", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string", "description": "The word a request names in choice.effort." }, "label": { "type": "string" } } } } } }, "AssistantCatalogueState": { "description": "The current local model catalogue. The optional assistant-models.json in DEZFIL_DATA_DIR adds and overrides entries. A missing or rejected copy uses shipped knowledge; a valid copy, including an empty one, reports merged. A rejection reason names the invalid field or read failure without file contents. Each enabled status read and new message admission reads the current files.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "source", "instance" ], "properties": { "source": { "const": "shipped" }, "instance": { "const": "absent" } } }, { "type": "object", "additionalProperties": false, "required": [ "source", "instance" ], "properties": { "source": { "const": "merged" }, "instance": { "const": "applied" } } }, { "type": "object", "additionalProperties": false, "required": [ "source", "instance", "reason" ], "properties": { "source": { "const": "shipped" }, "instance": { "const": "rejected" }, "reason": { "type": "string" } } } ] }, "AssistantProvenance": { "type": "object", "description": "What a run asked for and what its provider answers reported. Two separate facts: a requested setting is never evidence of the reasoning work a provider actually did.", "properties": { "requested": { "type": "object", "required": [ "model", "effort", "defaulted" ], "description": "The pair the first accepted submission bound, written before any provider request exists, so a run that fails before an answer still reports it. effort is \"default\" where none was chosen.", "properties": { "model": { "type": "string" }, "effort": { "type": "string" }, "defaulted": { "type": "object", "required": [ "model", "effort" ], "description": "Which halves the instance supplied rather than the requester.", "properties": { "model": { "type": "boolean" }, "effort": { "type": "boolean" } } } } }, "reported": { "type": "array", "description": "The distinct identities completed provider responses reported, in first-seen order; a null entry is a response that completed reporting none. Absent means no provider response completed at all, which is not the same fact as a response that named nothing.", "items": { "type": [ "string", "null" ] } } } }, "AssistantPolicy": { "type": "object", "required": [ "page", "policy", "offer", "admitted", "offered", "discovery" ], "description": "A page's action policy and default offer. admitted is every operation a run under the page may call; offered is what its model is shown at the start, the discovery tool included when discovery is on; discovery says whether the admitted operations outside the offer are reachable through it. offer names the mode: subset (the page's operations and the grounding reads) or full (every admitted operation).", "properties": { "page": { "type": "string", "enum": [ "builder", "sql", "workflow" ] }, "policy": { "type": "string", "enum": [ "full", "read_only" ] }, "offer": { "type": "string", "enum": [ "subset", "full" ] }, "admitted": { "type": "array", "items": { "type": "string" } }, "offered": { "type": "array", "items": { "type": "string" } }, "discovery": { "type": "boolean" } } }, "AssistantPendingList": { "type": "object", "required": [ "pending" ], "properties": { "pending": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/AssistantPendingAction" } } } }, "AssistantRun": { "type": "object", "description": "Read-only progress snapshot. Observation starts no work and cannot resume an interrupted run. Working state is lost on process replacement.", "required": [ "id", "state", "text", "actions", "incomplete" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "reserved", "running", "awaiting_confirmation", "completed", "interrupted", "failed", "unavailable" ] }, "text": { "type": "string" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantAction" } }, "pending": { "$ref": "#/components/schemas/AssistantPendingAction" }, "error": { "type": "object" }, "incomplete": { "type": "boolean" }, "confirmations": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantConfirmationRecord" }, "description": "Settled confirmations of this run, in order." }, "provenance": { "$ref": "#/components/schemas/AssistantProvenance" } } }, "AssistantStatus": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string", "description": "Present when disabled." }, "provider": { "type": "string", "description": "Present when enabled." }, "model": { "type": "string", "description": "Present when enabled." }, "catalogue": { "$ref": "#/components/schemas/AssistantCatalogueState", "description": "Present when enabled; absent when disabled." }, "stepBudget": { "type": "integer", "description": "Present when enabled." }, "autoCheck": { "type": "boolean", "description": "Present when enabled: whether the assistant checks the map by itself after a turn that changed it. The instance owner's setting, DEZFIL_ASSISTANT_AUTO_CHECK, on by default; 0, false or off turns it off. An explicit check is available whatever this says." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantModelChoice" }, "description": "Present when enabled: every model a request may choose on this instance, the resolved provider's list alone, with the default among them exactly once. The instance owner narrows and orders it with DEZFIL_AI_MODELS_ANTHROPIC or DEZFIL_AI_MODELS_OPENAI. Unset offers the effective catalogue in file order. A set empty or separators-only list offers the default alone. The default stays where listed or is prepended when missing. Unknown identities read as themselves with default effort alone. Listing an identity grants permission to request it; whether the provider has it is the provider's own answer." } }, "required": [ "enabled" ] }, "AssistantRequest": { "description": "Either a message (optionally with history and a superseded pending action) or a resolution, never both.", "oneOf": [ { "type": "object", "title": "Message", "properties": { "runId": { "type": "string", "description": "Identity obtained before submission from POST /api/assistant/runs." }, "message": { "type": "string" }, "context": { "$ref": "#/components/schemas/AssistantContext" }, "history": { "type": "array", "description": "Prior turns as {role, text}; conversations are not stored server-side.", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string" } } } }, "supersedes": { "type": "string", "description": "A pending-action id this message abandons (the implicit decline). Unknown ids are ignored." }, "choice": { "type": "object", "description": "Optional: the model and the effort this run is sent to, both optional inside it. An omitted model is the instance default; an omitted effort is the selected model's provider-default entry; an empty choice is an omission. GET /api/assistant reports what this instance offers. The first accepted submission binds the pair for the whole run, tool continuations, confirmation continuations and the map check's observation included; a choice supplied on a resolution is ignored, as a context supplied there already is. A malformed choice (400 assistant_choice_invalid), a model this instance does not offer (400 assistant_model_not_offered), an effort the selected model does not offer (400 assistant_effort_not_offered) and a named level for a model that has no levels of its own (400 assistant_effort_not_supported) are each refused before the run binds and before any provider call or product operation, leaving the reservation unbound and reusable. The entry \"default\" is accepted for every offered model and resolves exactly as omitting the effort does; the two differ only in what provenance.requested.defaulted records.", "additionalProperties": false, "properties": { "model": { "type": "string", "description": "An identity from the status read's models." }, "effort": { "type": "string", "description": "One of that model's own effort values, \"default\" among them." } } } }, "required": [ "message", "runId" ], "not": { "required": [ "resolution" ] } }, { "type": "object", "title": "Resolution", "description": "Resolve the confirmation a confirm_required event raised, instead of sending a message. Binds to the server-issued pending-action id; at most one resolution ever takes effect. Any context supplied on a resolution is ignored; the run retains its original context while server-owned facts are refreshed.", "properties": { "resolution": { "type": "object", "properties": { "pending": { "type": "string" }, "approved": { "type": "boolean" } }, "required": [ "pending", "approved" ] } }, "required": [ "resolution" ], "not": { "required": [ "message" ] } } ] }, "AssistantEvent": { "type": "object", "description": "One streamed event. text_delta carries an incremental text chunk and messageId; message carries the complete text for that same messageId. Legacy clients ignore deltas; delta-aware clients replace that message at completion, never append it twice. Recovery text is a replacement snapshot, not a delta. Partial tool arguments and private reasoning are not emitted or executed. Action events carry resolved effects; confirm_required carries target and consequence words. outcome distinguishes succeeded, accepted, refused and uncertain; jobId identifies accepted asynchronous work. `type` is one of text_delta, message, tool_call, tool_result, observation, confirm_required, error, done. On confirm_required, `id` is the server-issued pending-action id a resolution references (not a provider tool-call id); the run has paused and the stream ends until a resolution request continues it.", "properties": { "type": { "type": "string", "enum": [ "text_delta", "message", "tool_call", "tool_result", "observation", "confirm_required", "error", "done" ] }, "text": { "type": "string" }, "messageId": { "type": "string" }, "model": { "type": "string", "description": "Actual provider model on a completed model message." }, "effects": { "$ref": "#/components/schemas/AssistantEffects" }, "confirmation": { "$ref": "#/components/schemas/AssistantConfirmation" }, "callId": { "type": "string", "description": "On confirm_required: the provider tool-call id the gate holds." }, "outcome": { "type": "string", "enum": [ "succeeded", "accepted", "refused", "uncertain" ] }, "jobId": { "type": "string" }, "label": { "type": "string", "description": "On tool_call and tool_result: the record's line for the action." }, "subject": { "$ref": "#/components/schemas/AssistantSubject" }, "elapsedMs": { "type": "integer", "minimum": 0, "description": "On tool_result: execution time around the dispatch alone." }, "history": { "$ref": "#/components/schemas/AssistantHistory" }, "decision": { "type": "string", "enum": [ "approved", "declined" ], "description": "On the tool_result a resolution settled: how." }, "render": { "$ref": "#/components/schemas/MapLookRender", "description": "On a map check's tool_result: the render's facts, never its bytes." }, "automatic": { "type": "boolean", "enum": [ true ], "description": "On a map check's tool_call and tool_result: the loop scheduled it itself." }, "state": { "type": "string", "enum": [ "awaited", "captured", "silent", "interrupted", "unavailable" ], "description": "On observation: the observation's lifecycle state; id names the check action, text the displayed sentence, reason why none will come." }, "id": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object" }, "ok": { "type": "boolean" }, "body": {}, "code": { "type": "string", "enum": [ "picture_upload_retired", "setting_locked", "project_owner_cannot_leave", "method_not_allowed", "authentication_required", "invalid_credentials", "account_deactivated", "setup_complete", "weak_password", "email_taken", "self_change_refused", "account_not_deactivated", "deletion_in_progress", "deletion_unreadable", "deletion_changed", "last_admin", "forbidden", "invalid_link", "token_expired", "rule_refused", "current_password_required", "authentication_busy", "ingress_unavailable", "geometry_not_supported", "geometry_choice_invalid", "geometry_in_flight", "unsupported_format", "unsupported_image", "image_too_large", "upload_too_large", "archive_too_large", "remote_fetch_failed", "remote_fetch_abandoned", "remote_too_large", "remote_timeout", "egress_blocked", "imagery_unavailable", "area_too_large", "name_taken", "not_refreshable", "dependencies_unresolved", "export_failed", "refresh_in_flight", "connection_failed", "connection_password_required", "malformed_file", "request_body_too_large", "mcp_read_failed", "mcp_transport_failed", "mcp_response_invalid", "stale_revision", "invalid_request", "not_found", "sql_rejected", "sql_error", "query_timeout", "engine_memory_exceeded", "data_processing_timeout", "request_timeout", "upload_stalled", "render_bytes_exceeded", "query_memory_exceeded", "query_result_too_large", "tile_build_timeout", "render_cap_exceeded", "tiler_unavailable", "tile_build_failed", "render_unavailable", "render_timeout", "render_failed", "look_target_missing", "look_image_too_large", "look_image_unavailable", "attachment_too_large", "operation_timeout", "operation_queue_full", "run_in_flight", "plan_changed", "operation_interrupted", "input_changed", "geocoder_unconfigured", "geocoder_failed", "isochrone_unconfigured", "isochrone_failed", "service_address_unreadable", "basemap_not_offered", "measurement_crs_unavailable", "operation_superseded", "widget_layer_missing", "column_unavailable", "field_not_published", "catalogue_not_published", "selection_incompatible", "rate_limited", "catalogue_too_large", "assistant_reservation_required", "assistant_run_unavailable", "assistant_run_conflict", "assistant_capacity", "assistant_run_state", "assistant_submission_too_large", "assistant_recovery_limit", "assistant_plan_unavailable", "assistant_action_uncertain", "assistant_action_interrupted", "assistant_action_not_admitted", "assistant_choice_invalid", "assistant_model_not_offered", "assistant_effort_not_offered", "assistant_effort_not_supported", "assistant_context_invalid", "assistant_context_too_large", "assistant_context_unavailable", "assistant_disabled", "assistant_auth", "assistant_provider", "pending_unknown", "pending_resolved", "pending_superseded", "invalid_sketch_feature", "not_a_sketch", "feature_not_found", "vertex_move_refused", "sketch_gone", "map_not_found", "template_not_listed", "templates_catalogue_off", "template_archive_too_large", "template_checksum_mismatch", "template_unpacked_too_large", "template_malformed", "template_entry_escapes", "template_members_mismatch", "template_format_unsupported", "template_invalid", "template_forbidden", "template_picture_too_large", "template_licence_refused", "template_credit_missing", "template_reference_outside", "template_record_mismatch", "template_not_installed", "template_reference_unbound", "internal" ] }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "end", "budget", "interrupted", "cancelled", "exhausted", "failed" ], "description": "On done: why the turn ended (end, budget, interrupted). On observation: why no observation will come (cancelled, exhausted, failed); the loop yields exhausted when the last step was spent on the check itself." } }, "required": [ "type" ] } } }, "x-error-codes": { "picture_upload_retired": "Browser picture uploads are retired. Request a server picture with POST /api/maps/{id}/picture/refresh.", "setting_locked": "An environment variable locks a submitted setting. No settings changed; change or remove the named variable and restart before editing this setting.", "project_owner_cannot_leave": "The project's owner cannot leave. Transfer or delete the project instead.", "method_not_allowed": "This method is not allowed for this path.", "authentication_required": "Sign in with a valid session or account token to continue.", "invalid_credentials": "Email or password is incorrect.", "account_deactivated": "This account is deactivated. Contact an admin.", "setup_complete": "This instance already has an account. First-account creation is unavailable.", "weak_password": "Use at least eight characters and avoid very common passwords.", "email_taken": "An account already uses this normalized email address.", "self_change_refused": "Another admin must change your admin flag, deactivate your account or delete it.", "account_not_deactivated": "Deactivate this account before deleting it.", "deletion_in_progress": "This account is being deleted and cannot be reactivated.", "deletion_unreadable": "This deletion record cannot be read. Its files remain unchanged. Restore a readable record before continuing this deletion.", "deletion_changed": "This account or its work has changed. Review a fresh deletion preview before confirming.", "last_admin": "Keep at least one active admin.", "forbidden": "This request is not permitted for the current account or origin: an admin-only request, a cookie request from another origin, or a change to something the account can view but cannot make. A refused change has no effect.", "invalid_link": "This sign-in link is unavailable, expired, replaced or already used.", "token_expired": "The API token has passed the expiry it was created with and no longer works. Create a new token; the expired one stays listed until it is revoked.", "rule_refused": "An instance rule an admin sets refuses this action for the current account: creating an API token, publishing a map or changing a live publication, adding a database connection or pointing one at another host, port or database, or importing from a link. The refusal's rule field names the rule as PATCH /api/instance/settings takes it. Nothing changed, and what already exists keeps working.", "current_password_required": "Enter your current password to make this change.", "authentication_busy": "Authentication is busy. Try again shortly.", "ingress_unavailable": "Trusted socket provenance is unavailable. Authentication entry and published reads cannot proceed.", "geometry_not_supported": "Set geometry is available only for file uploads and URL imports.", "geometry_choice_invalid": "The geometry choice cannot be applied. The message explains the projection, source or validator issue.", "geometry_in_flight": "A geometry edit or refresh is already running for this dataset or URL import group.", "unsupported_format": "The uploaded file type is not one of the supported formats.", "unsupported_image": "The picture is not a still JPEG, PNG or WebP image: another kind, an animated image, or one that is damaged or incomplete. Nothing changed.", "image_too_large": "The picture has more pixels than the fixed limit of 64 million, read from its header before any pixel is decoded. Nothing changed.", "upload_too_large": "The upload exceeds its size cap: the configured upload cap, or a picture's fixed 10 MB.", "archive_too_large": "The archive's unpacked content exceeds the configured upload size cap.", "remote_fetch_failed": "The remote file could not be fetched (unreachable, denied, or missing).", "remote_fetch_abandoned": "The outbound request was abandoned before it finished, because whoever asked for it stopped waiting.", "remote_too_large": "The remote file exceeds the configured remote size cap.", "remote_timeout": "The remote fetch exceeded the configured remote time bound.", "egress_blocked": "The destination address is blocked by the egress policy (loopback, private, link-local, or metadata space); the configured allowlist admits exceptions.", "imagery_unavailable": "The satellite imagery did not answer a tile the instance relays with one: it could not be reached, its address is refused by the egress policy, it answered an error, too slowly, past the size bound or with something other than a raster image, or its tile address carries a user name or password and is not drawn. The message says which, never the tile address or its key.", "area_too_large": "The selected area exceeds the import budget for the chosen theme.", "name_taken": "A table of that name already exists. Operations never replace or rename around an existing table. Choose another name.", "not_refreshable": "The table has no re-runnable remote source, so it cannot be refreshed.", "dependencies_unresolved": "A layer's statement could not be analyzed, so the map's datasets cannot be listed completely. Fix the layer's SQL and try again.", "export_failed": "The project archive could not be assembled; nothing was delivered. Retry, and check the server's disk space if it recurs.", "refresh_in_flight": "A refresh of this table (or its OSM import group) is already running; retry when it completes.", "connection_failed": "The database connection failed (unreachable, authentication, or missing extension).", "connection_password_required": "Enter the password again when changing the host or port, or turning SSL off.", "malformed_file": "The file could not be parsed as its declared format.", "request_body_too_large": "The request body exceeds its documented byte limit.", "mcp_read_failed": "The read could not be completed because its response could not be received.", "mcp_transport_failed": "The operation's response could not be received. Its outcome is unknown.", "mcp_response_invalid": "The instance returned a response that does not match this operation's documented result.", "stale_revision": "This item has changed. Reload it before trying again.", "invalid_request": "The request was malformed or failed validation, including a missing or malformed required edit revision. Read the item before a covered write.", "not_found": "The requested resource was not found.", "sql_rejected": "The SQL was not an accepted read-only query.", "sql_error": "The SQL failed to parse or execute.", "query_timeout": "The query exceeded the configured timeout.", "engine_memory_exceeded": "Trusted data work exceeded its shared memory or scratch budget. Reduce the work, or raise DEZFIL_TRUSTED_MEMORY_MB and restart.", "data_processing_timeout": "Data processing exceeded its admitted time limit. An admin can change Data processing time limit for new work; a picture's limits are fixed.", "request_timeout": "The request body was not received within 300 s.", "upload_stalled": "The upload sent no body bytes for 60 seconds. Retry the upload.", "render_bytes_exceeded": "The features to draw exceed the configured byte limit.", "query_memory_exceeded": "The query exceeded the configured engine memory budget for user SQL.", "query_result_too_large": "The result is too large to return: more than 32 MB in total, or one non-geometry value over 2 MB. Select fewer rows or columns, or shorten the value.", "tile_build_timeout": "A tile-build stage exceeded the configured tile-build timeout.", "render_cap_exceeded": "The layer's result exceeds the inline render cap; tiled rendering is unavailable for this geometry or configuration.", "tiler_unavailable": "The result is too large for inline rendering and no tile builder is installed on this instance.", "tile_build_failed": "The layer's tile archive could not be built.", "render_unavailable": "The image renderer's browser is not available on this instance, so image export cannot run.", "render_timeout": "The image render exceeded the configured export render budget (queue wait included).", "render_failed": "The image could not be rendered. Retry; if it persists, the instance's renderer needs attention.", "look_target_missing": "No map was named for the check and none is in context, so there is nothing to render.", "look_image_too_large": "No image of the map fits inside the check's byte bound at any documented size, so none was returned.", "look_image_unavailable": "The image of this check is no longer kept on this instance: it was evicted under the retention bounds or did not survive a restart. It is never rendered again.", "attachment_too_large": "The tool attachment exceeds the configured cap; narrow the export or raise the cap.", "operation_timeout": "The operation exceeded the configured execution budget for a run. Time spent waiting for the lane is not counted against it.", "operation_queue_full": "Too many operations are already queued; the run was refused rather than accepted into a queue that would not drain. Retry once some complete.", "run_in_flight": "This workflow already has a run in flight; a workflow runs one at a time. Wait for it, or cancel it, then run again.", "plan_changed": "The workflow changed since the run was confirmed, so the nodes it would run are not the ones confirmed. Nothing started; look at the plan again.", "operation_interrupted": "The server stopped while this run was in the lane, so it did not finish. Nothing partial was kept; run it again.", "input_changed": "An input was replaced while the run was waiting, so the answers it had prepared belong to data that is no longer there. Nothing was written; run it again against the current data.", "geocoder_unconfigured": "No geocoding endpoint is configured on this instance (the Address finder an admin sets, or DEZFIL_GEOCODER_URL), so an operation that asks a provider for addresses cannot run. The message says which one to change now.", "geocoder_failed": "The configured geocoding endpoint did not answer, twice in a row. The run published nothing rather than recording an absent answer as an address that does not exist.", "isochrone_unconfigured": "No routing endpoint is configured on this instance (the travel-time endpoint an admin sets, or DEZFIL_ISOCHRONE_URL), so an operation that asks a provider for travel-time areas cannot run. The message says which one to change now.", "isochrone_failed": "The configured routing endpoint did not answer, twice in a row. The run published nothing rather than recording an absent answer as an unreachable origin.", "service_address_unreadable": "A service address, or the satellite imagery's tile template, an admin saved in Settings cannot be read with this instance's encryption key, which changed after it was saved. The service, or the imagery style, refuses rather than reach a default; an admin saves the address again.", "basemap_not_offered": "The basemap a map write or an undo or redo would put a map on is one this instance does not offer now: a style an admin hid, or, while style addresses on single maps are off, a style address the basemap library does not offer. It cannot be chosen anew. The refusal's setting field names the switch, as PATCH /api/instance/settings takes it. Nothing changed; a map already on that basemap keeps it, and Auto is always offered.", "measurement_crs_unavailable": "The data is too wide to measure a distance over in ground metres: in a projection centred on it, a distance at its widest point would be off by more than 1 %, or it crosses the antimeridian. The message names its width and extent. Split it by region and measure each part; an area over the same data succeeds and records the global projection it used.", "operation_superseded": "The step this run belonged to was changed or removed while it was working, so the run lost its authority to publish and wrote nothing. What it would have produced is no longer what the step means.", "widget_layer_missing": "The widget references a layer that no longer exists, so its value cannot be computed.", "column_unavailable": "The write introduces a reference to a column the layer's result does not provide, or provides with a type the channel cannot use, so it was refused; stored references are never retro-refused.", "field_not_published": "The selection references a field the published surface does not declare: outside the layer's effective published field set and not a published widget's field.", "catalogue_not_published": "A published layer or widget whose SQL reads the instance's catalogue does not evaluate on the link while its owner holds datasets the map does not name: a published map reaches only the datasets its own layers name, and the link would otherwise disclose the others.", "selection_incompatible": "The selection's values cannot be evaluated against its field's type (for example a time range on a non-time field); it was refused before evaluation.", "rate_limited": "Too many requests or sign-in attempts; retry after the indicated delay.", "catalogue_too_large": "The schema page exceeds 96 KiB. Request fewer tables or columns.", "assistant_reservation_required": "Reserve a run with POST /api/assistant/runs, then send its id as runId.", "assistant_run_unavailable": "This run identity is unavailable and cannot execute.", "assistant_run_conflict": "This run identity is already bound to different input.", "assistant_capacity": "Eight assistant runs occupy capacity. Read GET /api/assistant/pending; release an unused reservation or abandon a pending turn with DELETE /api/assistant/runs/{id}.", "assistant_run_state": "This operation is not available in the current run state.", "assistant_submission_too_large": "The assistant submission exceeds 128 KiB.", "assistant_recovery_limit": "Further work stopped before the live recovery bound could be exceeded.", "assistant_plan_unavailable": "The current workflow membership could not be established. No run was approved or started.", "assistant_action_uncertain": "The action outcome could not be established. Its declared resources may have changed.", "assistant_action_interrupted": "The read was interrupted before completion.", "assistant_action_not_admitted": "The run's page context does not admit this operation; nothing was performed. Runs under a /sql or workflow context admit only operations that declare themselves read-only, and none that reaches outside this server or asks for confirmation.", "assistant_choice_invalid": "The submitted model choice is malformed: it must be an object whose optional model and effort are strings.", "assistant_model_not_offered": "The requested model is not one this instance offers. GET /api/assistant lists the models it offers.", "assistant_effort_not_offered": "The requested effort is not one the selected model offers. GET /api/assistant lists each model's own efforts.", "assistant_effort_not_supported": "The selected model has no effort levels of its own, so it takes only the provider default. Send the effort \"default\", or no effort at all, or choose a model that offers levels. GET /api/assistant lists each model's own efforts.", "assistant_context_invalid": "The submitted page context is malformed or refers to an incompatible object.", "assistant_context_too_large": "Page context exceeds 64 KiB of UTF-8 JSON.", "assistant_context_unavailable": "The page context could not be read from this instance.", "assistant_disabled": "The assistant is not enabled; no model credential is configured.", "assistant_auth": "The configured model credential was rejected by the provider.", "assistant_provider": "The model provider request failed (outage, quota, or network).", "pending_unknown": "The referenced pending action is unknown; it may have expired with the server's working state.", "pending_resolved": "The referenced pending action was already resolved; it will not run again.", "pending_superseded": "A newer message superseded the referenced pending action, declining it.", "invalid_sketch_feature": "The submitted sketch feature failed the structural gate: kind, geometry family, coordinate ranges, ring closure or the published vertex ceiling.", "not_a_sketch": "The named table is not a sketch dataset; sketch operations apply only to tables drawn on a map.", "feature_not_found": "No drawn feature with the given id exists in the sketch dataset.", "vertex_move_refused": "The vertex move was refused: only drawn polygons and freehand shapes offer vertex handles, and the index must name an existing vertex.", "sketch_gone": "The sketch dataset was deleted or replaced while the change was in flight; nothing was written.", "map_not_found": "No map exists with the given id.", "template_not_listed": "No template with that id is shipped with this instance, downloaded to it or listed by the catalogue list it last read.", "templates_catalogue_off": "An admin turned the template catalogue off (the templates.catalogue setting), so the server reaches it for nothing: no refresh, Test or download is sent. Shipped and downloaded templates still open and copy.", "template_archive_too_large": "A template's archive is larger than the size the catalogue's index declares for it, or than the 150 MB a template archive may be; nothing was installed.", "template_checksum_mismatch": "A template's archive arrived with another size or another SHA-256 than the catalogue's index declares; nothing was installed.", "template_unpacked_too_large": "A template's archive unpacks past this instance's upload cap; nothing was installed.", "template_malformed": "A template's archive is not one this server reads: not a readable ZIP holding one .dezfil folder, a document that is not JSON, or a dataset the upload's reader cannot read.", "template_entry_escapes": "A member of a template's archive names a path outside its folder.", "template_members_mismatch": "A template's documents name a member it does not hold, or it holds a member nothing names.", "template_format_unsupported": "A template is in a format version this server does not read.", "template_invalid": "A template's document fails the rules a client's document is held to, one of its layers or steps does not bind to the template's own data as a client's would or names one of its datasets other than as a plain table reference (inside a string or a table function's argument, or qualified by a schema), or a layer draws more than the default of the render cap or of Bytes drawn per layer.", "template_forbidden": "A template carries a publication, token, connection, service address or setting, which no template may.", "template_picture_too_large": "A template's map picture is larger than its 2 MB bound.", "template_licence_refused": "A template's data is under a licence that does not allow redistribution.", "template_credit_missing": "A template's credit note does not name every source with its licence.", "template_reference_outside": "A template's layer or step names a dataset that is neither the template's own nor the result of an earlier step, such as a person's dataset or another template's.", "template_record_mismatch": "An installed template's files differ from the record written when it was installed, so it is refused rather than trusted.", "template_not_installed": "That version of the template is listed by the catalogue but not on this server yet, so it cannot be copied; fetch it first (POST /api/templates/{id}/fetch), then copy. Nothing was created.", "template_reference_unbound": "A layer or step of the template names a dataset the copy could not bind to the datasets it makes, so the copy was refused whole and nothing was created.", "internal": "An unexpected server error occurred." }, "x-resource-error-statuses": { "engine_memory_exceeded": 422, "data_processing_timeout": 408, "upload_stalled": 408, "request_timeout": 408, "render_bytes_exceeded": 422 } }