VecML GraphDB REST API (v0.6)

This document describes the HTTP/JSON interface exposed by the VecML Graph Database RESTful API, including:

Endpoint URL
Expected Request Body (JSON)
Response Format (JSON)
Relevant Details or Constraints
Example Requests / Responses

All RESTful API calls to the VecML cloud graph database should be sent to: https://graphdb.vecml.com/api. All endpoints require a JSON body unless otherwise noted.

Rate and request size limit

For resource allocation and server stability, the server enforces a rate limit on the number of API calls per second. If exceeded, the server responds with:

400 Bad Request
Request limit reached, please try again later

Please avoid high-frequency API calls. For example, when inserting multiple entities, please use /batch_create_entity instead of iteratively calling /create_entity.

The size of each request cannot exceed 200MB.

Managing Unique IDs for the graph

Entities and Relationships are identified by UNIQUE string IDs. An entity and relationship can have the same name as they are defined in different namespaces.

Authentication (API key):

VecML RESTful API requests are authenticated through user's API key. The API key can be generated as follows:

Go to https://account.vecml.com/user-api-keys , sign up for a free VecML account.
After registration, you can get an API key by clicking "Create New API Key".
This unique API key will only be seen once at the creation time, so please keep the API key safely. If you need to re-generate an API key, simply delete the previous one and then create a new key.

An Example Workflow

Python

import requests, json, time

# Configuration
API_KEY = "replace_this_with_your_api_key"
BASE_URL = "https://graphdb.vecml.com/api"
GRAPH_ID  = "cinema_graph"

def post(endpoint: str, payload: dict):
    url  = f"{BASE_URL}/{endpoint}"
    resp = requests.post(url, json=payload, timeout=30)
    print(f"[{resp.status_code}] {endpoint}")
    time.sleep(0.1)
    if not resp.ok:
        raise RuntimeError(resp.text)
    return resp.json() if resp.text else None

try:
  post("remove_graph", {"user_api_key": API_KEY, "graph_id": GRAPH_ID})
except Exception as e:
    # Fallback for any other exception
    print("Something went wrong:", e)
finally:
    pass

# 1️⃣  ─ Create the graph (idempotent if already exists)
post("create_graph", {"user_api_key": API_KEY, "graph_id": GRAPH_ID})

# 2️⃣  ─ Add entities with attributes
entities = [
    ("entity1", {"name": "Tom Cruise", "type": "Person", "profession": "Actor",    "born": "1962"}),
    ("entity2", {"name": "Emily Blunt", "type": "Person", "profession": "Actor",    "born": "1983"}),
    ("entity3", {"name": "Christopher McQuarrie", "type": "Person", "profession": "Director","born": "1968"}),
    ("entity4", {"name": "Edge of Tomorrow", "type": "Movie",  "year": "2014", "genre": "Sci-Fi"}),
    ("entity5", {"name": "Mission Impossible – Fallout", "type": "Movie", "year": "2018", "genre": "Action"})
]
for eid, attrs in entities:
    post("create_entity", {"user_api_key": API_KEY, "graph_id": GRAPH_ID, "entity_id": eid})
    post("set_entity_attributes", {
        "user_api_key": API_KEY, "graph_id": GRAPH_ID,
        "entity_id": eid, "attributes": attrs
    })

# 3️⃣  ─ Create relationships with attributes
relationships = [
    ("entity1", "acted_in_movie", "entity4"),
    ("entity2", "acted_in_movie", "entity4"),
    ("entity3", "directed_movie", "entity4"),
    ("entity1", "acted_in_1", "entity5"),
    ("entity3", "directed_movie", "entity5")
]

relationships_attributes = [
    ("acted_in_movie", {"type": "acted_in", "media": "movie", "role_type": "on_screen"}),
    ("directed_movie", {"type": "directed", "media": "movie", "role_type": "behind_the_scenes"}),
    ("acted_in_1", {"type": "acted_in", "media": "movie", "role": "main_character", "role_type": "on_screen"})
]

for src, rel, dst in relationships:
    post("create_relationship", {
        "user_api_key": API_KEY, "graph_id": GRAPH_ID,
        "src_entity_id": src, "relationship_id": rel, "dest_entity_id": dst
    })

for rel, attrs in relationships_attributes:
    post("set_relationship_attributes", {
        "user_api_key": API_KEY, "graph_id": GRAPH_ID,
        "relationship_id": rel, "attributes": attrs
    })

# 4️⃣  ─ Build an Entity Attribute Index on the "type" attribute
post("create_entity_index", {
    "user_api_key": API_KEY, "graph_id": GRAPH_ID,
    "attribute_name": "type",
    "index_type":     "Attribute Index"
})

# 5️⃣  ─ Search the index for nodes with type "Person”
search_resp = post("search_entity_index", {
    "user_api_key": API_KEY, "graph_id": GRAPH_ID,
    "attribute_name": "type", "index_type": "Attribute Index",
    "attribute_value": "Person", "top_k": 5
})

print("\n≈≈≈ Search results for 'Person' ≈≈≈")
for idx, eid in enumerate(search_resp["entity_ids"], 1):
    print(f"{idx}. {eid}") # This should print out entity1, entity2, entity3

# 6️⃣  ─ Build a Relationship Attribute Index on the "role_type" attribute
post("create_relationship_index", {
    "user_api_key": API_KEY, "graph_id": GRAPH_ID,
    "attribute_name": "role_type",
    "index_type":     "Attribute Index"
})

# 7️⃣  ─ Search the index for edges with type "on_screen"
search_resp = post("search_relationship_index", {
    "user_api_key": API_KEY, "graph_id": GRAPH_ID,
    "attribute_name": "role_type", "index_type": "Attribute Index",
    "attribute_value": "on_screen", "top_k": 5
})

print("\n≈≈≈ Search results for 'Person' ≈≈≈")
for idx, eid in enumerate(search_resp["relationship_ids"], 1):
    print(f"{idx}. {eid}") # This should print out acted_in_movie, acted_in_1

Common Error Responses

All endpoints return JSON bodies with at least error_code and, when relevant, an error_message. In addition to the endpoint-specific failure codes noted throughout this guide, expect these shared responses:

400 Bad Request — Missing or malformed fields, invalid filters, or vectors that fail schema validation.
Example:
```
{
  "error_code": "InvalidParameter",
  "error_message": "graph_id is required"
}
```

403 Forbidden — The user_api_key is absent, expired, or revoked.

{
  "error_code": "InvalidUser",
  "error_message": "unauthorized"
}

404 Not Found — The referenced graph, entity, relationship, index, or clustering does not exist. Each section calls out which resource triggered the 404 when it differs from this general rule.
409 Conflict — A create request attempted to reuse an existing identifier (graph, entity, relationship, index, clustering, etc.).
500 Internal Server Error — Unexpected failures inside the service. The response always echoes the internal error code plus an explanatory error_message.

When use_job is set to true, the HTTP response will be 202 Accepted with a job_id. Poll /get_job_status or /get_job_result to retrieve the eventual payload shown in the Examples.

1. User API

1.1 `/create_graph`

Description

Creates a graph under the specified graph_id for the user.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string"
}

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Response:

409: Graph already exists.

Example

Request:

POST /create_graph
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph"
}

Response:

{
  "error_code": "Success"
}

1.2 `/remove_graph`

Description

Removes the graph identified by graph_id for the given user. The server will return 202, indicating that the deletion is in progress and will succeed (after other operations on this graph are completed).

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string"
}

Response

Success Response (202 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /remove_graph
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph"
}

Response:

{
  "error_code": "Success"
}

1.3 `/get_graphs`

Description

Retrieves the list of graph IDs available to the user.

Method

POST

Request Body

{
  "user_api_key": "string"
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "graph_ids": ["string", ...]
}

Example

Request:

POST /get_graphs
Content-Type: application/json

{
  "user_api_key": "api_key_123"
}

Response:

{
  "error_code": "Success",
  "graph_ids": ["graph1", "graph2", "graph3"]
}

1.4 `/create_checkpoint`

Description

Creates a transactional checkpoint for the specified graph. The server returns a transaction_id that can be supplied later to /revert_checkpoint in order to roll the graph back to the saved state.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "transaction_id": integer
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /create_checkpoint
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "transaction_id": 42
}

1.5 `/revert_checkpoint`

Description

Restores a graph to a previously recorded checkpoint identified by transaction_id.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "transaction_id": integer,
  "use_job": false
}

transaction_id: Identifier returned by /create_checkpoint.

Response

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /revert_checkpoint
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "transaction_id": 42,
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2. Basic Graph API

2.1 `/create_entity`

Description

Creates a new entity (node) within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
409: Entity already exists.

Example

Request:

POST /create_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.2 `/remove_entity`

Description

Removes an existing entity (node) from the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /remove_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.3 `/set_entity_attributes`

Description

Sets or updates textual attributes and optional vector vectors for an entity in the specified graph. Existing attributes or vectors with the same names will be overwritten.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "attributes": { "key1": "value1", ... },
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ ... ]
    },
    ...
  ],
  "use_job": false
}

attributes (optional): JSON object mapping attribute names to string values.
vectors (optional): Array of vector objects, each with a name, type, and vector data. See appendix for more details about vector objects.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

400: Missing or invalid fields or invalid vector format.
404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /set_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "attributes": {
    "color": "red",
    "size": "large",
    "status": "active"
  }
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, 2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [[3, 0.7], [42, 1.9], [69, -2.7]]
    }
  ],
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.4 `/remove_entity_attributes`

Description

Removes one or more textual attributes and/or vectors from an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "attribute_names": ["key1", "key2", ...],
  "vector_names": ["vec1", "vec2", ...],
  "use_job": false
}

attribute_names: Array of attribute keys to remove.
vector_names (optional): Array of vector names to remove.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /remove_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "attribute_names": ["color", "size", "status"],
  "vector_names": ["vector_location", "vector_word"],
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.5 `/get_entity_attributes`

Description

Retrieves values of specified textual attributes for an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "attribute_names": ["key1", "key2", ...],
  "use_job": false
}

attribute_names: Array of attribute keys to fetch.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "values": ["value1", "value2", ...]
}

Error Responses:

404: Graph, entity, or attribute(s) does not exist.

Example

Request:

POST /get_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "attribute_names": ["color", "size", "status"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "values": ["red", "large", "active"]
}

2.6 `/get_all_entity_attributes`

Description

Retrieves all textual attributes (key-value pairs) for an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "attributes": {
    "name1": "value1",
    "name2": "value2",
    ...
  }
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /get_all_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "attributes": {
    "size": "large",
    "color": "red",
    "status": "active"
  }
}

2.7 `/get_entity_vectors`

Description

Retrieves vectors (dense or sparse) for an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "vector_names": ["string", "string", ...],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ /* float list or [ [index, value], ... ] */ ]
    },
    ...
  ]
}

See appendix for more details about vector objects.

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /get_entity_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "vector_names": ["vector_location", "vector_word"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, -2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [
        [5, -2.7],
        [42, 1.1],
        [69, -3]
      ]
    }
  ]
}

2.8 `/get_all_entity_vector_names`

Description

Retrieves the list of vector names associated with an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "names": ["vec1", "vec2", ...]
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /get_all_entity_vector_names
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "names": ["vector_location", "vector_word"]
}

2.9 `/get_all_entity_vectors`

Description

Retrieves all vectors (dense or sparse) and their data for an entity in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ /* float list or [ [index, value], ... ] */ ]
    },
    ...
  ]
}

See appendix for more details about vector objects.

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /get_all_entity_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_id": "entity",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, -2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [
        [5, -2.7],
        [42, 1.1],
        [69, -3]
      ]
    }
  ]
}

2.10 `/filter_entity`

Description

Filters entities in the specified graph based on a provided JSON filter spec.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "entity_filter": { ... },
  "use_job": false
}

entity_filter: JSON filter spec combining conditions using and, or, not, and leaf operations like match_attribute, less_than, etc. See appendix for more details about filters.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "entity_ids": ["id1", "id2", ...]
}

Error Responses:

400: Missing or invalid fields or filter spec.
404: Graph does not exist.

Example

Request:

POST /filter_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_filter": {
    "and": [
      {
        "match_attribute": {
          "key": "type",
          "values": ["Person"]
        }
      },
      {
        "less_than": {
          "key": "age",
          "value": 30
        }
      },
      {
        "not": {
          "attribute_exists": "inactive"
        }
      }
    ]
  },
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Alice", "Charlie", "Bob"]
}

