Intelligence & Skills API

Endpoints for memory systems, skills marketplace, ClawHub, hands automation, extensions, plugins, and media generation.

Memory Endpoints

LibreFang provides two memory systems: a simple key-value store per agent and a proactive semantic memory system (mem0-style) with relationship graphs and decay.

GET /api/memory/agents/{id}/kv

List all key-value pairs for an agent.

Response 200 OK:

{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}

GET /api/memory/agents/{id}/kv/{key}

Get a specific key-value pair.

Response 200 OK:

{
  "key": "preferences",
  "value": {"theme": "dark"}
}

Response 404 Not Found (key does not exist):

{
  "error": "Key 'preferences' not found"
}

PUT /api/memory/agents/{id}/kv/{key}

Set a key-value pair. Creates or overwrites.

Request Body:

{
  "value": {"theme": "dark", "language": "en"}
}

Response 200 OK:

{
  "status": "stored",
  "key": "preferences"
}

DELETE /api/memory/agents/{id}/kv/{key}

Delete a key-value pair.

Response 200 OK:

{
  "status": "deleted",
  "key": "preferences"
}

GET /api/memory

List all proactive memory entries (global, across agents and users).

POST /api/memory

Add a new proactive memory entry.

Request Body:

{
  "content": "User prefers concise answers",
  "agent_id": "a1b2c3d4-...",
  "user_id": "user-1",
  "tags": ["preference"]
}

GET /api/memory/search

Search proactive memory using semantic similarity.

Query Parameters:

q (required): Search query string
agent_id (optional): Limit to a specific agent
limit (optional): Max results (default: 10)

GET /api/memory/stats

Get aggregate statistics for the proactive memory store.

POST /api/memory/cleanup

Remove expired or stale memory entries.

POST /api/memory/decay

Apply time-decay to memory entry scores (reduces relevance of old entries).

POST /api/memory/bulk-delete

Delete multiple memory entries by ID list.

PUT /api/memory/items/{memory_id}

Update a specific memory entry.

DELETE /api/memory/items/{memory_id}

Delete a specific memory entry.

GET /api/memory/items/{memory_id}/history

Get the edit history for a specific memory entry.

GET /api/memory/user/{user_id}

Get all memory entries associated with a user.

GET /api/memory/agents/{id}

List all proactive memory entries for a specific agent.

DELETE /api/memory/agents/{id}

Delete all proactive memory entries for a specific agent.

GET /api/memory/agents/{id}/search

Search proactive memory for a specific agent.

GET /api/memory/agents/{id}/stats

Get memory statistics for a specific agent.

DELETE /api/memory/agents/{id}/level/{level}

Clear all memory entries at a specific importance level for an agent.

GET /api/memory/agents/{id}/duplicates

Find duplicate memory entries for an agent.

POST /api/memory/agents/{id}/consolidate

Consolidate and deduplicate memory entries for an agent.

GET /api/memory/agents/{id}/count

Get the total memory entry count for an agent.

GET /api/memory/agents/{id}/relations

Query relationship graph entries for an agent.

POST /api/memory/agents/{id}/relations

Store new relationship graph entries for an agent.

GET /api/memory/agents/{id}/export

Export all proactive memory entries for an agent as JSON.

POST /api/memory/agents/{id}/import

Import proactive memory entries for an agent from JSON.

Skills & Marketplace Endpoints

Manage the skill registry. Skills extend agent capabilities with Python, Node.js, WASM, or prompt-only modules. All skill installations go through SHA256 verification and prompt injection scanning.

GET /api/skills

List all installed skills. Supports optional category filtering.

Query Parameters:

category (optional): Filter by skill category tag (e.g., devops, data)

Response 200 OK:

{
  "skills": [
    {
      "name": "github",
      "version": "1.0.0",
      "runtime": "PromptOnly",
      "description": "GitHub integration for issues, PRs, and repos",
      "author": "librefang",
      "tags": ["devtools"],
      "tools_count": 0,
      "enabled": true,
      "has_prompt_context": true,
      "source": {"type": "local"}
    }
  ],
  "total": 60,
  "categories": ["ai-ml", "cloud", "data", "devtools", "general"]
}

