HTTP & Rest

The HTTP endpoints enable simple selection and modifications of all records or a single record in a table, in addition to support for custom SurrealQL queries with multiple statements, using traditional RESTful HTTP url endpoints.

Accessing Endpoints via Postman

You can access these endpoints via Postman. To do so, follow these steps:

1. Open Postman
2. Clone the SurrealDB Postman Collection
3. Select the appropriate HTTP method (GET, POST, etc.).
4. Enter the endpoint URL.
5. If the endpoint requires any parameters or a body, make sure to include those in your request.

Note: 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 Start command in the CLI, before querying the endpoints.

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

Function	Description
GET /status	Checks whether the database web server is running
GET /health	Checks the status of the database server and storage engine
GET /version	Returns the version of the SurrealDB database server
POST /import	Imports data into a specific Namespace and Database
GET /export	Exports all data for a specific Namespace and Database
POST /signup	Signs-up as a scope user to a specific scope
POST /signin	Signs-in as a root, namespace, database, or scope user
GET /key/:table	Selects all records in a table from the database
POST /key/:table	Creates a records in a table in the database
PUT /key/:table	Updates all records in a table in the database
PATCH /key/:table	Modifies all records in a table in the database
DELETE /key/:table	Deletes all records in a table from the database
GET /key/:table/:id	Selects the specific record from the database
POST /key/:table/:id	Creates the specific record in the database
PUT /key/:table/:id	Updates the specified record in the database
PATCH /key/:table/:id	Modifies the specified record in the database
DELETE /key/:table/:id	Deletes the specified record from the database
POST /sql	Allows custom SurrealQL queries
POST /ml/import	Import a SurrealML model into a specific Namespace and Database
GET /ml/export/:name/:version	Export a SurrealML model from a specific Namespace and Database

GET /status

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

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.

GET /version

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

POST /import

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

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, or database authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Example usage

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

GET /export

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

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, or database authentication data
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Example usage

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

POST /signin

Method and URL
POST /signin

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

The following headers can be used to customise the query and the response.

Header		Description
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED FOR DB & SC		The namespace to sign in to
DBREQUIRED FOR SC		The database to sign in to
SC		Specifies the scope
userREQUIRED FOR ROOT, NS & DB		The username of the database user
passREQUIRED FOR ROOT, NS & DB		The password of the database user

Example with Scope user

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","sc":"user_scope","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, 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",
    "sc": "account",
    "email": "",
    "pass": "123456"
}

Note: The sc parameter is only required if you are signing in as a scope user, otherwise you can omit it for namespace and root users.

POST /signup

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

Headers

Header		Description
AcceptREQUIRED		Sets the desired content-type of the response
namespaceREQUIRED FOR DB & SC		The namespace to sign up to
databaseREQUIRED FOR SC		The database to sign up to
scopeREQUIRED FOR SC		The scope to sign up to. Also pass any variables used in the scope

Example usage

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"test","db":"test","sc":"user_scope","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 sigup a new Scope user, you must first define a scope for the user. To do so, follow these steps:

You can also define System users and Define 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 scope authentication directly in SurrealDB
DEFINE SCOPE account SESSION 24h
    SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
    SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
;

The above query defines a scope called account that allows users to sign up and sign in. The scope 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",
    "sc": "account",
    "email": "",
    "pass": "123456"
}

6. In the header of the request, set the following key-value pairs:
   • Accept: application/json
   • namespace: test
   • database: test
   • scope: 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.eyJpYXQiOjE3MDY2MTA4MDMsIm5iZiI6MTcwNjYxMDgwMywiZXhwIjoxNzA2Njk3MjAzLCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOjZsOTl1OWI0bzVoa3h0NnY3c3NzIn0.oYnsMpFWyY5y2BVszDRkS_D0-KlAs5ixZN_iy9_SkR6YpY8aXQg_fXW3RdRGNAFtjFn0SDVxb7p7BtjsG_65CA"
}

GET /key/:table

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

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Translated query

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

POST /key/:table

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

This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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.

This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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.

This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Translated query

DELETE FROM type::table($table);

GET /key/:table/:id

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

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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.

This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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.

This HTTP endpoint expects the HTTP body to be a JSON or SurrealQL object.

Headers

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
AcceptREQUIRED		Sets the desired content-type of the response
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Example usage

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

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, database, or scope authentication data
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Example usage

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

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

Header		Description
AuthorizationOPTIONAL		Sets the root, namespace, or database authentication data
NSREQUIRED		Sets the selected Namespace for queries
DBREQUIRED		Sets the selected Database for queries

Example usage

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

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.