Skip to main content

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"

Table of Contents​

Authentication​

Status​

Graph Management​

Configuration Management​

User Management​

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