Back to top
Documentation Integration HTTP & REST

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.

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

GET /export endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, or database authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/octet-stream

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

GET /health endpoint

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.

POST /import endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, or database authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/octet-stream, application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

GET /key/:table endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

POST /key/:table endpoint

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.

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

DELETE /key/:table endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

DELETE FROM type::table($table);

GET /key/:table/:id endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

POST /key/:table/:id endpoint

This HTTP RESTful endpoint creates a single specific record into the database.

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

PUT /key/:table/:id endpoint

This HTTP RESTful endpoint creates or updates a single specific record in the database.

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

PATCH /key/:table/:id endpoint

This HTTP RESTful endpoint creates or updates a single specific record in the database. If the record already exists, then only the specified fields will be updated.

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

DELETE /key/:table/:id endpoint

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

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

Once this endpoint is called the following query will be run on the database:

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

POST /signup endpoint

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

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

Header Description
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

The following shows an example request.

curl -X POST \
	 -H "Accept: application/json" \
	 -d '{"ns":"test","db":"test","sc":"user_scope","username":"john.doe","password":"123456"}' \
	 http://localhost:8000/signup
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

POST /signin endpoint

This HTTP RESTful endpoint is used to sign in a user of the SurrealDB database server.

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

Header Description
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

The following shows example request on the different permission layers for signin.

Scope:

curl -X POST \
	 -H "Accept: application/json" \
	 -d '{"ns":"test","db":"test","sc":"user_scope","username":"john.doe","password":"123456"}' \
	 http://localhost:8000/signin
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Namespace:

curl -X POST \
	 -H "Accept: application/json" \
	 -d '{"ns":"test","username":"john.doe","password":"123456"}' \
	 http://localhost:8000/signin
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Root:

curl -X POST \
	 -H "Accept: application/json" \
	 -d '{"username":"john.doe","password":"123456"}' \
	 http://localhost:8000/signin
{
	"code": 200,
	"details": "Authentication succeeded",
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

POST /sql endpoint

The SQL endpoint enables advanced SurrealQL queries.

This HTTP endpoint expects the HTTP body to be a set of SurrealQL statements.

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

Header Description
Authorization Optional Sets the root, namespace, database, or scope authentication data
Accept Required Sets the desired content-type of the response

Can be one of application/json, application/cbor, application/pack

NS Optional Sets the selected Namespace for queries
DB Optional Sets the selected Database for queries

The following shows an example request.

curl -X POST \
	 -u "root:root" \
	 -H "NS: myapplication" \
	 -H "DB: myapplication" \
	 -H "Accept: application/json" \
	 -d "SELECT * FROM person WHERE age > 18" \
	 http://localhost:8000/sql
[
	{
		"time": "14.357166ms",
		"status": "OK",
		"result": [
			{
				"age": "23",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Simon",
			},
			{
				"age": "28",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Marcus",
			},
		]
	}
]

GET /status endpoint

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

GET /version endpoint

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