> ## Documentation Index
> Fetch the complete documentation index at: https://new.docs.falkordb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rest API

> Complete REST API reference for FalkorDB Browser, including authentication, graph management, query execution, and node/edge operations.

REST API for FalkorDB Browser - Graph Database Management Interface

**Version:** 1.4.6

**Base URL:** Your FalkorDB Browser instance URL

**Authentication:** Bearer Token (JWT)

## Getting Started

### Quick Start Guide

To start using the FalkorDB Browser REST API, follow these simple steps:

#### 1. Environment Setup

Before you can authenticate, configure the required environment variables:

**Step 1:** Copy the template

```bash theme={null}
cp .env.local.template .env.local
```

**Step 2:** Generate and add ENCRYPTION\_KEY

```bash theme={null}
openssl rand -hex 32
```

Add the generated key to your `.env.local` file:

```text theme={null}
ENCRYPTION_KEY=<generated_key>
```

Without the ENCRYPTION\_KEY, the authentication endpoints will fail with server configuration errors.

#### 2. Authentication

First, you need to authenticate to get a JWT token:

```bash theme={null}
curl -X POST "http://your-falkordb-browser-url/api/auth/tokens/credentials" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "default",
    "password": "",
    "host": "localhost",
    "port": "6379",
    "tls": "false"
  }'
```

This will return a JWT token that you'll use for all subsequent requests:

```json theme={null}
{
  "message": "Token created successfully",
  "token": "<JWT_TOKEN>"
}
```

#### 3. Check Connection Status

Verify that FalkorDB is running and accessible:

```bash theme={null}
curl -X GET "http://your-falkordb-browser-url/api/status" \
  -H "Authorization: Bearer $JWT_TOKEN"
```

#### 4. List Available Graphs

See what graphs are available in your FalkorDB instance:

```bash theme={null}
AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}"
curl -X GET "http://your-falkordb-browser-url/api/graph" \
  -H "$AUTH_HEADER"
```

#### 5. Execute Your First Query

Run a simple Cypher query on a graph:

```bash theme={null}
AUTH_HEADER="Authorization: Bearer ${JWT_TOKEN}"
curl -N -X GET "http://your-falkordb-browser-url/api/graph/my_graph?query=MATCH%20(n)%20RETURN%20n%20LIMIT%205&timeout=30000" \
  -H "$AUTH_HEADER" \
  -H "Accept: text/event-stream"
```

## Authentication

All endpoints except `/api/auth/tokens/credentials` require authentication using a JWT bearer token in the Authorization header:

```http theme={null}
Authorization: Bearer <your-jwt-token>
```

### **Generate JWT Token with Credentials** - `POST /api/auth/tokens/credentials`

Authenticate with direct credentials and generate a JWT Personal Access Token (PAT) for external API access, CLI tools, or programmatic access. This endpoint does NOT require an existing session.

#### Request Body

* Content-Type: `application/json`
* Required fields: `username`, `host`, `port`, `tls`
* Optional fields: `password`, `name`, `expiresAt`, `ttlSeconds`

Example request:

```json theme={null}
{
  "username": "default",
  "password": "",
  "name": "API Token",
  "expiresAt": null,
  "ttlSeconds": 31622400,
  "host": "localhost",
  "port": "6379",
  "tls": "false"
}
```

**Request Parameters:**

* `username` (required): Username for database connection
* `password` (optional): Password for database connection. Can be omitted (or empty) only when using the `default` user on localhost; otherwise a non-empty password is required
* `name` (optional): Token name
* `expiresAt` (optional): Token expiration date in ISO 8601 format
* `ttlSeconds` (optional): Time-to-live in seconds (max: 31622400)
* `host` (required): FalkorDB host
* `port` (required): FalkorDB port
* `tls` (required): Enable TLS connection - "true" or "false"

#### Responses

* **200**: Token generated successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Token created successfully",
      "token": "<JWT_TOKEN>"
    }
    ```

* **400**: Bad request - Invalid JSON, validation error, expiration date in the past, or invalid TTL value
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Expiration date must be in the future"
    }
    ```

* **401**: Authentication failed - Invalid credentials or connection failed
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Invalid credentials or connection failed"
    }
    ```

* **500**: Server configuration error - Missing NEXTAUTH\_SECRET or ENCRYPTION\_KEY
  * Content-Type: `application/json`
  * Example responses:

    ```json theme={null}
    {
      "message": "Server configuration error: NEXTAUTH_SECRET not set"
    }
    ```

    ```json theme={null}
    {
      "message": "Server configuration error: ENCRYPTION_KEY not set"
    }
    ```

### **List JWT tokens** - `GET /api/auth/tokens`

Get a list of active JWT tokens. Admins see all tokens, regular users see only their own tokens.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Responses

* **200**: List of tokens retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "tokens": [
        {
          "user_id": "7262bcaecc2b06ff66e28ede90e6dce39c218685af9272d7a3fbd63ae08d17c2",
          "token_id": "1761055513181-215c579b-c6e1-4f10-9b07-aacbf89cda21",
          "created_at": "2025-10-21T14:05:13.182Z",
          "expires_at": "2026-10-21T14:05:13.182Z",
          "last_used": null,
          "name": "API Token",
          "permissions": ["Admin"],
          "username": "adminuser"
        }
      ],
      "count": 8
    }
    ```

