Skip to content

Overview

API for managing ephemeral data enclaves.

Data access workflow

A data access request describes which datasets a user needs. Once it is approved and activated, env-manager provisions an isolated enclave for it: an env-enzo sidecar container that pulls the requested datasets into a local DuckDB database and answers read-only queries over them. env-enzo is the only enclave service type; its own paths (/v1/query/run, /v1/document/search, tagged query and document below) are documented so the request and response bodies are known, but they are never called directly. Clients always go through env-manager, which proxies both the body and the response verbatim.

Every env-manager step below accepts either a session bearer token (Authorization: Bearer ..., BearerAuth) or an API key created under Developer > API Keys (X-API-Key, ApiKeyAuth). A key inherits its creator’s permissions, so the approve step needs a key of an organization admin. The tunnel edge is the exception: it is reached with the credentials issued when the tunnel was created, not with an account key.

  1. Create POST /v1/requests with a title, description, business justification and the scope: per datasource, the datasets (source.kind table or path, source.name) and the columns wanted. The response carries the request id and status: pending.
  2. Approve POST /v1/admin/requests/{id}/approve as an organization admin. (POST /v1/admin/requests/{id}/deny rejects it.)
  3. Activate POST /v1/requests/{id}/activate as the requester. This provisions the enclave and starts the background data pull; the request is active as soon as its container runs, before the datasets arrive.
  4. Wait for data by polling GET /v1/requests/{id}/status until state is ready (provisioning → loading → ready | failed). The response also lists each loaded relation with its row count; those relation names are the table names to query.
  5. Query POST /v1/requests/{id}/query with {"sql": "..."}. The SQL is DuckDB dialect, must be read-only, and is capped at 10000 rows (truncated tells you when the cap hit). POST /v1/requests/{id}/nl-to-sql turns a natural-language question into SQL for the request’s scope. Document datasources are searched semantically with POST /v1/tunnels/{id}/edge/api/document/search through a tunnel.
  6. Share or script access by creating a tunnel, POST /v1/requests/{id}/tunnel, which returns a public edge URL and its credentials. POST /v1/tunnels/{id}/edge/api/{path} proxies query/run and document/search to the same enclave using those credentials (X-API-Key with the tunnel-issued key, or HTTP Basic). This is the route for tools that cannot hold an account key, and the only route that honours the limit field of a query.
  7. Revoke POST /v1/requests/{id}/revoke when done. The enclave is torn down and the request can no longer be queried; it also expires on its own at valid_until.

The same sequence with curl ($A10E is the env-manager base URL, $KEY an API key, $ADMIN_KEY an org admin’s key):

ID=$(curl -s -X POST "$A10E/v1/requests" -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{"title":"Churn analysis","description":"Q3 churn","business_justification":"Board report","scope":[{"datasource":"warehouse","datasets":[{"source":{"kind":"table","name":"public.customers"},"columns":["id","email","created_at"]}]}]}' | jq -r .data.id)
curl -s -X POST "$A10E/v1/admin/requests/$ID/approve" -H "X-API-Key: $ADMIN_KEY"
curl -s -X POST "$A10E/v1/requests/$ID/activate" -H "X-API-Key: $KEY"
until [ "$(curl -s "$A10E/v1/requests/$ID/status" -H "X-API-Key: $KEY" | jq -r .state)" = ready ]; do sleep 5; done
curl -s -X POST "$A10E/v1/requests/$ID/query" -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{"sql":"SELECT id, email FROM customers ORDER BY created_at DESC"}'
curl -s -X POST "$A10E/v1/requests/$ID/revoke" -H "X-API-Key: $KEY"

The /v1/environments and /env/{namespace}/{service}/{path} routes of the earlier Docker driver are internal to env-manager and are not part of the data access surface.

Information

  • OpenAPI version: 2.0

API key created under Developer > API Keys. Accepted only on the routes that also take a session (admin, catalog, datasources, requests, templates, MCP and skills). The key inherits its creator’s permissions.

Security scheme type: apiKey

Header parameter name: X-API-Key

Bearer token authentication using the Authorization header.

Security scheme type: apiKey

Header parameter name: Authorization