Nexus RPC Server API Documentation¶

Complete reference for all Nexus RPC server APIs (v0.5.1+)

Table of Contents¶

1. Overview
2. Special Data Types ⚠️ Important for bytes/binary data
3. Authentication
4. Endpoints
5. Error Codes
6. Core File Operations
7. Directory Operations
8. Search Operations
9. Workspace Management
10. Mount Management
11. Memory API
12. Agent Management
13. Sandbox Management
14. Admin API Management
15. ReBAC Permissions
16. Versioning Operations
17. Namespace Management
18. OAuth Management
19. Complete Method Reference

Overview¶

Nexus provides an HTTP-based RPC server exposing all filesystem operations via JSON-RPC 2.0 protocol.

Base URL: http://localhost:8765 (default) Protocol: JSON-RPC 2.0 Transport: HTTP POST Content-Type: application/json

Request Format¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Response Format (Success)¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Response Format (Error)¶

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": { ... }
  }
}

Special Data Types¶

The Nexus RPC protocol uses special encoding for certain data types that cannot be directly represented in JSON:

Strings (Text)¶

Regular text data uses standard JSON strings - no special encoding needed:

{
  "name": "This is a regular text string",
  "description": "Just use normal JSON strings"
}

Bytes (Binary Data)¶

Binary data (file content, images, etc.) must be base64-encoded using the following special format:

{
  "__type__": "bytes",
  "data": "<base64-encoded-string>"
}

Example:

# Python: Encode "Hello, World!" as bytes
import base64
content = base64.b64encode(b"Hello, World!").decode('utf-8')
# Result: "SGVsbG8sIFdvcmxkIQ=="

# JSON-RPC parameter:
{
  "content": {
    "__type__": "bytes",
    "data": "SGVsbG8sIFdvcmxkIQ=="
  }
}

⚠️ Common Error:

Passing base64 string directly will fail with error: "Strings must be encoded before hashing"

❌ Wrong:

{
  "content": "SGVsbG8sIFdvcmxkIQ=="
}

✅ Correct:

{
  "content": {
    "__type__": "bytes",
    "data": "SGVsbG8sIFdvcmxkIQ=="
  }
}

DateTime¶

Datetime values are encoded in ISO 8601 format (usually in responses):

{
  "__type__": "datetime",
  "data": "2025-01-15T10:35:00+00:00"
}

TimeDelta¶

Time duration values are encoded as total seconds (v0.5.0+):

{
  "__type__": "timedelta",
  "seconds": 3600
}

Note: When using the official Python client (RemoteNexusFS), these conversions are handled automatically. Manual API calls (curl, Postman, etc.) must use the formats above.

Authentication¶

API Key Authentication¶

Include API key in Authorization header:

Authorization: Bearer YOUR_API_KEY

Identity Headers (Optional)¶

For permission checks and multi-tenancy:

• X-Nexus-Subject: Subject identity (e.g., user:alice, agent:bot123)
• X-Nexus-Tenant-ID: Tenant identifier

Example Request¶

curl -H "Authorization: Bearer secret-key" \
     -H "Content-Type: application/json" \
     -H "X-Nexus-Subject: user:alice" \
     -X POST http://localhost:8765/api/nfs/read \
     -d '{"id":1,"method":"read","params":{"path":"/file.txt"}}'

Endpoints¶

Health Check¶

GET /health

Response:

{
  "status": "healthy",
  "service": "nexus-rpc"
}

Who Am I¶

GET /api/auth/whoami

Returns authenticated user context.

Response:

{
  "authenticated": true,
  "subject_type": "user",
  "subject_id": "alice",
  "tenant_id": "tenant-123",
  "is_admin": false
}

Status¶

GET /api/nfs/status

Returns server status and available methods.

Response:

{
  "status": "running",
  "service": "nexus-rpc",
  "version": "0.5.0",
  "methods": ["read", "write", "list", "..."],
  "backend": {
    "type": "gcs",
    "bucket": "nexi-hub"
  },
  "metadata_store": {
    "type": "postgresql",
    "instance": "nexi-lab-888:us-west1:nexus-hub"
  }
}

RPC Method Endpoint Pattern¶

POST /api/nfs/{method_name}

All filesystem operations use this pattern.

Error Codes¶

Standard JSON-RPC Errors¶

Nexus-Specific Errors¶

Core File Operations¶

read¶

Read file content with optional metadata.

