Skip to content

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.

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.

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.

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.json
jq '.data | {name, scope, parameters, validity_period}' template.json

Inspect the scope to confirm the datasets, columns, and filters you need. parameters lists any values you must supply, including their names and types.

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.json

Build 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.json
export REQUEST_ID=$(jq -er '.data.id' created-request.json)
jq '.data | {id, status, valid_until}' created-request.json

The 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.

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}'

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 5
done
jq -e '.state == "ready"' status.json

The status response has no .data wrapper. Its datasets[].relation values are the table names to use in SQL; rows_loaded reports loaded row counts.

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"}' | jq

The 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.

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.

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:8080
export A10E_API_KEY='ADMIN-API-KEY' # or omit to be prompted without echo
python3 query-local-mysql.py --revoke

Access 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.

  • 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.