* **401**: Authentication failed - invalid or missing token

* **500**: Internal server error

### **Get token metadata** - `GET /api/auth/tokens/{tokenId}`

Get detailed metadata for a specific JWT token by its token ID. Admins can view any token, regular users can only view their own tokens.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `tokenId` (path, required): Token ID to retrieve
  * Example: `1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81`

#### Responses

* **200**: Token metadata retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "token": {
        "user_id": "e5d09e7d2141f77f80008ff73f04104b9484f59baa8e19a4ea758495d289fd0f",
        "token_id": "1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81",
        "created_at": "2025-10-21T13:25:08.085Z",
        "expires_at": "2026-10-21T13:25:08.085Z",
        "last_used": null,
        "name": "API Token",
        "permissions": ["Read-Only"],
        "username": "readonlyuser"
      }
    }
    ```

* **401**: Authentication failed - invalid or missing token

* **403**: Forbidden - You can only view your own tokens (unless you are an Admin)
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Forbidden: You can only view your own tokens"
    }
    ```

* **404**: Token not found
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Token not found"
    }
    ```

* **500**: Internal server error

### **Revoke token by ID** - `DELETE /api/auth/tokens/{tokenId}`

Revoke a specific JWT token by its token ID. Once revoked, the token cannot be used for authentication. Admins can revoke any token, regular users can only revoke their own tokens.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `tokenId` (path, required): Token ID to revoke
  * Example: `1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81`

#### Responses

* **200**: Token revoked successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Token revoked successfully",
      "tokenId": "1761053108078-554350d7-c965-4ed7-8d32-679b7f705e81"
    }
    ```

* **400**: Bad request - Token is already revoked
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Token is already revoked"
    }
    ```

* **401**: Authentication failed - invalid or missing token

* **403**: Forbidden - You can only revoke your own tokens (unless you are an Admin)
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Forbidden: You can only revoke your own tokens"
    }
    ```

* **404**: Token not found
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Token not found"
    }
    ```

* **500**: Internal server error

***

## Status

### **Check FalkorDB connection status** - `GET /api/status`

Returns the current connection status to the FalkorDB database.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Responses

* **200**: Database is online and accessible
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "status": "online"
    }
    ```

* **404**: Database is offline or not accessible

* **500**: Internal server error

***

## Graph Management

### **List all graphs** - `GET /api/graph`

Get a list of all graphs in the FalkorDB instance.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Responses

* **200**: List of graphs retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "opts": [
        "social_network",
        "product_catalog",
        "user_interactions"
      ]
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Execute graph query** - `GET /api/graph/{graph}`

Execute a Cypher query on the specified graph (Server-Sent Events).

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name to query
  * Example: `social_network`
* `query` (query, required): Cypher query to execute
  * Example: `MATCH (n) RETURN n LIMIT 10`
* `timeout` (query, required): Query timeout in milliseconds
  * Example: `30000`

#### Responses

* **200**: Query executed successfully (Server-Sent Events stream)

### **Create or verify a graph** - `POST /api/graph/{graph}`

Create a new graph or verify that a graph exists.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name to create or verify

#### Responses

* **200**: Graph created or verified successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Graph created successfully"
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Rename graph** - `PATCH /api/graph/{graph}`

Rename an existing graph to a new name.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): New graph name
* `sourceName` (query, required): Current graph name to rename

#### Responses

* **200**: Graph renamed successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "data": {
        "result": "Graph renamed successfully"
      }
    }
    ```

* **400**: Bad request - graph already exists or missing sourceName

* **500**: Internal server error

### **Delete a graph** - `DELETE /api/graph/{graph}`

Delete a graph from the FalkorDB instance.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name to delete

#### Responses

* **200**: Graph deleted successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "graph_name graph deleted"
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Get query execution plan** - `GET /api/graph/{graph}/explain`

Get the execution plan for a Cypher query without executing it.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `query` (query, required): Cypher query to explain

#### Responses

* **200**: Query execution plan returned successfully

### **Profile query execution** - `GET /api/graph/{graph}/profile`

Get detailed profiling information for a Cypher query.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `query` (query, required): Cypher query to profile

#### Responses

* **200**: Query profiling information returned successfully

### **Get graph information** - `GET /api/graph/{graph}/info`

Get specific information about a graph (functions, property keys, labels, or relationship types).

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `type` (query, required): Type of information to retrieve
  * Options: `(function)`, `(property key)`, `(label)`, `(relationship type)`
  * Example: `(label)`

#### Responses

* **200**: Graph information retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "result": {
        "data": [
          {"(label)": "Person"},
          {"(label)": "Company"}
        ]
      }
    }
    ```