Endpoint: POST /api/nfs/read

Parameters: - path (string, required): File path - return_metadata (boolean, optional): Return metadata with content (default: false)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "read",
  "params": {
    "path": "/documents/file.txt",
    "return_metadata": true
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "base64_encoded_content",
    "encoding": "base64",
    "metadata": {
      "size": 1024,
      "etag": "abc123",
      "modified_at": "2025-01-15T10:30:00Z"
    }
  }
}

write¶

Write file content with optimistic concurrency control.

Endpoint: POST /api/nfs/write

Parameters: - path (string, required): File path - content (bytes, required): File content in special bytes format (see example below) - if_match (string, optional): ETag for optimistic concurrency - if_none_match (boolean, optional): Create-only mode (default: false) - force (boolean, optional): Skip version check (default: false)

IMPORTANT: The content parameter must use the special bytes encoding format:

{
  "__type__": "bytes",
  "data": "<base64-encoded-string>"
}

Example Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "write",
  "params": {
    "path": "/documents/file.txt",
    "content": {
      "__type__": "bytes",
      "data": "SGVsbG8sIFdvcmxkIQ=="
    },
    "if_none_match": false
  }
}

cURL Example:

curl -X POST http://localhost:2026/api/nfs/write \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "write",
    "params": {
      "path": "/workspace/hello.txt",
      "content": {
        "__type__": "bytes",
        "data": "SGVsbG8sIFdvcmxkIQ=="
      }
    }
  }'

Example Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "etag": "def456",
    "version": 2,
    "size": 1024,
    "modified_at": "2025-01-15T10:35:00Z"
  }
}

delete¶

Delete a file.

Endpoint: POST /api/nfs/delete

Parameters: - path (string, required): File path

Example Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "delete",
  "params": {
    "path": "/documents/old.txt"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "success": true
  }
}

rename¶

Rename or move a file.

Endpoint: POST /api/nfs/rename

Parameters: - old_path (string, required): Current file path - new_path (string, required): New file path

Example Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "rename",
  "params": {
    "old_path": "/documents/old-name.txt",
    "new_path": "/documents/new-name.txt"
  }
}

exists¶

Check if a file exists.

Endpoint: POST /api/nfs/exists

Parameters: - path (string, required): File path

Example Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "exists",
  "params": {
    "path": "/documents/file.txt"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": true
}

get_metadata¶

Get file metadata without content.

Endpoint: POST /api/nfs/get_metadata

Parameters: - path (string, required): File path

Example Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "path": "/documents/file.txt",
    "size": 1024,
    "etag": "abc123",
    "version": 3,
    "created_at": "2025-01-15T09:00:00Z",
    "modified_at": "2025-01-15T10:30:00Z",
    "content_type": "text/plain"
  }
}

Note: Returns null if workspace not found.

Directory Operations¶

mkdir¶

Create a directory.

Endpoint: POST /api/nfs/mkdir

Parameters: - path (string, required): Directory path - parents (boolean, optional): Create parent directories (default: false) - exist_ok (boolean, optional): Don't error if exists (default: false)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "mkdir",
  "params": {
    "path": "/projects/new-project",
    "parents": true,
    "exist_ok": false
  }
}

rmdir¶

Remove a directory.

Endpoint: POST /api/nfs/rmdir

Parameters: - path (string, required): Directory path - recursive (boolean, optional): Remove recursively (default: false)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "rmdir",
  "params": {
    "path": "/projects/old-project",
    "recursive": true
  }
}

list¶

List directory contents.

Endpoint: POST /api/nfs/list

Parameters: - path (string, optional): Directory path (default: "/") - recursive (boolean, optional): List recursively (default: true) - details (boolean, optional): Include file details (default: false) - prefix (string, optional): Filter by prefix - show_parsed (boolean, optional): Show parsed views (default: true)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "list",
  "params": {
    "path": "/documents",
    "recursive": false,
    "details": true
  }
}

Example Response (details=false):

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": [
    "/documents/file1.txt",
    "/documents/file2.txt",
    "/documents/subdir/"
  ]
}

Example Response (details=true):

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": [
    {
      "path": "/documents/file1.txt",
      "size": 1024,
      "etag": "abc123",
      "modified_at": "2025-01-15T10:00:00Z",
      "is_directory": false
    },
    {
      "path": "/documents/subdir/",
      "is_directory": true
    }
  ]
}

is_directory¶

Check if path is a directory.

