Skip to content

Tunnel API proxy

POST
/v1/tunnels/{id}/edge/api/{path}
curl --request POST \
--url https://localhost:8080/v1/tunnels/example/edge/api/example \
--header 'Content-Type: application/json' \
--data '{ "limit": 100, "sql": "SELECT id, email FROM customers WHERE created_at > '\''2026-01-01'\'' ORDER BY id" }'

Public edge of a request tunnel (POST /v1/requests/{id}/tunnel): authenticates with the tunnel’s own credentials and proxies the call to the enclave’s env-enzo sidecar, forwarding the request body and returning the sidecar’s response verbatim. path is the env-enzo path below /v1: query/run (body enzoapi.QueryRequest, response enzoapi.QueryResponse; this route forwards limit) or document/search (body enzoapi.SearchRequest, response enzoapi.SearchResponse). env-enzo error responses ({"error": "..."}) are passed through unchanged.

Authentication is not the account session or API key but the credential issued with the tunnel: either X-API-Key: <tunnel api key> or HTTP Basic with the issued username and password. 401 for a missing or revoked credential, 404 for an unknown or closed tunnel, 502 when the enclave is unreachable.

id
required
string

Tunnel ID

path
required
string

Env-enzo path below /v1: query/run or document/search

Body forwarded to env-enzo (QueryRequest for query/run, SearchRequest for document/search)

Media typeapplication/json
object
limit

Limit caps the number of rows returned. Omitted, 0, negative, or above 10000 all fall back to the 10000-row cap; when the cap truncates the result, the response sets truncated=true. Only honoured on the tunnel edge: the env-manager route POST /v1/requests/{id}/query forwards sql only.

integer
<= 10000

Example

100
sql
required

SQL is a single read-only statement in DuckDB SQL dialect, run against the enclave’s local DuckDB database. Table names are the request’s dataset relation names (see GET /v1/requests/{id}/status). Statements beginning with INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, REPLACE or MERGE are rejected with 400.

string

Example

SELECT id, email FROM customers WHERE created_at > '2026-01-01' ORDER BY id

Env-enzo response passed through (QueryResponse for query/run, SearchResponse for document/search)

Media typeapplication/json
object
columns

Columns are the result column names in SELECT order. The row objects in results are JSON objects whose keys are serialised alphabetically, so this list is the only place the query’s column order survives.

Array<string>
results

Results holds one object per row, keyed by column name. DuckDB values map to their natural JSON type (numbers, strings, booleans, null); timestamps and dates are RFC 3339 strings and INTERVAL values are rendered as DuckDB prints them (e.g. “1 year 2 days 04:05:06”). Empty when the query matched no rows.

Array<object>
object
key
additional properties
truncated

Truncated is true when more rows were available than the effective limit allowed and the result was cut off at that limit.

boolean

Example

{
"columns": [
"id",
"email"
],
"truncated": false
}

Empty path (env-manager) or rejected body (env-enzo, {error})

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Missing or invalid tunnel credentials

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Unknown or closed tunnel

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Enclave unreachable

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}