2.11 `/create_relationship`

Description

Creates a new relationship (edge) of type relationship_id from src_entity_id to dest_entity_id within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "src_entity_id": "string",
  "relationship_id": "string",
  "dest_entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /create_relationship
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "src_entity_id": "entity1",
  "relationship_id": "parent_of",
  "dest_entity_id": "entity2",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.12 `/remove_relationship`

Description

Removes an existing relationship (edge) of type relationship_id from src_entity_id to dest_entity_id within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "src_entity_id": "string",
  "relationship_id": "string",
  "dest_entity_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /remove_relationship
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "src_entity_id": "entity1",
  "relationship_id": "parent_of",
  "dest_entity_id": "entity2",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.13 `/set_relationship_attributes`

Description

Sets or updates textual attributes and optional vector vectors for a relationship in the specified graph. Existing attributes or vectors with the same names will be overwritten.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "attributes": { "key1": "value1", ... },
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ ... ]
    },
    ...
  ],
  "use_job": false
}

attributes (optional): JSON object mapping attribute names to string values.
vectors (optional): Array of vector objects, each with a name, type, and vector data. See appendix for more details about vector objects.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

400: Missing or invalid fields or invalid vector format.
404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /set_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "attributes": {
    "color": "red",
    "size": "large",
    "status": "active"
  }
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, 2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [[3, 0.7], [42, 1.9], [69, -2.7]]
    }
  ],
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.14 `/remove_relationship_attributes`

Description

Removes one or more textual attributes and/or vectors from a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "attribute_names": ["key1", "key2", ...],
  "vector_names": ["vec1", "vec2", ...],
  "use_job": false
}

attribute_names: Array of attribute names to remove.
vector_names (optional): Array of vector names to remove.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /remove_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "attribute_names": ["color", "size", "status"],
  "vector_names": ["vector_location", "vector_word"],
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

2.15 `/get_relationship_attributes`

Description

Retrieves values of specified textual attributes for a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "attribute_names": ["key1", "key2", ...],
  "use_job": false
}

attribute_names: Array of attribute names to fetch.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "values": ["value1", "value2", ...]
}

Error Responses:

404: Graph, relationship, or attribute(s) does not exist.

Example

Request:

POST /get_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "attribute_names": ["color", "size", "status"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "values": ["red", "large", "active"]
}

2.16 `/get_all_relationship_attributes`

Description

Retrieves all textual attributes (key-value pairs) for a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "attributes": {
    "name": "value",
    "name": "value",
    ...
  }
}

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /get_all_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "attributes": {
    "size": "large",
    "color": "red",
    "status": "active"
  }
}

2.17 `/get_relationship_vectors`

Description

Retrieves vectors (dense or sparse) for a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "vector_names": ["string", "string", ...],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ /* float list or [ [index, value], ... ] */ ]
    },
    ...
  ]
}

See appendix for more details about vector objects.

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /get_relationship_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "vector_names": ["vector_location", "vector_word"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, -2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [
        [5, -2.7],
        [42, 1.1],
        [69, -3]
      ]
    }
  ]
}

2.18 `/get_all_relationship_vector_names`

Description

Retrieves the list of vector names associated with a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "names": ["vec1", "vec2", ...]
}

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /get_all_relationship_vector_names
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "names": ["vector_location", "vector_word"]
}

2.19 `/get_all_relationship_vectors`

Description

Retrieves all vectors (dense or sparse) and their data for a relationship in the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "string",
      "type": "Float32" | "SFloat32",
      "vector_data": [ /* float list or [ [index, value], ... ] */ ]
    },
    ...
  ]
}

See appendix for more details about vector objects.

Error Responses:

404: Graph does not exist.
404: Relationship does not exist.

Example

Request:

POST /get_all_relationship_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_id": "relationship",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "vectors": [
    {
      "name": "vector_location",
      "type": "Float32",
      "vector_data": [3.141519, -2.72]
    },
    {
      "name": "vector_word",
      "type": "SFloat32",
      "vector_data": [
        [5, -2.7],
        [42, 1.1],
        [69, -3]
      ]
    }
  ]
}

2.20 `/filter_relationship`

Description

Filters relationships in the specified graph based on a provided JSON filter spec.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationship_filter": { ... },
  "use_job": false
}

relationship_filter: JSON filter spec combining conditions using and, or, not, and leaf operations like match_attribute, less_than, etc. See appendix for more details about filters.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "relationship_ids": ["id1", "id2", ...]
}

Error Responses:

400: Missing or invalid fields or filter spec.
404: Graph does not exist.

Example

Request:

POST /filter_relationship
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "relationship_filter": {
    "and": [
      {
        "match_attribute": {
          "key": "type",
          "values": ["Person"]
        }
      },
      {
        "less_than": {
          "key": "age",
          "value": 30
        }
      },
      {
        "not": {
          "attribute_exists": "inactive"
        }
      }
    ]
  },
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "relationship_ids": ["Alice", "Charlie", "Bob"]
}

2.21 `/get_all_entity_ids`

Description

Returns every entity ID that exists in the graph. The operation can run synchronously or be scheduled as a background job when the graph is large.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "entity_ids": ["node1", "node2", ...]
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /get_all_entity_ids
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Alice", "Bob", "Charlie"]
}

2.22 `/get_all_relationship_ids`

Description

Lists every relationship identifier in the target graph. This is helpful when you need to enumerate edges prior to additional queries.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "relationship_ids": ["rel1", "rel2", ...]
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /get_all_relationship_ids
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "relationship_ids": ["r12", "r24", "r34"]
}

2.23 `/get_all_relationships`

Description

Retrieves every relationship as triplets (source, relationship_id, destination). Results follow the same serialization used throughout the API where edge tuples are expressed as [[src, dest], relationship_id].

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "relationships": [
    [["Alice", "Bob"], "knows"],
    [["Bob", "Carol"], "reports_to"],
    ...
  ]
}

Error Responses:

404: Graph does not exist.

Example

Request:

POST /get_all_relationships
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "relationships": [
    [["Alice", "Bob"], "knows"],
    [["Bob", "Carol"], "collaborates_with"]
  ]
}

3. Graph Index API

3.1 `/create_entity_index`

Description

Creates an index on an entity attribute or vector to accelerate filtering or similarity search within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",       // e.g., "Attribute Index", "Fuzzy Attribute Index", "Vector Index"
  "dim": integer,               // dimension for vector indices (default 0)
  "dist_type": "string"        // distance metric, e.g., "Euclidean" or "Cosine",
  "use_job": false
}

attribute_name: Name of the attribute or vector to index.
index_type: Type of index to create (textual or vector-based). See appendix for more details about index types.
dim, dist_type: Optional index-specific parameters. See appendix for more details about dist_type.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
409: Index already exists.

Example

Request (Vector Index):

POST /create_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_location",
  "index_type": "Vector Index",
  "dim": 384,
  "dist_type": "Cosine",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Attribute Index):

POST /create_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "size",
  "index_type": "Attribute Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Fuzzy Attribute Index):

POST /create_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "location",
  "index_type": "Fuzzy Attribute Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Integer Linear Index):

POST /create_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Float Linear Index):

POST /create_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Float Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

3.2 `/remove_entity_index`

Description

Removes an existing index on an entity attribute or vector within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector indexed.
index_type: Type of index to remove (textual or vector-based).

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Index does not exist.

Example

Request:

POST /remove_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

3.3 `/entity_index_exists`

Description

Checks whether an index exists on an entity attribute or vector within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector indexed.
index_type: Type of index to check.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "exists": true|false
}

Example

Request:

POST /entity_index_exists
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "exists": true
}

3.4 `/get_all_entity_index`

Description

Retrieves a list of all indices (attribute_name) defined on entities within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "indices": ["string", ...]
}

Example

Request:

POST /get_all_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "indices": ["size", "vector_location"]
}

3.5 `/get_all_types_entity_index`

Description

Retrieves all index types available for a given entity attribute within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector whose index types to list.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "types": ["type1", "type2", ...]
}

Example

Request:

POST /get_all_types_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "name",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "types": ["Attribute Index", "Vector Index"]
}

3.6 `/search_entity_index`

Description

Performs a search against an entity index by exact attribute value or by similarity to a provided vector, with optional entity-level filtering.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  // Provide exactly one of (depending on index type):
  "attribute_value": "string",
  "vector": { "type": "Float32" | "SFloat32", "vector_data": [ ... ] },
  "top_k": integer,                   // optional, default 5
  "similarity_measure": "string",   // optional, e.g. "Euclidean" or "Cosine"
  "entity_filter": { ... }           // optional JSON filter spec,
  "use_job": false
}

attribute_value: Exact string to search in the index.
vector: vector object for similarity search. See appendix for more details about vector objects.
top_k: Number of results to return (default 5).
similarity_measure: Distance metric for vector search. See appendix for more details about similarity measure.
entity_filter (optional): JSON spec to filter returned entities. See appendix for more details about filters.
JSON vector payloads must use Float32 or SFloat32; other types are rejected.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "entity_ids": ["id1", "id2", ...]
}

Error Responses:

400: Missing or invalid fields, or both/neither of attribute_value and vector provided.
404: Graph does not exist.
404: Index does not exist.

Example

Request (Attribute Index):

POST /search_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Location",
  "index_type": "Attribute Index",
  "attribute_value": "Seattle",
  "top_k": 5,
  "entity_filter": {
    "or": [
      {
        "match_attribute": {
          "key": "Occupation",
          "values": ["Software Engineer", "Analyst"]
        }
      },
      {
        "less_than": {
          "key": "Age",
          "value": 30
        }
      }
    ]
  },
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["alice", "bob", "charlie", "dana", "evan"]
}

Request (Fuzzy Attribute Index):

POST /search_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Name",
  "index_type": "Fuzzy Attribute Index",
  "attribute_value": "Tom",
  "top_k": 5,
  "entity_filter": {
    "match_attribute": {
      "key": "Occupation",
      "values": ["Actor"]
    }
  },
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": [
    "Tom Hanks",
    "Tom Cruise",
    "Tom Hardy",
    "Tom Holland",
    "Tom Wilkinson"
  ]
}

Request (Vector Index):

POST /search_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Location",
  "index_type": "Vector Index",
  "vector": {
    "type": "Float32",
    "vector_data": [47.6061, -122.3328]
  },
  "top_k": 5,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Bellevue", "Tacoma", "Vancouver", "Portland", "Spokane"]
}

Request (Integer Linear Index):

POST /search_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Birth Year",
  "index_type": "Integer Linear Index",
  "vector": {
    "type": "Float32",
    "vector_data": [2000]
  },
  "top_k": 5,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Alice", "Bob", "Charlie", "Dave", "Edward"]
}

Request (Float Linear Index):

POST /search_entity_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Test Score",
  "index_type": "Float Linear Index",
  "vector": {
    "type": "Float32",
    "vector_data": [98.3]
  },
  "top_k": 5,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Alice", "Bob", "Charlie", "Dave", "Edward"]
}

3.7 `/create_relationship_index`

Description

Creates an index on a relationship attribute or vector to accelerate filtering or similarity search within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",       // e.g., "Attribute Index", "Fuzzy Attribute Index", "Vector Index"
  "dim": integer,               // dimension for vector indices (default 0)
  "dist_type": "string"        // distance metric, e.g., "Euclidean" or "Cosine",
  "use_job": false
}

attribute_name: Name of the attribute or vector to index.
index_type: Type of index to create (textual or vector-based). See appendix for more details about index types.
dim, dist_type: Optional index-specific parameters. See appendix for more details about dist_type.

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
409: Index already exists.

Example

Request (Vector Index):

POST /create_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_location",
  "index_type": "Vector Index",
  "dim": 384,
  "dist_type": "Cosine",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Attribute Index):

POST /create_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "size",
  "index_type": "Attribute Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Fuzzy Attribute Index):

POST /create_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "location",
  "index_type": "Fuzzy Attribute Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Integer Linear Index):

POST /create_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

Request (Float Linear Index):

POST /create_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Float Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

3.8 `/remove_relationship_index`

Description

Removes an existing index on a relationship attribute or vector within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector indexed.
index_type: Type of index to remove (textual or vector-based).