Endpoint: POST /api/nfs/is_directory

Parameters: - path (string, required): Path to check

Example Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": true
}

Search Operations¶

glob¶

Find files matching a glob pattern.

Endpoint: POST /api/nfs/glob

Parameters: - pattern (string, required): Glob pattern (e.g., **/*.txt) - path (string, optional): Search root path (default: "/")

Example Request:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "glob",
  "params": {
    "pattern": "**/*.py",
    "path": "/projects"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": [
    "/projects/app/main.py",
    "/projects/app/utils.py",
    "/projects/tests/test_main.py"
  ]
}

grep¶

Search file contents for a pattern.

Endpoint: POST /api/nfs/grep

Parameters: - pattern (string, required): Search pattern (regex) - path (string, optional): Search root path (default: "/") - file_pattern (string, optional): File pattern filter (glob) - ignore_case (boolean, optional): Case-insensitive search (default: false) - max_results (int, optional): Maximum results (default: 1000)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "grep",
  "params": {
    "pattern": "TODO",
    "path": "/projects",
    "file_pattern": "*.py",
    "ignore_case": false,
    "max_results": 100
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": [
    {
      "file": "/projects/app/main.py",
      "line": 42,
      "content": "# TODO: Implement error handling",
      "match": "TODO"
    },
    {
      "file": "/projects/app/utils.py",
      "line": 15,
      "content": "# TODO: Add validation",
      "match": "TODO"
    }
  ]
}

Workspace Management¶

Workspaces must be registered before creating snapshots.

register_workspace¶

Register a directory as a workspace.

Endpoint: POST /api/nfs/register_workspace

Parameters: - path (string, required): Workspace path - name (string, optional): Workspace name - description (string, optional): Description - created_by (string, optional): Creator identity - tags (array[string], optional): Tags - metadata (object, optional): Custom metadata - session_id (string, optional): Session identifier (v0.5.0) - ttl (number, optional): Time-to-live in seconds (v0.5.0)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "register_workspace",
  "params": {
    "path": "/my-workspace",
    "name": "main",
    "description": "Main development workspace",
    "created_by": "user:alice",
    "tags": ["development", "active"],
    "metadata": {
      "project_id": "12345",
      "team": "engineering"
    },
    "session_id": "session-abc",
    "ttl": 86400
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "path": "/my-workspace",
    "name": "main",
    "description": "Main development workspace",
    "created_by": "user:alice",
    "created_at": "2025-01-15T10:00:00Z",
    "tags": ["development", "active"],
    "metadata": {
      "project_id": "12345",
      "team": "engineering"
    }
  }
}

unregister_workspace¶

Unregister a workspace (does not delete files).

Endpoint: POST /api/nfs/unregister_workspace

Parameters: - path (string, required): Workspace path

Example Response:

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": true
}

list_workspaces¶

List all registered workspaces.

Endpoint: POST /api/nfs/list_workspaces

Parameters: None

Example Response:

{
  "jsonrpc": "2.0",
  "id": 15,
  "result": [
    {
      "path": "/my-workspace",
      "name": "main",
      "description": "Main workspace",
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "path": "/team/project",
      "name": "team-project",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ]
}

get_workspace_info¶

Get workspace information.

Endpoint: POST /api/nfs/get_workspace_info

Parameters: - path (string, required): Workspace path

Example Response:

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "path": "/my-workspace",
    "name": "main",
    "description": "Main workspace",
    "created_by": "user:alice",
    "created_at": "2025-01-15T10:00:00Z",
    "metadata": {
      "project_id": "12345"
    }
  }
}

Returns null if workspace not found.

workspace_snapshot¶

Create a workspace snapshot.

Endpoint: POST /api/nfs/workspace_snapshot

Parameters: - workspace_path (string, optional): Workspace path - agent_id (string, optional): Agent ID (DEPRECATED) - description (string, optional): Snapshot description - tags (array[string], optional): Tags - created_by (string, optional): Creator identity

Example Request:

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "workspace_snapshot",
  "params": {
    "workspace_path": "/my-workspace",
    "description": "Before refactoring",
    "tags": ["pre-refactor"],
    "created_by": "user:alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 17,
  "result": {
    "snapshot_number": 1,
    "timestamp": "2025-01-15T12:00:00Z",
    "description": "Before refactoring",
    "file_count": 42,
    "total_size": 1048576,
    "tags": ["pre-refactor"]
  }
}

workspace_restore¶

