# 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:

```sh
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'
```

```text
Ok.
1
```

## Authentication

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.

[Formats](https://coordinatordb.com/docs/reference/formats) · [Query log](https://coordinatordb.com/docs/reference/system-tables/query-log)