Skip to content

REST_API.md

Latest commit

 

History

History
1116 lines (976 loc) · 52.7 KB

REST_API.md

File metadata and controls

1116 lines (976 loc) · 52.7 KB
Raw

REST API for LiteGraph

This document describes the REST API endpoints for LiteGraph Server.

For client SDK libraries that wrap this API, see the sdk/ directory:

Authentication

v8.0 Account Model

As of v8.0 there is a single kind of account. Administrators are ordinary users carrying elevated flags, not a separate identity:

  • IsSystemAdmin — full access to every tenant and every request type. Equivalent to the legacy administrator bearer token, but attached to a real user record.
  • IsTenantAdmin — full management of the user's own tenant, including its users and credentials, but not tenant creation/deletion or server settings.

A user with neither flag is a regular user, constrained by the roles and credential scopes described in RBAC.md. The administrator bearer token defined in litegraph.json remains as a break-glass credential and is treated as system-admin. Endpoints that read below say "administrator bearer token authentication" describe the pre-v8 requirement; under v8 the same endpoints are additionally reachable by a user whose flags or granted scopes permit the request — see RBAC.md for the full permission matrix.

Users can authenticate API requests in one of three ways.

Bearer Token

A bearer token can be supplied in the Authorization header, i.e. Authorization: Bearer {token}. This bearer token can either be from a Credential object mapped to a user by GUID, or, the administrator bearer token defined in litegraph.json.

Credentials

The user's email, password, and tenant GUID can be passed in as headers using x-email, x-password, and x-tenant-guid. This method does not work for administrative API calls, as the administrator is only defined by bearer token in litegraph.json.

Security token

Temporal security tokens can be generated for regular users (not for the administrator). These security tokens expire after 24 hours, and can be used in the x-token header as an alternative to using bearer tokens or credentials.

To generate a security token, set the x-email, x-password, and x-tenant-guid headers, and call GET /v1.0/token. The result will look as follows:

{
    "TimestampUtc": "2025-01-30T22:54:41.963425Z",
    "ExpirationUtc": "2025-01-31T22:54:41.963426Z",
    "IsExpired": false,
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "UserGUID": "00000000-0000-0000-0000-000000000000",
    "Token": "mXCNtMWDsW0/pr+IwRFUje2n5Z9/qDGprgAY26bz4KYoJOUyufkzkzfK+Kiq0iv/PsZkzwewIXsuCMkpqJbsMJFMd94fyt8LLHr4CL0NMn1etyK7AC+uLH/xUqVnP+Jdww8LhEV2ly3gx27h91fiXMT60ScKNM772o3zq1WUkD1yBL1MCcZsUkHXQw3ZiP4EsFoZ6oxqquwN+/cRZROKXAbPWvArwcDNIIz9vnBvcvjDJYVCz/LiPq5BXIHtzSP7QffBqiZtttEaql8LIu17c9ms02N2mB/nyF0FF6U97ay1Vbo0V/0/akiRnieOKGYCOjiJBuU1kZ28uiDj1pENpzS1GUqkt5HqK44Jl4LtIco=",
    "Valid": true
}

The value found in Token can then be used when making API requests to LiteGraph, by adding the x-token header with the value, i.e.

GET /v1.0/tenants/00000000-0000-0000-0000-000000000000/graphs
x-token: mXCNtMWDsW0/pr+IwRFUje2...truncated...4Jl4LtIco=

To retrieve the details of a token and to verify it has not expired, call GET /v1.0/token/details with the x-token header set.

GET /v1.0/token/details
x-token: mXCNtMWDsW0/pr+IwRFUje2...truncated...4Jl4LtIco=

Response:
{
    "TimestampUtc": "2025-01-30T14:54:41.963425Z",
    "ExpirationUtc": "2025-01-31T14:54:41.963426Z",
    "IsExpired": false,
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "UserGUID": "00000000-0000-0000-0000-000000000000",
    "Valid": true
}

If you do not know the tenant GUID ahead of time, use the API to retrieve tenants for a given email by calling GET /v1.0/token/tenants with the x-email header set. It will return the list of tenants associated with the supplied email address.

GET /v1.0/token/tenants
x-email: default@user.com

Response:
[
    {
        "GUID": "00000000-0000-0000-0000-000000000000",
        "Name": "Default tenant",
        "Active": true,
        "CreatedUtc": "2025-02-06T18:22:56.789353Z",
        "LastUpdateUtc": "2025-02-06T18:22:56.788994Z"
    }
]

Data Structures

Backup File

{
    "Filename": "my-backup.db",
    "Length": 352256,
    "MD5Hash": "EF2A390E654BCFE3052DAF7364037DBE",
    "SHA1Hash": "74625881C00FEF2E654AB9B800A0C8E23CC7CBB0",
    "SHA256Hash": "584F2D85362F7E7B9755DF7A363120E6FF8F93A162E918E7085C795021D14DCF",
    "CreatedUtc": "2025-05-27T03:31:10.904886Z",
    "LastUpdateUtc": "2025-05-27T03:31:10.909897Z",
    "LastAccessUtc": "2025-05-27T03:31:13.634489Z",
    "Data": "... base64 data ..."
}

Subgraph Extraction Request

Body for POST /v1.0/tenants/{tenantGuid}/graphs/{graphGuid}/export/jsonl. The traversal starts at one or more nodes and walks edges outward, honoring the depth, count, label, tag, filter, and cost limits below. Start nodes are always included in the output even when they fail the node filters, so a selection never comes back empty because of an over-tight filter on the seeds themselves.