* **400**: Bad request - missing or invalid type parameter

### **Get graph element counts** - `GET /api/graph/{graph}/count`

Get the count of nodes and relationships in a graph.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name

#### Responses

* **200**: Element counts retrieved successfully

### **Export graph data** - `GET /api/graph/{graph}/export`

Export graph data in various formats.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name

#### Responses

* **200**: Graph data exported successfully

### **Duplicate a graph** - `PATCH /api/graph/{graph}/duplicate`

Create a copy of an existing graph with a new name.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): New graph name for the duplicate
* `sourceName` (query, required): Source graph name to duplicate from

#### Responses

* **200**: Graph duplicated successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "result": {
        "status": "Graph duplicated successfully"
      }
    }
    ```

* **400**: Bad request - missing sourceName parameter

* **500**: Internal server error

### **Get node information** - `GET /api/graph/{graph}/{node}`

Get detailed information about a specific node.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node ID

#### Responses

* **200**: Node information retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "result": {
        "data": [
          {
            "node": {
              "id": 1,
              "labels": ["Person"],
              "properties": {
                "name": "John Doe",
                "age": 30
              }
            },
            "relationships": []
          }
        ]
      }
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Delete node or relationship** - `DELETE /api/graph/{graph}/{node}`

Delete a node or relationship from the graph.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node or relationship ID

#### Request Body

* Content-Type: `application/json`
* Required field: `type`

Example request:

```json theme={null}
{
  "type": true
}
```

* `type`: `true` to delete a node, `false` to delete a relationship

#### Responses

* **200**: Node or relationship deleted successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Node deleted successfully"
    }
    ```

* **400**: Bad request - missing type parameter

* **500**: Internal server error

### **Add node label** - `POST /api/graph/{graph}/{node}/label`

Add a label to a specific node.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node ID

#### Request Body

* Content-Type: `application/json`

Example request:

```json theme={null}
{
  "label": "your_label"
}
```

#### Responses

* **200**: Label added successfully

### **Remove node label** - `DELETE /api/graph/{graph}/{node}/label`

Remove a label from a specific node.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node ID

#### Request Body

* Content-Type: `application/json`

Example request:

```json theme={null}
{
  "label": "your_label"
}
```

#### Responses

* **200**: Label removed successfully

### **Set node/relationship property** - `POST /api/graph/{graph}/{node}/{key}`

Set a property value on a node or relationship.

**IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node or relationship ID
* `key` (path, required): Property key name

#### Request Body

* Content-Type: `application/json`
* Required fields: `value`, `type`

Example request:

```json theme={null}
{
  "value": "your_property_value",
  "type": true
}
```

* `value`: Property value to set
* `type`: `true` for nodes, `false` for relationships

#### Responses

* **200**: Property set successfully

### **Remove node/relationship property** - `DELETE /api/graph/{graph}/{node}/{key}`

Remove a property from a node or relationship.

**IMPORTANT:** Use `type=true` for nodes, `type=false` for relationships.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `graph` (path, required): Graph name
* `node` (path, required): Node or relationship ID
* `key` (path, required): Property key name

#### Request Body

* Content-Type: `application/json`
* Required field: `type`

Example request:

```json theme={null}
{
  "type": true
}
```

* `type`: `true` for nodes, `false` for relationships

#### Responses

* **200**: Property removed successfully

***

## Configuration Management

### **Get all configuration values** - `GET /api/graph/config`

Get all FalkorDB configuration parameters and their values.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Responses

* **200**: Configuration values retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "configs": {
        "MAX_INFO_QUERIES": 700,
        "CMD_INFO": "server",
        "TIMEOUT": 1000
      }
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Get specific configuration value** - `GET /api/graph/config/{config}`

Get the value of a specific configuration parameter.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `config` (path, required): Configuration parameter name
  * Example: `MAX_INFO_QUERIES`

#### Responses

* **200**: Configuration value retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "config": 700
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Set configuration value** - `POST /api/graph/config/{config}`

Set the value of a specific configuration parameter.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `config` (path, required): Configuration parameter name
  * Example: `MAX_INFO_QUERIES`
