HTTP interface
The HTTP interface accepts authenticated SQL at POST / and returns a registered output format. Enable http_port in config.xml or pass serve --http-addr HOST:PORT.
First request
GET /ping is an unauthenticated health check. The following commands check readiness and run SQL against the selected database:
curl --silent http://127.0.0.1:7401/ping
curl --silent --user default: --data-binary 'SELECT 1 FORMAT csv' \
'http://127.0.0.1:7401/?database=data'Ok.
1Authentication
Basic authentication uses the configured username and password. Bearer authentication uses a configured API key. Without Authorization, the server attempts the explicitly configured default user with an empty password. Invalid explicit credentials never fall back to that user. There is no TLS; use a trusted connection or external TLS termination.
URL parameters
Only these parameters are accepted; duplicate parameters are errors:
| Parameter | Meaning |
|---|---|
query |
SQL text; when present, the body supplies INSERT FORMAT input. |
database |
Managed database selected for this request. |
default_format |
Output format for statements without an explicit FORMAT. |
result_limit |
Result-row cap per statement, from 1 through 50,000,000. |
Without query, the body is SQL. A result limit caps returned rows rather than a mutation's writes. Truncation is reported with X-Coordinator-Result-Truncated: 1.
Request state
Each HTTP request has its own session. To use a transaction or temporary table, send every related statement in the same request. An open transaction rolls back before the response is delivered. Bound parameters, persistent HTTP sessions, streaming responses and server-side cancellation are unsupported.
Body and response limits
SQL bodies require Content-Length and ordinary requests are limited to 16 MiB. An attached INSERT upload with SQL in query can use Content-Length or chunked transfer without a total upload-size ceiling. Header limits and receive timeouts still apply. Responses are buffered and retain the response-byte limit.
Status codes
Successful requests return 200. SQL errors usually return 400; authentication uses 401, origin rejection 403, receive timeout 408, missing Content-Length 411, oversize ordinary requests 413, server I/O/internal errors 500, and admission/locking failures 503. Unknown paths use 404; unsupported methods use 405.
Response metadata
Response headers include X-Coordinator-Query-Id, X-Coordinator-Database and X-Coordinator-Summary. Errors also have X-Coordinator-Exception-Code. The summary contains result_rows, elapsed_ms, read_rows, read_bytes, written_rows, written_bytes, memory_usage and peak_memory_usage. Content-Type follows the selected format; mixed results use text/plain.
Browser access
Browser requests must have matching Origin and Host. Empty-password users are restricted to IP hosts or localhost. CORS headers are not emitted. Passwords and keys are not accepted in URL parameters.