REST API
Two REST surfaces, on two ports, split by concern:
| Port | Surface | Swagger UI |
|---|---|---|
|
Platform - organizations, projects, users, API keys, tokens |
|
|
Data - collections, documents, graphs, nodes, edges, search |
The Swagger UI on a running container is the authoritative reference for every endpoint, parameter and response shape. This chapter covers the part Swagger cannot explain on its own: how authentication works.
What lives where
The split is not arbitrary, and it decides which credential you need:
-
Platform (7281) owns definitions and tenancy - creating and listing collections and graphs, projects, organizations, users, API keys, CDC sinks, the audit log.
-
Data (7282) owns the data itself - documents, nodes, edges, search, transactions, CyQL statements.
So a collection is created on 7281 and then filled with documents on 7282. Surprising the first
time; it follows from the data server holding no user database of its own.
The auth model
Two credentials, and - this is the part worth reading carefully - each server wants a different one:
| Server | Credential | Header |
|---|---|---|
Platform (7281) |
The API key itself |
|
Data (7282) |
A short-lived token |
|
The API key is long-lived and comes from the startup banner. The token lasts 300 seconds and is obtained by presenting the API key to the platform server. The data server accepts only the token: it authorizes purely from the token’s claims, which is what lets it scale without a user database.
Sending a bearer token to the platform server returns 401, and it is an easy hour to lose. Use the
API key there.
Exchange the key for a token
API_KEY=<the key from the startup banner>
curl -sS -X POST http://localhost:7281/api/v1/token \
-H "X-API-Key: $API_KEY"
{
"token": "eyJhbGciOiJIUzI1NiJ9...",
"expiresIn": 300
}
Note the exchange happens on the platform port even when your work is entirely on the data port.
A short walkthrough
Everything below assumes $TOKEN and the project ID from the banner.
Create a collection
On the platform port, with the API key - and note the fields are split into vectorFields and
metadataFields rather than one list:
curl -sS -X POST "http://localhost:7281/api/v1/projects/$PROJECT_ID/collections" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "articles",
"vectorFields": [
{"name": "vector", "dimension": 384, "similarityFunction": "COSINE", "compression": "NONE"}
],
"metadataFields": [
{"name": "title", "type": "STRING", "cardinality": "HIGH"},
{"name": "body", "type": "STRING", "cardinality": "HIGH", "fulltext": true},
{"name": "topic", "type": "STRING", "cardinality": "LOW"}
]
}'
No vector field is required. A collection without one is a document store: it stores, reads,
lists and filters on its metadata, and answers a full-text SEARCH on any field declared
fulltext: true - the body field above is one. Full-text is a property of that declaration, not of
the vectors: with no fulltext field at all, a text query is refused with No text fields configured
for this collection. What such a collection cannot do is similarity search, and a vector search
against it is rejected with 400 naming the unknown field.
cardinality picks the indexing strategy: HIGH for values that are nearly unique per record,
LOW for a small set of repeated values like a category or status. fulltext: true adds BM25 indexing
so the field can be used with SEARCH.
The response carries the collection id used in every data-plane path below.
Search
On the data port, with the token:
curl -sS -X POST "http://localhost:7282/api/v1/collections/$COLLECTION_ID/search" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vectorField": "vector",
"vector": [0.01, 0.02, 0.03],
"maxResults": 5,
"filter": "topic = $topic",
"filterParameters": {"topic": "accounts"}
}'
{"matches": []}
The vector array above is shortened to keep the example readable. It must hold exactly as many
numbers as the field’s dimension - 384 for the collection created earlier - and a shorter one is
rejected with a 400 saying so. In practice you are pasting an embedding from your model rather than
typing numbers, so this is usually a matter of piping one in rather than composing it by hand.
The filter narrows candidates before ranking, so a restrictive filter still yields a full
maxResults. Put caller-supplied values in filterParameters and reference them as $name rather
than splicing them into the filter string, where a crafted value could rewrite the predicate. The
multi-, hybrid- and graph /search bodies take filterParameters the same way; GET …/nodes?filter=
has no parameter map and takes literals only.
Matches carry no vectors unless the body sets "includeVectors": true; most callers read ids, scores and
metadata, and leaving the vectors out saves loading and sending them. The multi- and hybrid-search bodies
take the same field.
maxResults is optional - leave it out and you get 10. That holds for the multi-, hybrid- and
natural-language searches too. Optional fields generally can be left out rather than spelled with a
placeholder value: the exceptions are the few where an omitted value would be destructive or meaningless,
such as maxAgeHours on POST /api/v1/graphs/{id}/decay, which is required because a zero age would prune
the whole graph. Those answer with a 400 naming the field.
Documents and CyQL statements
The remaining data-plane endpoints follow the same pattern - data port, bearer token:
| Endpoint | Purpose |
|---|---|
|
Upsert a document ( |
|
Upsert many at once |
|
List documents |
|
BM25 and vector fused |
|
Run a CyQL statement ( |
|
Several operations, applied atomically |
|
Natural-language search, if a language model is configured |
Graphs mirror this under /api/v1/graphs/{id}/... with nodes, edges, traversal, context windows and the
Graph RAG operations.
In a graph transaction (POST /api/v1/graphs/{id}/transaction), an addEdge operation can connect a node
created earlier in the same request. In place of sourceId or targetId, give sourceOpIndex or
targetOpIndex: the zero-based position of the addNode or upsertNode that creates the node. To connect
a node by its external key, give sourceKey or targetKey; a key no node holds fails the request with 404.
Each endpoint takes exactly one of the three:
{"operations": [
{"op": "addNode", "labels": ["Person"], "metadata": {"name": "Ada"}},
{"op": "addNode", "labels": ["Person"], "metadata": {"name": "Bob"}},
{"op": "addEdge", "sourceOpIndex": 0, "targetOpIndex": 1, "type": "KNOWS", "weight": 0.9},
{"op": "addEdge", "sourceOpIndex": 0, "targetKey": "city:berlin", "type": "LIVES_IN"}
]}
Like the neighbour reads, POST /api/v1/graphs/{id}/traverse and /context-window return nodes without
their vectors unless the body sets "includeVectors": true. A traversal also takes a "limit" on the nodes it
returns, the start node included (zero or omitted means no limit), and answers {"nodes": […], "truncated":
…}, where truncated says the limit held reachable nodes back. With a limit the server stops walking once it
has the nodes it returns, so a traversal from a hub does not collect most of the graph first.
The reads that return edges leave the edges' metadata out unless asked: POST .../nodes/{nodeId}/neighbors
takes ?includeEdgeMetadata=true, and /batch-neighbors, /induced-subgraph, /context-window,
/reasoning-chain and /recall take "includeEdgeMetadata": true in the body. Omitted means false: each edge
then carries its id, type, endpoints and weight, an empty metadata and a createdAt of 0, and the server loads
no edge, which on a hub is most of the cost of the read.
Omitting id on an upsert has the store assign one, which is what you want for a new document; the
assigned id comes back in the response. Giving an id replaces that document - including id: 0, which is
a real document rather than a "no id" marker, so leave the field out rather than sending a zero.
Take the exact request bodies from the Swagger UI at localhost:7282/swagger-ui, or from the OpenAPI document it is generated from:
curl -sS http://localhost:7282/api-docs > openapi.json
That is generated from the running server, so it cannot drift the way a hand-copied example in a manual can. When a body is rejected the response usually names the field - see Errors below. For anything beyond a quick curl, an SDK is less work - Java and Python both take typed objects instead of JSON.
Errors
Standard HTTP status codes, with an RFC 7807 problem document as the body:
| Status | Means |
|---|---|
|
The request is malformed - a bad filter, a vector of the wrong length, a field that does not bind. |
|
Missing or invalid credential. On the data port, usually an expired token. |
|
Authenticated, but this role may not do this. |
|
No such collection, graph or document. |
|
A conflict, such as a uniqueness violation. |
When a 400 comes from a field that would not bind, detail names the property at fault, so you rarely
need to bisect a payload:
{
"title": "Bad Request",
"status": 400,
"detail": "vectorFields[0].dimension: Cannot deserialize value of type `java.lang.Integer` from String \"lots\": not a valid `java.lang.Integer` value",
"instance": "/api/v1/projects/.../collections"
}
Rejected enum values list what is accepted, which is quicker than looking them up:
similarityFunction: ... not one of the values accepted for Enum class: [COSINE, EUCLIDEAN, DOT_PRODUCT]
Not every 400 can be attributed to a single field. A request the server parsed but rejected on its
merits carries the reason without a property - Vector field names must be unique - and a body that
is not valid JSON at all reports the parse position instead, since there is no field to point at.
A 401 on a call that worked a few minutes ago is almost always the 300-second token expiry. Server-side
failures return a 500 without a detail - if you hit one, the container log has the reason.
Health and metrics
Unauthenticated on purpose, so a load balancer or docker healthcheck can reach them:
curl http://localhost:7282/actuator/health
curl http://localhost:7282/actuator/prometheus
See Operations.