Restore a workspace from a snapshot.

Endpoint: POST /api/nfs/workspace_restore

Parameters: - snapshot_number (int, required): Snapshot number to restore - workspace_path (string, optional): Workspace path - agent_id (string, optional): Agent ID (DEPRECATED)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 18,
  "method": "workspace_restore",
  "params": {
    "snapshot_number": 1,
    "workspace_path": "/my-workspace"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 18,
  "result": {
    "restored": true,
    "files_restored": 42,
    "snapshot_number": 1,
    "timestamp": "2025-01-15T12:00:00Z"
  }
}

workspace_log¶

List workspace snapshots.

Endpoint: POST /api/nfs/workspace_log

Parameters: - workspace_path (string, optional): Workspace path - agent_id (string, optional): Agent ID (DEPRECATED) - limit (int, optional): Maximum snapshots to return (default: 100)

Example Response:

{
  "jsonrpc": "2.0",
  "id": 19,
  "result": [
    {
      "snapshot_number": 2,
      "timestamp": "2025-01-15T14:00:00Z",
      "description": "After refactoring",
      "file_count": 45,
      "tags": ["post-refactor"]
    },
    {
      "snapshot_number": 1,
      "timestamp": "2025-01-15T12:00:00Z",
      "description": "Before refactoring",
      "file_count": 42,
      "tags": ["pre-refactor"]
    }
  ]
}

workspace_diff¶

Compare two workspace snapshots.

Endpoint: POST /api/nfs/workspace_diff

Parameters: - snapshot_1 (int, required): First snapshot number - snapshot_2 (int, required): Second snapshot number - workspace_path (string, optional): Workspace path - agent_id (string, optional): Agent ID (DEPRECATED)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "workspace_diff",
  "params": {
    "snapshot_1": 1,
    "snapshot_2": 2,
    "workspace_path": "/my-workspace"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 20,
  "result": {
    "added": [
      "/my-workspace/new-file.txt",
      "/my-workspace/utils/helper.py"
    ],
    "modified": [
      "/my-workspace/config.json",
      "/my-workspace/main.py"
    ],
    "deleted": [
      "/my-workspace/old-file.txt"
    ],
    "summary": {
      "added_count": 2,
      "modified_count": 2,
      "deleted_count": 1
    }
  }
}

Mount Management¶

Backend mount management for attaching multiple storage backends to different paths (v0.5.0+).

Nexus supports dynamic mount management, allowing you to add/remove storage backends at runtime. This is useful for: - User-specific storage (personal Google Drive, GCS buckets) - Multi-tenant scenarios with isolated storage per tenant - Temporary mounts for specific tasks - Mounting external buckets or shared storage

Supported Backend Types¶

• local - Local filesystem backend
• gcs - Google Cloud Storage (content-addressable, CAS-based)
• gcs_connector - GCS Connector (direct path mapping for external buckets)
• google_drive - Google Drive backend (requires authentication)

add_mount¶

Add a dynamic backend mount at runtime.

Endpoint: POST /api/nfs/add_mount

Parameters: - mount_point (string, required): Virtual path where backend is mounted (e.g., "/personal/alice") - backend_type (string, required): Backend type - "local", "gcs", "gcs_connector", "google_drive" - backend_config (object, required): Backend-specific configuration - priority (int, optional): Mount priority - higher values take precedence (default: 0) - readonly (bool, optional): Whether mount is read-only (default: false)

Backend Configuration Examples:

Local Backend:

{
  "data_dir": "/path/to/local/directory"
}

GCS Backend (CAS-based):

{
  "bucket": "bucket-name",
  "project_id": "my-project",
  "credentials_path": "/path/to/credentials.json"  // optional
}

GCS Connector Backend (Direct path mapping):

{
  "bucket": "external-bucket",
  "project_id": "my-project",
  "prefix": "workspace",  // optional prefix in bucket
  "credentials_path": "/path/to/credentials.json"  // optional
}

Example Request (Add GCS mount):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "add_mount",
  "params": {
    "mount_point": "/personal/alice",
    "backend_type": "gcs",
    "backend_config": {
      "bucket": "alice-personal-bucket",
      "project_id": "my-project"
    },
    "priority": 10
  }
}

Example Request (Add GCS Connector mount):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "add_mount",
  "params": {
    "mount_point": "/workspace/shared",
    "backend_type": "gcs_connector",
    "backend_config": {
      "bucket": "external-shared-bucket",
      "project_id": "my-project",
      "prefix": "team-workspace"
    },
    "priority": 5
  }
}

