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.
This HTTP endpoint expects the HTTP body to be a set of SurrealQL statements.
| 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. |
Example usage
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.
Set up Postman: Download and install Postman from the official website.
Create a new request: Open Postman and create a new HTTP request.
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;
- 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.