{
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "StartNodeGUIDs": [ "11111111-1111-1111-1111-111111111111" ],
    "MaxDepth": 2,
    "Direction": "Both",
    "MaxNodes": 0,
    "MaxEdges": 0,
    "EdgeLabels": [ ],
    "EdgeTags": { },
    "EdgeFilter": { },
    "MaxEdgeCost": null,
    "NodeLabels": [ ],
    "NodeTags": { },
    "NodeFilter": { },
    "IncludeData": false,
    "IncludeSubordinates": false
}
Field Type Default Notes
StartNodeGUIDs array of GUID required At least one seed node; the traversal fails with 400 if empty or a GUID is not in the graph
MaxDepth int 2 Edge hops from the seeds; 0 returns the start nodes plus edges among them
Direction string Both Outbound, Inbound, or Both
MaxNodes int 0 Node cap; 0 is unlimited
MaxEdges int 0 Edge cap; 0 is unlimited
EdgeLabels array of string [] Edges must carry one of these labels to be traversed
EdgeTags object {} Edge tag key/value constraints
EdgeFilter expression {} Expression filter over edge Data
MaxEdgeCost int or null null Edges above this cost are not traversed
NodeLabels array of string [] Non-seed nodes must carry one of these labels
NodeTags object {} Node tag key/value constraints
NodeFilter expression {} Expression filter over node Data
IncludeData bool false Emit the Data object on each record
IncludeSubordinates bool false Emit labels, tags, and vectors on each record

Graph Import Result

Returned by both import/jsonl endpoints. Counters report exactly what happened per record type, Warnings collects non-fatal problems such as dropped dangling edges and skipped malformed lines, and GuidMap maps each original GUID to its replacement (populated only under the regenerate strategy).

{
    "Success": true,
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "9de1f1a2-4b8c-4f7a-9a1b-2c3d4e5f6a7b",
    "GraphsCreated": 1,
    "NodesCreated": 128,
    "NodesUpdated": 0,
    "NodesSkipped": 0,
    "EdgesCreated": 205,
    "EdgesUpdated": 0,
    "EdgesSkipped": 0,
    "LinesRead": 334,
    "LinesIgnored": 6,
    "Warnings": [ ],
    "GuidMap": { }
}

For a merge into an existing graph, GraphGUID is the target graph; for an import that creates a new graph, it is the GUID of the graph that was created.

JSONL Format

The interchange format is UTF-8 text with one JSON value per line, terminated by \n. A line beginning with # is a comment and is ignored on import, so exporters can prepend a metadata header without breaking round-trips. Every non-comment line is a typed envelope: {"Type":"Node"|"Edge"|"Graph","Object":{...}}, where Object is the same JSON shape the REST API returns for that entity. The writer emits the graph record first, then node records, then edge records, but the importer does not depend on that order.

A whole-graph export carries the graph-backup kind; a subgraph export carries the subgraph kind. A typical header looks like this:

# litegraph-jsonl v1
# kind: graph-backup
# exported-utc: 2026-08-19T17:22:34.986575Z
# source-tenant: 00000000-0000-0000-0000-000000000000
# source-graph: 00000000-0000-0000-0000-000000000000 (name: "Default graph")
# generator: LiteGraph
{"Type":"Graph","Object":{"GUID":"00000000-0000-0000-0000-000000000000","Name":"Default graph"}}
{"Type":"Node","Object":{"GUID":"11111111-1111-1111-1111-111111111111","Name":"Ada"}}
{"Type":"Edge","Object":{"GUID":"22222222-2222-2222-2222-222222222222","From":"11111111-1111-1111-1111-111111111111","To":"33333333-3333-3333-3333-333333333333"}}

Import reconciles incoming GUIDs according to guidstrategy. preserve keeps original GUIDs and errors on any collision, which suits a restore into a fresh database because node and edge GUIDs are globally unique in the store. regenerate assigns fresh GUIDs everywhere, remaps every reference through the GuidMap, and cannot collide, so it is the default for merging one graph into another. skip leaves existing records untouched and imports only what is new. overwrite updates existing records in place and creates the rest. When a file references a node that already exists in the target graph but is not present in the file, the bridging edge still imports; an edge whose endpoint resolves to neither the file nor the store is dropped with a warning. Imports stream through node batches and a buffered edge pass, and a failure triggers compensating rollback of the records written so far.

{
    "Ordering": "CreatedDescending",
    "IncludeData": true,
    "IncludeSubordinates": true,
    "MaxResults": 5,
    "ContinuationToken": null,
    "Labels": [ ],
    "Tags": { },
    "Expr": { }
}

Enumeration Result

{
    "Success": true,
    "Timestamp": {
        "Start": "2025-06-22T01:17:42.984885Z",
        "End": "2025-06-22T01:17:43.066948Z",
        "TotalMs": 82.06,
        "Messages": {}
    },
    "MaxResults": 5,
    "ContinuationToken": "ca10f6ca-f4c2-4040-adfe-9de3a81b9f55",
    "EndOfResults": false,
    "TotalRecords": 17,
    "RecordsRemaining": 12,
    "Objects": [
        {
            "TenantGUID": "00000000-0000-0000-0000-000000000000",
            "GUID": "ebefc55b-6f74-4997-8c87-e95e40cb83d3",
            "GraphGUID": "00000000-0000-0000-0000-000000000000",
            "Name": "Active Directory",
            "CreatedUtc": "2025-06-21T05:23:14.100128Z",
            "LastUpdateUtc": "2025-06-21T05:23:14.100128Z",
            "Labels": [],
            "Tags": {},
            "Data": {
                "Name": "Active Directory"
            },
            "Vectors": []
        }, ...
    ]
}