Example Request (Add local mount):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "add_mount",
  "params": {
    "mount_point": "/shared/team",
    "backend_type": "local",
    "backend_config": {
      "data_dir": "/mnt/shared/team-data"
    },
    "priority": 5,
    "readonly": true
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "/personal/alice"
}

cURL Example:

curl -X POST http://localhost:2026/api/nfs/add_mount \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "add_mount",
    "params": {
      "mount_point": "/workspace/gcs",
      "backend_type": "gcs_connector",
      "backend_config": {
        "bucket": "my-external-bucket",
        "project_id": "my-project"
      },
      "priority": 10
    }
  }'

remove_mount¶

Remove a backend mount from the filesystem.

Endpoint: POST /api/nfs/remove_mount

Parameters: - mount_point (string, required): Virtual path of mount to remove

Example Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "remove_mount",
  "params": {
    "mount_point": "/personal/alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": true
}

list_mounts¶

List all active backend mounts.

Endpoint: POST /api/nfs/list_mounts

Parameters: None

Example Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "list_mounts",
  "params": {}
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": [
    {
      "mount_point": "/personal/alice",
      "priority": 10,
      "readonly": false,
      "backend_type": "GCSBackend"
    },
    {
      "mount_point": "/workspace/shared",
      "priority": 5,
      "readonly": false,
      "backend_type": "GCSConnectorBackend"
    },
    {
      "mount_point": "/shared/team",
      "priority": 5,
      "readonly": true,
      "backend_type": "LocalBackend"
    }
  ]
}

get_mount¶

Get details about a specific mount.

Endpoint: POST /api/nfs/get_mount

Parameters: - mount_point (string, required): Virtual path of mount

Example Request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "get_mount",
  "params": {
    "mount_point": "/personal/alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "mount_point": "/personal/alice",
    "priority": 10,
    "readonly": false,
    "backend_type": "GCSBackend"
  }
}

Response (not found):

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": null
}

has_mount¶

Check if a mount exists at the given path.

Endpoint: POST /api/nfs/has_mount

Parameters: - mount_point (string, required): Virtual path to check

Example Request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "has_mount",
  "params": {
    "mount_point": "/personal/alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": true
}

save_mount¶

Save a mount configuration to the database for persistence.

Endpoint: POST /api/nfs/save_mount

Parameters: - mount_point (string, required): Virtual path where backend is mounted - backend_type (string, required): Backend type - "local", "gcs", "gcs_connector", etc. - backend_config (object, required): Backend-specific configuration - priority (int, optional): Mount priority (default: 0) - readonly (bool, optional): Whether mount is read-only (default: false) - owner_user_id (string, optional): User who owns this mount - tenant_id (string, optional): Tenant ID for multi-tenant isolation - description (string, optional): Human-readable description

Example Request:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "save_mount",
  "params": {
    "mount_point": "/personal/alice",
    "backend_type": "google_drive",
    "backend_config": {
      "access_token": "ya29.xxx",
      "refresh_token": "1//xxx"
    },
    "owner_user_id": "google:alice123",
    "tenant_id": "acme",
    "description": "Alice's personal Google Drive",
    "priority": 10
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": "4594a9be-7a75-44c6-b96d-605c399ce8f7"
}

Note: The result is the mount ID (UUID string). This only saves the configuration - use load_mount to activate it.

list_saved_mounts¶

List mount configurations saved in the database.

Endpoint: POST /api/nfs/list_saved_mounts

Parameters: - owner_user_id (string, optional): Filter by owner user ID - tenant_id (string, optional): Filter by tenant ID

