---
title: "HTTP protocol"
description: "Query and modify data over plain HTTP endpoints."
canonical_url: "https://surrealdb.com/docs/reference/protocols/http-protocol"
section: "Protocols and APIs"
surrealdb_version: "4.x"
last_modified: "2026-11-19T06:06:22Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# HTTP protocol

Query and modify data over plain HTTP endpoints.

The HTTP endpoints exposed by SurrealDB instances provide a simple way to interact with the database over a traditional RESTful interface. This includes selecting and modifying one or more records, executing custom SurrealQL queries, and importing and exporting data.

The endpoints are designed to be simple and easy to use in stateless environments, making them ideal for lightweight applications where a persistent database connection is not required.

## Setup

The [`surreal db start`](/docs/reference/cli/db/commands/start.md) command without any arguments is all that is needed to start a server at the default `http://localhost:8000` address. Many examples below assume the flags `--user root` and `--pass secret` to create a root user with the name `root` and password `secret`. The `--unauthenticated` flag can be used when experimenting to turn off authentication, effectively allowing root access by any and all connections.

The [local database serving](/docs/reference/studio.md) functionality on the SurrealDB Studio can also be used to start a server.

## Querying via Postman

One convenient way to access these endpoints is via SurrealDB's Postman Collection. To do so, follow these steps:

1. Open Postman
2. Clone the [SurrealDB Postman Collection](https://postman.com/surrealdb/workspace/surrealdb/collection/19100500-3da237f3-588b-4252-8882-6d487c11116a)
3. Select the appropriate HTTP method (`GET /health`, `DEL /key/:table`, etc.).
4. Enter the endpoint URL.
5. If the endpoint requires any parameters or a body, make sure to include those in your request.

## Supported methods

You can use the HTTP endpoints to perform the following actions:

<br />

<table>
    <thead>
        <tr>
            <th scope="col">Function</th>
            <th scope="col">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td scope="row" data-label="Function"><a href="#status"><code>GET /status</code></a></td>
            <td scope="row" data-label="Description">Checks whether the database web server is running</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#health"><code>GET /health</code></a></td>
            <td scope="row" data-label="Description">Checks the status of the database server and storage engine</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#ready"><code>GET /ready</code></a></td>
            <td scope="row" data-label="Description">Checks whether the instance has finished startup and is ready to serve traffic</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#version"><code>GET /version</code></a></td>
            <td scope="row" data-label="Description">Returns the version of the SurrealDB database server</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#import"><code>POST /import</code></a></td>
            <td scope="row" data-label="Description">Imports data into a specific Namespace and Database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#export"><code>POST /export</code></a></td>
            <td scope="row" data-label="Description">Exports all data for a specific Namespace and Database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#kvexport"><code>POST /kvexport</code></a></td>
            <td scope="row" data-label="Description">Streams the datastore's entire keyspace from one snapshot (experimental)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#signup"><code>POST /signup</code></a></td>
            <td scope="row" data-label="Description">Signs-up as a record user using a specific record access method</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#signin"><code>POST /signin</code></a></td>
            <td scope="row" data-label="Description">Signs-in as a root, namespace, database, or record user</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#signin-cookie"><code>POST /signin/cookie</code></a></td>
            <td scope="row" data-label="Description">Signs in like <code>POST /signin</code>, and returns the token in an <code>HttpOnly</code> cookie (requires <code>--cookie-auth</code>)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#signup-cookie"><code>POST /signup/cookie</code></a></td>
            <td scope="row" data-label="Description">Signs up like <code>POST /signup</code>, and returns the token in an <code>HttpOnly</code> cookie (requires <code>--cookie-auth</code>)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#refresh-cookie"><code>POST /refresh/cookie</code></a></td>
            <td scope="row" data-label="Description">Exchanges the refresh cookie for a new access cookie and refresh cookie (requires <code>--cookie-auth</code>)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#signout"><code>POST /signout</code></a></td>
            <td scope="row" data-label="Description">Revokes the refresh token and clears the session cookies (requires <code>--cookie-auth</code>)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#get-table"><code>GET /key/:table</code></a></td>
            <td scope="row" data-label="Description">Selects all records in a table from the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#post-table"><code>POST /key/:table</code></a></td>
            <td scope="row" data-label="Description">Creates a record in a table in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#put-table"><code>PUT /key/:table</code></a></td>
            <td scope="row" data-label="Description">Updates all records in a table in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#patch-table"><code>PATCH /key/:table</code></a></td>
            <td scope="row" data-label="Description">Modifies all records in a table in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#delete-table"><code>DELETE /key/:table</code></a></td>
            <td scope="row" data-label="Description">Deletes all records in a table from the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#get-record"><code>GET /key/:table/:id</code></a></td>
            <td scope="row" data-label="Description">Selects the specific record from the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#post-record"><code>POST /key/:table/:id</code></a></td>
            <td scope="row" data-label="Description">Creates the specific record in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#put-record"><code>PUT /key/:table/:id</code></a></td>
            <td scope="row" data-label="Description">Updates the specified record in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#patch-record"><code>PATCH /key/:table/:id</code></a></td>
            <td scope="row" data-label="Description">Modifies the specified record in the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#delete-record"><code>DELETE /key/:table/:id</code></a></td>
            <td scope="row" data-label="Description">Deletes the specified record from the database</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#sql"><code>POST /sql</code></a></td>
            <td scope="row" data-label="Description">Allows custom SurrealQL queries</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#gql"><code>POST /gql</code></a></td>
            <td scope="row" data-label="Description">Runs ISO GQL graph pattern queries (`MATCH … RETURN …`, plus `INSERT` / `SET` / `REMOVE` / `DELETE`)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#graphql"><code>POST /graphql</code></a></td>
            <td scope="row" data-label="Description">Allows custom GraphQL queries</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#custom"><code>/api/:namespace/:database/:endpoint</code></a></td>
            <td scope="row" data-label="Description">Create a custom API endpoint for any number of HTTP methods (GET, POST, etc.)</td>
        </tr>
        <tr>
            <td scope="row" data-label="Function"><a href="#bucket"><code>/ns/:namespace/db/:database/bucket/:bucket</code></a></td>
            <td scope="row" data-label="Description">Reads, writes, copies, renames, deletes and lists the files in a bucket, with a session or a presigned URL</td>
        </tr>
    </tbody>
</table>

<br />

## Authentication

Most endpoints accept a user's name and password through HTTP Basic authentication, sent in the `Authorization` header (`curl -u name:password`). By default the server checks those credentials against the root users. A user defined on a namespace or a database is not found there, so the request fails with `401` and the message `There was a problem with authentication`.

To sign in as a namespace or database user, also send the headers that say where the user is defined:

| Header | Value | Needed for |
| --- | --- | --- |
| `Surreal-Auth-NS` | The namespace the user is defined on | Namespace and database users |
| `Surreal-Auth-DB` | The database the user is defined on | Database users |

These headers only locate the user. The namespace and database that the request works in still come from `Surreal-NS` and `Surreal-DB`, so a request usually sends both pairs. The following request signs in as `clerk`, a user defined with `DEFINE USER clerk ON DATABASE`, and queries the same database:

```bash
curl -X POST -u "clerk:hunter123" \
  -H "Surreal-Auth-NS: shop" -H "Surreal-Auth-DB: orders" \
  -H "Surreal-NS: shop" -H "Surreal-DB: orders" \
  -H "Accept: application/json" \
  -d "SELECT * FROM item;" \
  http://localhost:8000/sql
```

```json title="Response"
[{ "result": [{ "id": "item:1" }], "status": "OK", "time": "1.646375ms", "type": null }]
```

A namespace user needs only `Surreal-Auth-NS`. Without `Surreal-NS`, the same request authenticates but returns the error `Specify a namespace to use`.

To avoid sending a password with every request, sign in once with [`POST /signin`](#signin) and send the token it returns as `Authorization: Bearer <token>`. A token already carries the namespace and database of its user.

### Cookie authentication

_(since v4.0.0)_

A browser application can keep its access token in an `HttpOnly` cookie, which scripts on the page cannot read. The server issues and accepts the cookie only when it is started with `--cookie-auth` and an explicit `--allow-origin` list:

```bash
surreal db start --cookie-auth --allow-origin https://app.example.com --user root --pass secret surrealkv://data
```

The server does not start with `--cookie-auth` alone, and reports `cookie authentication requires an explicit --allow-origin list`. A list that contains `*` is refused with `cookie authentication refuses a wildcard --allow-origin`.

The application signs in through [`POST /signin/cookie`](#signin-cookie) or [`POST /signup/cookie`](#signup-cookie), which take the same body as `/signin` and `/signup`. The browser has to send credentials with the request so that it stores the cookie and sends it back:

```js
await fetch("https://db.example.com/signin/cookie", {
	method: "POST",
	credentials: "include",
	headers: { Accept: "application/json" },
	body: JSON.stringify({ ns: "main", db: "main", ac: "users", email: "tobie@example.com", pass: "secret" }),
});
```

The response sets the `surreal_token` cookie and holds no token in its body:

```text title="Response"
HTTP/1.1 200 OK
set-cookie: surreal_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900
access-control-allow-credentials: true
access-control-allow-origin: https://app.example.com

{"code":200,"details":"Authentication succeeded"}
```

The rules for the cookie are as follows:

- **Origins.** The server reads the cookie only from a request whose `Origin` header exactly matches an entry in `--allow-origin`, or which sends `Sec-Fetch-Site: same-origin`. Another subdomain, scheme or port does not match. The same check applies to WebSocket connections on `/rpc` and `/sql`.
- **A cookie that is not accepted.** A cookie from an origin that is not allowed is ignored, and the request runs as if it had no credentials. A cookie whose token fails verification, for example because it has expired, is also ignored, and the response clears it.
- **`Authorization` first.** A request that sends an `Authorization` header is authenticated with that header, and the cookie is not read.
- **Lifetime.** `Max-Age` is the time until the token or the session expires, whichever comes first. When neither the token nor the session expires, no cookie is issued, and the request fails with `A session cookie cannot be issued because the session has no expiry`. [`POST /signout`](#signout) clears the cookie.
- **Refresh cookie.** When a record user signs in or signs up through a [record access method](/docs/reference/query-language/statements/define/access/record.md) defined `WITH REFRESH`, the response also sets a `surreal_refresh` cookie with the same attributes. Its `Max-Age` is the duration of the access method's refresh grant, and no refresh cookie is issued when the grant does not expire. [`POST /refresh/cookie`](#refresh-cookie) exchanges it for a new access cookie and a new refresh cookie, so the application does not have to sign in again when the access token expires. The server never authenticates a request with the refresh cookie itself. Without a refresh cookie, the application signs in again when the token expires.
- **HTTPS.** The cookie is `Secure`, so a browser stores it only over HTTPS or on a loopback address such as `localhost`.
- **Status codes.** Without `--cookie-auth`, `/signin/cookie`, `/signup/cookie`, `/refresh/cookie` and `/signout` answer `404`. With it, a request to one of them from an origin that is not allowed, or with no `Origin` header, answers `403` with the message `The request origin is not allowed to use cookie authentication`.

> [!NOTE]
> The `surreal_token` and `surreal_refresh` cookies are removed from `$request.headers` in a [`DEFINE API`](/docs/reference/query-language/statements/define/api.md) handler. Other cookies in the request stay.

## Scoped URLs {#scoped-urls}

_(since v4.0.0)_

The namespace, database and access method can be part of the URL path, in place of the `Surreal-NS` and `Surreal-DB` headers and the `ns`, `db` and `ac` fields of a signin or signup body. The request from [Authentication](#authentication) becomes:

```bash
curl -X POST -u "clerk:hunter123" \
  -H "Surreal-Auth-NS: shop" -H "Surreal-Auth-DB: orders" \
  -H "Accept: application/json" \
  -d "SELECT * FROM item;" \
  http://localhost:8000/ns/shop/db/orders/sql
```

> [!NOTE]
> SurrealDB 4.x introduces a new, streamlined URL structure, which gives smoother and more predictable URLs and is the basis for upcoming functionality. The unscoped routes, headers and body fields stay supported.

A scope goes in front of the endpoint path, and `ac` can follow any level, because an access method can be defined on the root, a namespace or a database:

```text
/ns/{ns}/{endpoint}
/ns/{ns}/db/{db}/{endpoint}
/ac/{ac}/{endpoint}
/ns/{ns}/ac/{ac}/{endpoint}
/ns/{ns}/db/{db}/ac/{ac}/{endpoint}
```

For example:

```text
POST /ns/shop/db/orders/sql
GET  /ns/shop/db/orders/rpc                  (WebSocket upgrade)
GET  /ns/shop/db/orders/key/person/tobie
ANY  /ns/shop/db/orders/api/orders/42
POST /ns/shop/db/orders/signin               (database user)
POST /ns/shop/db/orders/ac/users/signup      (record access method)
POST /ac/admins/signin                       (root access method)
```

Each segment is percent-decoded once, so the namespace `a/b` is sent as `/ns/a%2Fb/...`. An empty or malformed segment answers `404`.

### Endpoints that take a scope

| Endpoint | `ns` and `db` | `ac` |
| --- | --- | --- |
| `/sql`, `/rpc`, `/import`, `/export`, `/key`, `/ml`, `/gql`, `/graphql`, `/mcp`, `/api`, `/bucket` | Yes | No |
| `/signin`, `/signup`, `/signin/cookie`, `/signup/cookie` | Yes | Yes |
| `/signout`, `/refresh/cookie`, `/health`, `/status`, `/ready`, `/version`, `/kvexport` | No | No |

An endpoint under a scope it does not take answers `404`, rather than ignoring the scope. `/signout` and `/refresh/cookie` act on a credential the request already carries, which names its own namespace, database and access method.

The scoped form of a [custom endpoint](#custom) is `/ns/{ns}/db/{db}/api/{endpoint}`, which reaches the same handler as `/api/{ns}/{db}/{endpoint}`. A scoped `/api` path without a database answers `404`.

### Headers and credentials under a scope

The path and the other sources have to agree. The path never overrides a header, and a header never overrides the path:

| Path | Other source | Result |
| --- | --- | --- |
| `/ns/shop` | `Surreal-NS: shop` | Accepted |
| `/ns/shop` | `Surreal-NS: other` | `400` |
| `/ns/shop` | `Surreal-DB: orders` | Namespace `shop`, database `orders` |
| `/ns/shop/db/orders` | Token for a user on `shop`/`orders` | Accepted |
| `/ns/shop/db/orders` | Token for a user on `shop`/`other` | `401` |
| `/ns/shop` | Basic authentication as a user on namespace `other` | `401` |
| `/ns/shop` | Root credentials | Namespace `shop` |

### The scope is the starting selection

The namespace and database in the path are where a request or connection starts, in the same way as the `Surreal-NS` and `Surreal-DB` headers. The server checks them once, when it authenticates the request or the connection, and the credentials must belong to that namespace and database. After that, the session can change its selection as it can on an unscoped URL:

- A SurrealQL `USE`, or an RPC [`use`](/docs/reference/protocols/rpc-protocol.md#use), can select another namespace or database, if the user has permission there.
- An RPC [`signin`](/docs/reference/protocols/rpc-protocol.md#signin) or `signup` can name another namespace or database in its credentials.
- An RPC [`reset`](/docs/reference/protocols/rpc-protocol.md#reset) returns the session to no namespace and no database.

```bash
curl -X POST -u "root:secret" -H "Accept: application/json" \
  -d "RETURN session::db(); USE DB archive; RETURN session::db();" \
  http://localhost:8000/ns/shop/db/orders/sql
```

The first statement returns `"orders"`, and the last returns `"archive"`.

### Signing in under a scope

[`/signin`](#signin) and [`/signup`](#signup) complete their body from the path. The following request signs in with `{"ns": "shop", "db": "orders", "ac": "users", "email": "tobie@example.com", "pass": "secret"}`:

```bash
curl -X POST -H "Accept: application/json" \
  -d '{"email":"tobie@example.com","pass":"secret"}' \
  http://localhost:8000/ns/shop/db/orders/ac/users/signin
```

The path fixes the level the credentials act at. A body field that repeats the path is accepted. A body field that names something else answers `400`, and so does a namespace or database the path leaves out: `/ac/admins/signin` always signs in with a root access method, and `/ns/shop/signin` always signs in at the namespace level. Without `ac` in the path, the body can name an access method at the path's level.

Scoped and unscoped signin requests from one client draw on the same [authentication rate limit](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables).

## Request size limits

Each endpoint caps the size of the request body it will accept. A request over the cap is rejected with `413 Payload Too Large`. The limits differ per endpoint because they are sized to the work each one does: `/sql` takes a query, `/import` takes a data file.

The defaults are the same in 2.x and 3.x:

| Endpoint | Default limit | Environment variable |
| -------- | ------------- | -------------------- |
| `POST /sql` | 1 MiB | `SURREAL_HTTP_MAX_SQL_BODY_SIZE` |
| `POST /rpc` | 4 MiB | `SURREAL_HTTP_MAX_RPC_BODY_SIZE` |
| `/api/:namespace/:database/:endpoint` | 4 MiB | `SURREAL_HTTP_MAX_API_BODY_SIZE` |
| `POST /gql` | 1 MiB | `SURREAL_HTTP_MAX_GQL_BODY_SIZE` |
| `POST /graphql` _(since v4.0.0)_ | 1 MiB | `SURREAL_HTTP_MAX_GRAPHQL_BODY_SIZE` |
| `/key` CRUD endpoints | 16 KiB | `SURREAL_HTTP_MAX_KEY_BODY_SIZE` |
| `POST /signin` | 1 KiB | `SURREAL_HTTP_MAX_SIGNIN_BODY_SIZE` |
| `POST /signup` | 1 KiB | `SURREAL_HTTP_MAX_SIGNUP_BODY_SIZE` |
| `POST /import` | 4 GiB | `SURREAL_HTTP_MAX_IMPORT_BODY_SIZE` |
| `POST /mcp` _(since v3.1.0)_ | 4 MiB | `SURREAL_HTTP_MAX_MCP_BODY_SIZE` |
| `PUT /ns/:namespace/db/:database/bucket/:bucket/:key` _(since v4.0.0)_ | 5 GiB | `SURREAL_HTTP_MAX_BUCKET_BODY_SIZE` |

The WebSocket `/rpc` endpoint is not bound by an HTTP body size. It allows up to 128 MiB per message (`SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE`). As most SDKs use the WebSocket engine by default, they are able to send payloads that the plain HTTP endpoints reject. See [Message size limits](/docs/reference/protocols/rpc-protocol.md#message-size-limits) for how the server ceiling interacts with the limit an SDK applies on its own side.

### Choosing an endpoint for a large payload

The 1 MiB ceiling that a large query runs into applies only to the raw HTTP `/sql` endpoint. Larger payloads have somewhere to go:

* For ordinary queries, connect through a client SDK such as [Rust](/docs/reference/rust.md) or [JavaScript](/docs/reference/javascript.md). The WebSocket engine raises the per-message ceiling to 128 MiB.
* To stay on plain HTTP, use [`POST /rpc`](/docs/reference/protocols/rpc-protocol.md) for 4 MiB.
* For bulk data loading, use [`POST /import`](#import), which accepts up to 4 GiB per request.

### Tuning the limits

Every limit above is set by an [environment variable](/docs/reference/cli/db/environment-variables.md#http-server-config) on a self-hosted server. From 3.0 those variables accept byte-size suffixes such as `16MiB` or `4GB`; on 2.x they take a raw byte count.

SurrealDB Cloud instances run the defaults listed above.

<br />

## Request timeouts

_(since v3.3.0)_

When the server is started with [`--query-timeout`](/docs/reference/cli/db/environment-variables.md#command-environment-variables) (`SURREAL_QUERY_TIMEOUT`), the same duration also limits the wall-clock time of a whole request on these endpoints:

- [`POST /sql`](#sql) and the `/sql` WebSocket.
- [`POST /gql`](#gql).
- [`POST /graphql`](#graphql), for a single request and for a batch.
- `POST /rpc`, for every [RPC method](/docs/reference/protocols/rpc-protocol.md), in the same way as on the WebSocket `/rpc` endpoint and over gRPC. This includes `signin`, `signup` and `authenticate`.

No wall-clock limit applies unless the option is set. The RPC `begin`, `commit` and `cancel` methods are exempt, because stopping a commit part-way is unsafe, although each statement run inside the explicit transaction is still limited on its own. GraphQL subscriptions over WebSocket and the [`POST /signin`](#signin) and [`POST /signup`](#signup) endpoints are not covered by the wall-clock limit.

When the limit ends a request to `POST /sql` or `POST /gql`, the response is `504 Gateway Timeout` with an error body, where earlier releases answered a timed-out request with `400`. The status is `504` rather than `503` because load balancers commonly read `503` as an unhealthy node, and one slow query is no reason to take a node out of rotation. With `--query-timeout 5s`, the body reads:

```json title="Response"
{
	"code": 504,
	"details": "Query timeout",
	"description": "The request exceeded the configured query timeout. Reduce the work performed by the request or raise the timeout.",
	"information": "The query was not executed because it exceeded the timeout: 5s"
}
```

A `/graphql` request that runs out of time returns a GraphQL response whose error message reads `The GraphQL request was not executed because it exceeded the timeout: 5s`. A `POST /rpc` call returns an RPC error response with the message `The query was not executed because it exceeded the timeout: 5s`, and the `/sql` WebSocket sends the same message as text.

<br />

## Memory pressure

_(since v3.3.5)_

When the server is started with [`SURREAL_MEMORY_THRESHOLD`](/docs/reference/cli/db/environment-variables.md#limits-config) and its tracked memory is above that size, `POST /rpc` refuses a request before it reads the body. The response is `503 Service Unavailable` with a `Retry-After: 1` header, so load balancers and clients can retry it once memory is released:

```json title="Response"
{
	"code": 503,
	"details": "Service unavailable",
	"description": "The server is under memory pressure and refused this request. Retry shortly.",
	"information": "..."
}
```

Before SurrealDB 3.3.5, the same refusal was answered with `400 Bad Request`.

<br />

## Datetimes and other types in a JSON body

JSON has no datetime, record ID or duration type, so a value sent in a JSON body, such as to `POST /key/:table`, arrives as a plain string. `{ "at": "2026-01-01T10:00:00Z" }` stores `at` as a string, and a field defined with `TYPE datetime` refuses it, because `TYPE` is checked before any conversion.

There are three ways to store a typed value:

- **Use SurrealQL in the query.** Through `POST /sql`, write the value as a literal, such as `d"2026-01-01T10:00:00Z"`, or cast a parameter with `<datetime> $at`.
- **Convert it in the field definition.** A field defined with `VALUE <datetime> $value` and no `TYPE`, or with `TYPE datetime | string`, converts the string when it is written, so every client can send JSON:

```surql
DEFINE FIELD at ON event VALUE <datetime> $value;
```

- **Use an SDK.** The SDKs exchange values with the server in CBOR, which keeps SurrealQL types, so a datetime from your language arrives as a datetime.

## `GET /status` {#status}

This HTTP RESTful endpoint checks whether the database web server is running, returning a 200 status code.

### Example usage

```bash title="Request"
curl -I http://localhost:8000/status
```

```bash title="Example output"
HTTP/1.1 200 OK
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.0.0
server: SurrealDB
x-request-id: fdb9bcdb-b085-4da0-80ef-a61105c432f9
content-length: 0
date: Tue, 03 Feb 2026 02:10:33 GMT
```

<br />

## `GET /health` {#health}

This HTTP RESTful endpoint checks whether the storage engine responds, by reading one key in a read-only transaction. It returns `200` when the read succeeds and `500` when it fails, or `403` when the `health` route is denied by [capabilities](/docs/learn/security/authorization/capabilities.md#http-route-names).

From SurrealDB 3.3.5, on a server started with [`SURREAL_MEMORY_THRESHOLD`](/docs/reference/cli/db/environment-variables.md#limits-config), `/health` also returns `503 Service Unavailable` once the memory threshold has refused every request without a break for `SURREAL_MEMORY_THRESHOLD_UNHEALTHY_AFTER` seconds, 60 by default. A process in that state does not release memory until it restarts, so a liveness probe on `/health` restarts it. A single moment below the threshold resets the count.

`/health` stays reachable while the server is still starting up, so a `200` shows that the storage engine answers, not that startup has finished. [`GET /ready`](#ready) is the endpoint that reports whether it has.

```bash title="Request"
curl -I http://localhost:8000/health
```

```bash title="Example output"
HTTP/1.1 200 OK
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.0.0
server: SurrealDB
x-request-id: 66938ec2-ad7c-4afb-928d-683e7a75433a
content-length: 0
date: Tue, 03 Feb 2026 02:15:08 GMT
```

<br />

## `GET /ready` {#ready}

_(since v3.2.0)_

This HTTP RESTful endpoint is the startup and readiness probe. It returns `200` when both of these hold:

- The startup work that follows opening the datastore has finished. From 3.3.0 this covers the version check and any data migrations, the default namespace and database, the root credentials, node registration, and any import set with `--import-file`.
- The node's cluster heartbeat is recent. The node refreshes it every `--node-membership-refresh-interval`, 3 seconds by default, and `/ready` treats it as stale once it is more than three intervals old.

It returns `503` while startup is still running, when the heartbeat is stale, or when the node has no cluster membership record, and `500` when the heartbeat cannot be read. A node with no cluster membership record returned `500` before 3.3.0. SurrealDB Enterprise adds conditions of its own, such as a valid [licence](/docs/operate/enterprise.md).

Until startup finishes, every other path except `/`, `/status`, `/health`, `/version` and `/metrics` returns `503` with `Retry-After: 1`, so query and authentication requests wait for the node while `/ready` stays reachable and orchestrators can tell a starting node from a failed one. With no import configured, the server waits up to 5 seconds for startup before it accepts connections, so an ordinary start reports `200` from the first probe. A start with an import accepts connections straight away, and one that runs past 5 seconds accepts them at that point, and both report `503` until startup finishes. A failure to initialise the datastore stops the process, while a failed import or credential initialisation leaves the server running and `/ready` at `503`.

Contrast with [`GET /status`](#status) (process and listener liveness only) and [`GET /health`](#health) (storage backend reachability only).

The CLI [`surreal db isready`](/docs/reference/cli/db/commands/isready.md) command calls this endpoint.

```bash title="Request"
curl -i http://localhost:8000/ready
```

```bash title="Output (ready)"
HTTP/1.1 200 OK
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.2.0
server: SurrealDB
content-length: 0
```

```bash title="Output (still starting)"
HTTP/1.1 503 Service Unavailable
content-type: application/json

{"code":503,"details":"Service unavailable","description":"The server is still starting up and cannot serve this request yet. Retry once the instance is ready.","information":"The server is still starting up and is not ready to serve requests"}
```

A gated endpoint returns the same body with a `retry-after: 1` header, which `/ready` itself does not send.

<br />

## `GET /version` {#version}

This HTTP RESTful endpoint returns the version of the SurrealDB database server.

### Example usage

```bash title="Request"
curl http://localhost:8000/version
```

```bash title="Example output"
surrealdb-4.0.0
```

<br />

## `POST /import` {#import}

This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific namespace and database.

The body is streamed: the server parses and applies statements as the bytes arrive rather than buffering the whole file. This is the endpoint to use for bulk data loading, since it accepts far more than [`/sql`](#sql) or [`/rpc`](/docs/reference/protocols/rpc-protocol.md) do.

### Size limit and partial imports

The default cap is 4 GiB (`SURREAL_HTTP_MAX_IMPORT_BODY_SIZE`). Two details of how it is enforced matter when planning an import:

* **The cap is cumulative for one request, not per chunk.** The limiter decrements a single allowance across every frame of the stream. A request whose `Content-Length` exceeds the cap is rejected immediately with `413`; a chunked request is accepted and then fails partway through, once the total bytes received cross the cap. Split larger datasets across several files rather than sending one oversized request. The gRPC import path enforces the same cumulative cap.
* **A failed import is partially applied.** Statements are committed as they are parsed, so an import that trips the cap - or is interrupted for any other reason - leaves everything applied up to that point in place. There is no rollback.
* **A partial import returns `422`.** From SurrealDB 3.3.1, the endpoint answers `422 Unprocessable Entity` when at least one statement did not apply, with the failures in the response body. A `2xx` status means that every statement applied. Earlier versions answered `200` for an import that only partly applied.

> [!IMPORTANT]
> Because a failed import leaves partial data behind, plan for how you would retry. Either structure the file so that re-running it is safe, or import into a fresh namespace or database and swap it in once the import has finished successfully.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the root, namespace, or database authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Example usage

> [!NOTE]
> The `-u` in the example below is a shorthand used by curl to send an Authorization header (name and password), in this case assuming the username `root` and password `secret`.

```bash title="Request"
curl -X POST -u "root:secret" \
  -H "Surreal-NS: main" \
  -H "Surreal-DB: main" \
  -H "Accept: application/json" \
  -d file.surql \
  http://localhost:8000/import
```

<br />

## `POST /export` {#export}

This HTTP RESTful endpoint exports all data for a specific Namespace and Database.

The caller must be a system user with a role (`VIEWER`, `EDITOR` or `OWNER`) at the database level or above. A record user, and a token that holds no role, are refused with `403` and the message `IAM error: Not enough permissions to perform this action`.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the root, namespace, or database authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

#### Export options

<table>
    <thead>
        <tr>
            <th>Arguments</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>
                `only`
                <label label="optional" />
            </td>
            <td>
                Whether only specific resources should be exported. When provided, only the resources specified will be exported.
            </td>
        </tr>
        <tr>
            <td>
                `users`
                <label label="optional" />
            </td>
            <td>
                Whether system users should be exported [possible values: true, false].
            </td>
        </tr>
        <tr>
            <td>
                `accesses`
                <label label="optional" />
            </td>
            <td>
                Whether access methods (Record or JWT) should be exported [possible values: true, false]
            </td>
        </tr>
        <tr>
            <td>
                `params`
                <label label="optional" />
            </td>
            <td>
                Whether databases parameters should be exported [possible values: true, false]
            </td>
        </tr>
        <tr>
            <td>
                `functions`
                <label label="optional" />
            </td>
            <td>
                Whether functions should be exported [possible values: true, false]
            </td>
        </tr>
        <tr>
            <td>
                `analyzers`
                <label label="optional" />
            </td>
            <td>
                Whether analyzers should be exported [possible values: true, false]
            </td>
        </tr>
        <tr>
            <td>
                `tables [tables]`
                <label label="optional" />
            </td>
            <td>
                Whether tables should be exported, optionally providing a list of tables
            </td>
        </tr>
        <tr>
            <td>
                `versions`
                <label label="optional" />
            </td>
            <td>
                Whether SurrealKV versioned records should be exported [possible values: true, false]
            </td>
        </tr>
        <tr>
            <td>
                `records`
                <label label="optional" />
            </td>
            <td>
                Whether records should be exported [possible values: true, false]
            </td>
        </tr>
    </tbody>
</table>

### Example usage

> [!NOTE]
> The `-u` in the example below is a shorthand used by curl to send an Authorization header (name and password), in this case assuming the username `root` and password `secret`. The `-o` allows the output to be written to a file.

```bash title="Request"
curl -X GET \
  -u "root:secret" \
  -H "Surreal-NS: main" \
  -H "Surreal-DB: main" \
  -H "Accept: application/json" \
  -o file.surql \
  http://localhost:8000/export
```

```bash title="Exporting specific parameters"
curl -X POST \
  -u "root:secret" \
  -H "Surreal-NS: main" \
  -H "Surreal-DB: main" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -o file.surql \
  -d '{
        "users": true,
        "accesses": false,
        "params": false,
        "functions": false,
        "analyzers": false,
        "versions": false,
        "tables": ["usersTable", "ordersTable"],
        "records": true
      }' \
  http://localhost:8000/export
```

<br />

## `POST /kvexport` {#kvexport}

This HTTP RESTful endpoint streams the open datastore's entire keyspace from a single snapshot. Unlike [`POST /export`](#export), which writes a SurrealQL export of one Namespace and Database, `/kvexport` streams the raw stored bytes of the whole datastore, so another instance can be seeded from a byte-level copy. It is a low-level operation, intended for migrating or cloning a datastore rather than for everyday backups.

The name stands for key-value export. SurrealDB keeps every record, definition and index entry as keys and values in its storage engine, and this endpoint exports those keys and values as they are stored, where `/export` writes SurrealQL statements that rebuild them. The endpoint exists to move a datastore to a different storage engine without an export and import. The new instance reads the stream and writes the keys into its own datastore before it starts. Because the copy includes the record of which data migrations the datastore has run, the new instance applies any that are still owed at startup, as it would on the original datastore. A SurrealQL import, by comparison, replays every statement through the query engine and starts from an empty datastore.

`POST /kvexport` is available in SurrealDB 3.2.6, 3.3.5 and 4.0.

> [!IMPORTANT]
> `POST /kvexport` is an experimental feature and is off by default. Start the server with `--allow-experimental kvexport` to enable it. It has its own HTTP route target, so `--deny-http kvexport` turns it off without affecting [`/export`](#export). See the [capabilities documentation](/docs/learn/security/authorization/capabilities.md) for how experimental features are enabled.

> [!WARNING]
> The stream carries the raw stored bytes, so it includes everything a SurrealQL export redacts: password hashes, each user's token-signing key, and the keys of access methods. A reader of the stream can mint tokens for this instance that outlive a password change. Only the root user with the owner role can call this endpoint, and every lower role is refused. The route reads no request body until the caller is authorised, and it never logs a request or response body.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Header">
                Authenticates the caller as the root user with the owner role, which this endpoint requires.
            </td>
        </tr>
    </tbody>
</table>

The endpoint streams the whole datastore, so it does not take the `Surreal-NS` or `Surreal-DB` headers.

#### Request body

The request body is an optional JSON object of up to 128 MiB. An empty body asks for the whole keyspace.

<table>
    <thead>
        <tr>
            <th>Field</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>
                `after`
                <label label="optional" />
            </td>
            <td>
                The hex encoding of a key. The stream starts at the first key after it, in key order. A caller that resumes a copy passes the last key it wrote.
            </td>
        </tr>
        <tr>
            <td>
                `latest_only`
                <label label="optional" />
            </td>
            <td>
                Set to `true` to copy a datastore that keeps version history. The stream then carries each key's latest value only. Without it, a versioned datastore is refused with `409 Conflict` rather than copied without its history.
            </td>
        </tr>
    </tbody>
</table>

### Response

The response is streamed, never compressed, and has the content type `application/vnd.surrealdb.kvexport`. It has four parts:

1. The four bytes `SKVX` and a format byte (`1`).
2. A `u32` length and that many bytes of JSON holding the source's keyspace version, read in the same snapshot as the data. A target checks it before it writes anything.
3. The data frames. Each frame is a `1` byte, a `u32` key length, the key, a `u32` value length, and the value.
4. A `0` byte, then the 32-byte BLAKE3 digest of every byte before it.

All lengths are little-endian. Every frame is read in one transaction, so the stream is a single snapshot of the keyspace, whatever the source commits while it is served. Frames come in key order, except the keyspace version key, which comes last. A body that stops before the digest, or whose digest does not match, was cut short.

### Example usage

> [!NOTE]
> The `-u` in the examples below is curl shorthand for an Authorization header (username and password), here the root user `root` with the password `secret`. The `-o` writes the output to a file.

```bash title="Request"
curl -X POST \
  -u "root:secret" \
  -o datastore.kvexport \
  http://localhost:8000/kvexport
```

```bash title="Resuming after a key, latest values only"
curl -X POST \
  -u "root:secret" \
  -H "Content-Type: application/json" \
  -o datastore.kvexport \
  -d '{
        "after": "<hex-of-last-written-key>",
        "latest_only": true
      }' \
  http://localhost:8000/kvexport
```

<br />

## `POST /signin` {#signin}

```json title="Method and URL"
POST /signin
```

This HTTP RESTful endpoint is used to access an existing account inside the SurrealDB database server.

When [authentication rate limiting](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) is enabled, an attempt beyond the client address's budget is refused with `429 Too Many Requests` and a `Retry-After` header giving the number of seconds to wait, and the error body says that too many authentication attempts were made from this client address. `/signin` and [`/signup`](#signup) draw on the same budget, and so does a request to any endpoint that carries HTTP Basic credentials. Authentication rate limiting is available from SurrealDB 3.3.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
     <tr>
            <td colspan="2" scope="row" data-label="Header">
                    <code>Accept</code>
                    <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
    </tbody>
</table>

### Data

<table>
    <thead>
        <tr>
            <th colspan="2">Data</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
    <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>ns</code>
                <label label="required">REQUIRED FOR DB & RECORD</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The namespace to sign in to this is required FOR DB & RECORD users
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>db</code>
                <label label="required">REQUIRED FOR RECORD</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The database to sign in to required for RECORD users
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>ac</code>
                <label label="required">REQUIRED FOR RECORD USER</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The record access method to use for signing in. required for RECORD users
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>user</code>
                <label label="required">REQUIRED FOR ROOT, NS & DB</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            The username of the database user required for ROOT, NS & DB users
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>pass</code>
                <label label="required">REQUIRED FOR ROOT, NS & DB</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            The password of the database user required for ROOT, NS & DB users
            </td>
        </tr>
    </tbody>
</table>

> [!IMPORTANT]
> The `ac` parameter is only required if you are signing in using an [access method](/docs/reference/query-language/statements/define/access.md) as a record user. For system users on the database, namespace, and root level, this parameter can be omitted.

### Example with a record user

The following example will work as long as an access method has been defined and a record user has been signed up using the [`/signup`](#signup) endpoint.

```bash title="Request"
curl -X POST -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"users","user":"johndoe","pass":"123456"}' http://localhost:8000/signin
```

```json title="Response"
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

### Example with root user

```bash title="Request"
curl -X POST -H "Accept: application/json" -d '{"user":"root","pass":"secret"}' http://localhost:8000/signin
```

```json title="Response"
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

### Example with namespace user

To create the namespace user needed for the following query, use the following command.

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'DEFINE USER johndoe ON NAMESPACE PASSWORD "123456" ROLES EDITOR' http://localhost:8000/sql
```

Once the user has been created, use this command to sign in.

```bash title="Request"
curl -X POST -H "Accept: application/json" -d '{"ns":"main","user":"johndoe","pass":"123456"}' http://localhost:8000/signin
```

```json title="Response"
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

### Example with a scoped URL

_(since v4.0.0)_

The namespace, database and access method can be part of the path instead of the body. See [Scoped URLs](#scoped-urls).

```bash title="Request"
curl -X POST -H "Accept: application/json" -d '{"user":"johndoe","pass":"123456"}' http://localhost:8000/ns/main/db/main/ac/users/signin
```

### Example usage via postman

After you have defined the permissions for the record user, you can use the `POST /signin` endpoint to sign in as a user.

Using the [user credentials](/docs/learn/security/authentication/users.md#record-users) created add the following to the request body:
```json
{
    "ns": "main",
    "db": "main",
    "ac": "account",
    "email": "",
    "pass": "123456"
}
```

<br />

## `POST /signup` {#signup}

This HTTP RESTful endpoint is used to create an account inside the SurrealDB database server.

When [authentication rate limiting](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) is enabled, an attempt beyond the client address's budget is refused with `429 Too Many Requests` and a `Retry-After` header giving the number of seconds to wait. `/signup` shares its budget with [`/signin`](#signin). Authentication rate limiting is available from SurrealDB 3.3.

### Header

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
    </tbody>
</table>

### Data

<table>
    <thead>
        <tr>
            <th colspan="2">Data</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>ns</code>
                <label label="required"></label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The namespace to sign up to. This data is `REQUIRED FOR DB & RECORD`
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>db</code>
                <label label="required"></label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The database to sign up to. This data is `REQUIRED FOR RECORD`
            </td>
        </tr>
                <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>access</code>
                <label label="required"></label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                The record access method to use for signing up. This data is `REQUIRED FOR RECORD`
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>user</code>
                <label label="required"></label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            The username of the database user. This data is `REQUIRED FOR ROOT, NS & DB`
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>pass</code>
                <label label="required"></label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            The password of the database user. This data is `REQUIRED FOR ROOT, NS & DB`
            </td>
        </tr>
    </tbody>
</table>

### Example usage

```bash title="Request"
curl -X POST -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"users","user":"johndoe","pass":"123456"}' http://localhost:8000/signup
```

```json title="Response"
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

The above example will only work if a record access method has already been set up.

### Setting up a record access method

Before you sign up a new [record user](/docs/learn/security/authentication/users.md#record-users), you must first [define a record access method](/docs/reference/query-language/statements/define/access/record.md) for the user. The following curl command will do so on the command line using the [`POST /sql`](#sql) endpoint.

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'DEFINE ACCESS users ON DATABASE TYPE RECORD
    SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
    SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
    DURATION FOR SESSION 24h' http://localhost:8000/sql
```

To do the same using Postman, use the following steps:

1. Navigate to the `POST /sql` endpoint in Postman.
2. Enter the following query in the body of the request:
```surql
-- Enable authentication directly against a SurrealDB record
DEFINE ACCESS users ON DATABASE TYPE RECORD
    SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
    SIGNIN ( SELECT * FROM user WHERE email = $email
      AND crypto::argon2::compare(pass, $pass) )
    DURATION FOR SESSION 24h
;
```

The above query defines a record access method called `account` that allows users to sign up and sign in. The access method also defines the session duration to be 24 hours.

3. Click `Send` to send the request to the SurrealDB database server.
4. Navigate to the `POST /signup` endpoint in Postman.
5. Enter the following query in the body of the request:

```json
{
    "ns": "main",
    "db": "main",
    "ac": "users",
    "email": "",
    "pass": "123456"
}
```
6. In the header of the request, set the following key-value pairs:
    - `Accept: application/json`
    - namespace: `test`
    - database: `test`
    - access: `account`
6. Click `Send` to send the request to the SurrealDB database server. You will receive the following response.

```json
{
    "code": 200,
    "details": "Authentication succeeded",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDY2MTA4MDMsIm5iZiI6MTcwNjYxMDgwMywiZXhwIjoxNzA2Njk3MjAzLCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJBQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOjZsOTl1OWI0bzVoa3h0NnY3c3NzIn0.3jR8PHgS8iLefZDuPHBFcdUFNfuB3OBNqQtqxLVVzxAIxVj1RAkD5rCEZHH2QaPV-D2zNwYO5Fh_a8jD1l_cqQ"
}
```

<br />

## `POST /signin/cookie` {#signin-cookie}

_(since v4.0.0)_

This endpoint signs in in the same way as [`POST /signin`](#signin), and takes the same headers and data. Instead of returning the token in the response body, it sets it in the `surreal_token` cookie. The server provides the endpoint only when it is started with `--cookie-auth`. See [Cookie authentication](#cookie-authentication) for the cookie attributes and the origins that can use it.

The endpoint shares its [authentication rate limit](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) budget with `/signin`.

### Example usage

```bash title="Request"
curl -i -X POST -H "Origin: https://app.example.com" -H "Accept: application/json" -d '{"user":"root","pass":"secret"}' https://db.example.com/signin/cookie
```

```text title="Response"
HTTP/1.1 200 OK
set-cookie: surreal_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=3600

{"code":200,"details":"Authentication succeeded"}
```

## `POST /signup/cookie` {#signup-cookie}

_(since v4.0.0)_

This endpoint signs up a record user in the same way as [`POST /signup`](#signup), and takes the same headers and data. Instead of returning the token in the response body, it sets it in the `surreal_token` cookie. The server provides the endpoint only when it is started with `--cookie-auth`. See [Cookie authentication](#cookie-authentication).

The endpoint shares its [authentication rate limit](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) budget with `/signup`.

### Example usage

```bash title="Request"
curl -i -X POST -H "Origin: https://app.example.com" -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"users","email":"tobie@example.com","pass":"secret"}' https://db.example.com/signup/cookie
```

```text title="Response"
HTTP/1.1 200 OK
set-cookie: surreal_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900

{"code":200,"details":"Authentication succeeded"}
```

## `POST /refresh/cookie` {#refresh-cookie}

_(since v4.0.0)_

This endpoint exchanges the `surreal_refresh` cookie that [`POST /signin/cookie`](#signin-cookie) or [`POST /signup/cookie`](#signup-cookie) set for a new `surreal_token` cookie and a new `surreal_refresh` cookie. The request needs no body. The server provides the endpoint only when it is started with `--cookie-auth`, and the request has to come from an allowed origin. See [Cookie authentication](#cookie-authentication).

A refresh token can be used once. If the cookie is missing, or its refresh token has expired, has been revoked or has already been used, the endpoint answers `401` and does not change any cookie. Because each refresh token can be used once, two refreshes sent at the same time, for example from two tabs, cannot both succeed, so an application should send one refresh at a time.

The endpoint shares its [authentication rate limit](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) budget with `/signin`.

### Example usage

```bash title="Request"
curl -i -X POST -H "Origin: https://app.example.com" -H "Accept: application/json" -b "surreal_refresh=..." https://db.example.com/refresh/cookie
```

```text title="Response"
HTTP/1.1 200 OK
set-cookie: surreal_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900
set-cookie: surreal_refresh=...; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=2592000

{"code":200,"details":"Authentication succeeded"}
```

## `POST /signout` {#signout}

_(since v4.0.0)_

This endpoint clears the `surreal_token` and `surreal_refresh` cookies that [`POST /signin/cookie`](#signin-cookie), [`POST /signup/cookie`](#signup-cookie) or [`POST /refresh/cookie`](#refresh-cookie) set. When the request carries a refresh cookie whose refresh token is valid, the server also revokes that refresh token, so it cannot be used again. The cookies are cleared whether or not the revocation succeeds. The server provides the endpoint only when it is started with `--cookie-auth`, and the request has to come from an allowed origin. See [Cookie authentication](#cookie-authentication).

The endpoint shares its [authentication rate limit](/docs/reference/cli/db/environment-variables.md#authentication-rate-limiting-environment-variables) budget with `/signin`.

### Example usage

```bash title="Request"
curl -i -X POST -H "Origin: https://app.example.com" https://db.example.com/signout
```

```text title="Response"
HTTP/1.1 200 OK
set-cookie: surreal_token=; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=0
set-cookie: surreal_refresh=; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=0
```

<br />

## `GET /key/:table` {#get-table}

This HTTP RESTful endpoint selects all records in a specific table in the database.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Query parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `limit` | `100` | The maximum number of records to return. |
| `start` | `0` | The number of records to skip before the first one returned. |
| `fields` | all fields | A field to return. Repeat it for several fields, as in `?fields=name&fields=email`. The record `id` is only included when it is one of the fields named. |

> [!IMPORTANT]
> Without a `limit`, this endpoint returns at most 100 records, even when the table holds more. Use `limit` and `start` to page through a larger table, or [`POST /sql`](#sql) for a query without a limit. A value that is not a number, such as `?limit=abc`, returns `400 Bad Request`.

### Translated query
```surql notest
-- Without `fields`
SELECT * FROM type::table($table) LIMIT $limit START $start;
-- With `fields`
SELECT type::fields($fields) FROM type::table($table) LIMIT $limit START $start;
```

### Example usage

```bash
curl -X GET -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person
```

To return the second page of 50 records, with only the `name` field:

```bash
curl -X GET -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" "http://localhost:8000/key/person?limit=50&start=50&fields=name"
```

<br/>

## `POST /key/:table` {#post-table}

This HTTP RESTful endpoint creates a record in a specific table in the database.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single inert value** (parsed with the SurrealQL value grammar and bound to **`$data`** in the translated statement). Literals, `$param` references, and constants are allowed; function calls, statements, and parenthesised executable forms are rejected. The body is not executed as a script. Use [`/sql`](/docs/reference/protocols/http-protocol.md#sql) or RPC when you need to run queries in the request body. JSON-shaped objects such as `{ name: "Billy" }` are valid SurrealQL values and are the usual choice on the wire.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query
```surql notest
CREATE type::table($table) CONTENT $data;
```

### Example usage

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ name: "Billy" }' http://localhost:8000/key/person
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:sf8l6ejkm6swdwoyx2mt",
				"name": "Billy"
			}
		],
		"status": "OK",
		"time": "160.375µs",
		"type": null
	}
]
```

<br />

## `PUT /key/:table` {#put-table}

This HTTP RESTful endpoint updates all records in a specific table in the database.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single inert value** (SurrealQL literal / object syntax; not an executable statement). Use [`/sql`](/docs/reference/protocols/http-protocol.md#sql) or RPC to run SurrealQL in the request body.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query
```surql notest
UPDATE type::table($table) CONTENT $data;
```

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ name: "Billy" }' http://localhost:8000/key/person
```

Then use this `PUT` endpoint to modify the existing record.

```bash
curl -X PUT -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ name: "Not Billy anymore" }' http://localhost:8000/key/person
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:f8i2ej4xluh5dgw2lgko",
				"name": "Not Billy anymore"
			}
		],
		"status": "OK",
		"time": "109.458µs",
		"type": null
	}
]
```

<br />

## `PATCH /key/:table` {#patch-table}

This HTTP RESTful endpoint modifies all records in a specific table in the database.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single inert value** (SurrealQL literal / object syntax; not an executable statement). Use [`/sql`](/docs/reference/protocols/http-protocol.md#sql) or RPC to run SurrealQL in the request body.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query
```surql notest
UPDATE type::table($table) MERGE $data;
```

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ id: person:one, name: "Billy" }' http://localhost:8000/key/person
```

Then use this `PATCH` endpoint to modify the existing records.

```bash
curl -X PATCH -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ "name": "Not Billy anymore" }' http://localhost:8000/key/person
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:one",
				"name": "Not Billy anymore"
			}
		],
		"status": "OK",
		"time": "162.167µs",
		"type": null
	}
]
```

<br />

## `DELETE /key/:table` {#delete-table}

This HTTP RESTful endpoint deletes all records from the specified table in the database.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query
```surql notest
DELETE FROM type::table($table) RETURN BEFORE;
```

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ id: person:one, name: "Billy" }' http://localhost:8000/key/person
```

Then use this `DELETE` endpoint to delete and return the records that were just removed.

```bash
curl -X DELETE -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:one",
				"name": "Billy"
			}
		],
		"status": "OK",
		"time": "234.75µs",
		"type": null
	}
]
```

<br />

## `GET /key/:table/:id` {#get-record}

This HTTP RESTful endpoint selects a specific record from the database.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query

```surql
SELECT * FROM type::record($table, $id);
```

<br />

### Example usage

```bash
curl -X GET -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person/1
```

<br/>

## `POST /key/:table/:id` {#post-record}

This HTTP RESTful endpoint creates a specific record in a table in the database.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query

```surql notest
CREATE type::record($table, $id) CONTENT $data;
```

<br />

### Example usage

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ name: "Billy" }' http://localhost:8000/key/person/1
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:1",
				"name": "Billy"
			}
		],
		"status": "OK",
		"time": "103.542µs",
		"type": null
	}
]
```

## `PUT /key/:table/:id` {#put-record}

This HTTP RESTful endpoint updates a specific record in a table in the database.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single inert value** (SurrealQL literal / object syntax; not an executable statement). Use [`/sql`](/docs/reference/protocols/http-protocol.md#sql) or RPC to run SurrealQL in the request body.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query

```surql
UPDATE type::record($table, $id) CONTENT $data;
```

<br />

## `PATCH /key/:table/:id` {#patch-record}

This HTTP RESTful endpoint modifies a specific record in a table in the database.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single inert value** (SurrealQL literal / object syntax; not an executable statement). Use [`/sql`](/docs/reference/protocols/http-protocol.md#sql) or RPC to run SurrealQL in the request body.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query

```surql
UPDATE type::record($table, $id) MERGE $data;
```

<br />

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ name: "Billy" }' http://localhost:8000/key/person/1
```

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ id: person:one, name: "Billy" }' http://localhost:8000/key/person
```

Then use this `PATCH` endpoint to modify the existing record.

```bash
curl -X PATCH -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ "name": "Not Billy anymore" }' http://localhost:8000/key/person/1
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:one",
				"name": "Not Billy anymore"
			}
		],
		"status": "OK",
		"time": "162.167µs",
		"type": null
	}
]
```

<br/>

## `DELETE /key/:table/:id` {#delete-record}

This HTTP RESTful endpoint deletes a single specific record from the database.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Translated query

```surql
DELETE FROM type::record($table, $id) RETURN BEFORE;
```

<br />

### Example usage

To use this example, first create a record using the `POST` endpoint:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d '{ id: person:one, name: "Billy" }' http://localhost:8000/key/person/1
```

Then use this `DELETE` endpoint to delete and return the record that was just removed.

```bash
curl -X DELETE -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person/1
```

```json title="Response"
[
	{
		"result": [
			{
				"id": "person:one",
				"name": "Billy"
			}
		],
		"status": "OK",
		"time": "145.042µs",
		"type": null
	}
]
```

<br/>

## `POST /sql` {#sql}

The SQL endpoint enables use of SurrealQL queries.

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a set of SurrealQL statements.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Parameters

Query parameters can be provided via URL query parameters. These parameters will securely replace any parameters that are present in the query. This practise is known as prepared statements or parameterised queries, and [should be used](/docs/learn/security/best-practices/security-best-practices.md#query-safety) whenever untrusted inputs are included in a query to prevent injection attacks.

A URL parameter always arrives as a string, so `?age=18` sets `$age` to `"18"`. Cast it in the query where another type is needed, as in `<int> $age` below, because a number compared with a string is never equal to it. To send an object, an array or other structured values, use [`POST /rpc`](/docs/reference/protocols/rpc-protocol.md#query) with the `query` method instead, which takes the variables as JSON:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"id": 1, "method": "query", "params": ["CREATE person CONTENT $data", {"data": {"name": "Ann", "tags": ["a", "b"]}}]}' \
  http://localhost:8000/rpc
```

### Example usage

> [!NOTE]
> The `-u` in the example below is a shorthand used by curl to send an Authorization header (name and password), in this case assuming the username `root` and password `secret`.

**V2.x+**

```bash title="Request"
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'SELECT * FROM person WHERE age > <int> $age' http://localhost:8000/sql?age=18
```

**V2.x with token**

```bash title="Request"
curl -X POST -H "Bearer: YourToken" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" \
  -d 'SELECT * FROM person WHERE age > <int> $age' http://localhost:8000/sql?age=18
```

```json title="Response"
[
	{
		"time": "14.357166ms",
		"status": "OK",
		"result": [
			{
				"age": "23",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Simon",
			},
			{
				"age": "28",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Marcus",
			},
		]
	}
]
```

### Usage in importing data

_(since v3.0.4)_

As of SurrealDB 3.0.4, imports via the [`surreal db import`](/docs/reference/cli/db/commands/import.md) and [`/import`](#import) HTTP endpoint require the automatically generated `OPTION IMPORT` line to be present in order to disable events, live queries, field processing, and result output for optimal import performance. If side effects are desired when importing data, remove the line and use this endpoint instead.

<br />

## `POST /gql` {#gql}

_(since v3.2.0)_

The GQL endpoint runs [ISO GQL](/docs/learn/querying/gql/overview.md) graph pattern queries against your existing tables and `RELATE` edges - `MATCH … RETURN` reads and data-modifying `INSERT`, `SET`, `REMOVE`, and `DELETE` ([GQL mutations](/docs/learn/querying/gql/mutations.md)).

> [!NOTE]
> From **3.3.0**, GQL is enabled by default - no experimental capability is required. On **3.2.x**, enable it with [`--allow-experimental gql`](/docs/reference/cli/db/commands/start.md#experimental-capabilities) (or `SURREAL_CAPS_ALLOW_EXPERIMENTAL=gql`). `--allow-all` does not enable experimental capabilities on 3.2.x.

> [!NOTE]
> This endpoint is **not** [GraphQL](/docs/learn/querying/graphql/overview.md). GraphQL queries belong on [`POST /graphql`](#graphql).

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a **single raw GQL query** (UTF-8 text), not JSON-wrapped. Use [`POST /sql`](#sql) for SurrealQL.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response (`application/json` or `application/cbor`)
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Parameters

Pass GQL parameters through **WebSocket RPC** (`method: "gql"`, second element of `params` as a JSON object with typed values).

### Example usage

> [!NOTE]
> The `-u` in the example below is a shorthand used by curl to send an Authorization header (name and password), in this case assuming the username `root` and password `secret`.

```bash title="Request"
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json" -H "Content-Type: text/plain" \
  -d 'MATCH (n:person) RETURN n.name AS name ORDER BY name' \
  http://localhost:8000/gql
```

```json title="Response"
[
	{
		"status": "OK",
		"result": [
			{ "name": "A" },
			{ "name": "B" },
			{ "name": "C" }
		],
		"time": "1.5ms"
	}
]
```

Parse errors return **HTTP 400** with an error payload. See [GQL via HTTP](/docs/learn/querying/gql/via-http.md) for enabling GQL, seeding data, and RPC examples.

<br />

## `POST /graphql` {#graphql}

The GraphQL endpoint enables use of GraphQL queries to interact with your data.

> [!NOTE]
> This endpoint is **not** [ISO GQL](/docs/learn/querying/gql/overview.md). GQL `MATCH` queries belong on [`POST /gql`](#gql).

> [!NOTE]
> This HTTP endpoint expects the HTTP body to be a GraphQL query.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
            Sets the root, namespace, database, or record authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Accept</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the desired content-type of the response
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries
            </td>
        </tr>
    </tbody>
</table>

### Example usage

> [!NOTE]
> The `-u` in the example below is a shorthand used by curl to send an Authorization header (name and password), in this case assuming the username `root` and password `secret`.

First, use the `/sql` endpoint to send in a [`DEFINE CONFIG`](/docs/reference/query-language/statements/define/config.md#define-config-graphql) statement to set the database up to use GraphQL.

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'DEFINE TABLE person SCHEMAFULL; DEFINE FIELD name ON TABLE person TYPE string; DEFINE FIELD age ON TABLE person TYPE number;' \
  http://localhost:8000/sql

curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'CREATE person:simon SET name = "Simon", age = 23; CREATE person:marcus SET name = "Marcus", age = 28;' \
  http://localhost:8000/sql

curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json"
  -d 'DEFINE CONFIG GRAPHQL AUTO' \
  http://localhost:8000/sql
```

With that done, a GraphQL query can now be performed.

```bash title="Request"
curl -X POST \
  -u "root:secret" \
  -H "Surreal-NS: main" \
  -H "Surreal-DB: main" \
  -H "Accept: application/json" \
  -d '{"query": "query { person { id name age } }"}' \
  http://localhost:8000/graphql
```

```json title="Response"
{
	"data": {
		"person": [
			{
				"age": 28,
				"id": "person:marcus",
				"name": "Marcus"
			},
			{
				"age": 23,
				"id": "person:simon",
				"name": "Simon"
			}
		]
	}
}
```

<br />

## Custom endpoint at `/api/:ns/:db/:endpoint` {#custom}

A custom endpoint can be set using a [`DEFINE API`](/docs/reference/query-language/statements/define/api.md) statement. The possible HTTP methods (GET, PUT, etc.) are set using the statement itself. The path begins with `/api`, continues with the namespace and database, and ends with a custom endpoint that can include both static and dynamic path segments. From SurrealDB 4.0, the same handler is also reached at the [scoped URL](#scoped-urls) `/ns/:ns/db/:db/api/:endpoint`.

### Headers

<table>
    <thead>
        <tr>
            <th colspan="2">Header</th>
            <th colspan="2">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Authorization</code>
                <label label="optional">OPTIONAL</label>
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the root, namespace, or database authentication data
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-NS</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Namespace for queries.
            </td>
        </tr>
        <tr>
            <td colspan="2" scope="row" data-label="Header">
                <code>Surreal-DB</code>
                <label label="required" />
            </td>
            <td colspan="2" scope="row" data-label="Description">
                Sets the selected Database for queries.
            </td>
        </tr>
    </tbody>
</table>

### Example usage

To begin, start a server with the `surreal db start` command.

```bash
surreal db start --user root --pass secret
```

A custom endpoint can first be set up using a `DEFINE API` statement via the `/sql` endpoint.

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" -d 'DEFINE API "/custom_response" FOR get MIDDLEWARE api::res::body("json") THEN { { status: 200, body: { some: "info" } } }' http://localhost:8000/sql
```

Once this is set up, a simple curl command to the endpoint will suffice to see the response.

```bash title="Request"
curl http://localhost:8000/api/main/main/custom_response -H "Surreal-NS: ns" -H "Surreal-DB: db" -H "Accept: application/json"
```

```json title="Response"
{"some":"info"}
```

## Buckets at `/bucket/:bucket` {#bucket}

_(since v4.0.0)_

The `/bucket` route reads and writes the files in a [bucket](/docs/reference/query-language/statements/define/bucket.md) over plain HTTP. Each method does the same work as one of the [file functions](/docs/reference/query-language/functions/database-functions/file.md), and the bucket's `PERMISSIONS` clause decides each request as it decides the function.

| Method and path | Function | Success status |
| --- | --- | --- |
| `GET /bucket/:bucket/` | `file::list` | `200` |
| `GET /bucket/:bucket/:key` | `file::get` | `200`, or `206` for a range |
| `HEAD /bucket/:bucket/:key` | `file::head` | `200` |
| `PUT /bucket/:bucket/:key` | `file::put` | `201` |
| `DELETE /bucket/:bucket/:key` | `file::delete` | `204` |
| `POST /bucket/:bucket/:key` | `file::copy` or `file::rename` | `201` |

A bucket is defined on the root, on a namespace or on a database, and the [scope](#scoped-urls) in front of `/bucket` names which one:

```text
/bucket/:bucket/:key                               a bucket on the root
/ns/:namespace/bucket/:bucket/:key                 a bucket on a namespace
/ns/:namespace/db/:database/bucket/:bucket/:key    a bucket on a database
```

The level comes from the path only, so that a URL is complete without any headers, and the `Surreal-NS` and `Surreal-DB` headers never move a request to another level. The key is the rest of the path, so `/ns/main/db/main/bucket/images/u/avatar.png` is the file `f"images:/u/avatar.png"` in the database `main`. The route is not compatible with the Amazon S3 API.

### Authentication

A request is authenticated in one of three ways:

* **A session**, with an `Authorization` header holding a user's credentials (`Basic`) or a token (`Bearer`), as on the other endpoints. A user reaches a bucket at its own level or below: a root user any bucket, a namespace user the buckets of its namespace and of its databases, and a database or record user the buckets of its database.
* **A presigned URL** from [`file::presign_get`](/docs/reference/query-language/functions/database-functions/file.md#filepresign_get) or [`file::presign_put`](/docs/reference/query-language/functions/database-functions/file.md#filepresign_put). The signature in the query string is the credential, and the bucket's `PERMISSIONS` clause was already checked when the URL was made. A `GET` URL also accepts `HEAD`, and a `PUT` URL accepts only `PUT`. When a request has both a signature and a session, the signature is used.
* **No credentials.** The request is a guest, and is allowed only when the server runs with [`--allow-guests`](/docs/reference/cli/db/commands/start.md). A guest is then judged by the bucket's `PERMISSIONS` clause, so a bucket with `PERMISSIONS FULL` is readable by anyone on a server that allows guests.

Guests and record users cannot list a bucket, in the same way that they cannot call `file::list`. The route can be turned off with `--deny-http bucket`. See [HTTP routes and RPC methods](/docs/learn/security/authorization/capabilities.md#http-routes-and-rpc-methods).

### Reading a file

`GET` returns the bytes of the file, with these response headers:

* `Content-Type`: the type stored with the file, or `application/octet-stream` when it has none. The server never guesses a type from the key.
* `ETag` and `Last-Modified`, from the same metadata as `file::head`.
* `Accept-Ranges: bytes`. A `Range` header with one range, such as `bytes=0-1023`, returns that part with `206 Partial Content`, so a `<video>` element can seek. A range past the end of the file returns `416`.
* `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`. A user who can upload a file chooses its type, so these headers stop a stored HTML or SVG file from running scripts on the database's origin.

A request with `If-None-Match` and the file's current `ETag` returns `304 Not Modified` without the body. `HEAD` returns the same headers as `GET` and no body.

### Writing a file

`PUT` stores the request body at the key and answers `201 Created`. The `Content-Type` header is stored with the file, as the `content_type` option of `file::put` does. No header, or `application/octet-stream`, stores no type. A `file:` bucket cannot store a type, and answers `415 Unsupported Media Type` for any other value.

With `If-None-Match: *`, the write never replaces a file, and answers `412 Precondition Failed` when the key already holds one. The body is limited by `SURREAL_HTTP_MAX_BUCKET_BODY_SIZE`, which defaults to 5 GiB, and by the `max_size` of a presigned URL. A larger body answers `413 Payload Too Large`, and no file is left at the key.

### Copying and renaming a file

`POST` copies or renames the file at the key. The body is a JSON or CBOR object, sent with the matching `Content-Type`:

```json
{ "action": "copy", "target": "/archive/avatar.png", "overwrite": false }
```

`action` is `copy` or `rename`, and `target` is a key in the same bucket. `overwrite` defaults to `true`. With `false`, the request answers `412` when the target key holds a file. A missing source file answers `404`. A presigned URL cannot copy or rename.

### Listing a bucket

`GET` on the bucket itself, with or without a trailing `/`, lists it. The query parameters `prefix`, `delimiter`, `start` and `limit` work as the options of [`file::list`](/docs/reference/query-language/functions/database-functions/file.md#filelist). The response is JSON, or CBOR when the `Accept` header asks for `application/cbor`. Another format answers `406 Not Acceptable`, and an `Accept` value that the server cannot read answers `400`.

Each entry is `{ key, size, updated, etag }` for a file, with `key` as a plain string, or `{ prefix }` for a folder when `delimiter=/` is set.

### Status codes

| Status | Meaning |
| --- | --- |
| `400` | A malformed header, query parameter or `POST` body. |
| `401` | A presigned URL with a query string that the server cannot read, such as an unknown or repeated parameter. |
| `403` | The credentials do not allow the request: the bucket's `PERMISSIONS` clause refuses it, a presigned URL was changed or was revoked, an upload sends a `Content-Type` other than the one its presigned URL allows, or a request has no credentials on a server that does not allow guests. |
| `404` | No file at the key, or no source file for a copy or rename. |
| `406` | A listing with an `Accept` header for a format other than JSON or CBOR. |
| `410` | A presigned URL that has expired. Create a new one. |
| `412` | The key holds a file and the request asked not to replace it. |
| `413` | The body is larger than the presigned URL or the server allows. |
| `415` | A content type that the backend cannot store, or a `POST` body that is not JSON or CBOR. |
| `416` | A range that starts past the end of the file. |

### Example usage

The commands below start a server with a signing secret for presigned URLs, define a bucket, upload a file with a session, and then download it through a presigned URL.

```bash
SURREAL_BUCKET_PRESIGN_SECRET="replace-with-a-random-value-of-32-bytes-or-more" \
  surreal db start --user root --pass secret
```

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" \
  -d 'DEFINE BUCKET images BACKEND "memory"' http://localhost:8000/sql

curl -X PUT -u "root:secret" -H "Content-Type: image/png" \
  --data-binary @avatar.png http://localhost:8000/ns/main/db/main/bucket/images/u/avatar.png
```

A query creates the presigned URL, and any HTTP client can use its `path` without credentials until it expires:

```bash
curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" \
  -d 'file::presign_get(f"images:/u/avatar.png", { expires: 5m }).path' http://localhost:8000/sql

curl -i "http://localhost:8000/ns/main/db/main/bucket/images/u/avatar.png?exp=1793747188&sig=..."
```

```text title="Response"
HTTP/1.1 200 OK
accept-ranges: bytes
last-modified: Tue, 03 Nov 2026 23:01:28 GMT
x-content-type-options: nosniff
content-security-policy: sandbox
etag: "0"
content-type: image/png
content-length: 18
...
```
