HTTP & Rest

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 managing SurrealML models.

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.

Querying via Postman

The most 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
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.

Important

Ensure that your URL is set correctly, if running locally, the URL should be http://localhost:8000.By default, the URL is set to local. Start your server using the surreal start command in the CLI or through Surrealist’s local database serving functionality, before querying the endpoints.

Supported methods

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

GET /status

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

Example usage

Request
curl -I http://localhost:8000/status

Sample output
HTTP/1.1 200 OK
content-length: 0
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb-2.0.0+20240910.8f30ee08
server: SurrealDB
x-request-id: 3dedcc96-4d8a-451e-b60d-4eaac14fa3f8
date: Wed, 11 Sep 2024 00:52:49 GMT

GET /health

This HTTP RESTful endpoint checks whether the database server and storage engine are running.

The endpoint returns a 200 status code on success and a 500 status code on failure.

Request
curl -I http://localhost:8000/health

Sample output
HTTP/1.1 200 OK
content-length: 0
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb-2.0.0+20240910.8f30ee08
server: SurrealDB
x-request-id: 24a1e675-af50-4676-b8ff-6eee18e9a077
date: Wed, 11 Sep 2024 00:53:22 GMT

GET /version

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

Example usage

Request
curl http://localhost:8000/version

Sample output
surrealdb-2.0.0+20240910.8f30ee08

POST /import

This HTTP RESTful endpoint imports a set of SurrealQL queries into a specific Namespace and Database.

Headers

Example usage

Note

The -u in the example below is a shorthand used by curl to send an Authorization header.

Request
curl -X POST -u "root:root" \
  -H "ns: mynamespace" \
  -H "db: mydatabase" \
  -H "Accept: application/json" \
  -d path/to/file.surql \
  http://localhost:8000/import

Request
curl -X POST -u "root:root" \
  -H "Surreal-NS: mynamespace" \
  -H "Surreal-DB: mydatabase" \
  -H "Accept: application/json" \
  -d path/to/file.surql \
  http://localhost:8000/import

POST /export

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

Headers

Example usage

Note

The -u in the example below is a shorthand used by curl to send an Authorization header, while -o allows the output to be written to a file.

Request
curl -X GET \
  -u "root:root" \
  -H "ns: mynamespace" \
  -H "db: mydatabase" \
  -H "Accept: application/json" \
  -o path/to/file.surql \
  http://localhost:8000/export

Request
curl -X GET \
  -u "root:root" \
  -H "Surreal-NS: mynamespace" \
  -H "Surreal-DB: mydatabase" \
  -H "Accept: application/json" \
  -o path/to/file.surql \
  http://localhost:8000/export

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

POST /signin

Method and URL
POST /signin

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

Headers

Data

Important

The ac parameter is only required if you are signing in using an access method as a record user. For system users on the database, namespace, and root level, this parameter can be omitted.

Example with a Record user

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","ac":"users","user":"john.doe","pass":"123456"}' http://localhost:8000/signin

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

Example with Namespace user

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"test","user":"john.doe","pass":"123456"}' http://localhost:8000/signin

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

Example with Root user

Request
curl -X POST -H "Accept: application/json" -d '{"user":"john.doe","pass":"123456"}' http://localhost:8000/signin

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

Example usage via Postman

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

Using the user credentials created add the following to the request body:

{
    "ns": "test",
    "db": "test",
    "ac": "account",
    "email": "",
    "pass": "123456"
}

POST /signup

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

Header

Data

Example usage

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","ac":"users","user":"john.doe","pass":"123456"}' http://localhost:8000/signup

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

Example usage via Postman

Before you sign up a new record user, you must first define a record access method for the user. To do so, follow these steps:

Note

You can also define system users and user credentials using the POST /sql endpoint.

1. Navigate to the POST /sql endpoint in Postman.
2. Enter the following query in the body of the request:

-- Enable authentication directly against a SurrealDB record
DEFINE ACCESS account 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:

