FalkorDB Browser REST API

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. Authentication

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

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:

{
  "message": "Token created successfully",
  "token": "<JWT_TOKEN>"
}

2. Check Connection Status

Verify that FalkorDB is running and accessible:

curl -X GET "http://your-falkordb-browser-url/api/status" \
  -H "Authorization: Bearer $JWT_TOKEN"

3. List Available Graphs

See what graphs are available in your FalkorDB instance:

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

4. Execute Your First Query

Run a simple Cypher query on a graph:

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:

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:

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

{
  "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:
```
{
  "message": "Expiration date must be in the future"
}
```
401: Authentication failed - Invalid credentials or connection failed
- Content-Type: application/json
- Example response:
```
{
  "message": "Invalid credentials or connection failed"
}
```
500: Server configuration error - Missing NEXTAUTH_SECRET
- Content-Type: application/json
- Example response:
```
{
  "message": "Server configuration error: NEXTAUTH_SECRET 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:

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

{
  "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:
```
{
  "message": "Forbidden: You can only view your own tokens"
}
```
404: Token not found
- Content-Type: application/json
- Example response:
```
{
  "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:

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

400: Bad request - Token is already revoked
- Content-Type: application/json
- Example response:
```
{
  "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:
```
{
  "message": "Forbidden: You can only revoke your own tokens"
}
```
404: Token not found
- Content-Type: application/json
- Example response:
```
{
  "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:
```
{
  "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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[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:

["STRING", "default_name", "false", "true"]

FalkorDB Browser REST API

Getting Started

Quick Start Guide

1. Authentication

2. Check Connection Status

3. List Available Graphs

4. Execute Your First Query

Table of Contents

Authentication

Status

Graph Management

Configuration Management

User Management

Authentication

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

Request Body

Responses

List JWT tokens - GET /api/auth/tokens

Headers

Responses

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

Headers

Parameters

Responses

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

Headers

Parameters

Responses

Status

Check FalkorDB connection status - GET /api/status

Headers

Responses

Graph Management

List all graphs - GET /api/graph

Headers

Responses

Execute graph query - GET /api/graph/{graph}

Headers

Parameters

Responses

Create or verify a graph - POST /api/graph/{graph}

Headers

Parameters

Responses

Rename graph - PATCH /api/graph/{graph}

Headers

Parameters

Responses

Delete a graph - DELETE /api/graph/{graph}

Headers

Parameters

Responses

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

Headers

Parameters

Responses

Profile query execution - GET /api/graph/{graph}/profile

Headers

Parameters

Responses

Get graph information - GET /api/graph/{graph}/info

Headers

Parameters

Responses

Get graph element counts - GET /api/graph/{graph}/count

Headers

Parameters

Responses

Export graph data - GET /api/graph/{graph}/export

Headers

Parameters

Responses

Duplicate a graph - PATCH /api/graph/{graph}/duplicate

Headers

Parameters

Responses

Get node information - GET /api/graph/{graph}/{node}

Headers

Parameters

Responses

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

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

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

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

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

List all graphs - `GET /api/graph`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

List all users - `GET /api/user`

Create new user - `POST /api/user`

Delete multiple users - `DELETE /api/user`

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