HTTP protocol

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 SurrealDB Studio 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:

1. 1.

   Open Postman

2. 2.

   Clone the SurrealDB Postman Collection

3. 3.

   Select the appropriate HTTP method (GET /health, DEL /key/:table, etc.).

4. 4.

   Enter the endpoint URL.

5. 5.

   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:

Request size limits

Each endpoint caps the size of the request body it will accept. A request over the cap is rejected with 413 Payload Too Large. The limits differ per endpoint because they are sized to the work each one does: /sql takes a query, /import takes a data file.

The defaults are the same in 2.x and 3.x:

The WebSocket /rpc endpoint is not bound by an HTTP body size. It allows up to 128 MiB per message (SURREAL_WEBSOCKET_MAX_MESSAGE_SIZE). As most SDKs use the WebSocket engine by default, they are able to send payloads that the plain HTTP endpoints reject. See Message size limits for how the server ceiling interacts with the limit an SDK applies on its own side.

Choosing an endpoint for a large payload

The 1 MiB ceiling that a large query runs into applies only to the raw HTTP /sql endpoint. Larger payloads have somewhere to go:

• •

  For ordinary queries, connect through a client SDK such as Rust or JavaScript. The WebSocket engine raises the per-message ceiling to 128 MiB.

• •

  To stay on plain HTTP, use POST /rpc for 4 MiB.

• •

  For bulk data loading, use POST /import, which accepts up to 4 GiB per request.

Tuning the limits

Every limit above is set by an environment variable on a self-hosted server. From 3.0 those variables accept byte-size suffixes such as 16MiB or 4GB; on 2.x they take a raw byte count.

SurrealDB Cloud instances run the defaults listed above.

Request timeouts

Available since: v3.3.0

When the server is started with --query-timeout (SURREAL_QUERY_TIMEOUT), the same duration also limits the wall-clock time of a whole request on these endpoints:

• •

  POST /sql and the /sql WebSocket.

• •

  POST /gql.

• •

  POST /graphql, for a single request and for a batch.

• •

  POST /rpc, for every RPC method, in the same way as on the WebSocket /rpc endpoint and over gRPC. This includes signin, signup and authenticate.

No wall-clock limit applies unless the option is set. The RPC begin, commit and cancel methods are exempt, because stopping a commit part-way is unsafe, although each statement run inside the explicit transaction is still limited on its own. GraphQL subscriptions over WebSocket and the POST /signin and POST /signup endpoints are not covered by the wall-clock limit.

When the limit ends a request to POST /sql or POST /gql, the response is 504 Gateway Timeout with an error body, where earlier releases answered a timed-out request with 400. The status is 504 rather than 503 because load balancers commonly read 503 as an unhealthy node, and one slow query is no reason to take a node out of rotation. With --query-timeout 5s, the body reads:

{
	"code": 504,
	"details": "Query timeout",
	"description": "The request exceeded the configured query timeout. Reduce the work performed by the request or raise the timeout.",
	"information": "The query was not executed because it exceeded the timeout: 5s"
}

A /graphql request that runs out of time returns a GraphQL response whose error message reads The GraphQL request was not executed because it exceeded the timeout: 5s. A POST /rpc call returns an RPC error response with the message The query was not executed because it exceeded the timeout: 5s, and the /sql WebSocket sends the same message as text.

GET /status

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

Example usage

curl -I http://localhost:8000/status

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
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 storage engine responds, by reading one key in a read-only transaction. It returns 200 when the read succeeds and 500 when it fails, or 403 when the health route is denied by capabilities.

/health stays reachable while the server is still starting up, so a 200 shows that the storage engine answers, not that startup has finished. GET /ready is the endpoint that reports whether it has.

curl -I http://localhost:8000/health

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
server: SurrealDB
x-request-id: 66938ec2-ad7c-4afb-928d-683e7a75433a
content-length: 0
date: Tue, 03 Feb 2026 02:15:08 GMT

GET /ready

Available since: v3.2.0

This HTTP RESTful endpoint is the startup and readiness probe. It returns 200 when both of these hold:

• •

  The startup work that follows opening the datastore has finished. From 3.3.0 this covers the version check and any data migrations, the default namespace and database, the root credentials, node registration, and any import set with --import-file.

• •

  The node's cluster heartbeat is recent. The node refreshes it every --node-membership-refresh-interval, 3 seconds by default, and /ready treats it as stale once it is more than three intervals old.

It returns 503 while startup is still running, when the heartbeat is stale, or when the node has no cluster membership record, and 500 when the heartbeat cannot be read. A node with no cluster membership record returned 500 before 3.3.0. Available since: v3.3.0 SurrealDB Enterprise adds conditions of its own, such as a valid licence.

Until startup finishes, every other path except /, /status, /health, /version and /metrics returns 503 with Retry-After: 1, so query and authentication requests wait for the node while /ready stays reachable and orchestrators can tell a starting node from a failed one. With no import configured, the server waits up to 5 seconds for startup before it accepts connections, so an ordinary start reports 200 from the first probe. Available since: v3.3.0 A start with an import accepts connections straight away, and one that runs past 5 seconds accepts them at that point, and both report 503 until startup finishes. A failure to initialise the datastore stops the process, while a failed import or credential initialisation leaves the server running and /ready at 503.

