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. Environment Setup

Before you can authenticate, configure the required environment variables:

Step 1: Copy the template

cp .env.local.template .env.local

Step 2: Generate and add ENCRYPTION_KEY

openssl rand -hex 32

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

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:

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>"
}

3. 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"

4. 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"

5. 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 or ENCRYPTION_KEY
    • Content-Type: application/json

    • Example responses:

      {
  "message": "Server configuration error: NEXTAUTH_SECRET not set"
}

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

      {
  "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"]
Frequently Asked Questions 5
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.

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.

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

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.

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.