Base URL http://localhost:3333/api/ · Authentication · Conventions

Plugin Routes

Base path: /api/plugins

Get Installed Plugins

GET /installed

• Authentication: None
• Description: Get list of installed plugins with their status
• Response:

{
  "success": true,
  "plugins": [
    {
      "name": "plugin-name",
      "version": "1.0.0",
      "description": "Plugin description",
      "status": "active|inactive|error",
      "tools": ["tool1", "tool2"]
    }
  ],
  "stats": {
    "total": 5,
    "active": 3,
    "inactive": 2
  }
}

Get Installed Plugin Details

GET /installed/:name

• Authentication: None
• Parameters:
  • name (path): Plugin name
• Description: Get details of a specific installed plugin, including each tool's full input schema (use this to discover param types and allowed values without guessing).
• Response:

{
  "success": true,
  "plugin": {
    "name": "chucknorris-joke-plugin",
    "displayName": "Chuck Norris Jokes",
    "version": "1.0.0",
    "description": "Fetch random Chuck Norris jokes from the public Chuck Norris API.",
    "author": "AGNT User",
    "isValid": true,
    "tools": [
      {
        "type": "chucknorris-get-joke",
        "title": "Get Random Chuck Norris Joke",
        "description": "Retrieves a random Chuck Norris joke, optionally filtered by category.",
        "category": "action",
        "schema": {
          "title": "Get Random Chuck Norris Joke",
          "description": "Retrieves a random Chuck Norris joke, optionally filtered by category.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string",
                "enum": ["animal", "career", "celebrity", "dev", "explicit", "fashion", "food", "history", "money", "movie", "music", "political", "religion", "science", "sport", "travel"]
              }
            }
          }
        }
      }
    ]
  }
}

• Response (404): { "success": false, "error": "Plugin '<name>' not found" }

Get Plugin Source Code

GET /installed/:name/source

• Authentication: Required
• Parameters:
  • name (path): Plugin name
• Description: Get source code of an installed plugin
• Response:

{
  "success": true,
  "files": {
    "manifest.json": "{...}",
    "package.json": "{...}",
    "index.js": "console.log('hello');"
  }
}

Get Plugin Package

GET /installed/:name/package

• Authentication: Required
• Parameters:
  • name (path): Plugin name
• Description: Get the plugin as a packaged .agnt file (base64 encoded)
• Response:

{
  "success": true,
  "data": "base64-encoded-package-data",
  "size": 1024000,
  "fileName": "plugin-name.agnt"
}

Get Marketplace Plugins

GET /marketplace

• Authentication: None
• Description: Get list of available plugins from the marketplace
• Response:

{
  "plugins": [
    {
      "name": "marketplace-plugin",
      "version": "1.0.0",
      "description": "Marketplace plugin description",
      "author": "Author Name",
      "downloads": 1000,
      "rating": 4.5
    }
  ]
}

Install Plugin from Marketplace

POST /install

• Authentication: Required
• Body:

{
  "name": "plugin-name",
  "version": "latest"
}

• Response:

{
  "success": true,
  "message": "Plugin installed successfully",
  "plugin": {
    "name": "plugin-name",
    "version": "1.0.0"
  }
}

Install Plugin from File

POST /install-file

• Authentication: Required
• Body:

{
  "name": "plugin-name",
  "fileData": "base64-encoded-file-data",
  "fileName": "plugin.agnt"
}

• Response:

{
  "success": true,
  "message": "Plugin installed successfully",
  "plugin": {
    "name": "plugin-name",
    "version": "1.0.0"
  }
}

Uninstall Plugin

DELETE /:name

• Authentication: Required
• Parameters:
  • name (path): Plugin name
• Description: Uninstall a plugin
• Response:

{
  "success": true,
  "message": "Plugin uninstalled successfully"
}

Get Plugin Tools

GET /tools

• Authentication: None
• Description: Get all tools provided by plugins
• Response:

{
  "success": true,
  "tools": [
    {
      "type": "tool-type",
      "title": "Tool Title",
      "description": "Tool description",
      "category": "action",
      "icon": "tool-icon",
      "plugin": "plugin-name"
    }
  ],
  "count": 1
}

Generate Plugin with AI

POST /generate

• Authentication: Required
• Body:

{
  "description": "Natural language description of the plugin",
  "provider": "openai",
  "model": "gpt-4",
  "options": {}
}

• Response: Server-sent events stream with generation progress

Regenerate Plugin File

POST /regenerate-file

• Authentication: Required
• Body:

{
  "fileName": "index.js",
  "instructions": "Update the file to...",
  "currentManifest": {},
  "currentCode": {},
  "provider": "openai",
  "model": "gpt-4"
}

• Response:

{
  "success": true,
  "content": "Generated file content"
}

Regenerate Entire Plugin

POST /regenerate

• Authentication: Required
• Body:

{
  "description": "Updated plugin description",
  "currentManifest": {},
  "currentCode": {},
  "provider": "openai",
  "model": "gpt-4"
}

• Response: Server-sent events stream with regeneration progress

Build Generated Plugin

POST /build-generated

• Authentication: Required
• Body:

{
  "manifest": {},
  "toolCode": {},
  "packageJson": {},
  "installAfterBuild": true
}

• Response:

{
  "success": true,
  "pluginName": "generated-plugin",
  "outputFile": "/path/to/plugin.agnt",
  "installed": true,
  "installResult": {
    "success": true
  }
}

Reload Plugins

POST /reload

• Authentication: Required
• Description: Reload all plugins (useful after manual changes)
• Response:

{
  "success": true,
  "message": "Plugins reloaded",
  "stats": {
    "total": 5,
    "active": 3
  },
  "orchestratorReload": {
    "success": true
  },
  "workflowProcessReload": {
    "success": true
  }
}

---

Get Plugin Assets

GET /:name/assets

• Authentication: Required
• Description: Ecosystem assets a plugin currently owns (agents, workflows, skills, widgets) with per-asset is_user_modified flags — powers the uninstall confirmation modal so the user can see what will be deleted vs preserved
• Response:

{
  "success": true,
  "assets": [
    {
      "asset_type": "agent",
      "asset_slug": "my-agent",
      "local_id": "uuid",
      "installed_at": "2024-01-01T00:00:00Z",
      "deprecated_at": null,
      "is_user_modified": 0
    }
  ]
}

Bundle Plugin from Assets

POST /bundle-from-assets

• Authentication: Required
• Description: Builds a .agnt archive (base64) plus a generated manifest from selected local assets. Optional install: true also installs the bundle on this instance.
• Response: { "archive": "<base64>", "manifest": {...} }

Check Plugin Auth Requirements

POST /install-file/check-auth

• Authentication: Required
• Description: Scans a bundle's authProvider declarations across its tools so the install UI can prompt the user to configure missing providers before completing extraction
• Body:

{
  "fileData": "<base64 .agnt archive>"
}

• Response: Required/missing auth providers for the bundle

Inspect Plugin

GET /inspect/:name

• Authentication: Required
• Description: The disclosure report the install-consent modal renders: integrity state, detected capabilities (with file:line evidence), declared permissions, the undeclared diff, and the trust tier the plugin would receive
• Response: Inspection report object

Install Plugin from GitHub

POST /install-github

• Authentication: Required
• Description: Pulls a plugin directly from GitHub through the same staged/validated/permission-gated install path. Returns { requiresConfirmation: true } on a moved repo and { requiresConsent: true } on permission escalation.

Get Update Settings

GET /update-settings

• Authentication: Required
• Description: Auto-update scheduler settings
• Response: { "success": true, "settings": {...} }

Set Update Settings

POST /update-settings

• Authentication: Required
• Body:

{
  "autoCheck": true,
  "intervalHours": 24
}

• Response: { "success": true, "settings": {...} }

Set Per-Plugin Update Policy

POST /update-policy/:name

• Authentication: Required
• Description: Per-plugin auto-update policy, stored on the registry entry (merge semantics preserve it across installs/updates). 404 if the plugin isn't installed, 400 on an invalid policy.
• Body:

{
  "policy": "auto | notify | pinned"
}

• Response: { "success": true, "name": "...", "policy": "..." }

Check for Plugin Updates

GET /updates

• Authentication: None
• Description: Compares every installed plugin's version against the marketplace catalog. Non-semver installed versions (local, latest, unknown) surface as status unknown-version — never compared, never auto-updated over.
• Response: Per-plugin update status list

Update Plugin

POST /update/:name

• Authentication: Required
• Description: Updates a single plugin via the staged-install path (stage → validate → permission-diff gate → atomic swap). An update requesting NEW permissions returns { requiresConsent: true, permissionDiff } and changes nothing on disk until re-called with acceptedPermissions: true. On success all plugin processes are reloaded.
• Body:

{
  "acceptedPermissions": false
}

---

MCP Routes

Base path: /api/mcp

Get All MCP Servers

GET /servers

• Authentication: Required
• Description: Retrieve all MCP servers for the authenticated user
• Response:

{
  "success": true,
  "servers": [
    {
      "name": "server-name",
      "description": "Server description",
      "url": "https://server-url.com",
      "status": "active|inactive",
      "config": {}
    }
  ]
}

Add MCP Server

POST /servers

• Authentication: Required
• Body:

{
  "name": "server-name",
  "description": "Server description",
  "url": "https://server-url.com",
  "config": {}
}

• Response:

{
  "success": true,
  "server": {
    "name": "server-name",
    "description": "Server description",
    "url": "https://server-url.com",
    "status": "active",
    "config": {},
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Update MCP Server

PUT /servers/:name

• Authentication: Required
• Parameters:
  • name (path): Server name
• Body:

{
  "description": "Updated description",
  "url": "https://updated-url.com",
  "config": {}
}

• Response:

{
  "success": true,
  "server": {
    "name": "server-name",
    "description": "Updated description",
    "url": "https://updated-url.com",
    "status": "active",
    "config": {},
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Delete MCP Server

DELETE /servers/:name

• Authentication: Required
• Parameters:
  • name (path): Server name
• Description: Delete an MCP server by name
• Response:

{
  "success": true,
  "message": "MCP server deleted successfully"
}

Get Server Capabilities

GET /servers/:name/capabilities

• Authentication: Required
• Parameters:
  • name (path): Server name
• Description: Get capabilities of a specific MCP server
• Response:

{
  "success": true,
  "capabilities": {
    "tools": ["tool1", "tool2"],
    "resources": ["resource1", "resource2"],
    "prompts": ["prompt1", "prompt2"]
  }
}

Test MCP Server Connection

POST /servers/:name/test

• Authentication: Required
• Parameters:
  • name (path): Server name
• Description: Test connection to an MCP server
• Response:

{
  "success": true,
  "message": "Connection successful",
  "latency": 150,
  "capabilities": {
    "tools": ["tool1", "tool2"],
    "resources": ["resource1", "resource2"]
  }
}

---