Contrast with GET /status (process and listener liveness only) and GET /health (storage backend reachability only).

The CLI surreal isready command calls this endpoint.

curl -i http://localhost:8000/ready

HTTP/1.1 200 OK
vary: origin, access-control-request-method, access-control-request-headers
access-control-allow-origin: *
surreal-version: surrealdb/3.2.0
server: SurrealDB
content-length: 0

HTTP/1.1 503 Service Unavailable
content-type: application/json

{"code":503,"details":"Service unavailable","description":"The server is still starting up and cannot serve this request yet. Retry once the instance is ready.","information":"The server is still starting up and is not ready to serve requests"}

A gated endpoint returns the same body with a retry-after: 1 header, which /ready itself does not send.

GET /version

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

Example usage

curl http://localhost:8000/version

surrealdb-3.0.0

POST /import

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

The body is streamed: the server parses and applies statements as the bytes arrive rather than buffering the whole file. This is the endpoint to use for bulk data loading, since it accepts far more than /sql or /rpc do.

Size limit and partial imports

The default cap is 4 GiB (SURREAL_HTTP_MAX_IMPORT_BODY_SIZE). Two details of how it is enforced matter when planning an import:

• •

  The cap is cumulative for one request, not per chunk. The limiter decrements a single allowance across every frame of the stream. A request whose Content-Length exceeds the cap is rejected immediately with 413; a chunked request is accepted and then fails partway through, once the total bytes received cross the cap. Split larger datasets across several files rather than sending one oversized request. The gRPC import path enforces the same cumulative cap.

• •

  A failed import is partially applied. Statements are committed as they are parsed, so an import that trips the cap - or is interrupted for any other reason - leaves everything applied up to that point in place. There is no rollback.

Headers

Example usage

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

POST /export

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

Headers

Export options

Example usage

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

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

POST /signin

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

When authentication rate limiting is enabled, an attempt beyond the client address's budget is refused with 429 Too Many Requests and a Retry-After header giving the number of seconds to wait, and the error body says that too many authentication attempts were made from this client address. /signin and /signup draw on the same budget. Available since: v3.3.0

Headers

Data

Example with a record user

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

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

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

Example with root user

curl -X POST -H "Accept: application/json" -d '{"user":"root","pass":"secret"}' http://localhost:8000/signin

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

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

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

Example usage via postman

After you have defined the 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.

When authentication rate limiting is enabled, an attempt beyond the client address's budget is refused with 429 Too Many Requests and a Retry-After header giving the number of seconds to wait. /signup shares its budget with /signin. Available since: v3.3.0

Header

Data

Example usage

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

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

1. 1.

   Navigate to the POST /sql endpoint in Postman.

2. 2.

   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.

3. 3.

   Click Send to send the request to the SurrealDB database server.

4. 4.

   Navigate to the POST /signup endpoint in Postman.

5. 5.

   Enter the following query in the body of the request:

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

6. 6.

   In the header of the request, set the following key-value pairs:

   • ◦

     Accept: application/json

   • ◦

     namespace: test

   • ◦

     database: test

   • ◦

     access: account

7. 6.

   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

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.

Headers

Translated query

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

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

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

Headers

Translated query

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

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

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

Headers

Translated query

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

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

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

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

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

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

Translated query

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

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

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

Headers

Translated query

UPDATE type::record($table, $id) CONTENT $data;

PATCH /key/:table/:id

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

Headers

Translated query

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

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

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

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

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

POST /sql

The SQL endpoint enables use of SurrealQL queries.

Headers

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

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

[
	{
		"time": "14.357166ms",
		"status": "OK",
		"result": [
			{
				"age": "23",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Simon",
			},
			{
				"age": "28",
				"id": "person:6r7wif0uufrp22h0jr0o"
				"name": "Marcus",
			},
		]
	}
]

Usage in importing data

Available since: v3.0.4

As of SurrealDB 3.0.4, imports via the surreal import and /import HTTP endpoint require the automatically generated OPTION IMPORT line to be present in order to disable events, live queries, field processing, and result output for optimal import performance. If side effects are desired when importing data, remove the line and use this endpoint instead.

POST /gql

Available since: v3.2.0

The GQL endpoint runs ISO GQL (Cypher Query Language) graph pattern queries against your existing tables and RELATE edges - MATCH … RETURN reads and data-modifying INSERT, SET, REMOVE, and DELETE (GQL mutations).

Headers

Parameters

Pass GQL parameters through WebSocket RPC (method: "gql", second element of params as a JSON object with typed values).

Example usage

curl -X POST -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" \
  -H "Accept: application/json" -H "Content-Type: text/plain" \
  -d 'MATCH (n:person) RETURN n.name AS name ORDER BY name' \
  http://localhost:8000/gql

[
	{
		"status": "OK",
		"result": [
			{ "name": "A" },
			{ "name": "B" },
			{ "name": "C" }
		],
		"time": "1.5ms"
	}
]

Parse errors return HTTP 400 with an error payload. See GQL via HTTP for enabling GQL, seeding data, and RPC examples.

POST /graphql

The GraphQL endpoint enables use of GraphQL queries to interact with your data.

Headers

Example usage

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.

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

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

Example usage

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

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

Example usage

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

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

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.

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

{"some":"info"}