Tenant Statistics (All)

{
    "00000000-0000-0000-0000-000000000000": {
        "Graphs": 1,
        "Nodes": 17,
        "Edges": 22,
        "Labels": 0,
        "Tags": 0,
        "Vectors": 0
    }, ...
}

Tenant Statistics (Individual)

{
    "Graphs": 1,
    "Nodes": 17,
    "Edges": 22,
    "Labels": 0,
    "Tags": 0,
    "Vectors": 0
}

Graph Statistics (All)

{
    "00000000-0000-0000-0000-000000000000": {
        "Nodes": 17,
        "Edges": 22,
        "Labels": 0,
        "Tags": 0,
        "Vectors": 0
    }
}

Graph Statistics (Individual)

{
    "Nodes": 17,
    "Edges": 22,
    "Labels": 0,
    "Tags": 0,
    "Vectors": 0
}

Tenant

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Default tenant",
    "Active": true,
    "CreatedUtc": "2024-12-27T22:09:09.410802Z",
    "LastUpdateUtc": "2024-12-27T22:09:09.410168Z"
}

User

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "FirstName": "Default",
    "LastName": "User",
    "Email": "default@user.com",
    "Password": "password",
    "Active": true,
    "IsSystemAdmin": true,
    "IsTenantAdmin": true,
    "CreatedUtc": "2024-12-27T22:09:09.446911Z",
    "LastUpdateUtc": "2024-12-27T22:09:09.446777Z"
}

IsSystemAdmin and IsTenantAdmin were added in v8.0 and default to false. The seeded default user shown above is a system administrator.

Credential

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "UserGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Default credential",
    "BearerToken": "default",
    "Active": true,
    "CreatedUtc": "2024-12-27T22:09:09.468134Z",
    "LastUpdateUtc": "2024-12-27T22:09:09.467977Z"
}

Label

{
    "GUID": "738d4956-a833-429a-9531-c99336638617",
    "TenantGUID": "ba1dc0a6-372d-47ee-aea5-75e7dbbbd175",
    "GraphGUID": "97826e1a-d0c1-4884-820a-bfda74b3be33",
    "EdgeGUID": "971da046-8234-4627-8ae8-e062311874c8",
    "Label": "edge",
    "CreatedUtc": "2025-01-08T23:28:05.312128Z",
    "LastUpdateUtc": "2025-01-08T23:28:05.312128Z"
}

Tag

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "NodeGUID": "00000000-0000-0000-0000-000000000000",
    "EdgeGUID": "00000000-0000-0000-0000-000000000000",
    "Key": "mykey",
    "Value": "myvalue",
    "CreatedUtc": "2024-12-27T22:14:36.459901Z",
    "LastUpdateUtc": "2024-12-27T22:14:36.459902Z"
}

Vector

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "NodeGUID": "00000000-0000-0000-0000-000000000000",
    "EdgeGUID": "00000000-0000-0000-0000-000000000000",
    "Model": "testmodel",
    "Dimensionality": 3,
    "Content": "test content",
    "Vectors": [ 0.05, -0.25, 0.45 ],
    "CreatedUtc": "2025-01-15T10:41:13.243174Z",
    "LastUpdateUtc": "2025-01-15T10:41:13.243188Z"
}

Graph

{
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GUID": "00000000-0000-0000-0000-000000000000",
    "Name": "My test graph",
    "Labels": [ "test" ],
    "Tags": {
        "Key": "Value"
    },
    "Data": {
        "Hello": "World"
    },
    "Vectors": [
        {
            "GUID": "00000000-0000-0000-0000-000000000000",
            "TenantGUID": "00000000-0000-0000-0000-000000000000",
            "GraphGUID": "00000000-0000-0000-0000-000000000000",
            "NodeGUID": "00000000-0000-0000-0000-000000000000",
            "EdgeGUID": "00000000-0000-0000-0000-000000000000",
            "Model": "testmodel",
            "Dimensionality": 3,
            "Content": "test content",
            "Vectors": [ 0.05, -0.25, 0.45 ],
            "CreatedUtc": "2025-01-15T10:41:13.243174Z",
            "LastUpdateUtc": "2025-01-15T10:41:13.243188Z"
        }
    ],
    "CreatedUtc": "2024-07-01 15:43:06.991834"
}

Graph Vector Index

{
    "VectorIndexType": "HnswSqlite",
    "VectorIndexFile": "graph-00000000-0000-0000-0000-000000000000-hnsw.db",
    "VectorIndexThreshold": null,
    "VectorDimensionality": 384,
    "VectorIndexM": 16,
    "VectorIndexEf": 50,
    "VectorIndexEfConstruction": 200
}

Node