* `value` (query, required): Configuration value to set (numeric values will be parsed as integers except for CMD\_INFO)
  * Example: `700`

#### Responses

* **200**: Configuration value set successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "config": "OK"
    }
    ```

* **400**: Bad request - missing value or invalid value

* **500**: Internal server error

***

***

## User Management

### **List all users** - `GET /api/user`

Get a list of all FalkorDB users.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Responses

* **200**: List of users retrieved successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "result": [
        {
          "username": "john_doe",
          "role": "Read-Write",
          "selected": false
        },
        {
          "username": "admin_user",
          "role": "Admin",
          "selected": false
        }
      ]
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Create new user** - `POST /api/user`

Create a new FalkorDB user with specified username, password, and role.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Request Body

* Content-Type: `application/json`
* Required fields: `username`, `password`, `role`

Example request:

```json theme={null}
{
  "username": "new_user",
  "password": "secure_password",
  "role": "Read-Write"
}
```

* `username`: Username for the new user
* `password`: Password for the new user
* `role`: Role to assign to the user (`Admin`, `Read-Write`, `Read-Only`)

#### Responses

* **201**: User created successfully
  * Content-Type: `application/json`

  * Example response:

    ```json theme={null}
    {
      "message": "Success"
    }
    ```

  * Headers:
    * `location`: Location of the created user resource (example: `/api/db/user/new_user`)

* **400**: Bad request - missing parameters

* **409**: User already exists

* **500**: Internal server error

### **Delete multiple users** - `DELETE /api/user`

Delete multiple FalkorDB users by providing an array of usernames.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Request Body

* Content-Type: `application/json`
* Required field: `users`

Example request:

```json theme={null}
{
  "users": [
    { "username": "user_1741261105156" },
    { "username": "another_user" }
  ]
}
```

* `users`: Array of user objects to delete

#### Responses

* **200**: Users deleted successfully
  * Content-Type: `application/json`
  * Example response:

    ```json theme={null}
    {
      "message": "Users deleted"
    }
    ```

* **400**: Bad request

* **500**: Internal server error

### **Update user role** - `PATCH /api/user/{user}`

Update the role of a FalkorDB user.

#### Headers

* `Authorization: Bearer <token>` (required)

#### Parameters

* `user` (path, required): Username to update
* `role` (query, required): New role for the user (`Admin`, `Read-Write`, `Read-Only`)

#### Responses

* **200**: User role updated successfully

***

## Error Responses

All endpoints may return the following common error responses:

* **401**: Unauthorized - Invalid or missing authentication token
* **403**: Forbidden - Insufficient permissions for the requested operation
* **404**: Not Found - Requested resource does not exist
* **500**: Internal Server Error - Unexpected server error

## Data Types

### Attribute Types

The following data types are supported for node and relationship attributes:

* `STRING`: Text values
* `INTEGER`: Numeric integer values
* `FLOAT`: Numeric decimal values
* `BOOLEAN`: True/false values

### Attribute Configuration

When defining attributes, use the following format:

```json theme={null}
[type, default_value, unique, required]
```

* `type`: One of the supported data types (`STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`)
* `default_value`: Default value for the attribute
* `unique`: `"true"` if the attribute must be unique, `"false"` otherwise
* `required`: `"true"` if the attribute is required, `"false"` otherwise

Example:

```json theme={null}
["STRING", "default_name", "false", "true"]
```

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How do I authenticate with the FalkorDB REST API?">
    Use **Bearer Token (JWT)** authentication. First, call the `/api/auth/tokens/credentials` endpoint with your credentials to obtain a token, then include it as `Authorization: Bearer <token>` in subsequent requests.
  </Accordion>

  <Accordion title="What is the ENCRYPTION_KEY and why is it required?">
    The `ENCRYPTION_KEY` is a hex string (generated via `openssl rand -hex 32`) stored in your `.env.local` file. It is required for the authentication system to function — without it, auth endpoints will return server configuration errors.
  </Accordion>

  <Accordion title="What operations can I perform through the REST API?">
    The REST API supports **graph management** (create, delete, list graphs), **query execution** (run Cypher queries), **node and edge operations** (CRUD), **schema management**, and **authentication** (token generation and validation).
  </Accordion>

  <Accordion title="What data types are supported for node/edge attributes?">
    Supported data types include `STRING`, `INTEGER`, `FLOAT`, and `BOOLEAN`. Attributes are configured with type, default value, uniqueness constraint, and required flag.
  </Accordion>

  <Accordion title="Can I use the REST API for production workloads?">
    Yes, the REST API is the primary interface for the FalkorDB Browser and supports full graph database operations. For high-throughput scenarios, consider using the native client libraries which communicate over the Redis protocol.
  </Accordion>
</AccordionGroup>