---
title: "Query SurrealDB from Postman"
description: "In this tutorial, you will learn how to query the SurrealDB RESTful HTTP API endpoints using Postman."
canonical_url: "https://surrealdb.com/docs/learn/tutorials/walkthroughs/http-via-postman"
section: "Tutorials"
surrealdb_version: "4.x"
last_modified: "2026-11-19T06:06:22Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Query SurrealDB from Postman

In this tutorial, you will learn how to query the SurrealDB RESTful HTTP API endpoints using Postman.

SurrealDB provides a RESTful HTTP API for interacting with the database.

In this tutorial, you will learn how to query SurrealDB endpoints via the [Postman collection](https://postman.com/surrealdb/workspace/surrealdb/collection/19100500-3da237f3-588b-4252-8882-6d487c11116a). SurrealDB supports requests over HTTP and REST, which can handle queries ranging from creating simple tables to graph relationships between complex tables.

Check out the [HTTP & REST integration documentation](/docs/reference/protocols/http-protocol.md) for a detailed list of all the endpoints supported.

## Prerequisites

This tutorial assumes that you have the following:

- A Postman account to fork the [SurrealDB collection](https://postman.com/surrealdb/workspace/surrealdb/collection/19100500-3da237f3-588b-4252-8882-6d487c11116a)
- SurrealDB installed - If you do not, see the [installation guide](/docs/running/installation.md) specific to your machine.

## Getting started

Before forking the Collection from Postman, ensure that you have your SurrealDB instance running locally because by default the collection endpoint is set to [`localhost:8000`](http://localhost:8000) or [`http://127.0.0.1:8000`](http://127.0.0.1:8000/)

To do so run the [Start command](/docs/reference/cli/db/commands/start.md) in your terminal:

```bash
surreal db start --user root --pass secret
```

The above command starts SurrealDB with [authentication](/docs/reference/cli/db/commands/start.md#authentication) and specifies that the user and password are `root`. Note that this is just for demonstration purposes. You can replace `root` in both instances with any other value.

After running locally, head over to Postman and create a fork for your workspace. You should see all the endpoints listed. You can also [check the endpoints in the documentation](/docs/reference/protocols/http-protocol.md).

## Using the `INFO` statement

You can get information about your workspace by using the INFO statement. However, you need the right permissions in order to see the output. See the documentation for the [INFO statement](/docs/reference/query-language/statements/info.md).

Note that the `namespace` and `database` values for the Postman collection are set to `test` by default.

You can see the JSON output using the [INFO statement](/docs/reference/query-language/statements/info.md) in the body of the request.

```surql
INFO FOR ROOT / DB / NS
```

Below is the output of querying for the info of the current namespace.

```surql
INFO FOR NS
```

```json
[
    {
        "result": {
            "accesses": {},
            "databases": {
                "test": "DEFINE DATABASE test"
            },
            "users": {}
        },
        "status": "OK",
        "time": "190.166µs"
    }
]
```

## Defining a record user

To define a [record user](/docs/learn/security/authentication/users.md#record-users), first navigate to the `POST /sql`  endpoint and in the header of the request add the following fields:

```json
Accept:application/json
NS:{{namespace}}
DB:{{database}}
```
You can also [define](/docs/reference/query-language/statements/define/user.md) a [system user](/docs/learn/security/authentication/users.md#system-users) with other credentials such as Root or Database user. For this tutorial, we will be using only [record users](/docs/learn/security/authentication/users.md#record-users).

> [!NOTE]
> The Namespace and Database fields are set to the value `test` by default. You can change this in the collection settings.

In the request body, [define the record access method](/docs/reference/query-language/statements/define/access/record.md) `human` with a session of 24 hours:

```surql
DEFINE ACCESS human 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 code above allows a user to sign up as a record user with their email and password, and hashes the password with the [`crypto::argon2::generate`](/docs/reference/query-language/functions/database-functions/crypto.md#cryptoargon2generate) function.

The sign in logic gets all the users where the emails match and uses the [`crypto::argon2::compare`](/docs/reference/query-language/functions/database-functions/crypto.md#cryptoargon2compare) function to compare the stored hash with the password provided.

Now when you get the info of the Database using `INFO for DB` you can see the access method `human` in the following output:

```json
[
    {
        "result": null,
        "status": "OK",
        "time": "102.458µs"
    },
    {
        "result": {
            "accesses": {
                "human": "DEFINE ACCESS human 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 TOKEN 1h, FOR SESSION 1d"
            },
            "analyzers": {},
            "functions": {},
            "models": {},
            "params": {},
            "tables": {},
            "users": {}
        },
        "status": "OK",
        "time": "78.084µs"
    }
]
```

## Signing up a new scope user

After defining the `signup` and `signin` logic head over to the `POST /signup` endpoint to signup and in the header of the request add the following fields:

```json
Accept:application/json
namespace:test
database:test
access:human  
```

In the body of the request add the following information:

```json
{
    "ns": "test",
    "db": "test",
    "ac": "human",
    "email": "test@surreal.com",
    "pass":"1234567886"
}
```

The result will be a  JSON object:

```json
{
    "code": 200,
    "details": "Authentication succeeded",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDY2NTgsIm5iZiI6MTcwNzE0NjY1OCwiZXhwIjoxNzA3MjMzMDU4LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJBQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOnc2ZzBsNmh5eHpjZzlubTY2dGVjIn0.8Gud51cocThB8DMKD1zovtGiVgf5L1dAS6-pjWb6Lm6a7-4Spp7xXjD7JrHHdtJVNX1O0d8GdjZwRGTsP_NM9A"
}
```

## Signing in a record user

Now that a user is defined, you can sign in. To do so, go to the `POST /signin` endpoint and use the same credentials. In the body of the request, add the same information you used to sign up:

```json
{
    "ns": "test",
    "db": "test",
    "ac": "human",
    "email": "test3@surreal.com",
    "pass":"1234567886"
} 
```

This should return a similar JSON object indicating successful authentication and providing a new token.

```json
{
    "code": 200,
    "details": "Authentication succeeded",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE3MDcxNDY2NTgsIm5iZiI6MTcwNzE0NjY1OCwiZXhwIjoxNzA3MjMzMDU4LCJpc3MiOiJTdXJyZWFsREIiLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJBQyI6Imh1bWFuIiwiSUQiOiJ1c2VyOnc2ZzBsNmh5eHpjZzlubTY2dGVjIn0.8Gud51cocThB8DMKD1zovtGiVgf5L1dAS6-pjWb6Lm6a7-4Spp7xXjD7JrHHdtJVNX1O0d8GdjZwRGTsP_NM9A"
}
```

## Using table endpoints

The Postman collection has a couple of endpoints for `POST` `GET` `PUT` `PATCH` `DEL` operations. For example, if you want to add a new entry to the table `Person` (which is the default table in the collection), go to the [`POST /key/:table`](/docs/reference/protocols/http-protocol.md#post-table) endpoint and add the table content in the body of the request. For example:

```json
{
    age: 32,
    name: 'John'
}
```

You should get a response as seen below, notice that there is a [record ID](/docs/reference/query-language/language-primitives/data-types/record-ids.md), with this record ID you can now use any of the [`/key/:table/:id`](/docs/reference/protocols/http-protocol.md#get-record) endpoints for  `POST` `GET` `PUT` `PATCH` `DEL` operations.

```json
[
    {
        "result": [
            {
                "age": 32,
                "id": "person:p1cdf6cx89gnfboq5wye",
                "name": "John"
            }
        ],
        "status": "OK",
        "time": "105.667µs"
    }
]
```

## Conclusion

In this tutorial, we've walked through how to set up and use SurrealDB over HTTP using Postman. We've covered how to define a new record access method, sign up a new user, and sign in with a user. These are the steps for managing user authentication in your applications using SurrealDB.

The Postman collection is still in active development. For more information on using SurrealDB via the HTTP endpoints, [check out our documentation on HTTP and REST endpoints](/docs/reference/protocols/http-protocol.md).

## Learn more about this topic

- [6: Defining users and permissions](https://surrealdb.com/learn/movies/page-06#signing-in-as-a-record-user) (SurrealDB University, section "Signing in as a record user")
