API Reference

Qinematos exposes three API interfaces: REST (port 8080), gRPC (port 9000), and MCP (port 8080/mcp).

REST API (Port 8080)

Health & Info

Topics

Create Topic

curl -X POST http://localhost:8080/api/v1/topics \
  -H "Content-Type: application/json" \
  -d '{
    "name": "finance.trades",
    "description": "Real-time trade data",
    "schemaType": "finance.market_data"
  }'

Publish to Topic

curl -X POST http://localhost:8080/api/v1/topics/finance.trades/publish \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"symbol": "AAPL", "price": 185.50, "volume": 1000000},
      {"symbol": "GOOG", "price": 142.30, "volume": 500000}
    ],
    "lineageId": "optional-trace-id"
  }'

Schemas & Statistics

Demo Endpoints

gRPC API (Port 9000)

The gRPC API provides streaming subscriptions for real-time context delivery.

ContextOrchestrator Service

Watch API Example

The Watch API is the primary method for receiving zero-copy context updates.

message WatchRequest {
  string agent_id = 1;
  repeated string topic_patterns = 2;  // e.g., ["finance.*", "market.**"]
  AgentCapabilities capabilities = 3;
  DeliveryOptions delivery_options = 4;
  int64 from_version = 5;  // Optional: replay from version
}

message SubscriptionUpdate {
  string update_id = 1;
  string topic = 2;
  int64 version = 3;
  int64 timestamp_nanos = 4;

  // Key field: IPC handle for zero-copy access
  IPCHandle ipc_handle = 5;

  // Fallback: inline Arrow payload (if IPC not available)
  bytes arrow_payload = 6;

  LineageMetadata lineage = 7;
}

IPCHandle Structure

The IPCHandle contains everything needed for zero-copy data access:

message IPCHandle {
  string handle_id = 1;
  string file_path = 2;      // e.g., "/dev/shm/qinematos/contexts/finance.trades/123.arrow"
  int64 offset = 3;          // Byte offset (after header)
  int64 length = 4;          // Payload length
  string checksum = 5;       // Integrity verification
}

Delivery Methods

enum DeliveryMethod {
  DELIVERY_METHOD_IPC = 0;          // Zero-copy, local only
  DELIVERY_METHOD_ARROW_FLIGHT = 1; // Remote, distributed
  DELIVERY_METHOD_INLINE = 2;       // Fallback, inline bytes
}

MCP API (Port 8080/mcp)

The Model Context Protocol interface allows any MCP-compliant AI agent to interact with Qinematos.

Initialization

Resources

Tools

Available MCP Tools

MCP Tool Call Example

curl -X POST http://localhost:8080/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "publish_context",
    "arguments": {
      "topic": "finance.trades",
      "data": [{"symbol": "AAPL", "price": 185.50}],
      "lineage_id": "trace-123"
    }
  }'

Python Client Example

Reading zero-copy context from a Python agent:

import pyarrow as pa

# Received IPCHandle from gRPC Watch stream
ipc_handle = {
    "file_path": "/dev/shm/qinematos/contexts/finance.trades/123.arrow",
    "offset": 32,  # Skip Qinematos header
    "length": 4096
}

# Memory-map the file (true zero-copy!)
source = pa.memory_map(ipc_handle["file_path"], 'r')
source.seek(ipc_handle["offset"])

# Read Arrow table directly from shared memory
reader = pa.ipc.open_stream(source)
table = reader.read_all()

# Data is now accessible without any copying
print(f"Read {table.num_rows} rows in zero-copy!")
print(table.to_pandas())

Error Codes