Response

Success Response (200 OK):

{
  "error_code": "Success"
}

Error Responses:

404: Graph does not exist.
404: Index does not exist.

Example

Request:

POST /remove_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success"
}

3.9 `/relationship_index_exists`

Description

Checks whether an index exists on a relationship attribute or vector within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector indexed.
index_type: Type of index to check.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "exists": true|false
}

Example

Request:

POST /relationship_index_exists
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "vector_time",
  "index_type": "Integer Linear Index",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "exists": true
}

3.10 `/get_all_relationship_index`

Description

Retrieves a list of all indices (attribute_name) defined on relationships within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "use_job": false
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "indices": ["string", ...]
}

Example

Request:

POST /get_all_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "indices": ["size", "vector_location"]
}

3.11 `/get_all_types_relationship_index`

Description

Retrieves all index types available for a given relationship attribute within the specified graph.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "use_job": false
}

attribute_name: Name of the attribute or vector whose index types to list.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "types": ["type1", "type2", ...]
}

Example

Request:

POST /get_all_types_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "types": ["Attribute Index", "Vector Index"]
}

3.12 `/search_relationship_index`

Description

Performs a search against a relationship index by exact attribute value or by similarity to a provided vector, with optional relationship-level filtering.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "attribute_name": "string",
  "index_type": "string",
  // Provide exactly one of (depending on index type):
  "attribute_value": "string",
  "vector": { "type": "Float32" | "SFloat32", "vector_data": [ ... ] },
  "top_k": integer,                   // optional, default 5
  "similarity_measure": "string",   // optional, e.g. "Euclidean" or "Cosine"
  "relationship_filter": { ... }           // optional JSON filter spec,
  "use_job": false
}

attribute_value: Exact string to search in the index.
vector: vector object for similarity search. See appendix for more details about vector objects.
top_k: Number of results to return (default 5).
similarity_measure: Distance metric for vector search. See appendix for more details about similarity measure.
relationship_filter (optional): JSON spec to filter returned entities. See appendix for more details about filters.
JSON vector payloads must use Float32 or SFloat32; other types are rejected.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "relationship_ids": ["id1", "id2", ...]
}

Error Responses:

400: Missing or invalid fields, or both/neither of attribute_value and vector provided.
404: Graph does not exist.
404: Index does not exist.

Example

Request:

POST /search_relationship_index
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "attribute_name": "Location",
  "index_type": "Attribute Index",
  "attribute_value": "Seattle",
  "top_k": 5,
    "relationship_filter": {
    "or": [
      {
        "match_attribute": {
          "key": "Occupation",
          "values": ["Software Engineer", "Analyst"]
        }
      },
      {
        "less_than": {
          "key": "Age",
          "value": 30
        }
      }
    ]
  },
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "relationship_ids": ["alice", "bob", "charlie", "dana", "evan"]
}

4. Graph Algorithms

4.0 `/get_neighbors`

Description

Returns the immediate neighbors of src_entity_id. The optional type flag controls directionality.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "src_entity_id": "string",
  "type": 3
}

src_entity_id: Entity whose neighbors to return.
type (optional): 1 (outbound only), 2 (inbound only), or 3 (both). Defaults to 3 when omitted.

Response

{
  "error_code": "Success",
  "neighbors": [
    { "entity_id": "string", "relationship_id": "string" },
    ...
  ]
}

Error Responses:

404: Graph does not exist.
404: Entity does not exist.

Example

Request:

POST /get_neighbors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "src_entity_id": "entity1",
  "type": 1
}

Response:

{
  "error_code": "Success",
  "neighbors": [
    { "entity_id": "entity2", "relationship_id": "knows" },
    { "entity_id": "entity3", "relationship_id": "works_with" }
  ]
}

4.1 Shortest Path Algorithms

4.1.1 `/find_k_hop`

Description

Finds all entities reachable within k hops from src_entity_id, optionally restricting the traversal with entity and relationship predicates. Supports synchronous execution or job submission.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "src_entity_id": "string",
  "type": 1,
  "k": 2,
  "entity_filters": [ { ... } ],
  "relationship_filters": [ { ... } ],
  "use_job": false
}

src_entity_id: Starting entity for the hop traversal.
type: 1 (outbound), 2 (inbound), or 3 (bidirectional).
k: Maximum hop count.
entity_filters / relationship_filters (optional): JSON predicate arrays to restrict traversal (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "entity_ids": ["id1", "id2", ...],
  "relationships": [
    [["src", "dst"], "relationship_id"],
    ...
  ]
}

Error Responses:

400: Missing field or invalid filter configuration.
404: Graph or source entity not found.

Example

Request:

POST /find_k_hop
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "src_entity_id": "Tom Cruise",
  "type": 1,
  "k": 2,
  "entity_filters": [
    {
      "match_attribute": {
        "key": "type",
        "values": ["Person"]
      }
    }
  ],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "entity_ids": ["Emily Blunt", "Edge of Tomorrow"],
  "relationships": [
    [["Tom Cruise", "Emily Blunt"], "friend"],
    [["Emily Blunt", "Edge of Tomorrow"], "acted_in"]
  ]
}

4.1.2 `/dijkstra`

Description

Runs Dijkstra's single-source shortest path algorithm from one or more source nodes, optionally constraining the graph with attribute filters and returning explicit paths.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_ids": ["string", ...],
  "target_node_ids": ["string", ...],
  "weight_attr_name": "string",
  "is_undirected": false,
  "return_paths": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

source_node_ids: One or more starting nodes (required).
target_node_ids (optional): Limit destinations; omit or empty to compute all reachable nodes.
weight_attr_name (optional): Edge attribute storing numeric weights; omit to treat edges as weight 1.
is_undirected (optional): Treat edges as undirected when true.
return_paths (optional): When true, return edge-by-edge paths.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "distances": [["node_id", 2.0], ...],
  "paths": [
    [
      [["src", "mid"], "rel_id"],
      [["mid", "dst"], "rel_id"]
    ],
    ...
  ]
}

paths is omitted unless return_paths is true. Each entry encodes the sequence of traversed relationships for the corresponding target in distances.

Error Responses:

404: Graph or referenced entity not found.

Example

Request:

POST /dijkstra
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_ids": ["1"],
  "target_node_ids": ["4"],
  "weight_attr_name": "weight",
  "return_paths": true,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "distances": [["4", 2.0]],
  "paths": [
    [
      [["1", "3"], "r13"],
      [["3", "4"], "r34"]
    ]
  ]
}

4.1.3 `/astar`

Description

Computes shortest paths with the A* heuristic algorithm. Entities referenced in source_node_ids and target_node_ids must contain an vector attribute (coor_attr_name) representing coordinates for the heuristic.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_ids": ["string", ...],
  "target_node_ids": ["string", ...],
  "coor_attr_name": "string",
  "weight_attr_name": "string",
  "is_undirected": false,
  "return_paths": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

source_node_ids: One or more starting nodes (required).
target_node_ids (optional): Limit destinations; omit or empty to compute all reachable nodes.
coor_attr_name: Node vector attribute containing coordinates used for the A* heuristic.
weight_attr_name (optional): Edge weight attribute; omit for unit weights.
is_undirected (optional): Treat edges as undirected when true.
return_paths (optional): When true, include path details in the response.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

Identical in shape to /dijkstra: distances plus optional paths.

Error Responses:

400: Missing field or invalid heuristic configuration.
404: Graph or referenced entity not found.

Example

Request:

POST /astar
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_ids": ["1"],
  "target_node_ids": ["4"],
  "coor_attr_name": "pos",
  "weight_attr_name": "weight",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "distances": [["4", 2.0]],
  "paths": [
    [
      [["1", "3"], "a13"],
      [["3", "4"], "a34"]
    ]
  ]
}

4.1.4 `/spfa`

Description

Runs the Shortest Path Faster Algorithm (SPFA) from a single source node. Optionally returns explicit paths and respects filter predicates.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_id": "string",
  "target_node_ids": ["string", ...],
  "weight_attr_name": "string",
  "return_paths": true,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

source_node_id: Starting node for the traversal.
target_node_ids (optional): Limit destinations; omit or empty to compute all reachable nodes.
weight_attr_name (optional): Edge weight attribute; omit for unit weights.
return_paths (optional): When true, include path details in the response.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

distances: array [entity_id, distance].
When return_paths is true, paths is an array of [reachable:boolean, [["src", "dst"], "rel_id"], ...] structures aligned with target_node_ids.

Additional failure codes:

400: Invalid filters or incompatible weight settings.
404: Graph or referenced source/target nodes do not exist.

Example

Request:

POST /spfa
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_id": "1",
  "target_node_ids": ["4"],
  "weight_attr_name": "weight",
  "return_paths": true,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "distances": [["4", 6.0]],
  "paths": [
    [
      true,
      [["1", "2"], "s12"],
      [["2", "3"], "s23"],
      [["3", "4"], "s34"]
    ]
  ]
}

4.1.5 `/delta_stepping`

Description

Executes the parallel delta-stepping algorithm for single-source shortest paths. Optional path_node_ids restricts which destinations should include path reconstructions.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_id": "string",
  "path_node_ids": ["string", ...],
  "delta": 1.0,
  "weight_attr_name": "string",
  "is_undirected": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

source_node_id: Starting node for the traversal.
path_node_ids (optional): Nodes for which to return path reconstructions.
delta: Bucket width for the delta-stepping algorithm (must be > 0).
weight_attr_name (optional): Edge weight attribute; omit for unit weights.
is_undirected (optional): Treat edges as undirected when true.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

distances: array [entity_id, distance].
paths: only present when path_node_ids is non-empty.

Additional failure codes:

400: Invalid delta or filter specification.
404: Graph or referenced nodes do not exist.

Example

Request:

POST /delta_stepping
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_id": "1",
  "path_node_ids": ["4"],
  "delta": 1.0,
  "weight_attr_name": "weight",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "distances": [["4", 2.0]],
  "paths": [
    [
      [["1", "3"], "d13"],
      [["3", "4"], "d34"]
    ]
  ]
}

4.2 Trees & Connectivity

4.2.1 `/prim`

Description

Builds a Minimum Spanning Tree using Prim's algorithm over the (optionally filtered) graph. For undirected graphs, insert symmetric edges before invoking the API.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "start_node_ids": ["string", ...],
  "weight_attr_name": "string",
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

start_node_ids (optional): Starting nodes for the MST; leave empty to let the server choose per component.
weight_attr_name (optional): Edge weight attribute; omit for unit weights.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "mst_edges": [
    [["u", "v"], "relationship_id"],
    ...
  ],
  "total_weight": 5.0
}

Additional failure codes:

400: Missing weight attributes or invalid filter specifications.
404: Graph or supplied start nodes do not exist.

Example

Request:

POST /prim
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "start_node_ids": [],
  "weight_attr_name": "weight",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "mst_edges": [
    [["1", "2"], "p12"],
    [["2", "3"], "p23"]
  ],
  "total_weight": 5.0
}

4.2.2 `/steiner_tree`

Description

Computes an approximate Steiner tree connecting source_node_id and terminal_node_ids. Optional rerouting refines the solution.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_id": "string",
  "terminal_node_ids": ["string", ...],
  "weight_attr_name": "string",
  "apply_rerouting": false,
  "use_job": false
}

source_node_id: Root node for the Steiner tree.
terminal_node_ids: Terminal nodes to connect.
weight_attr_name (optional): Edge weight attribute; omit for unit weights.
apply_rerouting (optional): When true, run rerouting refinement.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "tree_edges": [
    [["u", "v"], "relationship_id"],
    ...
  ],
  "total_cost": 2.0
}

Additional failure codes:

400: Missing terminal_node_ids or invalid parameters.
404: Graph, source node, or one of the terminal nodes does not exist.

Example

Request:

POST /steiner_tree
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_id": "1",
  "terminal_node_ids": ["3", "4"],
  "weight_attr_name": "weight",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "tree_edges": [
    [["1", "3"], "st13"],
    [["3", "4"], "st34"]
  ],
  "total_cost": 2.0
}

4.3 Flow (Push-Relabel)

4.3.1 `/max_flow_push_relabel`

Description

Computes the maximal flow from source_node_id to sink_node_id using the push-relabel algorithm. Capacities and (optional) flow outputs are read from edge attributes.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_id": "string",
  "sink_node_id": "string",
  "capacity_attr_name": "string",
  "flow_attr_name": "string",
  "use_job": false
}

