API Reference

Complete API reference for the Ensue memory network.

Public URLs

Service URL
MCP https://api.ensue-network.ai/
Streaming https://events.ensue-network.ai/mcp

Authentication

All API requests require authentication via Bearer token in the Authorization header.

Get Your API Key

  1. Sign in to the Ensue Dashboard
  2. Click Create New Key
  3. Copy the key and store it securely—it won't be shown again

Set Your Environment Variable 

export ENSUE_API_KEY="your-api-key-here"

Request Headers

All requests must include:

Header Value
Authorization Bearer $ENSUE_API_KEY
Content-Type application/json

Base URL 

https://api.ensue-network.ai/

Example Request 

curl -X POST https://api.ensue-network.ai/ \
  -H "Authorization: Bearer $ENSUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_keys",
      "arguments": {"limit": 10}
    },
    "id": 1
  }'

Memory Operations

Core operations for creating, reading, updating, and deleting memories.

create_memory

Create one or more memory entries with unique keys. Supports batch operations (1-100 items). Memories can store any type of data and optionally be embedded for semantic search.

Parameters:

Field Type Required Description
items array Yes List of memories to create (1-100 items)

Item fields:

Field Type Required Description
key_name string Yes The unique key name for this memory
description string Yes Description of what this memory contains (used for search)
value string Yes The actual data to store
embed boolean No Generate vector embeddings for semantic search (default: false)
embed_source string No Field to use for embedding: description or value (default: description)
base64 boolean No Whether value is base64 encoded (default: false)

Example:

ensue create_memory --items '[{
  "key_name": "preferences/coding-style",
  "description": "User prefers early returns over nested conditionals",
  "value": "When writing functions, use early returns to handle edge cases first.",
  "embed": true
}]'

Batch Example:

ensue create_memory --items '[
  {"key_name": "project/api/auth", "description": "Auth decision", "value": "Using JWT", "embed": true},
  {"key_name": "project/api/database", "description": "DB choice", "value": "PostgreSQL", "embed": true}
]'

get_memory

Retrieve one or more memories by key names. Supports batch operations (1-100 keys). Returns description, value, size, and timestamps for each key.

Parameters:

Field Type Required Description
key_names string[] Yes List of key names to retrieve (1-100 keys)

Example:

ensue get_memory --key-names '["preferences/coding-style"]'

Batch Example:

ensue get_memory --key-names '["project/api/auth", "project/api/database", "project/api/caching"]'

update_memory

Update the value of an existing memory. Only the value is updated; the description remains unchanged.

Parameters:

Field Type Required Description
key_name string Yes The key name of the memory to update
value string Yes The new value
embed boolean No Regenerate vector embeddings (default: false)
embed_source string No Field to use for embedding: description or value
base64 boolean No Whether value is base64 encoded (default: false)

Example:

ensue update_memory --key-name "preferences/coding-style" --value "Use early returns and guard clauses. Maximum function length: 20 lines." --embed true

delete_memory

Delete one or more memories by key names. Supports batch operations (1-100 keys). Permanently removes memories and their vector embeddings.

Parameters:

Field Type Required Description
key_names string[] Yes List of key names to delete (1-100 keys)

Example:

ensue delete_memory --key-names '["outdated/old-preference"]'

Search & Discovery

Find memories using semantic similarity or browse by key.

search_memories

Search for memories using semantic similarity. Returns results ranked by relevance score with full memory content.

Parameters:

Field Type Required Description
query string Yes Natural language query
limit integer No Maximum results (default: 10, max: 100)
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp
prefix string No Namespace prefix to scope the search. Supports @org/prefix/ for cross-org.

Example:

ensue search_memories --query "authentication decisions" --limit 5

With Time Filter:

ensue search_memories --query "recent bugs" --within-days 7 --limit 10

Cross-Org Search:

ensue search_memories --query "design tokens" --prefix "@bravo/shared/"

discover_memories

Discover memory keys using semantic similarity without retrieving values. Returns key names, relevance scores, and metadata. Use this for exploration, then use get_memory to retrieve specific values.

Parameters:

Field Type Required Description
query string Yes Natural language query
limit integer No Maximum results (default: 10, max: 100)
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp
prefix string No Namespace prefix to scope the search. Supports @org/prefix/ for cross-org.

Example:

ensue discover_memories --query "what do I know about caching" --limit 5

list_keys

List memory keys with their metadata (description, size, timestamps). Supports pagination and prefix filtering.

Parameters:

Field Type Required Description
limit integer No Maximum keys to return (default: 100)
offset integer No Offset for pagination (default: 0)
prefix string No Filter by prefix (supports SQL LIKE wildcards: % for any sequence, _ for single char)

Example:

ensue list_keys --limit 20

With Prefix Filter:

ensue list_keys --prefix "projects/web/" --limit 50

list_recent_keys

List the most recently created or updated memory keys, sorted by timestamp (newest first).

Parameters:

Field Type Required Description
limit integer No Maximum keys to return (default: 10, max: 100)
sort_by string No Sort by created or updated
prefix string No Namespace prefix to scope the listing. Supports @org/prefix/ for cross-org.

Example:

ensue list_recent_keys --limit 10 --sort-by updated

Hypergraph

Build semantic relationship graphs from your memories.

build_hypergraph

Build a semantic hypergraph from memories matching a search query. The hypergraph identifies semantic clusters and relationships among memories. Returns immediately with a job ID—check the output_key for results.

Parameters:

Field Type Required Description
query string Yes Natural language query to find related memories
limit integer Yes Maximum memories to include (max: 50)
output_key string Yes Key where the hypergraph result will be written
model string No Model for inference: llama-3.3-70b-versatile, llama-3.1-8b-instant, mixtral-8x7b-32768, qwen-3-32b
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue build_hypergraph --query "coding mistakes and lessons learned" --limit 30 --output-key "analysis/coding-patterns"

build_namespace_hypergraph

Build a semantic hypergraph from memories within a specific namespace. Only keys starting with the namespace prefix are included.

Parameters:

Field Type Required Description
namespace_path string Yes Namespace prefix (e.g., projects/web/)
query string Yes Query for computing semantic similarity weights
output_key string Yes Key where the hypergraph result will be written
limit integer No Maximum keys to include (default: 50, max: 100)
model string No Model for inference
within_days integer No Filter to memories updated within last N days
created_after integer No Filter by Unix timestamp
created_before integer No Filter by Unix timestamp
updated_after integer No Filter by Unix timestamp
updated_before integer No Filter by Unix timestamp

Example:

ensue build_namespace_hypergraph --namespace-path "sessions/" --query "patterns and recurring issues" --output-key "analysis/session-insights" --within-days 14

Subscriptions

Subscribe to memory changes and receive notifications.

subscribe_to_memory

Subscribe to notifications for changes to a memory key. Receive notifications when the memory is created, updated, or deleted. Subscription duration is limited by your organization's tier (free tier: 3 hours).

Parameters:

Field Type Required Description
key_name string Yes The key name to subscribe to

Example:

ensue subscribe_to_memory --key-name "shared/config"

unsubscribe_from_memory

Unsubscribe from notifications for a memory key.

Parameters:

Field Type Required Description
key_name string Yes The key name to unsubscribe from

Example:

ensue unsubscribe_from_memory --key-name "shared/config"

list_subscriptions

List all active memory subscriptions for the current user. Shows which memory keys you are subscribed to and when each subscription expires.

Parameters: None required.

Example:

ensue list_subscriptions

Sharing & Permissions

Manage access control for memories across users, groups, and organizations.

Access Control Scopes

Ensue supports five grantable permission actions, plus an org-owner permission:

Action Description
read View memory content
create Create new memories in the namespace
update Modify existing memory values
delete Remove memories permanently
public_read Make matching keys discoverable without authentication

The sharing permission (manage users, groups, and permissions) is reserved for organization owners and cannot be granted via the share grant command.

Key Patterns & Namespaces

Permissions are granted on key patterns—regex patterns that match memory keys. Use namespaces to organize and control access:

Pattern Matches Use Case
^public/.* All keys under public/ Org-wide readable content
^alice/.* All keys under alice/ User's private namespace
^projects/web/.* All keys under projects/web/ Project-specific access
^shared/config$ Exact key shared/config Single key access
^team-a/.* All keys under team-a/ Team namespace

Namespace convention: Use forward slashes to create hierarchical namespaces. Grant permissions at the appropriate level:

users/alice/           → Alice's personal memories
projects/acme/         → Acme project team access
org/announcements/     → Organization-wide updates
shared/configs/        → Shared configuration

list_permissions

List all permissions that apply to the current user. Returns permission grants at the organization, group, and user level. Optionally specify an org name to list your proxy user's permissions in a cross-org context.

Parameters:

Field Type Required Description
org_name string No Org name to list your proxy user's permissions in that org

Example:

ensue list_permissions

Cross-Org Permissions:

ensue list_permissions --org-name "bravo"

share

Manage users, groups, and permissions for sharing memory keys. Requires sharing permission.

User Management Commands:

Command Description Example
create_user Create a new user {"command": "create_user", "username": "alice"}
delete_user Delete a user {"command": "delete_user", "username": "alice"}

Group Management Commands:

Command Description Example
create_group Create a new group {"command": "create_group", "group_name": "editors"}
delete_group Delete a group {"command": "delete_group", "group_name": "editors"}
add_member Add user to group {"command": "add_member", "group_name": "editors", "username": "alice"}
remove_member Remove user from group {"command": "remove_member", "group_name": "editors", "username": "alice"}

Permission Management Commands:

Command Description
grant Grant permission to org, user, or group
revoke Revoke a permission grant by ID
list List current permissions (supports org_name for cross-org listing)

External Group Commands:

Command Description Example
set_external_group Set which group external orgs auto-join {"command": "set_external_group", "group_name": "partners"}
get_external_group View current external group assignment {"command": "get_external_group"}
clear_external_group Remove external group auto-assignment {"command": "clear_external_group"}

Grant Targets:

Target Type Description Example
org Entire organization {"type": "org"}
user Specific user {"type": "user", "username": "alice"}
group User group {"type": "group", "group_name": "editors"}

Examples:

Grant read access to entire organization:

ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "read", "key_pattern": "public/"}'

Grant update access to a user:

ensue share --command '{"command": "grant", "target": {"type": "user", "username": "alice"}, "action": "update", "key_pattern": "alice/"}'

Grant delete access to a group:

ensue share --command '{"command": "grant", "target": {"type": "group", "group_name": "editors"}, "action": "delete", "key_pattern": "shared/"}'

Make a namespace publicly discoverable:

ensue share --command '{"command": "grant", "target": {"type": "org"}, "action": "public_read", "key_pattern": "public/"}'

Create a group and add members:

ensue share --command '{"command": "create_group", "group_name": "team-a"}'
ensue share --command '{"command": "add_member", "group_name": "team-a", "username": "alice"}'

Set external group auto-assignment:

ensue share --command '{"command": "set_external_group", "group_name": "partners"}'

View current external group:

ensue share --command '{"command": "get_external_group"}'

Clear external group:

ensue share --command '{"command": "clear_external_group"}'

Revoke a permission:

ensue share --command '{"command": "revoke", "grant_id": "uuid-of-grant"}'

List all permissions:

ensue share --command '{"command": "list"}'

Filter permissions by target type and action:

ensue share --command '{"command": "list", "target_type": "user", "action": "read"}'

List permissions in another organization (cross-org):

ensue share --command '{"command": "list", "org_name": "bravo"}'

Org & Invite Management

Standalone tools for managing cross-organization collaboration. These are not sub-commands of share—they are separate MCP tools.

For the full invite flow and dashboard walkthrough, see Invites & Cross-Org.

create_invite

Create an invite link that other organizations can use to request access to your org.

Parameters:

Field Type Required Description
auto_approve boolean No Auto-approve organizations that claim this invite (default: false)
max_uses integer No Maximum number of times this invite can be claimed (default: unlimited)
expires_at integer No Unix timestamp when this invite expires (default: never)

Example:

ensue create_invite --auto-approve true --max-uses 5

get_invite

Get the current invite link for your organization, if one exists.

Parameters: None required.

Example:

ensue get_invite

claim_invite

Claim an invite link from another organization to request access.

Parameters:

Field Type Required Description
token string Yes The invite token to claim

Example:

ensue claim_invite --token "abc123"

list_my_external_orgs

List organizations that you have joined or requested to join.

Parameters:

Field Type Required Description
limit integer No Maximum results (default: 100)
offset integer No Offset for pagination (default: 0)

Example:

ensue list_my_external_orgs

list_pending_invites

List pending membership requests from organizations that want to join yours.

