Skip to main content

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​

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.

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 surreal start command in the CLI or through Surrealist's local database serving functionality, before querying the endpoints.

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


FunctionDescription
GET /statusChecks whether the database web server is running
GET /healthChecks the status of the database server and storage engine
GET /versionReturns the version of the SurrealDB database server
POST /importImports data into a specific Namespace and Database
GET /exportExports all data for a specific Namespace and Database
POST /signupSigns-up as a record user using a specific record access method
POST /signinSigns-in as a root, namespace, database, or record user
GET /key/:tableSelects all records in a table from the database
POST /key/:tableCreates a record in a table in the database
PUT /key/:tableUpdates all records in a table in the database
PATCH /key/:tableModifies all records in a table in the database
DELETE /key/:tableDeletes all records in a table from the database
GET /key/:table/:idSelects the specific record from the database
POST /key/:table/:idCreates the specific record in the database
PUT /key/:table/:idUpdates the specified record in the database
PATCH /key/:table/:idModifies the specified record in the database
DELETE /key/:table/:idDeletes the specified record from the database
POST /sqlAllows custom SurrealQL queries
POST /graphqlAllows custom GraphQL queries
POST /ml/importImport a SurrealML model into a specific Namespace and Database
GET /ml/export/:name/:versionExport 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.

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​

HeaderDescription
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​

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 path/to/file.surql http://localhost:8000/import

GET /export​

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

Headers​

HeaderDescription
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​

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 "surreal-ns: mynamespace" -H "surreal-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.

Headers​

HeaderDescription
AcceptREQUIRED

Sets the desired content-type of the response

Data​

DataDescription
nsREQUIRED FOR DB & RECORD

The namespace to sign in to

dbREQUIRED FOR RECORD

The database to sign in to

acREQUIRED FOR RECORD USER

The record access method to use for signing in.

userREQUIRED FOR ROOT, NS & DB

The username of the database user

passREQUIRED FOR ROOT, NS & DB

The password of the database user

Note: 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.

HeaderDescription
AcceptREQUIRED

Sets the desired content-type of the response

Data​

DataDescription
nsREQUIRED FOR DB & RECORD

The namespace to sign up to

dbREQUIRED FOR RECORD

The database to sign up to

accessREQUIRED FOR RECORD

The record access method to use for signing up.

userREQUIRED FOR ROOT, NS & DB

The username of the database user

passREQUIRED FOR ROOT, NS & DB

The password of the database user

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:

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.

  1. Click Send to send the request to the SurrealDB database server.
  2. Navigate to the POST /signup endpoint in Postman.
  3. Enter the following query in the body of the request:
{
    "ns": "test",
    "db": "test",
    "ac": "account",
    "email": "",
    "pass": "123456"
}
  1. In the header of the request, set the following key-value pairs:
    • Accept: application/json
    • namespace: test
    • database: test
    • access: account
  2. 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record 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​

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 "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 /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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record authentication data

AcceptREQUIRED

Sets the desired content-type of the response

surreal-nsREQUIRED

Sets the selected Namespace for queries

surreal-dbREQUIRED

Sets the selected Database for queries

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​

HeaderDescription
AuthorizationOPTIONAL

Sets the root, namespace, database, or record authentication data

nsREQUIRED

Sets the selected Namespace for queries.

dbREQUIRED

Sets the selected Database for queries.

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 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​

HeaderDescription
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​

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 "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
What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.