{
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GUID": "11111111-1111-1111-1111-111111111111",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "My test node",
    "Labels": [ "test" ],
    "Tags": {
        "Key": "Value"
    },
    "Data": {
        "Hello": "World"
    },
    "Vectors": [
        {
            "GUID": "00000000-0000-0000-0000-000000000000",
            "TenantGUID": "00000000-0000-0000-0000-000000000000",
            "GraphGUID": "00000000-0000-0000-0000-000000000000",
            "NodeGUID": "00000000-0000-0000-0000-000000000000",
            "EdgeGUID": "00000000-0000-0000-0000-000000000000",
            "Model": "testmodel",
            "Dimensionality": 3,
            "Content": "test content",
            "Vectors": [ 0.05, -0.25, 0.45 ],
            "CreatedUtc": "2025-01-15T10:41:13.243174Z",
            "LastUpdateUtc": "2025-01-15T10:41:13.243188Z"
        }
    ],
    "CreatedUtc": "2024-07-01 15:43:06.991834"
}

Edge

{
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "GUID": "FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "My test edge",
    "From": "11111111-1111-1111-1111-111111111111",
    "To": "22222222-2222-2222-2222-222222222222",
    "Cost": 10,
    "Labels": [ "test" ],
    "Tags": {
        "Key": "Value"
    },
    "Data": {
        "Hello": "World"
    },
    "Vectors": [
        {
            "GUID": "00000000-0000-0000-0000-000000000000",
            "TenantGUID": "00000000-0000-0000-0000-000000000000",
            "GraphGUID": "00000000-0000-0000-0000-000000000000",
            "NodeGUID": "00000000-0000-0000-0000-000000000000",
            "EdgeGUID": "00000000-0000-0000-0000-000000000000",
            "Model": "testmodel",
            "Dimensionality": 3,
            "Content": "test content",
            "Vectors": [ 0.05, -0.25, 0.45 ],
            "CreatedUtc": "2025-01-15T10:41:13.243174Z",
            "LastUpdateUtc": "2025-01-15T10:41:13.243188Z"
        }
    ],
    "CreatedUtc": "2024-07-01 15:43:06.991834"
}

Route Request

{
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Graph": "00000000-0000-0000-0000-000000000000",
    "From": "11111111-1111-1111-1111-111111111111",
    "To": "22222222-2222-2222-2222-222222222222",
    "NodeFilter": null,
    "EdgeFilter": null,
}

Existence Request

{
    "Nodes": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "Edges": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "EdgesBetween": [
        {
            "From": "[fromguid]",
            "To": "[toguid]"
        },
        ...
    ]
}

Existence Result

{
    "ExistingNodes": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "MissingNodes": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "ExistingEdges": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "MissingEdges": [
        "[guid1]",
        "[guid2]",
        ...
    ],
    "ExistingEdgesBetween": [
        {
            "From": "[fromguid]",
            "To": "[toguid]"
        },
        ...
    ],
    "MissingEdgesBetween": [
        {
            "From": "[fromguid]",
            "To": "[toguid]"
        },
        ...
    ]
}

Vector Search Request

{
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "Domain": "Node",
    "SearchType": "CosineSimilarity",
    "Labels": [],
    "Tags": {},
    "Expr": null,
    "TopK": 10,
    "MinimumScore": 0.1,
    "MaximumDistance": 100,
    "MinimumInnerProduct": 0.1,
    "Embeddings": [ 0.1, 0.2, 0.3 ]
}

Valid domains are Graph Node Edge Valid search types are CosineSimilarity CosineDistance EuclidianSimilarity EuclidianDistance DotProduct

Vector Search Result

[
    {
        "Score": 0.874456,
        "Distance": null,
        "InnerProduct": null,
        "Graph": { ... },
        "Node": { ... },
        "Edge": { ... }
    },
    ...
]

Graph Query Request

Native graph queries execute within one tenant and one graph. See DSL.md for the supported syntax, parameter rules, result metadata, mutation behavior, and examples.

{
    "Query": "MATCH (n:Person) WHERE n.data.role = $role RETURN n LIMIT 10",
    "Parameters": {
        "role": "engineer"
    },
    "MaxResults": 100,
    "TimeoutSeconds": 30,
    "IncludeProfile": false
}

Read-only queries require read permission. Mutation queries require write permission.

Graph Query Response

{
    "Success": true,
    "Mutated": false,
    "RowCount": 1,
    "Rows": [
        {
            "n": {
                "GUID": "00000000-0000-0000-0000-000000000000",
                "Name": "Ada"
            }
        }
    ],
    "Objects": [],
    "Plan": {
        "Kind": "Read",
        "UsesVectorSearch": false,
        "Mutates": false
    },
    "ExecutionProfile": null
}

Graph Transaction Request

Graph transactions execute atomically inside one tenant and one graph. See TRANSACTIONS.md for the complete operation model.

{
    "Operations": [
        {
            "OperationType": "Create",
            "ObjectType": "Node",
            "Payload": {
                "Name": "Ada",
                "Data": {
                    "role": "mathematician"
                }
            }
        }
    ],
    "MaxOperations": 100,
    "TimeoutSeconds": 30,
    "IsolationLevel": "Default"
}

Server-side REST settings can cap transaction size and timeout through LiteGraph.Transactions.MaxOperations, LiteGraph.Transactions.MaxTimeoutSeconds, LITEGRAPH_TRANSACTION_MAX_OPERATIONS, and LITEGRAPH_TRANSACTION_MAX_TIMEOUT_SECONDS.

Graph Transaction Response

Committed transactions return HTTP 200. Request-shape validation failures return HTTP 400 with a transaction result body and ValidationFailure: true when LiteGraph can identify the failed operation. Failed transaction execution after provider work begins returns HTTP 409 with the same transaction result shape so callers can inspect rollback diagnostics.

