Skip to main content
The Python and JavaScript SDKs handle request construction and response parsing automatically. These endpoint details are for developers building their own client or calling the API directly.
All endpoints require authentication via X-API-Key header (or Authorization: Bearer <token>) and collection-level access.

​
Export Snapshot

Export a collection’s full graph state as a portable snapshot. 
POST /v1/device-memory/snapshot/export
FieldTypeRequiredDescription
collection_idstringYesUUID of the collection to export
Returns a SnapshotEnvelope containing entities, relationships, embeddings, FTS metadata, and a root_hash for optimistic concurrency. 
from nebula import Nebula

client = Nebula(api_key="YOUR_API_KEY")
snapshot = client.export_snapshot(collection_id="YOUR_COLLECTION_ID")

​
Import Snapshot

Import a SnapshotEnvelope into an ephemeral server-side collection. Useful for debugging or running server-side operations against a client-owned snapshot. 
POST /v1/device-memory/snapshot/import
FieldTypeRequiredDescription
snapshotSnapshotEnvelopeYesThe full snapshot to import
Returns { "ephemeral_collection_id": "<uuid>" }. 
ephemeral_id = client.import_snapshot(snapshot=snapshot)

​
Compute

Send new events for processing and receive a patch with the resulting changes. 
POST /v1/device-memory/compute

​
Request

The request body wraps a ComputeRequest:
FieldTypeRequiredDescription
request.collection_idstringYesUUID of the collection
request.eventsEvent[]YesNew content to process
request.contextSnapshotEnvelopeYesYour current snapshot
request.request_idstringNoIdempotency key (UUID)
request.base_generationintegerNoGeneration from your current snapshot
request.base_root_hashstringNoRoot hash from your current snapshot
request.context_selectionobjectNoHow context was selected (default: {"strategy": "full_snapshot"})
Event fields:
FieldTypeRequiredDescription
contentstringYesThe text content to process
source_typestringNo"document" or "conversation" (default: "document")
metadataobjectNoArbitrary metadata
timestampstringNoISO 8601 timestamp

​
Response

Returns a PatchEnvelope with full-value put/delete operations:
FieldTypeDescription
collection_idstringThe collection this patch applies to
previous_root_hashstringHash of the pre-state snapshot
next_root_hashstringExpected hash after applying the patch
put_entitiesEntityRecord[]Entities to upsert
delete_entitiesstring[]Entity IDs to remove
put_relationshipsRelationshipRecord[]Relationships to upsert
delete_relationshipsstring[]Relationship IDs to remove
eventsEvent[]Events that were processed
patch = client.compute({
    "collection_id": "YOUR_COLLECTION_ID",
    "context": snapshot,
    "events": [
        {"content": "Had a meeting with Alice about the Q2 roadmap"},
        {"content": "Bob mentioned the API deadline is March 20th"},
    ],
})
Verify the patch by checking that your post-patch root hash matches next_root_hash. If it doesn’t, re-export the snapshot to resync.

​
Query

Search your memory through Nebula’s traversal engine. Your snapshot is scored and results are returned. Nothing is persisted server-side. 
POST /v1/device-memory/query
FieldTypeRequiredDescription
snapshotSnapshotEnvelopeYesYour full snapshot
querystringYesNatural language search query
query_embeddingfloat[]NoPre-computed query embedding. If omitted, Nebula generates it.
limitintegerNoMaximum entities to return (default: 10)
Returns { "entities": [...], "relationships": [...] } with scored results. 
results = client.query_snapshot(
    snapshot=snapshot,
    query="What do I know about Alice?",
    limit=10,
)

for entity in results.get("entities", []):
    print(f"{entity['name']}: {entity['description']}")