Version: Nightly

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
`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
`GET /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.

`GET /import`

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

Headers

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

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

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

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

`POST /signup`

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

Headers

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

Example usage

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

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

`GET /key/:table`

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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);

`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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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;

`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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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;

`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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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;

`DELETE /key/:table`

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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);

`GET /key/:table/:id`

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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::thing($table, $id);

`POST /key/:table/:id`

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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::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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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::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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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::thing($table, $id) MERGE $body;

`DELETE /key/:table/:id`

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope 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::thing($table, $id);

`POST /sql`

The SQL endpoint enables advanced SurrealQL queries.

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

Headers

Header		Description
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope authentication data
`Accept`REQUIRED		Sets the desired content-type of the response
`NS`OPTIONAL		Sets the selected Namespace for queries
`DB`OPTIONAL		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
`Authorization`OPTIONAL		Sets the root, namespace, database, or scope authentication data
`NS`REQUIRED		Sets the selected Namespace for queries
`DB`REQUIRED		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
`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

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/export/prediction/1.0.0

HTTP & Rest

HTTP & Rest

GET /status​

GET /health​

GET /version​

GET /import​

Headers​

Example usage​

GET /export​

Headers​

Example usage​

POST /signin​

Example with Scope user​

Example with Namespace user​

Example with Root user​

POST /signup​

Headers​

Example usage​

GET /key/:table​

Headers​

Translated query​

POST /key/:table​

Headers​

translated query​

PUT /key/:table​

Headers​

Translated query​

PATCH /key/:table​

Headers​

Translated query​

DELETE /key/:table​

Headers​

Translated query​

GET /key/:table/:id​

Headers​

Translated query​

POST /key/:table/:id​

Headers​

Translated query​

PUT /key/:table/:id​

Headers​

Translated query​

PATCH /key/:table/:id​

Headers​

Translated query​

DELETE /key/:table/:id​

Headers​

Translated query​

POST /sql​

Headers​

Example usage​

POST /ml/import​

Headers​

Example usage​

Usage in Python​

GET /ml/export/:name/:version​

Headers​

Example usage​

`GET /status`

`GET /health`

`GET /version`

`GET /import`

Headers

Example usage

`GET /export`

Headers

Example usage

`POST /signin`

Example with Scope user

Example with Namespace user

Example with Root user

`POST /signup`

Headers

Example usage

`GET /key/:table`

Headers

Translated query

`POST /key/:table`

Headers

translated query

`PUT /key/:table`

Headers

Translated query

`PATCH /key/:table`

Headers

Translated query

`DELETE /key/:table`

Headers

Translated query

`GET /key/:table/:id`

Headers

Translated query

`POST /key/:table/:id`

Headers

Translated query

`PUT /key/:table/:id`

Headers

Translated query

`PATCH /key/:table/:id`

Headers

Translated query

`DELETE /key/:table/:id`

Headers

Translated query

`POST /sql`

Headers

Example usage

`POST /ml/import`

Headers

Example usage

Usage in Python

`GET /ml/export/:name/:version`

Headers

Example usage