{
    "Success": true,
    "TransactionId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "State": "Committed",
    "RolledBack": false,
    "ValidationFailure": false,
    "FailedOperationIndex": null,
    "Error": null,
    "Operations": [
        {
            "Index": 0,
            "OperationType": "Create",
            "ObjectType": "Node",
            "GUID": "00000000-0000-0000-0000-000000000000",
            "Success": true,
            "Result": { },
            "Error": null
        }
    ],
    "OperationCount": 1,
    "StartedUtc": "2026-06-17T19:00:00.000000Z",
    "CompletedUtc": "2026-06-17T19:00:00.012500Z",
    "DurationMs": 12.5,
    "CommitDurationMs": 1.25,
    "RollbackDurationMs": 0,
    "Provider": "Postgresql",
    "IsolationLevel": "Default",
    "IsolatedRepository": true,
    "SerializedByGate": false,
    "RetryCount": 0,
    "Retryable": false,
    "ConcurrencyConflict": false,
    "ProviderErrorCode": null
}

Authorization Role

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "GraphReader",
    "Description": "Read-only graph access",
    "BuiltIn": false,
    "Immutable": false,
    "Permissions": [ "Read" ],
    "ResourceTypes": [ "Graph", "Node", "Edge", "Label", "Tag", "Vector", "Query" ],
    "ResourceScope": "Graph",
    "InheritToGraphs": false
}

User Role Assignment

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "UserGUID": "00000000-0000-0000-0000-000000000000",
    "RoleGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "Active": true
}

Credential Scope Assignment

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "CredentialGUID": "00000000-0000-0000-0000-000000000000",
    "RoleGUID": "00000000-0000-0000-0000-000000000000",
    "GraphGUID": "00000000-0000-0000-0000-000000000000",
    "Permissions": [ "Read" ],
    "ResourceTypes": [ "Graph", "Node", "Edge", "Query" ],
    "Active": true
}

General APIs

API Method URL
Validate connectivity HEAD /
Server information GET /
Prometheus metrics GET /metrics

The metrics route is registered only when observability and Prometheus are enabled. It is intentionally unauthenticated in v6.0.0 and should be protected by network policy or a reverse proxy when exposed outside trusted networks.

Admin APIs

Admin APIs require system-administrator authentication (the administrator bearer token, or a user with IsSystemAdmin).

API Method URL
Flush in-memory database to disk POST /v1.0/flush

Settings APIs

Introduced in v8.0. Settings APIs require system-administrator authentication. See SETTINGS.md for the field-by-field reference and which fields apply live versus require a restart.

API Method URL
Read settings GET /v1.0/settings
Update settings PUT /v1.0/settings
Restart server POST /v1.0/settings/restart

GET /v1.0/settings returns the effective server settings (secrets redacted). PUT /v1.0/settings persists the supplied settings to litegraph.json, hot-reloads fields that can apply live, and returns a SettingsUpdateResult:

{
    "Success": true,
    "AppliedLive": [ "RequestTimeoutSeconds" ],
    "RestartRequired": [ "Rest.Port" ],
    "Message": "Settings saved. 1 field applied live; 1 field requires a restart."
}

POST /v1.0/settings/restart flushes pending state and exits the process so the container/orchestrator restarts it with the new configuration. In the checked-in Docker deployment the LiteGraph services run with restart: unless-stopped, so this brings the server back automatically.

Backup APIs

Backup APIs require administrator bearer token authentication.

API Method URL
Create POST /v1.0/backups
Read many GET /v1.0/backups
Read GET /v1.0/backups/[guid]
Delete DELETE /v1.0/backups/[guid]
Exists HEAD /v1.0/backups/[guid]

Tenant APIs

Tenant create and delete require system-administrator authentication. Tenant read/exists and update are additionally available to a tenant-administrator of that tenant (IsTenantAdmin), and any authenticated user may read the tenants associated with their email via GET /v1.0/token/tenants.

When specifying multiple GUIDs to retrieve, i.e. ?guids=..., use a comma-separated list of values, i.e. ?guids=00000000-0000-0000-0000-000000000000,11111111-1111-1111-1111-111111111111.

API Method URL
Create PUT /v1.0/tenants
Update PUT /v1.0/tenants/[guid]
Read many GET /v1.0/tenants
Read many GET /v1.0/tenants?guids=...
Read GET /v1.0/tenants/[guid]
Delete DELETE /v1.0/tenants/[guid]
Delete w/ cascade DELETE /v1.0/tenants/[guid]?force
Exists HEAD /v1.0/tenants/[guid]

User APIs

User management (create, delete, list, cross-user read/update) requires system-administrator authentication or a tenant-administrator of the target tenant. A regular user may additionally read, check existence of, and update their own user record (self-service); they cannot list users or act on other users.

The UserMaster object carries two v8.0 flags: IsSystemAdmin and IsTenantAdmin (both default false). Only a system-administrator may set IsSystemAdmin; a tenant-administrator may set IsTenantAdmin on users within their own tenant. Both flags are returned on user reads and are redacted-safe (they are not secrets).

API Method URL
Create PUT /v1.0/tenants/[guid]/users
Update PUT /v1.0/tenants/[guid]/users/[guid]
Read many GET /v1.0/tenants/[guid]/users
Read many GET /v1.0/tenants/[guid]/users?guids=...
Read GET /v1.0/tenants/[guid]/users/[guid]
Delete DELETE /v1.0/tenants/[guid]/users/[guid]
Exists HEAD /v1.0/tenants/[guid]/users/[guid]