source_node_id: Source node for the flow.
sink_node_id: Sink node for the flow.
capacity_attr_name: Edge attribute containing capacities.
flow_attr_name (optional): Edge attribute for reading or writing flow values.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "max_flow_value": 12.5
}

Error Responses:

400: Invalid parameter.
404: Graph or endpoint node not found.

Example

Request:

POST /max_flow_push_relabel
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "network",
  "source_node_id": "s",
  "sink_node_id": "t",
  "capacity_attr_name": "capacity",
  "flow_attr_name": "flow",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "max_flow_value": 12.5
}

4.4 Link Prediction & Neighborhood Similarity

4.4.1 `/common_neighbors`

Description

Counts (and optionally returns) the intersection of neighbors for the provided node_ids. Supports directed or undirected semantics plus attribute filters.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "node_ids": ["string", ...],
  "is_undirected": false,
  "return_nodes": true,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

node_ids: Node IDs whose neighbor intersection is computed (two or more).
is_undirected (optional): Treat edges as undirected when true.
return_nodes (optional): When true, include common node IDs in the response.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "num_common": 3,
  "common_nodes": ["3", "4", "5"]
}

common_nodes is omitted when return_nodes is false.

Additional failure codes:

400: Invalid filter configuration.
404: Graph or one of the input nodes does not exist.

Example

Request:

POST /common_neighbors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "node_ids": ["1", "2"],
  "return_nodes": true,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "num_common": 3,
  "common_nodes": ["3", "4", "5"]
}

4.4.2 `/adamic_adar`

Description

Computes the Adamic–Adar link prediction score between nodes u and v. The score can be evaluated on directed or undirected neighborhoods and filtered by attributes.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "u": "string",
  "v": "string",
  "is_undirected": false,
  "use_log": true,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

u: First node ID.
v: Second node ID.
is_undirected (optional): Treat edges as undirected when true.
use_log (optional): When true, apply log degree weighting.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "score": 0.6931471
}

Additional failure codes:

400: Invalid parameter combination (e.g., missing node IDs).
404: Graph or one of the input nodes does not exist.

Example

Request:

POST /adamic_adar
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "u": "1",
  "v": "2",
  "is_undirected": true,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "score": 0.9102392
}

4.4.3 `/preferential_attachment`

Description

Calculates the Preferential Attachment score (deg(u) × deg(v) under filter constraints) for the candidate link (u, v).

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "u": "string",
  "v": "string",
  "is_undirected": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

u: First node ID.
v: Second node ID.
is_undirected (optional): Treat edges as undirected when true.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "score": 4.0
}

Additional failure codes:

400: Invalid parameter combination (e.g., missing u or v).
404: Graph or one of the input nodes does not exist.

Example

Request:

POST /preferential_attachment
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "u": "1",
  "v": "2",
  "is_undirected": true,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "score": 4.0
}

4.5 Ranking, Ordering, & Inference

4.5.1 `/topsort`

Description

Produces a depth-first topological ordering of the (filtered) DAG starting from the supplied nodes. If start_node_ids is empty, the algorithm covers the entire reachable component.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "start_node_ids": ["string", ...],
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

start_node_ids (optional): Starting nodes for the traversal; empty to cover the reachable DAG.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "order": ["1", "2", "3"]
}

Additional failure codes:

400: Invalid DAG filters or cycles detected in the provided subgraph.
404: Graph or referenced starting nodes do not exist.

Example

Request:

POST /topsort
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "start_node_ids": ["1"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "order": ["1", "2", "3"]
}

4.5.2 `/topsort_kahn`

Description

Generates a level-by-level topological ordering using Kahn's algorithm. Each level array contains nodes with the same depth.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "start_node_ids": ["string", ...],
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

start_node_ids (optional): Starting nodes for the traversal; empty to cover the reachable DAG.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "levels": [["1"], ["2", "3"], ["4"]]
}

Example

Request:

POST /topsort_kahn
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "start_node_ids": ["1"],
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "levels": [["1"], ["2", "3"], ["4"]]
}

4.5.3 `/dag_longest_path`

Description

Computes longest paths within a Directed Acyclic Graph (DAG) using dynamic programming. Optional filters limit the nodes and edges considered. Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "source_node_ids": ["string", ...],
  "target_node_ids": ["string", ...],
  "weight_attr_name": "string",
  "return_paths": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

source_node_ids: One or more starting nodes.
target_node_ids (optional): Limit destinations; omit or empty to compute all reachable nodes.
weight_attr_name: Edge attribute storing numeric weights.
return_paths (optional): When true, include path details in the response.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

Matches the structure used by /dijkstra (distances plus optional paths).

Additional failure codes:

400: Invalid DAG (cycles present) or missing weight attribute.
404: Graph or referenced nodes do not exist.

Example

Request:

POST /dag_longest_path
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "source_node_ids": ["1"],
  "target_node_ids": ["4"],
  "weight_attr_name": "weight",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "distances": [["4", 5.0]]
}

4.5.4 `/pagerank`

Description

Evaluates PageRank over the (optionally filtered) graph. Supports weighted edges and personalization scalers.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "damping_factor": 0.85,
  "max_iterations": 100,
  "edge_weight_attr": "string",
  "node_weight_attr": "string",
  "scaler": "string",
  "is_undirected": false,
  "node_filters": [ { ... } ],
  "edge_filters": [ { ... } ],
  "use_job": false
}

damping_factor (optional): Damping factor between 0 and 1.
max_iterations (optional): Maximum iteration count.
edge_weight_attr (optional): Edge weight attribute for weighted PageRank.
node_weight_attr (optional): Node weight attribute for personalization.
scaler (optional): Name of a scaling function applied to node weights.
is_undirected (optional): Treat edges as undirected when true.
node_filters / edge_filters (optional): JSON predicate arrays (see Filters).
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "scores": [["node", 0.32], ...]
}

Example

Request:

POST /pagerank
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "damping_factor": 0.85,
  "max_iterations": 20,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "scores": [
    ["1", 0.19],
    ["2", 0.23],
    ["3", 0.42],
    ["4", 0.16]
  ]
}

4.5.5 `/loopy_bp_map`

Description

Runs loopy belief propagation (discrete MAP inference) on factor graphs encoded in the database. Nodes must carry a type attribute (variables vs. factors). Custom factor potentials are currently limited to the built-in uniform default.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "type_attr_name": "string",
  "K": 2,
  "max_iterations": 10,
  "damping": 0.2,
  "tol": 1e-6,
  "use_job": false
}

type_attr_name: Node attribute indicating variable vs factor type.
K: Number of discrete states per variable.
max_iterations (optional): Maximum iterations to run.
damping (optional): Damping factor for message updates.
tol (optional): Convergence tolerance.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "assignments": {
    "x": 0,
    "y": 1
  }
}

Additional failure codes:

400: Invalid potential definitions, degree settings, or damping/iteration parameters.
404: Graph or the referenced type_attr_name does not exist.

Example

Request:

POST /loopy_bp_map
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "type_attr_name": "type",
  "K": 2,
  "max_iterations": 10,
  "damping": 0.3,
  "tol": 1e-6,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "assignments": {
    "x": 0,
    "y": 1
  }
}

4.5.6 `/loopy_bp_map_continuous`

Description

Continuous variant of loopy BP supporting bounded continuous variables and Monte Carlo sampling parameters.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "type_attr_name": "string",
  "bounds": {
    "x": [0.0, 2.0]
  },
  "num_samples": 2,
  "num_mc_samples": 2,
  "max_iterations": 5,
  "damping": 0.2,
  "tol": 1e-6,
  "use_job": false
}

type_attr_name: Node attribute indicating variable vs factor type.
bounds: Map of variable IDs to [min, max] bounds.
num_samples: Number of samples per variable for estimation.
num_mc_samples: Monte Carlo samples per iteration.
max_iterations (optional): Maximum iterations to run.
damping (optional): Damping factor for message updates.
tol (optional): Convergence tolerance.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "assignments": {
    "x": 1.2,
    "y": 2.4
  }
}

Example

Request:

POST /loopy_bp_map_continuous
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "type_attr_name": "type",
  "bounds": {
    "x": [0.0, 2.0],
    "y": [1.0, 3.0]
  },
  "num_samples": 2,
  "num_mc_samples": 2,
  "max_iterations": 5,
  "damping": 0.2,
  "tol": 1e-6,
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "assignments": {
    "x": 1.1,
    "y": 2.3
  }
}

4.6 Clustering

4.6.1 `/create_clustering`

Description

Builds a named clustering over the graph using one of the supported algorithms (e.g., Louvain, label propagation, k-means). The server infers the parameter set from the fields you supply.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "clustering_name": "string",
  "clustering_algorithm": "string",
  "max_iter": 20,
  "resolution": 1.0,
  "weight_attribute": "edge_weight",
  "objective_function": "modularity",
  "vector_name": "embedding_384",
  "k": 8,
  "dist_type": "Cosine",
  "use_job": false
}

clustering_name: Name for the clustering result.
clustering_algorithm: Algorithm identifier (e.g., louvain, label_propagation, kmeans).
max_iter (optional): Maximum iterations for the algorithm.
resolution (optional): Resolution parameter for Louvain.
weight_attribute (optional): Edge weight attribute to use.
objective_function (optional): Objective function name (e.g., modularity).
vector_name (optional): Vector attribute used for k-means.
k (optional): Number of clusters for k-means.
dist_type (optional): Distance metric for vector clustering (e.g., Cosine).
use_job (optional): Run asynchronously as a job.
Supply max_iter + resolution (and optionally weight_attribute, objective_function) for Louvain-style community detection.
Supply only max_iter for label propagation.
Supply vector_name, k, max_iter, and optional dist_type for k-means clustering over stored vectors.
Omit the optional fields for algorithms that do not need them.

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "clustering_name": "communities_v1"
}

Additional failure codes:

400: Unsupported algorithm or missing/invalid parameters.
404: Graph does not exist.
409: Clustering with the same name already exists.

Example

Request:

POST /create_clustering
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "clustering_name": "communities_v1",
  "clustering_algorithm": "louvain",
  "max_iter": 25,
  "resolution": 1.0,
  "weight_attribute": "edge_weight",
  "objective_function": "modularity",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "clustering_name": "communities_v1"
}

4.6.2 `/get_clustering`

Description

Returns the full clustering as an array of clusters, each containing the entity IDs assigned to that cluster.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "clustering_name": "string",
  "use_job": false
}

clustering_name: Name of the clustering to fetch.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "clusters": [
    ["entity1", "entity2"],
    ["entity3", "entity4", "entity5"]
  ]
}

Additional failure codes:

404: Graph or clustering does not exist.

Example

Request:

POST /get_clustering
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "clustering_name": "communities_v1",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "clusters": [
    ["movie_1", "movie_2"],
    ["movie_3", "movie_4", "movie_5"]
  ]
}

4.6.3 `/get_clustering_cluster`

Description

Fetches the members of a single cluster (by numeric cluster_id) from a named clustering.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "clustering_name": "string",
  "cluster_id": 0
}

clustering_name: Name of the clustering to query.
cluster_id: Cluster index to return.

Response

{
  "error_code": "Success",
  "cluster_id": 0,
  "entities": ["movie_1", "movie_2"]
}

Additional failure codes:

404: Graph does not exist.
404: Clustering or the requested cluster ID does not exist.

Example

Request:

POST /get_clustering_cluster
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "clustering_name": "communities_v1",
  "cluster_id": 1
}

Response:

{
  "error_code": "Success",
  "cluster_id": 1,
  "entities": ["movie_3", "movie_4", "movie_5"]
}

4.6.4 `/get_clustering_membership`

Description

Looks up which cluster a specific entity belongs to within a named clustering. Supports synchronous or asynchronous execution.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "clustering_name": "string",
  "entity_id": "string",
  "use_job": false
}

clustering_name: Name of the clustering to query.
entity_id: Entity ID to look up.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "cluster_id": 2
}

Additional failure codes:

404: Graph does not exist.
404: Entity does not exist.
404: Entity is not assigned to the requested clustering.

Example

Request:

POST /get_clustering_membership
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "clustering_name": "communities_v1",
  "entity_id": "movie_4",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "cluster_id": 1
}

