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 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 start 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 functionality on the Surrealist UI 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:

Open Postman
Clone the SurrealDB Postman Collection
Select the appropriate HTTP method (GET /health, DEL /key/:table, etc.).
Enter the endpoint URL.
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:

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
`POST /export`	Exports all data for a specific Namespace and Database
`POST /signup`	Signs-up as a record user using a specific record access method
`POST /signin`	Signs-in as a root, namespace, database, or record user
`GET /key/:table`	Selects all records in a table from the database
`POST /key/:table`	Creates a record 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 /graphql`	Allows custom GraphQL 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
`/api/:namespace/:database/:endpoint`	Create a custom API endpoint for any number of HTTP methods (GET, POST, etc.)

`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
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.0.0-beta
server: SurrealDB
x-request-id: fdb9bcdb-b085-4da0-80ef-a61105c432f9
content-length: 0
date: Tue, 03 Feb 2026 02:10:33 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
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.0.0-beta
server: SurrealDB
x-request-id: 66938ec2-ad7c-4afb-928d-683e7a75433a
content-length: 0
date: Tue, 03 Feb 2026 02:15:08 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-3.0.0-beta

`POST /import`

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

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		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 (name and password), in this case assuming the username root and password secret.

V2.x+
V1.x

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

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

`POST /export`

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

Headers

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Export options

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

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.

V2.x+
V1.x

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

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

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

`POST /signin`

Method and URL
POST /signin

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

Headers

Header		Description
`Accept` required		Sets the desired content-type of the response

Data

Data		Description
`ns` required		The namespace to sign in to this is required FOR DB & RECORD users
`db` required		The database to sign in to required for RECORD users
`ac` required		The record access method to use for signing in. required for RECORD users
`user` required		The username of the database user required for ROOT, NS & DB users
`pass` required		The password of the database user required for ROOT, NS & DB users

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

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

Request
curl -X POST -H "Accept: application/json" -d '{"ns":"main","db":"main","ac":"users","user":"johndoe","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":"root","pass":"secret"}' http://localhost:8000/signin

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.

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.

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

`POST /signup`

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

Header		Description
`Accept` required		Sets the desired content-type of the response

Data

Data		Description
`ns` required		The namespace to sign up to. This data is `REQUIRED FOR DB & RECORD`
`db` required		The database to sign up to. This data is `REQUIRED FOR RECORD`
`access` required		The record access method to use for signing up. This data is `REQUIRED FOR RECORD`
`user` required		The username of the database user. This data is `REQUIRED FOR ROOT, NS & DB`
`pass` required		The password of the database user. This data is `REQUIRED FOR ROOT, NS & DB`

Example usage

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

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, you must first define a record access method for the user. The following curl command will do so on the command line using the POST /sql endpoint.

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:

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

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

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

{
    "ns": "main",
    "db": "main",
    "ac": "users",
    "email": "",
    "pass": "123456"
}

In the header of the request, set the following key-value pairs:
- Accept: application/json
- namespace: test
- database: test
- access: account
Click Send to send the request to the SurrealDB database server. You will receive the following response.

{
    "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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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.

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

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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.

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

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

`DELETE /key/:table`

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

Headers

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

DELETE FROM type::table($table) RETURN BEFORE;

Example usage

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

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.

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

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

`GET /key/:table/:id`

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

Headers

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

`POST /key/:table/:id`

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

Headers

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

UPDATE type::record($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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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:

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.

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

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

`DELETE /key/:table/:id`

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

Headers

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Translated query

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

Example usage

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

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.

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

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

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 (name and password), in this case assuming the username root and password secret.

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 > $age' http://localhost:8000/sql?age=18

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 > $age' http://localhost:8000/sql?age=18

Request
curl -X POST -u "root:secret" -H "ns: main" -H "db: main" -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

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Accept` required		Sets the desired content-type of the response
`Surreal-NS` required		Sets the selected Namespace for queries
`Surreal-DB` required		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 (name and password), in this case assuming the username root and password secret.

First, use the /sql endpoint to send in a DEFINE CONFIG statement to set the database up to use GraphQL.

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.

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

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

`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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, database, or record authentication data
`ns` required		Sets the selected Namespace for queries.
`db` required		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 (name and password), in this case assuming the username root and password secret.

V2.x+
V1.x

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

Request
curl -X POST \
  -u "root:secret" \
  -H "ns: main" \
  -H "db: main" \
  -H "Accept: application/json" \
  -d 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

V2.x+
V1.x

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`ns` required		Sets the selected Namespace for queries.
`db` required		Sets the selected Database for queries.

Example usage

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

V2.x+
V1.x

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

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

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

Available since: v2.2.0

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

Header		Description
`Authorization` optional		Sets the root, namespace, or database authentication data
`Surreal-NS` required		Sets the selected Namespace for queries.
`Surreal-DB` required		Sets the selected Database for queries.

Example usage

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

surreal start --user root --pass secret

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

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.

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

Response
{"some":"info"}

On this page

Was this page helpful?

What did you like?

What went wrong?