Example Request:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "list_saved_mounts",
  "params": {
    "owner_user_id": "google:alice123"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": [
    {
      "mount_id": "4594a9be-7a75-44c6-b96d-605c399ce8f7",
      "mount_point": "/personal/alice",
      "backend_type": "google_drive",
      "backend_config": {
        "access_token": "ya29.xxx",
        "refresh_token": "1//xxx"
      },
      "priority": 10,
      "readonly": false,
      "owner_user_id": "google:alice123",
      "tenant_id": "acme",
      "description": "Alice's personal Google Drive",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

load_mount¶

Load a saved mount configuration and activate it.

Endpoint: POST /api/nfs/load_mount

Parameters: - mount_point (string, required): Virtual path of saved mount to load

Example Request:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "load_mount",
  "params": {
    "mount_point": "/personal/alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": "/personal/alice"
}

Error Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "error": {
    "code": -32000,
    "message": "Mount not found in database: /personal/alice"
  }
}

delete_saved_mount¶

Delete a saved mount configuration from the database.

Endpoint: POST /api/nfs/delete_saved_mount

Parameters: - mount_point (string, required): Virtual path of mount to delete

Example Request:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "delete_saved_mount",
  "params": {
    "mount_point": "/personal/alice"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": true
}

Note: This only removes the saved configuration. Use remove_mount to deactivate an active mount.

Mount Workflow Example¶

Complete workflow for user-specific mounts:

# 1. Add a mount at runtime
mount_id = client.add_mount(
    mount_point="/personal/alice",
    backend_type="gcs",
    backend_config={
        "bucket": "alice-personal-bucket",
        "project_id": "my-project"
    },
    priority=10
)

# 2. Save the mount configuration for persistence
saved_id = client.save_mount(
    mount_point="/personal/alice",
    backend_type="gcs",
    backend_config={
        "bucket": "alice-personal-bucket",
        "project_id": "my-project"
    },
    owner_user_id="google:alice123",
    description="Alice's personal storage",
    priority=10
)

# 3. Use the mount (files are automatically routed)
client.write("/personal/alice/file.txt", b"Hello!")
content = client.read("/personal/alice/file.txt")

# 4. Later: Load saved mount after server restart
client.load_mount("/personal/alice")

# 5. Remove the active mount
client.remove_mount("/personal/alice")

# 6. Delete the saved configuration
client.delete_saved_mount("/personal/alice")

Memory API¶

Agent memory management for trajectories, reflections, and playbooks (v0.5.0).

register_memory¶

Register a directory as agent memory storage.

Endpoint: POST /api/nfs/register_memory

Parameters: - path (string, required): Memory path - name (string, optional): Memory name - description (string, optional): Description - created_by (string, optional): Creator identity - metadata (object, optional): Custom metadata - session_id (string, optional): Session identifier - ttl (number, optional): Time-to-live in seconds

unregister_memory¶

Unregister agent memory.

Endpoint: POST /api/nfs/unregister_memory

Parameters: - path (string, required): Memory path

list_memories¶

List registered memories.

Endpoint: POST /api/nfs/list_memories

Parameters: - limit (int, optional): Maximum memories (default: 50) - scope (string, optional): Filter by scope - memory_type (string, optional): Filter by type

get_memory_info¶

Get memory information.

Endpoint: POST /api/nfs/get_memory_info

Parameters: - path (string, required): Memory path

start_trajectory¶

Start tracking an execution trajectory.

Endpoint: POST /api/nfs/start_trajectory

Parameters: - task_description (string, required): Task description - task_type (string, optional): Task type/category

Example Request:

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "start_trajectory",
  "params": {
    "task_description": "Implement user authentication",
    "task_type": "feature-development"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 21,
  "result": {
    "trajectory_id": "traj-abc123",
    "started_at": "2025-01-15T10:00:00Z",
    "task_description": "Implement user authentication"
  }
}

log_trajectory_step¶

Log a step in an execution trajectory.

Endpoint: POST /api/nfs/log_trajectory_step

Parameters: - trajectory_id (string, required): Trajectory ID - step_type (string, required): Step type (e.g., "read", "write", "execute") - description (string, required): Step description - result (any, optional): Step result

Example Request:

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "log_trajectory_step",
  "params": {
    "trajectory_id": "traj-abc123",
    "step_type": "write",
    "description": "Created authentication module",
    "result": {
      "file": "/app/auth.py",
      "lines": 150
    }
  }
}

complete_trajectory¶

Mark a trajectory as complete.

Endpoint: POST /api/nfs/complete_trajectory

Parameters: - trajectory_id (string, required): Trajectory ID - status (string, required): Completion status (e.g., "success", "failure") - success_score (float, optional): Success score (0.0-1.0) - error_message (string, optional): Error message if failed

Example Request:

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "complete_trajectory",
  "params": {
    "trajectory_id": "traj-abc123",
    "status": "success",
    "success_score": 0.95
  }
}

query_trajectories¶

Query execution trajectories.

Endpoint: POST /api/nfs/query_trajectories

Parameters: - agent_id (string, optional): Filter by agent ID - status (string, optional): Filter by status - limit (int, optional): Maximum results (default: 50)