4.6.5 `/delete_clustering`

Description

Deletes a previously created clustering (metadata only; entities remain untouched). Can run synchronously or as a job.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "clustering_name": "string",
  "use_job": false
}

clustering_name: Name of the clustering to delete.
use_job (optional): Run asynchronously as a job.

Response

{
  "error_code": "Success",
  "clustering_name": "communities_v1"
}

Additional failure codes:

404: Graph or clustering does not exist.

Example

Request:

POST /delete_clustering
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "clustering_name": "communities_v1",
  "use_job": false
}

Response:

{
  "error_code": "Success",
  "clustering_name": "communities_v1"
}

5. Graph Batch Operations

Note: Batch operations will execute concurrently only when submitted as jobs. Without job usage, operations run sequentially.

5.1 `/batch_create_entity`

Description

Creates a batch of entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id"    : "string",
  "entity_ids"  : [
    "string",
    "string",
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "string",
      "error_code": "string"
    },
    {
      "entity_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request (All created):

POST /batch_create_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_ids": [
    "John",
    "Alice",
    "Bob",
    "Charlie"
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "John",
      "error_code": "Success"
    },
    {
      "entity_id": "Alice",
      "error_code": "Success"
    },
    {
      "entity_id": "Bob",
      "error_code": "Success"
    },
    {
      "entity_id": "Charlie",
      "error_code": "Success"
    }
  ]
}

Request (Graph missing):

POST /batch_create_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_ids": [
    "John",
    "Alice",
    "Bob",
    "Charlie"
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "John",
      "error_code": "GraphNotFound"
    },
    {
      "entity_id": "Alice",
      "error_code": "GraphNotFound"
    },
    {
      "entity_id": "Bob",
      "error_code": "GraphNotFound"
    },
    {
      "entity_id": "Charlie",
      "error_code": "GraphNotFound"
    }
  ]
}

5.2 `/batch_remove_entity`

Description

Removes a batch of entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id"    : "string",
  "entity_ids"  : [
    "string",
    "string",
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "string",
      "error_code": "string"
    },
    {
      "entity_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request (All removed):

POST /batch_remove_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_ids": [
    "John",
    "Alice",
    "Bob",
    "Charlie"
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "John",
      "error_code": "Success"
    },
    {
      "entity_id": "Alice",
      "error_code": "Success"
    },
    {
      "entity_id": "Bob",
      "error_code": "Success"
    },
    {
      "entity_id": "Charlie",
      "error_code": "Success"
    }
  ]
}

Request (Entities missing):

POST /batch_remove_entity
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "entity_ids": [
    "John",
    "Alice",
    "Bob",
    "Charlie"
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "John",
      "error_code": "EntityNotFound"
    },
    {
      "entity_id": "Alice",
      "error_code": "EntityNotFound"
    },
    {
      "entity_id": "Bob",
      "error_code": "EntityNotFound"
    },
    {
      "entity_id": "Charlie",
      "error_code": "EntityNotFound"
    }
  ]
}

5.3 `/batch_set_entity_attributes`

Description

Sets attributes and vectors for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id"    : "string",
  "entities"  : [
    {
      "entity_id": "string",
      "attributes": {
        "string": "string",
        ...
      },
      "vectors": [
        {
          "name": "string",
          "type": "string",
          "vector_data": [ ... ]
        },
        {
          "name": "string",
          "type": "string",
          "vector_data": [ ... ]
        },
        ...
      ]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "string",
      "error_code": "string"
    },
    {
      "entity_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_set_entity_attributes
Content-Type: application/json
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "entities": [
    {
      "entity_id": "node1",
      "attributes": {
        "name": "Alice",
        "age": "30",
        "country": "Canada"
      },
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.12, 0.34, 0.56, 0.78]
        },
        {
          "name": "sparse_pref",
          "type": "SFloat32",
          "vector_data": [
            [0, 1.0],
            [3, 2.5]
          ]
        }
      ]
    },
    {
      "entity_id": "node2",
      "attributes": {
        "name": "Bob",
        "age": "25"
      }
    },
    {
      "entity_id": "node3",
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.01, 0.02, 0.03]
        }
      ]
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success"
    },
    {
      "entity_id": "node2",
      "error_code": "EntityNotFound"
    },
    {
      "entity_id": "node3",
      "error_code": "Success"
    }
  ]
}

5.4 `/batch_remove_entity_attributes`

Description

Removes previously set string‑valued attributes and/or vectors from multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id":       "string",
      "attribute_names": ["string", ...],
      "vector_names":      ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id":  "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_remove_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "entities": [
    {
      "entity_id":       "node1",
      "attribute_names": ["age","country"],
      "vector_names":      ["profile_vec"]
    },
    {
      "entity_id":       "node2",
      "attribute_names": ["name"]
      // no vectors to remove
    },
    {
      "entity_id":  "node3"
      // neither attributes nor vectors: no‑ops
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success"
    },
    {
      "entity_id": "node2",
      "error_code": "EntityNotFound"
    },
    {
      "entity_id": "node3",
      "error_code": "AttributeNotFound"
    }
  ]
}

5.5 `/batch_get_entity_attributes`

Description

Fetches string‑valued attributes for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id":       "string",
      "attribute_names": ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id":  "string",
      "error_code": "string",
      "values":      ["string", ...]
    },
    ...
  ]
}

Example

Request:

POST /batch_get_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "entities": [
    { "entity_id": "node1", "attribute_names": ["name","age"] },
    { "entity_id": "node2", "attribute_names": ["country"]   },
    { "entity_id": "nodeX", "attribute_names": ["name"]      }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "values": ["Alice", "30"]
    },
    {
      "entity_id": "node2",
      "error_code": "AttributeNotFound"
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

5.6 `/batch_get_all_entity_attributes`

Description

Fetches all string‑valued attributes for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id":       "string",
      "error_code":      "string",
      "attributes": {
        "string": "string",
        ...
      }
    },
    ...
  ]
}

Example

Request:

POST /batch_get_all_entity_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "entities": [
    {"entity_id": "node1"},
    {"entity_id": "node2"},
    {"entity_id": "nodeX"}
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "attributes": {
        "name": "Alice",
        "age": "30",
        "country": "Canada"
      }
    },
    {
      "entity_id": "node2",
      "error_code": "Success",
      "attributes": { "name": "Bob" }
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

5.7 `/batch_get_entity_vectors`

Description

Fetches specified vectors for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id": "string",
      "vector_names": ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "string",
      "error_code": "string",
      "vectors": [
        {
          "name": "string",
          "type": "Float32" | "SFloat32",
          "vector_data": [ ... ]
        },
        ...
      ]
    },
    ...
  ]
}

Example

Request:

POST /batch_get_entity_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "entities": [
    { "entity_id": "node1", "vector_names": ["vector_a", "vector_b"] },
    { "entity_id": "node2", "vector_names": ["vector_c"] },
    { "entity_id": "nodeX", "vector_names": ["vector_y"] }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "vectors": [
        {
          "name": "vector_a",
          "type": "Float32",
          "vector_data": [0.1, 0.2, 0.3]
        },
        {
          "name": "vector_b",
          "type": "Float32",
          "vector_data": [0.4, 0.5, 0.6]
        }
      ]
    },
    {
      "entity_id": "node2",
      "error_code": "Success",
      "vectors": [
        {
          "name": "vector_c",
          "type": "Float32",
          "vector_data": [0.7, 0.8]
        }
      ]
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

5.8 `/batch_get_all_entity_vector_names`

Description

Fetches all vector names (keys) for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "string",
      "error_code": "string",
      "vector_names": ["string", ...]
    },
    ...
  ]
}

Example

Request:

POST /batch_get_all_entity_vector_names
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "entities": [
    { "entity_id": "node1" },
    { "entity_id": "node2" },
    { "entity_id": "nodeX" }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "vector_names": ["profile_vec", "sparse_pref"]
    },
    {
      "entity_id": "node2",
      "error_code": "Success",
      "vector_names": []
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

5.9 `/batch_get_all_entity_vectors`

Description

Fetches all vectors (dense and sparse) for multiple entities in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "entities": [
    {
      "entity_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "vectors": [
        {
          "name":        "string",
          "type":        "string",
          "vector_data": [ ... ]
        },
        {
          "name":        "string",
          "type":        "string",
          "vector_data": [ ... ]
        }
      ]
    },
    {
      "entity_id": "node2",
      "error_code": "Success",
      "vectors": []
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

Example

Request:

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "entities": [
    { "entity_id": "node1" },
    { "entity_id": "node2" },
    { "entity_id": "nodeX" }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "entity_id": "node1",
      "error_code": "Success",
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.12, 0.34, 0.56, 0.78]
        },
        {
          "name": "sparse_pref",
          "type": "SFloat32",
          "vector_data": [
            [0, 1.0],
            [3, 2.5]
          ]
        }
      ]
    },
    {
      "entity_id": "node2",
      "error_code": "Success",
      "vectors": []
    },
    {
      "entity_id": "nodeX",
      "error_code": "EntityNotFound"
    }
  ]
}

5.10 `/batch_create_relationship`

Description

Creates multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationships": [
    {
      "src_entity_id": "string",
      "relationship_id": "string",
      "dest_entity_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "src_entity_id": "string",
      "relationship_id": "string",
      "dest_entity_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_create_relationship
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "relationships": [
    {
      "src_entity_id": "nd1",
      "relationship_id": "rel1",
      "dest_entity_id": "nd2",
    },
    {
      "src_entity_id": "nd2",
      "relationship_id": "rel2",
      "dest_entity_id": "nd3",
    },
    {
      "src_entity_id": "nd3",
      "relationship_id": "rel3",
      "dest_entity_id": "nd4",
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "src_entity_id": "nd1",
      "relationship_id": "rel1",
      "dest_entity_id": "nd2",
      "error_code": "Success"
    },
    {
      "src_entity_id": "nd2",
      "relationship_id": "rel2",
      "dest_entity_id": "nd3",
      "error_code": "Success"
    },
    {
      "src_entity_id": "nd3",
      "relationship_id": "rel3",
      "dest_entity_id": "nd4",
      "error_code": "EntityNotFound"
    }
  ]
}

5.11 `/batch_remove_relationship`

Description

Removes multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "relationships": [
    {
      "src_entity_id": "string",
      "relationship_id": "string",
      "dest_entity_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "src_entity_id": "string",
      "relationship_id": "string",
      "dest_entity_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_remove_relationship
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "relationships": [
    {
      "src_entity_id": "nd1",
      "relationship_id": "rel1",
      "dest_entity_id": "nd2",
    },
    {
      "src_entity_id": "nd2",
      "relationship_id": "rel2",
      "dest_entity_id": "nd3",
    },
    {
      "src_entity_id": "nd3",
      "relationship_id": "rel3",
      "dest_entity_id": "nd4",
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "src_entity_id": "nd1",
      "relationship_id": "rel1",
      "dest_entity_id": "nd2",
      "error_code": "Success"
    },
    {
      "src_entity_id": "nd2",
      "relationship_id": "rel2",
      "dest_entity_id": "nd3",
      "error_code": "Success"
    },
    {
      "src_entity_id": "nd3",
      "relationship_id": "rel3",
      "dest_entity_id": "nd4",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.12 `/batch_set_relationship_attributes`

Description

Sets attributes and vectors for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id"    : "string",
  "relationships"  : [
    {
      "relationship_id": "string",
      "attributes": {
        "string": "string",
        ...
      },
      "vectors": [
        {
          "name": "string",
          "type": "Float32" | "SFloat32",
          "vector_data": [ ... ]
        }
      ]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id": "string",
      "error_code": "string"
    },
    {
      "relationship_id": "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_set_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "relationships": [
    {
      "relationship_id": "node1",
      "attributes": {
        "name": "Alice",
        "age": "30",
        "country": "Canada"
      },
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.12, 0.34, 0.56, 0.78]
        },
        {
          "name": "sparse_pref",
          "type": "SFloat32",
          "vector_data": [
            [0, 1.0],
            [3, 2.5]
          ]
        }
      ]
    },
    {
      "relationship_id": "node2",
      "attributes": {
        "name": "Bob",
        "age": "25"
      }
    },
    {
      "relationship_id": "node3",
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.01, 0.02, 0.03]
        }
      ]
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success"
    },
    {
      "relationship_id": "node2",
      "error_code": "RelationshipNotFound"
    },
    {
      "relationship_id": "node3",
      "error_code": "Success"
    }
  ]
}