Credential APIs

Credential APIs require system-administrator authentication or a tenant-administrator of the target tenant.

API Method URL
Create PUT /v1.0/tenants/[guid]/credentials
Update PUT /v1.0/tenants/[guid]/credentials/[guid]
Read many GET /v1.0/tenants/[guid]/credentials
Read many GET /v1.0/tenants/[guid]/credentials?guids=...
Read GET /v1.0/tenants/[guid]/credentials/[guid]
Read by bearer token GET /v1.0/credentials/bearer/[bearerToken]
Delete DELETE /v1.0/tenants/[guid]/credentials/[guid]
Delete all in tenant DELETE /v1.0/tenants/[guid]/credentials
Delete by user DELETE /v1.0/tenants/[guid]/users/[guid]/credentials
Exists HEAD /v1.0/tenants/[guid]/credentials/[guid]

Authorization APIs

Authorization APIs require an administrator bearer token or an authenticated user/credential with an effective admin grant for the requested scope. Built-in roles are readable but immutable.

API Method URL
Create role PUT /v1.0/tenants/[tenantGuid]/roles
Read roles GET /v1.0/tenants/[tenantGuid]/roles
Read role GET /v1.0/tenants/[tenantGuid]/roles/[roleGuid]
Update role PUT /v1.0/tenants/[tenantGuid]/roles/[roleGuid]
Delete role DELETE /v1.0/tenants/[tenantGuid]/roles/[roleGuid]
Assign user role PUT /v1.0/tenants/[tenantGuid]/users/[userGuid]/roles
Read user role assignments GET /v1.0/tenants/[tenantGuid]/users/[userGuid]/roles
Read user role assignment GET /v1.0/tenants/[tenantGuid]/users/[userGuid]/roles/[assignmentGuid]
Update user role assignment PUT /v1.0/tenants/[tenantGuid]/users/[userGuid]/roles/[assignmentGuid]
Delete user role assignment DELETE /v1.0/tenants/[tenantGuid]/users/[userGuid]/roles/[assignmentGuid]
Read user effective permissions GET /v1.0/tenants/[tenantGuid]/users/[userGuid]/permissions
Assign credential scope PUT /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/scopes
Read credential scope assignments GET /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/scopes
Read credential scope assignment GET /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/scopes/[assignmentGuid]
Update credential scope assignment PUT /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/scopes/[assignmentGuid]
Delete credential scope assignment DELETE /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/scopes/[assignmentGuid]
Read credential effective permissions GET /v1.0/tenants/[tenantGuid]/credentials/[credentialGuid]/permissions

See RBAC.md for role definitions, permission/resource mappings, compatibility behavior for existing users, and credential-scope examples.

Label APIs

Label APIs require administrator bearer token authentication.

Bulk create endpoints accept an optional return query parameter. Omit it or use return=full to keep the existing response shape. Use return=minimal to return only top-level created objects and skip optional node/edge subordinate hydration. Invalid values return 400 BadRequest.

API Method URL
Create PUT /v1.0/tenants/[guid]/labels
Create many PUT /v1.0/tenants/[guid]/labels/bulk?return=minimal
Update PUT /v1.0/tenants/[guid]/labels/[guid]
Read many GET /v1.0/tenants/[guid]/labels
Read many GET /v1.0/tenants/[guid]/labels?guids=...
Read GET /v1.0/tenants/[guid]/labels/[guid]
Read all in tenant GET /v1.0/tenants/[guid]/labels/all
Read all in graph GET /v1.0/tenants/[guid]/graphs/[guid]/labels/all
Read graph labels GET /v1.0/tenants/[guid]/graphs/[guid]/labels
Read node labels GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/labels
Read edge labels GET /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/labels
Delete DELETE /v1.0/tenants/[guid]/labels/[guid]
Delete multiple DELETE /v1.0/tenants/[guid]/labels/bulk
Delete all in tenant DELETE /v1.0/tenants/[guid]/labels/all
Delete all in graph DELETE /v1.0/tenants/[guid]/graphs/[guid]/labels/all
Delete graph labels DELETE /v1.0/tenants/[guid]/graphs/[guid]/labels
Delete node labels DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/labels
Delete edge labels DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/labels
Exists HEAD /v1.0/tenants/[guid]/labels/[guid]

Tag APIs

Tag APIs require administrator bearer token authentication.

API Method URL
Create PUT /v1.0/tenants/[guid]/tags
Create many PUT /v1.0/tenants/[guid]/tags/bulk?return=minimal
Update PUT /v1.0/tenants/[guid]/tags/[guid]
Read many GET /v1.0/tenants/[guid]/tags
Read many GET /v1.0/tenants/[guid]/tags?guids=...
Read GET /v1.0/tenants/[guid]/tags/[guid]
Read all in tenant GET /v1.0/tenants/[guid]/tags/all
Read all in graph GET /v1.0/tenants/[guid]/graphs/[guid]/tags/all
Read graph tags GET /v1.0/tenants/[guid]/graphs/[guid]/tags
Read node tags GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/tags
Read edge tags GET /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/tags
Delete DELETE /v1.0/tenants/[guid]/tags/[guid]
Delete all in tenant DELETE /v1.0/tenants/[guid]/tags/all
Delete all in graph DELETE /v1.0/tenants/[guid]/graphs/[guid]/tags/all
Delete graph tags DELETE /v1.0/tenants/[guid]/graphs/[guid]/tags
Delete node tags DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/tags
Delete edge tags DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/tags
Exists HEAD /v1.0/tenants/[guid]/tags/[guid]

