API Support
Overview
Alien Giraffe Connector API 1.0
Section titled “Alien Giraffe Connector API 1.0”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.
- Create
POST /v1/requestswith a title, description, business justification and the scope: per datasource, the datasets (source.kindtableorpath,source.name) and the columns wanted. The response carries the requestidandstatus: pending. - Approve
POST /v1/admin/requests/{id}/approveas an organization admin. (POST /v1/admin/requests/{id}/denyrejects it.) - Activate
POST /v1/requests/{id}/activateas the requester. This provisions the enclave and starts the background data pull; the request isactiveas soon as its container runs, before the datasets arrive. - Wait for data by polling
GET /v1/requests/{id}/statusuntilstateisready(provisioning→loading→ready|failed). The response also lists each loaded relation with its row count; those relation names are the table names to query. - Query
POST /v1/requests/{id}/querywith{"sql": "..."}. The SQL is DuckDB dialect, must be read-only, and is capped at 10000 rows (truncatedtells you when the cap hit).POST /v1/requests/{id}/nl-to-sqlturns a natural-language question into SQL for the request’s scope. Document datasources are searched semantically withPOST /v1/tunnels/{id}/edge/api/document/searchthrough a tunnel. - 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}proxiesquery/runanddocument/searchto the same enclave using those credentials (X-API-Keywith 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 thelimitfield of a query. - Revoke
POST /v1/requests/{id}/revokewhen done. The enclave is torn down and the request can no longer be queried; it also expires on its own atvalid_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.
Authentication
Section titled “Authentication”ApiKeyAuth
Section titled “ApiKeyAuth”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
BearerAuth
Section titled “BearerAuth”Bearer token authentication using the Authorization header.
Security scheme type: apiKey
Header parameter name: Authorization