5.13 `/batch_remove_relationship_attributes`

Description

Removes previously set string‑valued attributes and/or vectors from multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id":       "string",
      "attribute_names": ["string", ...],
      "vector_names":      ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id":  "string",
      "error_code": "string"
    },
    ...
  ]
}

Example

Request:

POST /batch_remove_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "relationships": [
    {
      "relationship_id":       "node1",
      "attribute_names": ["age","country"],
      "vector_names": ["profile_vec"]
    },
    {
      "relationship_id":       "node2",
      "attribute_names": ["name"]
      // no vectors to remove
    },
    {
      "relationship_id":  "node3"
      // neither attributes nor vectors: no‑ops
    }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success"
    },
    {
      "relationship_id": "node2",
      "error_code": "RelationshipNotFound"
    },
    {
      "relationship_id": "node3",
      "error_code": "AttributeNotFound"
    }
  ]
}

5.14 `/batch_get_relationship_attributes`

Description

Fetches string‑valued attributes for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id":       "string",
      "attribute_names": ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id":  "string",
      "error_code": "string",
      "values":      ["string", ...]
    },
    ...
  ]
}

Example

Request:

POST /batch_get_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "relationships": [
    { "relationship_id": "node1", "attribute_names": ["name","age"] },
    { "relationship_id": "node2", "attribute_names": ["country"]   },
    { "relationship_id": "nodeX", "attribute_names": ["name"]      }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success",
      "values": ["Alice", "30"]
    },
    {
      "relationship_id": "node2",
      "error_code": "AttributeNotFound",
      "values": []
    },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.15 `/batch_get_all_relationship_attributes`

Description

Fetches all string‑valued attributes for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id":"string",
      "error_code":     "string",
      "attributes": {
        "string": "string",
        ...
      }
    },
    ...
  ]
}

Example

Request:

POST /batch_get_all_relationship_attributes
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "relationships": [
    {"relationship_id": "node1"},
    {"relationship_id": "node2"},
    {"relationship_id": "nodeX"}
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code":        "Success",
      "attributes": {
        "name": "Alice",
        "age": "30",
        "country": "Canada"
      }
    },
    {
      "relationship_id": "node2",
      "error_code":        "Success",
      "attributes": { "name": "Bob" }
    },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.16 `/batch_get_relationship_vectors`

Description

Fetches specified vectors for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id": "string",
      "vector_names": ["string", ...]
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
      {
        "relationship_id": "string",
        "error_code": "string",
        "vectors": [
          {
            "name": "string",
            "type": "Float32" | "SFloat32",
            "vector_data": [ ... ]
          },
          ...
        ]
      },
    ...
  ]
}

Example

Request:

POST /batch_get_relationship_vectors
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "relationships": [
    { "relationship_id": "node1", "vector_names": ["vector_a", "vector_b"] },
    { "relationship_id": "node2", "vector_names": ["vector_c"] },
    { "relationship_id": "nodeX", "vector_names": ["vector_y"] }
  ],
  "use_job": false
}

Response:

{
  "results": [
      {
        "relationship_id": "node1",
        "error_code": "Success",
        "vectors": [
          {
            "name": "vector_a",
            "type": "Float32",
            "vector_data": [0.1, 0.2, 0.3]
          },
          {
            "name": "vector_b",
            "type": "Float32",
            "vector_data": [0.4, 0.5, 0.6]
          }
        ]
      },
      {
        "relationship_id": "node2",
        "error_code": "Success",
        "vectors": [
          {
            "name": "vector_c",
            "type": "Float32",
            "vector_data": [0.7, 0.8]
          }
        ]
      },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.17 `/batch_get_all_relationship_vector_names`

Description

Fetches all vector names (keys) for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id": "string",
      "error_code": "string",
      "vector_names": ["string", ...]
    },
    ...
  ]
}

Example

Request:

POST /batch_get_all_relationship_vector_names
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id":     "graph_ABC",
  "relationships": [
    { "relationship_id": "node1" },
    { "relationship_id": "node2" },
    { "relationship_id": "nodeX" }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success",
      "vector_names": ["profile_vec", "sparse_pref"]
    },
    {
      "relationship_id": "node2",
      "error_code": "Success",
      "vector_names": []
    },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.18 `/batch_get_all_relationship_vectors`

Description

Fetches all vectors (dense and sparse) for multiple relationships in one request.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id":     "string",
  "relationships": [
    {
      "relationship_id": "string"
    },
    ...
  ],
  "use_job": false
}

Response

Success Response (200 OK):

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success",
      "vectors": [
        {
          "name":        "string",
          "type":        "string",
          "vector_data": [ ... ]
        },
        {
          "name":        "string",
          "type":        "string",
          "vector_data": [ ... ]
        }
      ]
    },
    {
      "relationship_id": "node2",
      "error_code": "Success",
      "vectors": []
    },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

Example

Request:

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "relationships": [
    { "relationship_id": "node1" },
    { "relationship_id": "node2" },
    { "relationship_id": "nodeX" }
  ],
  "use_job": false
}

Response:

{
  "results": [
    {
      "relationship_id": "node1",
      "error_code": "Success",
      "vectors": [
        {
          "name": "profile_vec",
          "type": "Float32",
          "vector_data": [0.12, 0.34, 0.56, 0.78]
        },
        {
          "name": "sparse_pref",
          "type": "SFloat32",
          "vector_data": [
            [0, 1.0],
            [3, 2.5]
          ]
        }
      ]
    },
    {
      "relationship_id": "node2",
      "error_code": "Success",
      "vectors": []
    },
    {
      "relationship_id": "nodeX",
      "error_code": "RelationshipNotFound"
    }
  ]
}

5.19 `/batch_search_entity_index`

Description

Executes multiple /search_entity_index queries in a single request. Each query can perform either exact attribute matching or vector similarity search and may include its own filter.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "batch_queries": [
    {
      "attribute_name": "string",
      "index_type": "string",
      // Provide exactly one of the following:
      "attribute_value": "string",
      "vector": { "type": "Float32", "vector_data": [ ... ] },
      "top_k": 5,
      "similarity_measure": "Cosine",
      "entity_filter": { ... }
    },
    ...
  ],
  "use_job": false
}

batch_queries: Ordered list of searches. For vector indices supply the vector object under vector; for attribute indices supply attribute_value.
top_k, similarity_measure, and entity_filter are optional per-query overrides.

Response

{
  "results": [
    {
      "attribute_name": "string",
      "index_type": "string",
      "entity_ids": ["string", ...],
      "error_code": "Success"
    },
    ...
  ]
}

The results array aligns with batch_queries order. Each entry echoes the query metadata and includes the per-query error_code (for example IndexNotFound, InvalidParameter, etc.).

Error Responses:

400: A query omitted both attribute_value and vector, or provided both; unsupported similarity_measure.

Example

Request:

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "batch_queries": [
    {
      "attribute_name": "name",
      "index_type": "Attribute Index",
      "attribute_value": "Seattle"
    },
    {
      "attribute_name": "vector_location",
      "index_type": "Vector Index",
      "vector": {
        "type": "Float32",
        "vector_data": [47.6061, -122.3328]
      },
      "top_k": 3
    }
  ],
  "use_job": false
}

Example Response (200 OK)

Response:

{
  "results": [
    {
      "attribute_name": "name",
      "index_type": "Attribute Index",
      "entity_ids": ["seattle_office", "seattle_hq"],
      "error_code": "Success"
    },
    {
      "attribute_name": "vector_location",
      "index_type": "Vector Index",
      "entity_ids": ["seattle_hq", "bellevue_branch", "tacoma_branch"],
      "error_code": "Success"
    }
  ]
}

5.20 `/batch_search_relationship_index`

Description

Vectorised equivalent of /search_relationship_index that evaluates several relationship-index queries in one call.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "batch_queries": [
    {
      "attribute_name": "string",
      "index_type": "string",
      // Provide exactly one of the following:
      "attribute_value": "string",
      "vector": { "type": "Float32", "vector_data": [ ... ] },
      "top_k": 5,
      "similarity_measure": "Cosine",
      "relationship_filter": { ... }
    },
    ...
  ],
  "use_job": false
}

Query fields mirror /batch_search_entity_index, with relationship_filter applying the predicate at query time.

Response

{
  "results": [
    {
      "attribute_name": "string",
      "index_type": "string",
      "relationship_ids": ["string", ...],
      "error_code": "Success"
    },
    ...
  ]
}

Error Responses:

400: Missing or conflicting attribute_value/vector in a query.

Example

Request:

{
  "user_api_key": "api_key_123",
  "graph_id": "graph_ABC",
  "batch_queries": [
    {
      "attribute_name": "type",
      "index_type": "Attribute Index",
      "attribute_value": "acted_in"
    },
    {
      "attribute_name": "vector_direction",
      "index_type": "Vector Index",
      "vector": {
        "type": "Float32",
        "vector_data": [0.01, 0.9, -0.2]
      },
      "relationship_filter": {
        "match_attribute": {
          "key": "status",
          "values": ["active"]
        }
      }
    }
  ],
  "use_job": false
}

Example Response (200 OK)

Response:

{
  "results": [
    {
      "attribute_name": "type",
      "index_type": "Attribute Index",
      "relationship_ids": ["r101", "r203"],
      "error_code": "Success"
    },
    {
      "attribute_name": "vector_direction",
      "index_type": "Vector Index",
      "relationship_ids": ["r305", "r402"],
      "error_code": "Success"
    }
  ]
}

5.21 `/import_entities`

Description

Bulk-ingests entities from a CSV or JSON source. Provide format to select the parser and either a url (supports http://, https://, and file://) or inline file_data. Set use_job to queue the import as a background job.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "format": "csv",
  "url": "https://example.com/entities.csv",
  "headers": ["entity_id", "name", "vector_a"],
  "is_vector": [false, false, true],
  "use_job": true
}

format: "csv" or "json".
url or file_data: Location or literal contents of the file. When supplying CSV, you can omit headers/is_vector to let the server read them from the file. For JSON, file_data must be a JSON object keyed by entity_id with optional "attributes" and "vectors" entries.
headers (CSV): Column names. The first column must be entity_id. Provide headers here or include a header row in the CSV; one of them must exist. Avoid providing both, since CSV parsing will be offset.
is_vector (CSV): Boolean flags indicating which columns are vectors. The first column must be false. Provide is_vector here or include vector flags in the CSV; one of them must exist. Avoid providing both, since CSV parsing will be offset.
use_job (optional): When true, return a job_id and process asynchronously.

Response

{
  "error_code": "Success",
  "job_id": "string"
}

When use_job is false, the request completes synchronously and returns per-row outcomes:

{
  "error_code": "Success",
  "create_success": 2,
  "create_failure": 1,
  "create_entity_ids": ["id3"],
  "create_ecs": ["EntityExist"],
  "set_success": 2,
  "set_failure": 1,
  "set_entity_ids": ["id3"],
  "set_ecs": ["EntityExist"]
}

create_success: Number of entities created successfully.
create_failure: Number of entities that failed to create.
create_entity_ids: Entity IDs that failed to create (matches create_ecs by index).
create_ecs: Error codes for the failed creates.
set_success: Number of attribute/vector sets that succeeded.
set_failure: Number of attribute/vector sets that failed.
set_entity_ids: Entity IDs that failed to set (matches set_ecs by index).
set_ecs: Error codes for the failed sets.

When use_job is true, the same payload is available in /get_job_result.

Error Responses (during request submission):

400: Missing format or source data (url/file_data), invalid URL scheme, unsupported format, or malformed headers.
502: Remote CSV could not be downloaded.

Graph-level failures (e.g., graph not found, duplicate IDs) surface inside the per-job statistics.

Example

Request:

POST /import_entities
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "format": "csv",
  "url": "https://data.example.com/entities.csv",
  "use_job": true
}

Response:

{
  "error_code": "Success",
  "job_id": "im_api_key_123_graph_7384efd5"
}

5.22 `/import_relationships`

Description

Imports relationships from CSV or JSON. Provide format and either a url or inline file_data. Set use_job to run asynchronously.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "format": "csv",
  "url": "file:///absolute/path/to/relationships.csv",
  "headers": ["src_entity_id", "relationship_id", "dest_entity_id", "weight"],
  "is_vector": [false, false, false, false],
  "use_job": true
}