Vector APIs

Vector APIs require administrator bearer token authentication, aside from the vector search API.

API Method URL
Create PUT /v1.0/tenants/[guid]/vectors
Create many PUT /v1.0/tenants/[guid]/vectors/bulk?return=minimal
Update PUT /v1.0/tenants/[guid]/vectors/[guid]
Read many GET /v1.0/tenants/[guid]/vectors
Read many GET /v1.0/tenants/[guid]/vectors?guids=...
Read GET /v1.0/tenants/[guid]/vectors/[guid]
Read all in tenant GET /v1.0/tenants/[guid]/vectors/all
Read all in graph GET /v1.0/tenants/[guid]/graphs/[guid]/vectors/all
Read graph vectors GET /v1.0/tenants/[guid]/graphs/[guid]/vectors
Read node vectors GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/vectors
Read edge vectors GET /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/vectors
Delete DELETE /v1.0/tenants/[guid]/vectors/[guid]
Delete all in tenant DELETE /v1.0/tenants/[guid]/vectors/all
Delete all in graph DELETE /v1.0/tenants/[guid]/graphs/[guid]/vectors/all
Delete graph vectors DELETE /v1.0/tenants/[guid]/graphs/[guid]/vectors
Delete node vectors DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/vectors
Delete edge vectors DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]/vectors
Exists HEAD /v1.0/tenants/[guid]/vectors/[guid]
Search POST /v1.0/tenants/[guid]/vectors
Search in graph POST /v1.0/tenants/[guid]/graphs/[guid]/vectors/search

Graph APIs

API Method URL
Create PUT /v1.0/tenants/[guid]/graphs
Update PUT /v1.0/tenants/[guid]/graphs/[guid]
Read GET /v1.0/tenants/[guid]/graphs/[guid]
Read many GET /v1.0/tenants/[guid]/graphs
Read many GET /v1.0/tenants/[guid]/graphs?guids=...
Read all in tenant GET /v1.0/tenants/[guid]/graphs/all
Read first POST /v1.0/tenants/[guid]/graphs/first
Statistics GET /v1.0/tenants/[guid]/graphs/[guid]/stats
All graph statistics GET /v1.0/tenants/[guid]/graphs/stats
Delete DELETE /v1.0/tenants/[guid]/graphs/[guid]
Delete w/ cascade DELETE /v1.0/tenants/[guid]/graphs/[guid]?force
Delete all in tenant DELETE /v1.0/tenants/[guid]/graphs/all
Exists HEAD /v1.0/tenants/[guid]/graphs/[guid]
Search POST /v1.0/tenants/[guid]/graphs/search
Render as GEXF GET /v1.0/tenants/[guid]/graphs/[guid]/export/gexf?incldata
Export as JSONL GET /v1.0/tenants/[guid]/graphs/[guid]/export/jsonl?incldata&inclsub
Export subgraph JSONL POST /v1.0/tenants/[guid]/graphs/[guid]/export/jsonl
Import JSONL (merge) POST /v1.0/tenants/[guid]/graphs/[guid]/import/jsonl?guidstrategy=regenerate&onerror=abort&batchsize=1000
Import JSONL (new graph) POST /v1.0/tenants/[guid]/graphs/import/jsonl?guidstrategy=regenerate&onerror=abort&batchsize=1000
Batch existence POST /v1.0/tenants/[guid]/graphs/[guid]/existence
Native query POST /v1.0/tenants/[guid]/graphs/[guid]/query
Graph transaction POST /v1.0/tenants/[guid]/graphs/[guid]/transaction
Node subgraph GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/subgraph
Node subgraph stats GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/subgraph/stats

Native graph query and graph transaction endpoints are graph scoped. They cannot cross tenants or graphs.

The four JSONL endpoints move a graph (or a slice of one) as newline-delimited JSON. Export needs read scope; import needs write scope. Both directions stream: exports send a chunked application/x-ndjson body so the server never buffers the whole graph in memory, and imports read the request body line by line. GET .../export/jsonl renders an entire graph and doubles as a provider-agnostic per-graph backup; incldata and inclsub are valueless flags that pull in the Data object and subordinate labels, tags, and vectors. POST .../export/jsonl takes a SubgraphExtractionRequest body and streams only the traversed subgraph. The .../import/jsonl endpoints accept a raw JSONL body and return a GraphImportResult; the graph-scoped form merges into an existing graph, and the tenant-scoped graphs/import/jsonl form creates a new graph. A missing graph returns 404; a malformed request or JSONL line under onerror=abort returns 400; a GUID collision under the preserve strategy returns 409.

Import query parameters:

Parameter Values Default Meaning
guidstrategy preserve, regenerate, skip, overwrite regenerate How incoming GUIDs are reconciled against the store
onerror abort, skip abort Whether a bad line stops the import or is counted and skipped
batchsize positive integer 1000 Nodes buffered per insert batch

Graph Vector Index APIs

