SurrealQL via HTTP

SurrealDB provides a powerful HTTP API that allows you to interact with the database programmatically. This API can be used to perform a wide range of database operations, from querying data to modifying records and managing database structures.

The HTTP API is designed to be simple and intuitive, with a RESTful interface that provides a consistent way to interact with the database. You can use the API to perform a wide range of database operations, from querying data to modifying records and managing database structures.

Using curl POST /sql

The /sql endpoint enables use of SurrealQL queries.

Important

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

Headers

Example usage

Important

The -u in the example below is a shorthand used by curl to send an Authorization header.

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 > 18" http://localhost:8000/sql

Request
curl -X POST -u "root:secret" -H "NS: main" -H "DB: main" -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",
			},
		]
	}
]

Using Postman

Postman is a popular tool for testing APIs. You can use it to send HTTP requests to your SurrealDB instance and perform various database operations.

1. Set up Postman: Download and install Postman from the official website.

2. Create a new request: Open Postman and create a new HTTP request.

3. Configure the request:

   • Set the request method to POST.
   • Enter the URL of your SurrealDB instance, e.g., http://localhost:8000/sql.
   • In the headers section, add a Content-Type header with the value application/json.
   • In the Body section, select raw and set the type to Text. Enter your SQL query, for example:

INFO FOR DB;

4. Send the request: Click the Send button to execute the query. You will see the response from SurrealDB in the lower section of the Postman interface.

Learn more

Learn more about other HTTP Endpoints available in SurrealDB. For a more detailed tutorial on using Postman with SurrealDB, refer to the working with SurrealDB over HTTP via Postman tutorial.