Query Data Through The API
Create your key in the dashboard, then use the API for every step from selecting a template to querying data. You need curl, jq, and an existing template available to your organization.
How the steps fit together
Section titled “How the steps fit together”sequenceDiagram
autonumber
actor User as Requester
participant Dashboard
participant API as env-manager API
actor Admin as Organization admin
participant Enclave as env-enzo / DuckDB
User->>Dashboard: Create key in Developer > API Keys
Dashboard->>API: Create key using dashboard session
API-->>Dashboard: Key secret (shown once)
Dashboard-->>User: Copy key
Note over User,API: Requester sends X-API-Key on subsequent API calls
User->>API: GET /v1/request-templates
API-->>User: Available templates
User->>API: GET /v1/request-templates/{template_id}
API-->>User: Scope, parameters, validity period
User->>API: POST /v1/requests (template ID, scope, parameter values, expiry, details)
API-->>User: Request ID, status pending
Admin->>API: POST /v1/admin/requests/{id}/approve (admin key)
API-->>Admin: Request approved
User->>API: POST /v1/requests/{id}/activate
API->>Enclave: Provision environment and start data pull
API-->>User: Request active (data may still be loading)
loop Poll until ready (stop on failed)
User->>API: GET /v1/requests/{id}/status
API->>Enclave: Check readiness and loaded datasets
Enclave-->>API: Loading, ready, or failed with relation names
API-->>User: Data status and datasets
end
User->>API: POST /v1/requests/{id}/query (SQL)
API->>Enclave: Execute read-only SQL
Enclave-->>API: Columns, results, truncated
API-->>User: Query result
User->>API: POST /v1/requests/{id}/revoke
API->>Enclave: Tear down environment
API-->>User: Request revoked
Approval uses an admin’s key; activation and querying use the requester’s key. Wait for data status ready before querying, even if the request is already active.
1. Create an API key
Section titled “1. Create an API key”In the dashboard, select the organization you want to work in. Open Developer > API Keys, click Create key, give it a name and expiration, and copy the secret before closing the dialog. The full key is shown only once.
The key inherits your permissions in that organization. Approval requires an organization admin’s key; a requester key cannot approve access.
Set your API base URL and key in your shell:
export A10E='https://YOUR-API-HOST'export KEY='YOUR-API-KEY'Use the env-manager API host, not the dashboard’s /api routes. All calls below use X-API-Key and /v1 paths. Keep the key out of source control.
2. Pick an existing template
Section titled “2. Pick an existing template”List the templates available to your user (personal templates and shared configured templates):
curl --fail-with-body -sS "$A10E/v1/request-templates" \ -H "X-API-Key: $KEY" \ | jq '.data.templates[] | {id, name, validity_period, parameters}'Copy the ID of the template you want, then fetch its full definition:
export TEMPLATE_ID='TEMPLATE-UUID'curl --fail-with-body -sS "$A10E/v1/request-templates/$TEMPLATE_ID" \ -H "X-API-Key: $KEY" > template.jsonjq '.data | {name, scope, parameters, validity_period}' template.jsonInspect the scope to confirm the datasets, columns, and filters you need. parameters lists any values you must supply, including their names and types.
3. Create the request
Section titled “3. Create the request”Create parameters.json with values for every listed parameter. Values are strings; names must match the template. For example, a template with two DATE parameters might need:
{"date_1": "2026-01-01", "date_2": "2026-02-01"}For a template with no parameters:
printf '{}\n' > parameters.jsonBuild the request using the template’s scope and validity period. Edit the description and justification to explain your actual use:
jq --slurpfile params parameters.json ' .data as $t | {"1h":3600,"3h":10800,"5h":18000,"1d":86400,"3d":259200,"7d":604800} as $durations | { title: ($t.name + " — API request"), description: "Analyze the data for the monthly report", business_justification: "Prepare the monthly operations review", request_template_id: $t.id, scope: $t.scope, parameters: $params[0], valid_until: ((now + $durations[$t.validity_period]) | todateiso8601) }' template.json > request.json
curl --fail-with-body -sS -X POST "$A10E/v1/requests" \ -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \ --data-binary @request.json > created-request.jsonexport REQUEST_ID=$(jq -er '.data.id' created-request.json)jq '.data | {id, status, valid_until}' created-request.jsonThe request starts as pending. Sending only request_template_id is insufficient: the API also requires scope. The example copies it unchanged and supplies parameter values separately. Expiry starts from the timestamp calculated here, so allow time for approval and loading.
4. Approve the request
Section titled “4. Approve the request”An organization admin must approve it. The admin runs this with their own key from the same organization (if you are an admin, you can use your key):
export ADMIN_KEY='ADMIN-API-KEY'curl --fail-with-body -sS -X POST "$A10E/v1/admin/requests/$REQUEST_ID/approve" \ -H "X-API-Key: $ADMIN_KEY" -H 'Content-Type: application/json' \ -d '{"notes":"Approved for the stated analysis"}'If someone else handles approval, check the request until .data.status is approved. A denied or expired request cannot be activated.
curl --fail-with-body -sS "$A10E/v1/requests/$REQUEST_ID" \ -H "X-API-Key: $KEY" | jq '.data | {id, status, valid_until}'5. Activate and wait for data
Section titled “5. Activate and wait for data”Activate with the requester’s key. This provisions the isolated env-enzo environment and starts pulling the scoped data into DuckDB:
curl --fail-with-body -sS -X POST "$A10E/v1/requests/$REQUEST_ID/activate" \ -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d '{}'An active request may still be loading. Poll the data status; query only when state is ready. This loop stops on failure or after roughly five minutes; rerun it if loading is still progressing:
for attempt in $(seq 1 60); do curl --fail-with-body -sS "$A10E/v1/requests/$REQUEST_ID/status" \ -H "X-API-Key: $KEY" > status.json || break jq '{state, error, datasets}' status.json state=$(jq -r '.state' status.json) case "$state" in ready|failed) break ;; esac sleep 5donejq -e '.state == "ready"' status.jsonThe status response has no .data wrapper. Its datasets[].relation values are the table names to use in SQL; rows_loaded reports loaded row counts.
6. Query the data
Section titled “6. Query the data”Replace customers with a relation returned by the status endpoint. For a namespaced relation such as pg.orders, use FROM pg.orders.
curl --fail-with-body -sS -X POST "$A10E/v1/requests/$REQUEST_ID/query" \ -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \ -d '{"sql":"SELECT * FROM customers LIMIT 20"}' | jqThe response is the query result directly:
{ "columns": ["id", "email"], "results": [{"id": 1, "email": "customer@example.com"}], "truncated": false}SQL uses DuckDB dialect and must be read-only. columns preserves SELECT order. Results are capped at 10,000 rows; truncated: true means more rows were available. Use SQL WHERE, ORDER BY, and LIMIT to narrow results. This route accepts sql only; do not send a separate limit field. Call the request route through env-manager, rather than the sidecar’s /v1/query/run path.
Numbers arrive as JSON numbers, with one exception: a value that a 64-bit float can’t hold exactly is sent as a JSON string with every digit, because most JSON parsers would round it. That covers whole numbers outside ±9007199254740991 (a 19-digit id, a 25-digit reference) and decimals with more than 15 significant digits. Read a numeric column as “number or string” if it can hold values that large.
7. End access
Section titled “7. End access”Revoke when finished to tear down the environment:
curl --fail-with-body -sS -X POST "$A10E/v1/requests/$REQUEST_ID/revoke" \ -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \ -d '{"reason":"Analysis complete"}'Access also expires at valid_until. Revoke the API key separately in Developer > API Keys if you no longer need it.
Reference script
Section titled “Reference script”Download query-local-mysql.py for a complete Python example of steps 3 through 7 with one admin key. It needs only the Python 3 standard library. It builds a manual scope for the merchant table of a datasource named local-mysql, rather than using a template, then approves, activates, waits for ready, and queries the first 20 rows.
export A10E='https://YOUR-API-HOST' # defaults to http://localhost:8080export A10E_API_KEY='ADMIN-API-KEY' # or omit to be prompted without echopython3 query-local-mysql.py --revokeAccess stays active for one hour unless you pass --revoke, which tears the request down on exit, including after a failure. Adapt the datasource name, table, and columns to your own sources. The key must belong to an organization admin, because the script approves its own request.
If a call fails
Section titled “If a call fails”- 400: inspect the response for missing template parameters, invalid values, or SQL errors.
- 401: check the key’s value, expiration, and revocation status.
- 403: check permissions; approval needs an admin key.
- 404: check the ID, organization, and request ownership.
- 409 when querying: poll the data status again; the request or its datasets may not be ready.
- 502 / 503: the enclave is unreachable or the deployment lacks the query proxy; contact your operator.
Errors raised by env-manager use {success, message, error}. Query errors from env-enzo use {"error":"..."} and are passed through unchanged.