Parameters:

Field Type Required Description
limit integer No Maximum results (default: 100)
offset integer No Offset for pagination (default: 0)

Example:

ensue list_pending_invites

approve_invite

Approve a pending membership request from another organization.

Parameters:

Field Type Required Description
member_org_name string Yes Name of the member organization to approve

Example:

ensue approve_invite --member-org-name "bravo"

reject_invite

Reject a pending membership request from another organization.

Parameters:

Field Type Required Description
member_org_name string Yes Name of the member organization to reject

Example:

ensue reject_invite --member-org-name "bravo"

list_org_members

List organizations that have joined yours (all statuses).

Parameters:

Field Type Required Description
limit integer No Maximum results (default: 100)
offset integer No Offset for pagination (default: 0)

Example:

ensue list_org_members

remove_member

Remove an approved member organization from yours.

Parameters:

Field Type Required Description
member_org_name string Yes Name of the member organization to remove

Example:

ensue remove_member --member-org-name "bravo"

leave_org

Leave a host organization that you previously joined.

Parameters:

Field Type Required Description
host_org_name string Yes Name of the host organization to leave

Example:

ensue leave_org --host-org-name "bravo"

Membership Statuses

Status Description
pending Request submitted, awaiting host org approval
approved Membership active, proxy user created, access granted
rejected Host org denied the request
removed Host org removed a previously approved member
cancelled Member org left the organization

Cross-Org Memory Access

Once an external organization is approved, they can access the host org's memories by prefixing key names with @host-org-name/. The request is routed through the proxy user in the host org and governed by its permissions.

Read memories from another organization:

ensue get_memory --key-names '["@bravo/shared/design-tokens"]'

Search across a host org's memories:

ensue search_memories --query "design system guidelines" --prefix "@bravo/"

The @org-name/ prefix works with get_memory, search_memories, discover_memories, list_keys, and list_recent_keys. Access is limited to keys the proxy user has been granted permissions for.

Public Access

Access publicly shared memories without authentication. The public MCP endpoint exposes a subset of tools that only work for keys with public_read grants.

Public MCP Endpoint

Service URL
Public MCP https://api.ensue-network.ai/public

No authentication required. Only keys with public_read grants are accessible.

public_get_memory

Retrieve a publicly accessible memory by path.

Parameters:

Field Type Required Description
path string Yes Public path in format @org-name/key-name (e.g. @acme/research/paper)

Example:

curl -X POST https://api.ensue-network.ai/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"public_get_memory","arguments":{"path":"@acme/research/paper"}},"id":1}'

public_list_keys

List publicly accessible memory keys. Supports pagination and path prefix filtering.

Parameters:

Field Type Required Description
path string No Path prefix to scope listing (e.g. @acme/ or @acme/research/). If omitted, lists public keys across all organizations.
limit integer No Maximum keys to return (default: 100)
offset integer No Offset for pagination (default: 0)

Example:

curl -X POST https://api.ensue-network.ai/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"public_list_keys","arguments":{"path":"@acme/","limit":10}},"id":1}'

public_discover_memories

Search for publicly accessible memories using semantic similarity.

Parameters:

Field Type Required Description
query string Yes Natural language query
path string No Path prefix to scope search (e.g. @acme/ or @acme/research/). If omitted, searches public memories across all organizations.
limit integer No Maximum results (default: 10, max: 100)

Example:

curl -X POST https://api.ensue-network.ai/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"public_discover_memories","arguments":{"query":"machine learning research","path":"@acme/"}},"id":1}'

public_subscribe_to_memory

Subscribe to a public memory key in another organization. Receive real-time notifications when the key changes.

Parameters:

Field Type Required Description
path string Yes Public path in format @org-name/key-name (e.g. @acme/research/paper)

Example:

curl -X POST https://api.ensue-network.ai/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"public_subscribe_to_memory","arguments":{"path":"@acme/research/paper"}},"id":1}'

public_unsubscribe_from_memory

Unsubscribe from a public memory key in another organization.

Parameters:

Field Type Required Description
path string Yes Public path in format @org-name/key-name (e.g. @acme/research/paper)

Example:

curl -X POST https://api.ensue-network.ai/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"public_unsubscribe_from_memory","arguments":{"path":"@acme/research/paper"}},"id":1}'