format: "csv" or "json".
url or file_data: Source CSV/JSON contents. For CSV, omit headers/is_vector to parse them from the file. Columns 1–3 must be src_entity_id, relationship_id, and dest_entity_id and must not be vectors.
headers (CSV): Override parsed headers; the first three headers must be src_entity_id, relationship_id, and dest_entity_id. Provide headers here or include a header row in the CSV; one of them must exist. Avoid providing both, since CSV parsing will be offset.
is_vector (CSV): Override parsed flags; the first three entries must be false. Provide is_vector here or include vector flags in the CSV; one of them must exist. Avoid providing both, since CSV parsing will be offset.
JSON format: Provide an array (or an object with a relationships array) of objects each containing src_entity_id, relationship_id, dest_entity_id, optional "attributes" (string map), and optional "vectors" (vector objects).
use_job (optional): When true, return a job_id and process asynchronously.

Response

{
  "error_code": "Success",
  "job_id": "string"
}

When use_job is false, the response summarizes per-row create/set outcomes:

{
  "error_code": "Success",
  "create_success": 10,
  "create_failure": 2,
  "create_src_entity_ids": ["src_bad1", "src_bad2"],
  "create_relationship_ids": ["rel_bad1", "rel_bad2"],
  "create_dest_entity_ids": ["dst_bad1", "dst_bad2"],
  "create_ecs": ["EntityNotFound", "EntityNotFound"],
  "set_success": 9,
  "set_failure": 1,
  "set_relationship_ids": ["rel_bad2"],
  "set_ecs": ["AttributeNotFound"]
}

create_success: Count of relationships created successfully.
create_failure: Count of relationships that failed to create.
create_src_entity_ids: Source entity IDs for relationships that failed to create.
create_relationship_ids: Relationship IDs that failed to create.
create_dest_entity_ids: Destination entity IDs for relationships that failed to create.
create_ecs: Error codes corresponding to create_relationship failures.
set_success: Count of attribute/vector sets that succeeded.
set_failure: Count of attribute/vector sets that failed.
set_relationship_ids: Relationship IDs that failed to set attributes/vectors.
set_ecs: Error codes corresponding to attribute/vector set failures.

Error Responses:

400: Missing format or source data (url/file_data), invalid or incomplete header, unsupported URI scheme, or unsupported format.
502: Remote CSV could not be downloaded.

Example

Request:

POST /import_relationships
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "format": "csv",
  "url": "https://data.example.com/relationships.csv",
  "use_job": true
}

Response:

{
  "error_code": "Success",
  "job_id": "im_api_key_123_graph_1f9cb0f7"
}

6. Node Embedding Algorithms

6.1 `/remove_model`

Description

Deletes a stored embedding model by name for the authenticated user. This is useful to clean up old GraphSAGE/GCN models before retraining with the same name.

Method

POST

Request Body

{
  "user_api_key": "string",
  "model_name": "string"
}

Response

{
  "error_code": "Success",
  "model_name": "string"
}

Error Responses:

404: Model does not exist.

Example

Request:

POST /remove_model
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "model_name": "sage_model"
}

Response:

{
  "error_code": "Success",
  "model_name": "sage_model"
}

6.2 `/node2vec`

Description

Runs the Node2Vec algorithm to generate node embeddings. Biased random walks are sampled with parameters p and q, then a skip-gram style model trains vectors of dimension emb_dim. Embeddings are stored on each node under embedding_name. All Node2Vec parameters are configurable; computation runs with a fixed thread count managed by the server (not configurable).

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "p": 1.0,
  "q": 1.0,
  "walk_len": 40,
  "num_walks": 10,
  "emb_dim": 128,
  "window_size": 10,
  "negative_samples": 5,
  "num_epochs": 5,
  "learning_rate": 0.01,
  "embedding_name": "node2vec",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "node2vec"
}

Example

Request:

POST /node2vec
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "p": 1.0,
  "q": 1.0,
  "walk_len": 40,
  "num_walks": 10,
  "emb_dim": 64,
  "window_size": 10,
  "negative_samples": 5,
  "num_epochs": 5,
  "learning_rate": 0.01,
  "embedding_name": "node2vec",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "node2vec_api_key_123_graph_abcdef01"
}

6.3 `/fastrp`

Description

Runs the Fast Random Projection (FastRP) algorithm to generate node embeddings. Iterative random projections are weighted by iteration_weights to balance hop influence. Embeddings are stored on each node under embedding_name. Computation uses an internal offload batch size (not exposed as a parameter) and runs with a fixed thread count managed by the server (not configurable).

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "embedding_dim": 64,
  "iteration_weights": [0.0, 1.0, 1.0],
  "normalization_strength": 0.0,
  "node_self_influence": 0.0,
  "random_seed": -1,
  "embedding_name": "fastrp",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "fastrp"
}

Example

Request:

POST /fastrp
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "embedding_dim": 32,
  "iteration_weights": [0.0, 1.0, 1.0],
  "embedding_name": "custom_fastrp",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "fastrp_api_key_123_graph_abcdef01"
}

6.4 `/hashgnn`

Description

Runs the HashGNN algorithm to generate node embeddings. Embeddings are stored on each node under embedding_name. Optionally, feature_attribute can be used to binarize existing feature vectors before training. Computation runs with a fixed thread count managed by the server (not configurable).

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "iterations": 5,
  "embedding_density": 4,
  "embedding_dim": 128,
  "neighbor_influence": 1.0,
  "random_seed": -1,
  "embedding_name": "hashgnn",
  "output_dim": -1,
  "initial_density": 3,
  "feature_attribute": "",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "hashgnn"
}

Example

Request:

POST /hashgnn
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "iterations": 3,
  "embedding_density": 4,
  "embedding_dim": 64,
  "neighbor_influence": 1.0,
  "embedding_name": "custom_hashgnn",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "hashgnn_api_key_123_graph_abcdef01"
}

6.5 `/sage_train`

Description

Runs the GraphSAGE algorithm to generate node embeddings. All training-related parameters are exposed; embeddings are stored on each node under embedding_name. Device selection is handled internally by the server.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "iterations": 100,
  "batch_size": 32,
  "embedding_dimension": 128,
  "feature_properties": [],
  "learning_rate": 0.01,
  "sample_sizes": [25, 10],
  "aggregator": "mean",
  "negative_sample_weight": 1,
  "penalty_l2": 0.0001,
  "tolerance": 1e-6,
  "epochs": 10,
  "max_iterations": 1000,
  "activation_function": "relu",
  "random_seed": 42,
  "embedding_name": "sage_embedding",
  "is_multi_label": false,
  "projected_feature_dimension": 0,
  "neighbor_influence": 1.0,
  "search_depth": 2,
  "dropout_rate": 0.5,
  "use_residual": true,
  "include_self": true,
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "sage_embedding"
}

Example

Request:

POST /sage_train
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "sage_model",
  "embedding_dimension": 16,
  "epochs": 1,
  "batch_size": 8,
  "sample_sizes": [5, 5],
  "aggregator": "mean",
  "activation_function": "relu",
  "embedding_name": "custom_sage",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "sage_train_api_key_123_graph_abcdef01"
}

6.6 `/sage_infer`

Description

Runs GraphSAGE inference from a previously trained model. Embeddings are written to the graph using the metadata stored with the model. Device selection is handled internally by the server.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "model_name": "sage_model"
}

Example

Request:

POST /sage_infer
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "sage_model",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "sage_infer_api_key_123_graph_abcdef01"
}

6.7 `/gcn_train`

Description

Runs the GCN algorithm to generate node embeddings. All training-related parameters are exposed; embeddings are stored on each node under embedding_name. Device selection is handled internally by the server.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "iterations": 100,
  "batch_size": 32,
  "embedding_dimension": 128,
  "feature_properties": [],
  "learning_rate": 0.01,
  "dropout_rate": 0.5,
  "negative_sample_weight": 1,
  "penalty_l2": 0.0001,
  "tolerance": 1e-6,
  "epochs": 10,
  "max_iterations": 1000,
  "activation_function": "relu",
  "random_seed": 42,
  "embedding_name": "gcn_embedding",
  "is_multi_label": false,
  "projected_feature_dimension": 0,
  "normalize_features": true,
  "self_loops": true,
  "use_sparse_adjacency": true,
  "use_supervised": false,
  "label_attribute": "label",
  "num_classes": 2,
  "supervised_loss_weight": 1.0,
  "reconstruction_loss_weight": 1.0,
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "gcn_embedding"
}

Example

Request:

POST /gcn_train
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gcn_model",
  "embedding_dimension": 16,
  "epochs": 1,
  "batch_size": 8,
  "activation_function": "relu",
  "embedding_name": "custom_gcn",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "gcn_train_api_key_123_graph_abcdef01"
}

6.8 `/gcn_infer`

Description

Runs GCN inference from a previously trained model. Embeddings are written to the graph using the metadata stored with the model. Device selection is handled internally by the server.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "model_name": "gcn_model"
}

Example

Request:

POST /gcn_infer
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gcn_model",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "gcn_infer_api_key_123_graph_abcdef01"
}

6.9 `/gcn_predict`

Description

Runs GCN prediction from a supervised model and returns per-entity labels. Predictions are also written to each entity under label_attribute stored in the model metadata. Prediction keys are internal numeric entity IDs serialized as strings.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "model_name": "gcn_model",
  "predictions": {
    "123": 0,
    "456": 1
  }
}

Example

Request:

POST /gcn_predict
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gcn_model",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "gcn_predict_api_key_123_graph_abcdef01"
}

6.10 `/attention_train`

Description

Runs the Graph Attention Network (GAT) training routine. When task_type is unsupervised, embeddings are stored on each node under embedding_name.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "epochs": 10,
  "embedding_dimension": 128,
  "learning_rate": 0.001,
  "penalty_l2": 0.0001,
  "dropout_rate": 0.0,
  "train_split": 0.8,
  "num_heads": 8,
  "hidden_dims": [128, 64],
  "attention_dropout": 0.0,
  "negative_slope": 0.2,
  "task_type": "classification",
  "target_attribute": "",
  "feature_attribute": "",
  "num_classes": 2,
  "embedding_name": "gat_embedding",
  "random_seed": 42,
  "model_path": "gat_model.pt",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "embedding_name": "gat_embedding"
}

Example

Request:

POST /attention_train
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gat_model",
  "epochs": 1,
  "embedding_dimension": 16,
  "hidden_dims": [16, 16],
  "task_type": "unsupervised",
  "embedding_name": "custom_gat",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "attention_train_api_key_123_graph_abcdef01"
}

6.11 `/attention_infer`

Description

Runs GAT inference from a previously trained model and stores embeddings using the metadata stored with the model.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "model_name": "gat_model"
}

Example

Request:

POST /attention_infer
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gat_model",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "attention_infer_api_key_123_graph_abcdef01"
}

6.12 `/attention_predict`

Description

Runs GAT prediction and returns per-entity outputs. For task_type = unsupervised, the prediction values contain embedding vectors serialized as strings. Prediction keys are internal numeric entity IDs serialized as strings.

Method

POST

Request Body

{
  "user_api_key": "string",
  "graph_id": "string",
  "model_name": "string",
  "use_job": false
}

Response

{
  "error_code": "Success",
  "model_name": "gat_model",
  "predictions": {
    "123": "class_a",
    "456": "class_b"
  }
}

Example

Request:

POST /attention_predict
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "graph_id": "graph",
  "model_name": "gat_model",
  "use_job": true
}

Response when enqueued as a job:

{
  "error_code": "Success",
  "job_id": "attention_predict_api_key_123_graph_abcdef01"
}

7. Server Job API

To support long-running or resource-intensive operations without requiring clients to maintain a persistent connection, most API endpoints offer asynchronous job execution. When you enable this feature, your request will be processed in the background, and you can poll for its completion using the job API.

To submit an API call as a job, add these parameters to your request body:

{
  "use_job": true
}

use_job: Set to true to process the operation asynchronously.

When a request is submitted as a job, the server responds with the job identifier:

{
  "error_code": "string",
  "job_id": "string"
}

Note: Not all endpoints support asynchronous job execution. The following endpoints do not support jobs and must be called synchronously:

All job management endpoints: /get_job_status, /get_job_result
Graph management: /create_graph, /remove_graph, /get_graphs

Import pipelines (/import_entities, /import_relationships) accept use_job; when enabled, the server enqueues the import work and returns a job_id.

The following API endpoints are used to monitor and manage jobs:

7.1 `/get_job_status`

Description

Retrieves the current status of a job specified by job_id.

Method

POST

Request Body

{
  "user_api_key": "string",
  "job_id": "string"
}

Response

Success Response (200 OK):

{
  "error_code": "Success",
  "status": "Pending" | "In Progress" | "Success" | "Failed" | "Unknown"
}

Error Responses:

404: Job not found.

Example

Request:

POST /get_job_status
Content-Type: application/json

{
  "user_api_key": "API_KEY",
  "job_id": "job_abc123"
}

Response:

{
  "error_code": "Success",
  "status": "Success"
}

7.2 `/get_job_result`

Description

Retrieves the result of a completed job specified by job_id. If the job is still in progress, the response will indicate that the result is not yet available.

Method

POST

Request Body

{
  "user_api_key": "string",
  "job_id": "string"
}

Response

Success Response (200 OK): Returns the response object for the original API call (format depends on the endpoint you invoked with use_job=true).
Accepted Response (202 Accepted): Indicates that the job is still running and the result is not yet available.
Error Responses:
404: Job not found.

Example

Request:

POST /get_job_result
Content-Type: application/json

{
  "user_api_key": "API_KEY",
  "job_id": "job_abc123"
}

Response (when completed):

Response:

{
  "error_code": "Success",
  "entity_ids": ["Alice", "Bob", "Charlie"]
}

Response (when still running):

{
  "error_code": "Success",
  "error_message": "job still running"
}

Appendix

The appendix contains several notes about how the Graph API works.

Filters

The VecML GraphDB REST API supports expressive, composable JSON predicates to filter entities.

Overall Structure

A filter is a JSON object representing either:

A logical combinator (and, or, xor, not) whose value is one or more sub-predicates, or
A leaf operation that tests a single property.

Example

{
  "and": [
    {
      "match_attribute": {
        "key": "status",
        "values": ["active"]
      }
    },
    {
      "less_than": {
        "key": "age",
        "value": 18
      }
    }
  ]
}

Logical Combinators

Operator	Syntax	Description
AND	`{"and":[<pred>,<pred>,…]}`	True if all sub-predicates are true.
OR	`{"or":[<pred>,<pred>,…]}`	True if any sub-predicate is true.
XOR	`{"xor":[<pred>,<pred>]}`	True if exactly one sub-predicate is true.
NOT	`{"not":<pred>}`	True if the sub-predicate is false.

Leaf Operations

Operation	Syntax	Description
match_attribute	`{"match_attribute":{"key":"<attr>","values":["v1","v2",…]}}`	`<attr>` equals any listed value.
attribute_exists	`{"attribute_exists":"<attr>"}`	Entity has attribute `<attr>`.
attribute_is_integer	`{"attribute_is_integer":"<attr>"}`	`<attr>` is an integer.
attribute_is_float	`{"attribute_is_float":"<attr>"}`	`<attr>` is a float.
less_than	`{"less_than":{"key":"<attr>","value":<num>}}`	`<attr>` < `value` (numeric or lexicographic).
true	`{"true":{}}`	Always true.
false	`{"false":{}}`	Always false.

vectors

JSON endpoints accept two vector encodings, each represented as an object with type and vector_data:

Dense float vectors – type: "Float32" – vector_data: an array of 32-bit floating-point values
Sparse float vectors – type: "SFloat32" – vector_data: an array of [index, value] pairs, where value is a 32-bit float

Some endpoints also require or return a "name" attribute alongside the two fields above. When importing from CSV, the server will auto-detect integer literals and may store them as integer vectors internally, but JSON payloads must use the two types above.

Examples

// Dense float vector (with name)
{
  "name": "vector_location",
  "type": "Float32",
  "vector_data": [0.12, 0.83, 0.44, …]
}

// Sparse float vector (with name)
{
  "name": "vector_word",
  "type": "SFloat32",
  "vector_data": [
    [3, 0.7],
    [42, 1.9],
    …
  ]
}

Distance Function

When building or querying a Vector Index or a Fuzzy Attribute Index, you must specify a distance‐function. The supported values for dist_type / similarity_measure reside in the DistanceFunctionType enum:

Euclidean (default)
Standard L₂‐norm (ℓ₂) distance:

$$ d_{\text{Euclidean}}(\mathbf x, \mathbf y) \;=\; \sqrt{\sum_{i}(x_i - y_i)^2} $$

Cosine
One minus the cosine‐similarity.
InnerProduct
Equivalent to negative cosine when vectors are normalized; otherwise, the raw dot‐product.
Hamming
For binary‐encoded/sparse‐packed vectors, counts the number of differing bits.
WeightedJaccard / WeightedContainment
Negative weighted Jaccard/containment similarity.
Custom
Reserved for custom distance functions (index-specific).

Note:

Only Vector Index and Fuzzy Attribute Index consult dist_type. All other index types ignore it.

If you do not explicitly pass dist_type, the API defaults to Euclidean.

In code, these are defined under enum DistanceFunctionType { Euclidean, InnerProduct, Cosine, Custom, Hamming, WeightedJaccard, WeightedContainment }.

Index Types

The following index types are supported by the GraphInterface API (see “Types of Indices” in the SDK docs): :contentReference[oaicite:0]{index=0}

Attribute Index
Finds all entities (or relationships) whose attribute value exactly equals the query term.
Fuzzy Attribute Index
Performs approximate string‐matching on attribute values (e.g. edit‐distance or n‐gram based) to find entities (or relationships) whose attribute “approximately” matches the query term.
Vector Index
An approximate nearest‐neighbor index over dense or sparse vectors. Commonly used for high‐dimensional vectors (e.g. Float32). When creating a Vector Index, you supply:
dim – dimensionality of the vectors
dist_type – distance metric to use (see 0.6)
Integer Linear Index
A linear (brute‐force) similarity search over integer‐valued vectors. Useful for scalar or quantized vectors. JSON vector payloads must still use Float32/SFloat32; integer vectors can be supplied via CSV import.
Float Linear Index
A linear (brute‐force) similarity search over floating‐point vectors. Similar to Integer Linear Index, but for Float32‐typed vectors.

VecML GraphDB REST API (v0.6)

Authentication (API key):

An Example Workflow

Common Error Responses

1. User API

1.1 /create_graph

1.2 /remove_graph

1.3 /get_graphs

1.4 /create_checkpoint

1.5 /revert_checkpoint

2. Basic Graph API

2.1 /create_entity

2.2 /remove_entity

2.3 /set_entity_attributes

2.4 /remove_entity_attributes

2.5 /get_entity_attributes

2.6 /get_all_entity_attributes

2.7 /get_entity_vectors

2.8 /get_all_entity_vector_names

2.9 /get_all_entity_vectors

2.10 /filter_entity

2.11 /create_relationship

2.12 /remove_relationship

2.13 /set_relationship_attributes

2.14 /remove_relationship_attributes

2.15 /get_relationship_attributes

2.16 /get_all_relationship_attributes

2.17 /get_relationship_vectors

2.18 /get_all_relationship_vector_names

2.19 /get_all_relationship_vectors

2.20 /filter_relationship

2.21 /get_all_entity_ids

2.22 /get_all_relationship_ids

2.23 /get_all_relationships

3. Graph Index API

3.1 /create_entity_index

3.2 /remove_entity_index

3.3 /entity_index_exists

3.4 /get_all_entity_index

3.5 /get_all_types_entity_index

3.6 /search_entity_index

3.7 /create_relationship_index

3.8 /remove_relationship_index

3.9 /relationship_index_exists

3.10 /get_all_relationship_index

3.11 /get_all_types_relationship_index

3.12 /search_relationship_index

4. Graph Algorithms

4.0 /get_neighbors

4.1 Shortest Path Algorithms

4.1.1 /find_k_hop

4.1.2 /dijkstra

4.1.3 /astar

4.1.4 /spfa

4.1.5 /delta_stepping

4.2 Trees & Connectivity

4.2.1 /prim

4.2.2 /steiner_tree

4.3 Flow (Push-Relabel)

4.3.1 /max_flow_push_relabel

4.4 Link Prediction & Neighborhood Similarity

4.4.1 /common_neighbors

4.4.2 /adamic_adar

4.4.3 /preferential_attachment

4.5 Ranking, Ordering, & Inference

4.5.1 /topsort

4.5.2 /topsort_kahn

4.5.3 /dag_longest_path

4.5.4 /pagerank

4.5.5 /loopy_bp_map

4.5.6 /loopy_bp_map_continuous

4.6 Clustering

4.6.1 /create_clustering

4.6.2 /get_clustering

4.6.3 /get_clustering_cluster

4.6.4 /get_clustering_membership

4.6.5 /delete_clustering

5. Graph Batch Operations

5.1 /batch_create_entity

5.2 /batch_remove_entity

1.1 `/create_graph`

1.2 `/remove_graph`

1.3 `/get_graphs`

1.4 `/create_checkpoint`

1.5 `/revert_checkpoint`

2.1 `/create_entity`

2.2 `/remove_entity`

2.3 `/set_entity_attributes`

2.4 `/remove_entity_attributes`

2.5 `/get_entity_attributes`

2.6 `/get_all_entity_attributes`

2.7 `/get_entity_vectors`

2.8 `/get_all_entity_vector_names`

2.9 `/get_all_entity_vectors`

2.10 `/filter_entity`

2.11 `/create_relationship`

2.12 `/remove_relationship`

2.13 `/set_relationship_attributes`

2.14 `/remove_relationship_attributes`

2.15 `/get_relationship_attributes`

2.16 `/get_all_relationship_attributes`

2.17 `/get_relationship_vectors`

2.18 `/get_all_relationship_vector_names`

2.19 `/get_all_relationship_vectors`

2.20 `/filter_relationship`

2.21 `/get_all_entity_ids`

2.22 `/get_all_relationship_ids`

2.23 `/get_all_relationships`

3.1 `/create_entity_index`

3.2 `/remove_entity_index`

3.3 `/entity_index_exists`

3.4 `/get_all_entity_index`

3.5 `/get_all_types_entity_index`

3.6 `/search_entity_index`

3.7 `/create_relationship_index`

3.8 `/remove_relationship_index`

3.9 `/relationship_index_exists`

3.10 `/get_all_relationship_index`

3.11 `/get_all_types_relationship_index`

3.12 `/search_relationship_index`

4.0 `/get_neighbors`

4.1.1 `/find_k_hop`

4.1.2 `/dijkstra`

4.1.3 `/astar`

4.1.4 `/spfa`

4.1.5 `/delta_stepping`

4.2.1 `/prim`

4.2.2 `/steiner_tree`

4.3.1 `/max_flow_push_relabel`

4.4.1 `/common_neighbors`

4.4.2 `/adamic_adar`

4.4.3 `/preferential_attachment`

4.5.1 `/topsort`

4.5.2 `/topsort_kahn`

4.5.3 `/dag_longest_path`

4.5.4 `/pagerank`

4.5.5 `/loopy_bp_map`

4.5.6 `/loopy_bp_map_continuous`

4.6.1 `/create_clustering`

4.6.2 `/get_clustering`

4.6.3 `/get_clustering_cluster`

4.6.4 `/get_clustering_membership`

4.6.5 `/delete_clustering`

5.1 `/batch_create_entity`

5.2 `/batch_remove_entity`

5.3 `/batch_set_entity_attributes`

5.4 `/batch_remove_entity_attributes`

5.5 `/batch_get_entity_attributes`

5.6 `/batch_get_all_entity_attributes`

5.7 `/batch_get_entity_vectors`

5.8 `/batch_get_all_entity_vector_names`

5.9 `/batch_get_all_entity_vectors`

5.10 `/batch_create_relationship`

5.11 `/batch_remove_relationship`

5.12 `/batch_set_relationship_attributes`

5.13 `/batch_remove_relationship_attributes`

5.14 `/batch_get_relationship_attributes`

5.15 `/batch_get_all_relationship_attributes`

5.16 `/batch_get_relationship_vectors`

5.17 `/batch_get_all_relationship_vector_names`