API Method
Enable PUT /v1.0/tenants/[guid]/graphs/[guid]/vectorindex/enable
Delete DELETE /v1.0/tenants/[guid]/graphs/[guid]/vectorindex
Read configuration GET /v1.0/tenants/[guid]/graphs/[guid]/vectorindex/config
Read statistics GET /v1.0/tenants/[guid]/graphs/[guid]/vectorindex/stats
Rebuild index POST /v1.0/tenants/[guid]/graphs/[guid]/vectorindex/rebuild

Node APIs

API Method URL
Create PUT /v1.0/tenants/[guid]/graphs/[guid]/nodes
Create many PUT /v1.0/tenants/[guid]/graphs/[guid]/nodes/bulk?return=minimal
Update PUT /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]
Read GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]
Read many GET /v1.0/tenants/[guid]/graphs/[guid]/nodes
Read many GET /v1.0/tenants/[guid]/graphs/[guid]/nodes?guids=...
Read all in tenant GET /v1.0/tenants/[guid]/nodes
Read all in graph GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/all
Read most connected GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/mostconnected
Read least connected GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/leastconnected
Delete DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]
Delete all in graph DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/all
Delete all in tenant DELETE /v1.0/tenants/[guid]/nodes
Delete multiple DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/bulk
Exists HEAD /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]
Search POST /v1.0/tenants/[guid]/graphs/[guid]/nodes/search

Edge APIs

API Method URL
Create PUT /v1.0/tenants/[guid]/graphs/[guid]/edges
Create many PUT /v1.0/tenants/[guid]/graphs/[guid]/edges/bulk?return=minimal
Update PUT /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]
Read GET /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]
Read many GET /v1.0/tenants/[guid]/graphs/[guid]/edges
Read many GET /v1.0/tenants/[guid]/graphs/[guid]/edges?guids=...
Read all in tenant GET /v1.0/tenants/[guid]/edges
Read all in graph GET /v1.0/tenants/[guid]/graphs/[guid]/edges/all
Read between nodes GET /v1.0/tenants/[guid]/graphs/[guid]/edges/between
Delete DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]
Delete all in graph DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/all
Delete all in tenant DELETE /v1.0/tenants/[guid]/edges
Delete multiple DELETE /v1.0/tenants/[guid]/graphs/[guid]/edges/bulk
Delete node edges DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/edges
Delete node edges (bulk) DELETE /v1.0/tenants/[guid]/graphs/[guid]/nodes/edges
Exists HEAD /v1.0/tenants/[guid]/graphs/[guid]/edges/[guid]
Search POST /v1.0/tenants/[guid]/graphs/[guid]/edges/search

Traversal and Networking

API Method URL
Get edges from a node GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/edges/from
Get edges to a node GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/edges/to
Get edges connected to a node GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/edges
Get node neighbors GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/neighbors
Get node parents GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/parents
Get node children GET /v1.0/tenants/[guid]/graphs/[guid]/nodes/[guid]/children
Get routes between nodes POST /v1.0/tenants/[guid]/graphs/[guid]/routes

Request History APIs

Request history APIs require read/admin access according to the authenticated principal and optional tenant scope. Request history is intended for recent diagnostics; use Prometheus and OpenTelemetry for aggregate monitoring.

API Method URL
List request history GET /v1.0/requesthistory
Request history summary GET /v1.0/requesthistory/summary
Read entry GET /v1.0/requesthistory/[requestGuid]
Read detailed entry GET /v1.0/requesthistory/[requestGuid]/detail
Delete entry DELETE /v1.0/requesthistory/[requestGuid]
Bulk delete DELETE /v1.0/requesthistory/bulk

Common query-string filters include tenantGuid, method, statusCode, success, path, sourceIp, hasTransactionDiagnostics, transactionId, paging, and time-range filters. Detailed entries include captured request/response metadata subject to configured redaction and truncation.

Graph transaction entries include TransactionDiagnosticsJson when LiteGraph can parse the transaction result body. The compact JSON includes transaction ID, operation count, isolation level, provider, rollback and validation state, retry/conflict fields, and provider error code. Use hasTransactionDiagnostics=true to list only graph transaction rows, hasTransactionDiagnostics=false to exclude them, and transactionId=[full-or-partial-id] to find entries for a known transaction ID.

Enumeration APIs

The v2.0 enumeration routes accept an Enumeration Query as JSON on POST and equivalent query-string filters on GET where supported.

Resource Method URL
Tenants GET /v2.0/tenants
Tenants POST /v2.0/tenants
Users GET /v2.0/tenants/[tenantGuid]/users
Users POST /v2.0/tenants/[tenantGuid]/users
Credentials GET /v2.0/tenants/[tenantGuid]/credentials
Credentials POST /v2.0/tenants/[tenantGuid]/credentials
Graphs GET /v2.0/tenants/[tenantGuid]/graphs
Graphs POST /v2.0/tenants/[tenantGuid]/graphs
Nodes GET /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/nodes
Nodes POST /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/nodes
Edges GET /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/edges
Edges POST /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/edges
Labels GET /v2.0/tenants/[tenantGuid]/labels
Labels POST /v2.0/tenants/[tenantGuid]/labels
Graph labels POST /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/labels
Tags GET /v2.0/tenants/[tenantGuid]/tags
Tags POST /v2.0/tenants/[tenantGuid]/tags
Graph tags POST /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/tags
Vectors GET /v2.0/tenants/[tenantGuid]/vectors
Vectors POST /v2.0/tenants/[tenantGuid]/vectors
Graph vectors POST /v2.0/tenants/[tenantGuid]/graphs/[graphGuid]/vectors