API Reference
CoordiNode exposes services via gRPC on port 7080 and REST/JSON on port 7081 (HTTP/JSON transcoding via embedded structured-proxy). Bolt protocol (7082) and WebSocket subscriptions (7083) are planned for a future release.
Services
| Service | Description | Proto |
|---|---|---|
| CypherService | OpenCypher-compatible query execution service. | — |
| VectorService | Vector search operations. | — |
| TextService | Full-text search operations backed by tantivy (BM25 scoring, 30+ languages). | — |
| GraphService | Core graph CRUD operations. | — |
| SchemaService | Schema management: node label and edge type definitions, and the named constraints declared over them. A type definition describes an individual record: property types, requiredness, defaults and computed properties. It never declares uniqueness. Uniqueness, node keys and the other constraints are separate named objects, created and dropped through the constraint RPCs, which share one catalog and one admission path with CREATE CONSTRAINT / DROP CONSTRAINT in Cypher: a constraint created here is the same object a query sees, and the reverse. | — |
| BlobService | BlobStore service: content-addressed chunk storage for large values. Values >= 4KB are split into 256KB chunks identified by SHA-256 hash. Content-addressing provides automatic deduplication. | — |
| HealthService | Health checking service (grpc.health.v1 compatible semantics). | — |
| ClusterService | Cluster management operations. | — |
| VersionHandshake | The version handshake between two members of a consensus group. This file is frozen for the life of the product: its package, service, method and messages never change, so that members of any two releases can tell each other which version they run. Members whose versions differ exchange nothing but this. The same record also travels in the cn-version-handshake-bin request and response metadata of every other inter-node call; a call whose record does not match the receiver's version is refused before its payload is read. | — |
| ChangeStreamService | CE Change Data Capture: tail a shard's Raft log via gRPC server-side streaming. Client reconnects with a ResumeToken to continue from a position it chose. At-least-once delivery. History is released only up to a position the client acknowledges with AcknowledgeSubscription. | — |
| RaftService | Raft consensus inter-node protocol (gRPC-only, no REST — internal). Uses opaque bytes for openraft type serialization (msgpack). This decouples the proto schema from openraft's internal generic types, making the protocol stable across openraft version upgrades. | — |
| SegmentTransferService | Inter-node bulk segment transfer: the transport for replication repair, node resync, and (per shard) migration. The source streams a segment's pieces to the target, which verifies each piece's checksum, decodes it, and writes it to local storage. BitTorrent-inspired: a target that has received pieces can in turn serve them to other targets, turning linear transfer into O(log N) fanout. This is an internal cluster RPC (node-to-node), not a client-facing API. | — |
| SessionService | Multiplexed bidirectional session. One long-lived bidirectional stream carries many concurrent operations for a single client. The client fires a batch of requests into the stream; the server executes them concurrently and streams results back as independent cursors, tagged by request id, in completion order rather than send order. An interactive transaction rides the same session as one interleaved sub-thread alongside non-transactional requests, and change-stream subscriptions ride it too, delivered in batches within the credit the client grants. The session is sticky to the serving node for its lifetime. The unary query, transaction and change-stream RPCs remain for clients that cannot hold a stream; this stream carries the same messages and is what a driver uses by default. | — |
Common Types
Messages and enums shared across services: Common Types
Ports
| Port | Protocol | Status | Purpose |
|---|---|---|---|
| 7080 | gRPC (HTTP/2) | Active | Native gRPC API, inter-node communication |
| 7081 | HTTP/1.1 + JSON | Active | REST/JSON transcoding via structured-proxy |
| 7082 | Bolt | Planned | Neo4j wire protocol compatibility |
| 7083 | WebSocket | Planned | Subscriptions, live queries |
| 7084 | HTTP | Active | Prometheus /metrics, /health, /ready |