{
    "ns": "test",
    "db": "test",
    "ac": "account",
    "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
7. Click Send to send the request to the SurrealDB database server. You will get back a

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

GET /key/:table

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

Headers

Translated query

SELECT * FROM type::table($table);

POST /key/: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 JSON or SurrealQL object.

Headers

Translated query

CREATE type::table($table) CONTENT $body;

PUT /key/: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 JSON or SurrealQL object.

Headers

Translated query

UPDATE type::table($table) CONTENT $body;

PATCH /key/: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 JSON or SurrealQL object.

Headers

Translated query

UPDATE type::table($table) MERGE $body;

DELETE /key/:table

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

Headers

Translated query

DELETE FROM type::table($table);

GET /key/:table/:id

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

Headers

Translated query

SELECT * FROM type::thing($table, $id);

POST /key/:table/:id

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

Headers

Translated query

CREATE type::thing($table, $id) CONTENT $body;

PUT /key/:table/:id

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 JSON or SurrealQL object.

Headers

Translated query

UPDATE type::thing($table, $id) CONTENT $body;

PATCH /key/:table/:id

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 JSON or SurrealQL object.

Headers

Translated query

UPDATE type::thing($table, $id) MERGE $body;

DELETE /key/:table/:id

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

Headers

Translated query

DELETE FROM type::thing($table, $id);

POST /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

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 whenever untrusted inputs are included in a query to prevent injection attacks.

Example usage

Note

The -u in the example below is a shorthand used by curl to send an Authorization header.

Request
curl -X POST -u "root:root" -H "ns: mynamespace" -H "db: mydatabase" -H "Accept: application/json" \
  -d 'SELECT * FROM person WHERE age > $age' http://localhost:8000/sql?age=18

Request
curl -X POST -u "root:root" -H "Surreal-NS: mynamespace" -H "Surreal-DB: mydatabase" -H "Accept: application/json" \
  -d 'SELECT * FROM person WHERE age > $age' http://localhost:8000/sql?age=18

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

POST /graphql

Available since: v2.0.0

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

Note

This HTTP endpoint expects the HTTP body to be a GraphQL query.

Headers

Example usage

Note

The -u in the example below is a shorthand used by curl to send an Authorization header.

Request
curl -X POST \
  -u "root:root" \
  -H "Surreal-NS: mynamespace" \
  -H "Surreal-DB: mydatabase" \
  -H "Accept: application/json" \
  -d '{
    "query": "{ 
      person(filter: {age: {age_gt: 18}}) {
        id
        name
        age
      }
    }"
  }' \
  http://localhost:8000/graphql

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

POST /ml/import

This HTTP RESTful endpoint imports a SurrealML machine learning model into a specific Namespace and Database. It expects the file to be a SurrealML file packaged in the .surml file format. As machine learning files can be large, the endpoint expects a chunked HTTP request.

Headers

Example usage

Note

The -u in the example below is a shorthand used by curl to send an Authorization header.

Request
curl -X POST \
  -u "root:root" \
  -H "ns: mynamespace" \
  -H "db: mydatabase" \
  -H "Accept: application/json" \
  -d path/to/file.surml \
  http://localhost:8000/ml/import

Request
curl -X POST \
  -u "root:root" \
  -H "Surreal-NS: mynamespace" \
  -H "Surreal-DB: mydatabase" \
  -H "Accept: application/json" \
  -d path/to/file.surml \
  http://localhost:8000/ml/import

Usage in Python

When using Python, the surreaml package can be used to upload the model with the following code:

from surrealml import SurMlFile

url = "http://0.0.0.0:8000/ml/import"
SurMlFile.upload("./linear_test.surml", url, 5)

GET /ml/export/:name/:version

This HTTP RESTful endpoint exports a SurrealML machine learning model from a specific Namespace and Database. The output file with be a SurrealML file packaged in the .surml file format. As machine learning files can be large, the endpoint outputs a chunked HTTP response.

Headers

Example usage

Note

Note: The -u in the example below is a shorthand used by curl to send an Authorization header, while -o allows the output to be written to a file.

Request
curl -X GET \
  -u "root:root" \
  -H "ns: mynamespace" \
  -H "db: mydatabase" \
  -H "Accept: application/json" \
  -o path/to/file.surml \
  http://localhost:8000/ml/export/prediction/1.0.0

Request
curl -X GET \
  -u "root:root" \
  -H "Surreal-NS: mynamespace" \
  -H "Surreal-DB: mydatabase" \
  -H "Accept: application/json" \
  -o path/to/file.surml \
  http://localhost:8000/ml/export/prediction/1.0.0

Custom endpoint at /api/:ns/:db/:endpoint

Available since: v2.2.0

Caution

Currently, this is an experimental feature as such, it may be subject to breaking changes and may present unidentified security issues. Do not rely on this feature in production applications. To enable this, set the SURREAL_CAPS_ALLOW_EXPERIMENTAL environment variable to define_api.

A custom endpoint can be set using a DEFINE API 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.

Headers

Example usage

Request
curl http://localhost:8000/api/my_namespace/my_database/test_endpoint \
  -H "Surreal-NS: ns" -H "Surreal-DB: db" \
  -H "Accept: application/json"