API

Compass provides a Connect RPC API supporting both HTTP and gRPC protocols. API definitions are maintained in raystack/proton.

Endpoints

Entity

Method	Endpoint	Description
GET	`GetAllEntities`	List entities, filtered by types, source, or query
GET	`GetEntityByID`	Get entity by ID or URN
POST	`UpsertEntity`	Create or update an entity
DELETE	`DeleteEntity`	Delete by URN
GET	`SearchEntities`	Keyword, semantic, or hybrid search
GET	`SuggestEntities`	Autocomplete suggestions
GET	`GetEntityTypes`	List types with counts

Context & Impact

Method	Endpoint	Description
GET	`GetEntityContext`	Context subgraph with multi-hop traversal
GET	`GetEntityImpact`	Downstream blast radius

Edge

Method	Endpoint	Description
POST	`UpsertEdge`	Create or update an edge
GET	`GetEdges`	Get edges for an entity
DELETE	`DeleteEdge`	Delete an edge

Document

Method	Endpoint	Description
POST	`/v1/documents`	Create or update a document
GET	`/v1/documents`	List documents
GET	`/v1/documents/{id}`	Get document by ID
DELETE	`/v1/documents/{id}`	Delete a document
GET	`/v1/entities/{urn}/documents`	Get documents for an entity

Star

Method	Endpoint	Description
POST	`StarEntity`	Star an entity
DELETE	`UnstarEntity`	Unstar an entity
GET	`GetUserStarredEntities`	List user's starred entities
GET	`GetMyStarredEntities`	List current user's stars
GET	`GetMyStarredEntity`	Check if current user starred an entity
GET	`GetEntityStargazers`	List stargazers for an entity

Namespace

Method	Endpoint	Description
POST	`CreateNamespace`	Create a namespace
GET	`GetNamespace`	Get by ID or name
PATCH	`UpdateNamespace`	Update a namespace
GET	`ListNamespaces`	List all namespaces

Health

Method	Path	Description
GET	`/ping`	Returns "pong"

Authentication

Every request requires an identity header. The header key is configurable (default: Compass-User-UUID). An optional email header (Compass-User-Email) can also be provided.

Namespace isolation is controlled via the x-namespace header. If not provided, requests use the default namespace. Namespace can also be passed as a namespace_id claim in a JWT bearer token.

Protocol

Compass uses Connect RPC. You can call it using:

Connect protocol — HTTP POST with JSON or Protobuf
gRPC protocol — HTTP/2 with Protobuf
gRPC-Web — For browser clients

Example:

curl -X POST http://localhost:8080/raystack.compass.v1beta1.CompassService/SearchEntities \
  -H "Content-Type: application/json" \
  -H "Compass-User-UUID: user@example.com" \
  -d '{"text": "revenue", "mode": "hybrid"}'