Example Response:

{
  "jsonrpc": "2.0",
  "id": 24,
  "result": [
    {
      "trajectory_id": "traj-abc123",
      "task_description": "Implement user authentication",
      "status": "success",
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T11:00:00Z",
      "success_score": 0.95
    }
  ]
}

store_memory¶

Store an agent memory.

Endpoint: POST /api/nfs/store_memory

Parameters: - content (string, required): Memory content - memory_type (string, optional): Memory type (default: "fact") - scope (string, optional): Memory scope (default: "agent") - importance (float, optional): Importance score (default: 0.5) - tags (array[string], optional): Tags

Example Request:

{
  "jsonrpc": "2.0",
  "id": 25,
  "method": "store_memory",
  "params": {
    "content": "User prefers Python over JavaScript",
    "memory_type": "preference",
    "scope": "user",
    "importance": 0.8,
    "tags": ["language", "preference"]
  }
}

query_memories¶

Query stored memories.

Endpoint: POST /api/nfs/query_memories

Parameters: - memory_type (string, optional): Filter by type - scope (string, optional): Filter by scope - limit (int, optional): Maximum results (default: 50)

Example Response:

{
  "jsonrpc": "2.0",
  "id": 26,
  "result": {
    "memories": [
      {
        "memory_id": "mem-123",
        "content": "User prefers Python over JavaScript",
        "memory_type": "preference",
        "scope": "user",
        "importance": 0.8,
        "created_at": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

batch_reflect¶

Batch reflection across multiple trajectories.

Endpoint: POST /api/nfs/batch_reflect

Parameters: - agent_id (string, optional): Filter by agent ID - since (string, optional): ISO timestamp to reflect since - min_trajectories (int, optional): Minimum trajectories (default: 10) - task_type (string, optional): Filter by task type

Example Request:

{
  "jsonrpc": "2.0",
  "id": 27,
  "method": "batch_reflect",
  "params": {
    "agent_id": "agent-alice",
    "since": "2025-01-15T00:00:00Z",
    "min_trajectories": 5,
    "task_type": "feature-development"
  }
}

get_playbook¶

Retrieve an agent playbook.

Endpoint: POST /api/nfs/get_playbook

Parameters: - playbook_name (string, optional): Playbook name (default: "default")

Example Response:

{
  "jsonrpc": "2.0",
  "id": 28,
  "result": {
    "playbook_name": "default",
    "patterns": [
      {
        "pattern": "authentication-implementation",
        "description": "Best practices for implementing authentication",
        "steps": ["..."]
      }
    ],
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

curate_playbook¶

Auto-curate playbook from reflections.

Endpoint: POST /api/nfs/curate_playbook

Parameters: - reflection_memory_ids (array[string], required): Reflection memory IDs - playbook_name (string, optional): Playbook name (default: "default") - merge_threshold (float, optional): Similarity threshold (default: 0.7)

query_playbooks¶

Query playbooks.

Endpoint: POST /api/nfs/query_playbooks

Parameters: - agent_id (string, optional): Filter by agent ID - scope (string, optional): Filter by scope - limit (int, optional): Maximum results (default: 50)

process_relearning¶

Process re-learning queue.

Endpoint: POST /api/nfs/process_relearning

Parameters: - limit (int, optional): Maximum items to process (default: 10)

Agent Management¶

register_agent¶

Register a new agent.

Endpoint: POST /api/nfs/register_agent

Parameters: - agent_id (string, required): Agent identifier - name (string, required): Agent name - description (string, optional): Description - generate_api_key (boolean, optional): Generate API key (default: false)

Example Request:

{
  "jsonrpc": "2.0",
  "id": 29,
  "method": "register_agent",
  "params": {
    "agent_id": "agent-alice",
    "name": "Alice Assistant",
    "description": "Personal coding assistant",
    "generate_api_key": true
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 29,
  "result": {
    "agent_id": "agent-alice",
    "name": "Alice Assistant",
    "description": "Personal coding assistant",
    "api_key": "key-abc123",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

list_agents¶

List all registered agents.

Endpoint: POST /api/nfs/list_agents

Parameters: None

Example Response:

{
  "jsonrpc": "2.0",
  "id": 30,
  "result": [
    {
      "agent_id": "agent-alice",
      "name": "Alice Assistant",
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "agent_id": "agent-bob",
      "name": "Bob Bot",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ]
}

get_agent¶

Get agent information.

Endpoint: POST /api/nfs/get_agent

Parameters: - agent_id (string, required): Agent identifier

Example Response:

{
  "jsonrpc": "2.0",
  "id": 31,
  "result": {
    "agent_id": "agent-alice",
    "name": "Alice Assistant",
    "description": "Personal coding assistant",
    "created_at": "2025-01-15T10:00:00Z",
    "metadata": {
      "version": "1.0"
    }
  }
}

delete_agent¶

Delete an agent.

Endpoint: POST /api/nfs/delete_agent

Parameters: - agent_id (string, required): Agent identifier

Sandbox Management¶

Code execution sandbox management for running code in isolated environments (v0.5.0+).

sandbox_create¶

Create a new code execution sandbox.

Endpoint: POST /api/nfs/sandbox_create

Parameters: - name (string, required): User-friendly sandbox name (unique per user) - ttl_minutes (int, optional): Idle timeout in minutes (default: 10) - provider (string, optional): Sandbox provider ("e2b", "docker", etc.) (default: "e2b") - template_id (string, optional): Provider template ID - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sandbox_create",
  "params": {
    "name": "data-analysis",
    "ttl_minutes": 30,
    "provider": "e2b",
    "template_id": "python-base"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sandbox_id": "sbx-abc123",
    "name": "data-analysis",
    "status": "running",
    "provider": "e2b",
    "created_at": "2025-01-15T10:00:00Z",
    "expires_at": "2025-01-15T10:30:00Z"
  }
}

sandbox_run¶

Run code in a sandbox.

Endpoint: POST /api/nfs/sandbox_run

Parameters: - sandbox_id (string, required): Sandbox ID - language (string, required): Programming language ("python", "javascript", "bash") - code (string, required): Code to execute - timeout (int, optional): Execution timeout in seconds (default: 30) - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "sandbox_run",
  "params": {
    "sandbox_id": "sbx-abc123",
    "language": "python",
    "code": "print('Hello from sandbox!')\nresult = 2 + 2\nprint(f'Result: {result}')",
    "timeout": 30
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "stdout": "Hello from sandbox!\nResult: 4\n",
    "stderr": "",
    "exit_code": 0,
    "execution_time": 0.123
  }
}

sandbox_pause¶

Pause a sandbox to save costs.

Endpoint: POST /api/nfs/sandbox_pause

Parameters: - sandbox_id (string, required): Sandbox ID - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "sandbox_pause",
  "params": {
    "sandbox_id": "sbx-abc123"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "sandbox_id": "sbx-abc123",
    "status": "paused",
    "paused_at": "2025-01-15T10:15:00Z"
  }
}

sandbox_resume¶

Resume a paused sandbox.

Endpoint: POST /api/nfs/sandbox_resume

Parameters: - sandbox_id (string, required): Sandbox ID - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "sandbox_resume",
  "params": {
    "sandbox_id": "sbx-abc123"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "sandbox_id": "sbx-abc123",
    "status": "running",
    "resumed_at": "2025-01-15T10:20:00Z"
  }
}

sandbox_stop¶

Stop and destroy a sandbox.

Endpoint: POST /api/nfs/sandbox_stop

Parameters: - sandbox_id (string, required): Sandbox ID - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "sandbox_stop",
  "params": {
    "sandbox_id": "sbx-abc123"
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "sandbox_id": "sbx-abc123",
    "status": "stopped",
    "stopped_at": "2025-01-15T10:25:00Z"
  }
}

sandbox_list¶

List user's sandboxes.

Endpoint: POST /api/nfs/sandbox_list

Parameters: - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "sandbox_list",
  "params": {}
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "sandboxes": [
      {
        "sandbox_id": "sbx-abc123",
        "name": "data-analysis",
        "status": "running",
        "provider": "e2b",
        "created_at": "2025-01-15T10:00:00Z"
      },
      {
        "sandbox_id": "sbx-def456",
        "name": "test-env",
        "status": "paused",
        "provider": "docker",
        "created_at": "2025-01-15T09:00:00Z"
      }
    ]
  }
}

sandbox_status¶

Get sandbox status and metadata.

Endpoint: POST /api/nfs/sandbox_status

Parameters: - sandbox_id (string, required): Sandbox ID - context (dict, optional): Operation context

Example Request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "sandbox_status",
  "params": {
    "sandbox_id": "sbx-abc123"
  }
}