POST /api/skills/install

Install a skill from a local path or URL. The skill manifest is verified (SHA256 checksum) and scanned for prompt injection before installation.

Request Body:

{
  "source": "/path/to/skill",
  "verify": true
}

Response 201 Created:

{
  "status": "installed",
  "skill": "my-custom-skill",
  "version": "1.0.0"
}

POST /api/skills/uninstall

Remove an installed skill. Bundled skills cannot be uninstalled.

Request Body:

{
  "name": "my-custom-skill"
}

Response 200 OK:

{
  "status": "uninstalled",
  "skill": "my-custom-skill"
}

POST /api/skills/create

Create a new prompt-only skill via the evolution module. The skill is validated, security-scanned, and hot-reloaded into the registry immediately.

Request Body:

{
  "name": "csv-analysis",
  "description": "Expert CSV data analysis and cleaning workflows",
  "prompt_context": "# CSV Analysis\n\nWhen analyzing CSV files...",
  "tags": ["data", "csv"]
}

Response 200 OK:

{
  "status": "created",
  "name": "csv-analysis",
  "version": "0.1.0",
  "message": "Skill 'csv-analysis' created successfully"
}

GET /api/skills/{name}

Get detailed information about a specific skill, including evolution history, tools, supporting files, and usage metrics.

Response 200 OK:

{
  "name": "csv-analysis",
  "version": "0.1.2",
  "description": "Expert CSV data analysis and cleaning workflows",
  "author": "agent-evolved",
  "license": "",
  "tags": ["data", "csv"],
  "runtime": "PromptOnly",
  "tools": [],
  "has_prompt_context": true,
  "prompt_context_length": 2450,
  "source": "Local",
  "enabled": true,
  "path": "/home/user/.librefang/skills/csv-analysis",
  "linked_files": {
    "references": ["pandas-cheatsheet.md"],
    "templates": ["clean.py"]
  },
  "evolution": {
    "versions": [
      {
        "version": "0.1.0",
        "timestamp": "2026-04-16T12:00:00Z",
        "changelog": "Initial creation by agent",
        "content_hash": "a1b2c3..."
      },
      {
        "version": "0.1.2",
        "timestamp": "2026-04-16T14:30:00Z",
        "changelog": "Added encoding detection step",
        "content_hash": "d4e5f6..."
      }
    ],
    "use_count": 12,
    "evolution_count": 3
  }
}

Response 404 Not Found:

{
  "error": "Skill 'nonexistent' not found"
}

GET /api/marketplace/search

Search the FangHub marketplace for community skills.

Query Parameters:

q (required): Search query string
page (optional): Page number (default: 1)

Response 200 OK:

{
  "results": [
    {
      "name": "weather-api",
      "author": "community",
      "description": "Real-time weather data integration",
      "downloads": 1250,
      "version": "2.1.0"
    }
  ],
  "total": 1,
  "page": 1
}

Browse and install skills from ClawHub (OpenClaw ecosystem compatibility). All installations go through the full security pipeline: SHA256 verification, SKILL.md security scanning, and trust boundary enforcement.

GET /api/clawhub/search

Search ClawHub for compatible skills.

Query Parameters:

q (required): Search query

GET /api/clawhub/browse

Browse ClawHub categories.

Query Parameters:

category (optional): Filter by category
page (optional): Page number (default: 1)

GET /api/clawhub/skill/{slug}

Get detailed information about a specific ClawHub skill.

GET /api/clawhub/skill/{slug}/code

Get the raw source code of a ClawHub skill.

POST /api/clawhub/install

Install a skill from ClawHub. Downloads, verifies SHA256 checksum, scans for prompt injection, and converts SKILL.md format to LibreFang skill.toml automatically.

Request Body:

{
  "slug": "data-pipeline"
}

Response 201 Created:

{
  "status": "installed",
  "skill": "data-pipeline",
  "version": "1.2.0",
  "converted_from": "SKILL.md"
}

Hands Endpoints

Hands are persistent automation processes (browser automation, RPA, long-running bots) managed by the kernel.

GET /api/hands

List all installed hand definitions.

POST /api/hands/install

Install a hand from a manifest or registry slug.

GET /api/hands/active

List currently active (running) hand instances.

GET /api/hands/{hand_id}

Get detailed information about a specific hand definition.

POST /api/hands/{hand_id}/activate

Activate a hand, creating a new running instance.

POST /api/hands/{hand_id}/check-deps

Check whether all dependencies required by a hand are installed.

POST /api/hands/{hand_id}/install-deps

Install missing dependencies for a hand.

GET /api/hands/{hand_id}/settings

Get the current settings for a hand.

PUT /api/hands/{hand_id}/settings

Update the settings for a hand.

POST /api/hands/instances/{id}/pause

Pause a running hand instance.

POST /api/hands/instances/{id}/resume

Resume a paused hand instance.

DELETE /api/hands/instances/{id}

Deactivate and remove a hand instance.

GET /api/hands/instances/{id}/stats

Get runtime statistics for a hand instance (uptime, events processed, errors).

GET /api/hands/instances/{id}/browser

Get the current browser state for a browser-automation hand instance.

Extensions Endpoints

Extensions add new capabilities to the daemon itself (custom tools, routes, integrations) without modifying core code.

GET /api/extensions

List all installed extensions.

GET /api/extensions/{name}

Get information about a specific extension.

POST /api/extensions/install

Install an extension from a path or registry.

POST /api/extensions/uninstall

Uninstall an extension by name.

Plugins Endpoints

Context engine plugins extend the context assembly pipeline (RAG, preprocessing, document loaders, etc.).

GET /api/plugins/registries

List configured plugin registries (local and remote).

GET /api/plugins

List all installed plugins.

GET /api/plugins/{name}

Get information about a specific plugin.

POST /api/plugins/install

Install a plugin from a registry or local path.

POST /api/plugins/uninstall

Uninstall a plugin by name.

POST /api/plugins/scaffold

Scaffold a new plugin project from a template. Body: {"name": "...", "description": "...", "runtime": "python" | "native" | "v" | "node" | "deno" | "go" | "ruby" | "bash" | "bun" | "php" | "lua"}. Emits hook scaffolding in the chosen language.

GET /api/plugins/doctor

Probe every supported runtime for its launcher on PATH and cross-reference with every installed plugin. Response includes each runtime's detected version + install hint, and flags any plugin whose declared runtime is unavailable. Use this to debug plugins that silently do nothing.

POST /api/plugins/{name}/install-deps

Install runtime dependencies for a plugin (e.g., Python packages, Node modules).

Media Generation Endpoints

Provider-agnostic media generation — image, text-to-speech, video, and music. LibreFang auto-detects the first configured provider for each capability, or you can specify a provider explicitly via the provider field.

Supported providers: OpenAI (image, TTS), MiniMax (image, TTS, video, music).

POST /api/media/image

Generate one or more images from a text prompt.

Request Body:

{
  "prompt": "A futuristic city skyline at sunset",
  "provider": "openai",
  "model": "gpt-image-1",
  "width": 1024,
  "height": 1024,
  "count": 1
}

All fields except prompt are optional. If provider is omitted, the first configured provider with image capability is used.

Response 200 OK:

{
  "images": [
    { "url": "/api/uploads/550e8400-..." }
  ],
  "model": "gpt-image-1",
  "provider": "openai",
  "revised_prompt": "A detailed futuristic city..."
}

POST /api/media/speech

Synthesize speech from text (TTS).

Request Body:

{
  "text": "Hello, welcome to LibreFang.",
  "voice": "alloy",
  "format": "mp3",
  "speed": 1.0
}

All fields except text are optional.

Response 200 OK:

{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "provider": "openai",
  "model": "tts-1",
  "duration_ms": 2400,
  "sample_rate": 24000
}

POST /api/media/video

Submit an asynchronous video generation task. Returns a task ID for polling.

Request Body:

{
  "prompt": "A cat playing piano in a jazz bar",
  "provider": "minimax",
  "duration_secs": 5
}

All fields except prompt are optional.

Response 202 Accepted:

{
  "task_id": "task-abc123",
  "provider": "minimax"
}

GET /api/media/video/{task_id}?provider=minimax

Poll video generation task status. The provider query parameter is required.

Response 200 OK (in progress):

{
  "status": "processing",
  "task_id": "task-abc123"
}

Response 200 OK (completed):

{
  "status": "completed",
  "result": {
    "file_url": "https://cdn.example.com/video.mp4",
    "width": 1280,
    "height": 720,
    "duration_secs": 5.0,
    "provider": "minimax",
    "model": "T2V-01"
  }
}

POST /api/media/music

Generate music from a text prompt and/or lyrics.

Request Body:

{
  "prompt": "Upbeat electronic dance track",
  "lyrics": "",
  "instrumental": true,
  "format": "mp3"
}

At least one of prompt or lyrics is required.

Response 200 OK:

{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "duration_ms": 180000,
  "provider": "minimax",
  "model": "music-2.5",
  "sample_rate": 44100
}

GET /api/media/providers

List available media providers with their capabilities and configuration status.

Response 200 OK:

{
  "providers": [
    {
      "name": "openai",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech"]
    },
    {
      "name": "minimax",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech", "VideoGeneration", "MusicGeneration"]
    }
  ]
}

Intelligence & Skills API

Memory Endpoints

GET /api/memory/agents/{id}/kv

GET /api/memory/agents/{id}/kv/{key}

PUT /api/memory/agents/{id}/kv/{key}

DELETE /api/memory/agents/{id}/kv/{key}

GET /api/memory

POST /api/memory

GET /api/memory/search

GET /api/memory/stats

POST /api/memory/cleanup

POST /api/memory/decay

POST /api/memory/bulk-delete

PUT /api/memory/items/{memory_id}

DELETE /api/memory/items/{memory_id}

GET /api/memory/items/{memory_id}/history

GET /api/memory/user/{user_id}

GET /api/memory/agents/{id}

DELETE /api/memory/agents/{id}

GET /api/memory/agents/{id}/search

GET /api/memory/agents/{id}/stats

DELETE /api/memory/agents/{id}/level/{level}

GET /api/memory/agents/{id}/duplicates

POST /api/memory/agents/{id}/consolidate

GET /api/memory/agents/{id}/count

GET /api/memory/agents/{id}/relations

POST /api/memory/agents/{id}/relations

GET /api/memory/agents/{id}/export

POST /api/memory/agents/{id}/import

Skills & Marketplace Endpoints

GET /api/skills

POST /api/skills/install

POST /api/skills/uninstall

POST /api/skills/create

GET /api/skills/{name}

GET /api/marketplace/search

ClawHub Endpoints

GET /api/clawhub/search

GET /api/clawhub/browse

GET /api/clawhub/skill/{slug}

GET /api/clawhub/skill/{slug}/code

POST /api/clawhub/install

Hands Endpoints

GET /api/hands

POST /api/hands/install

GET /api/hands/active

GET /api/hands/{hand_id}

POST /api/hands/{hand_id}/activate

POST /api/hands/{hand_id}/check-deps

POST /api/hands/{hand_id}/install-deps

GET /api/hands/{hand_id}/settings

PUT /api/hands/{hand_id}/settings

POST /api/hands/instances/{id}/pause

POST /api/hands/instances/{id}/resume

DELETE /api/hands/instances/{id}

GET /api/hands/instances/{id}/stats

GET /api/hands/instances/{id}/browser

Extensions Endpoints

GET /api/extensions

GET /api/extensions/{name}

POST /api/extensions/install

POST /api/extensions/uninstall

Plugins Endpoints

GET /api/plugins/registries

GET /api/plugins

GET /api/plugins/{name}

POST /api/plugins/install

POST /api/plugins/uninstall

POST /api/plugins/scaffold

GET /api/plugins/doctor

POST /api/plugins/{name}/install-deps

Media Generation Endpoints

POST /api/media/image

POST /api/media/speech

POST /api/media/video

GET /api/media/video/{task_id}?provider=minimax

POST /api/media/music

GET /api/media/providers