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 and says whether everyone who installs it could connect each one: a sign-in must be declared in the plugin's own manifest.auth or be a shared AGNT sign-in (GET https://api.agnt.gg/auth/providers, no Authorization header). The marketplace applies the same rule at publish and refuses a plugin that fails it. The desktop publish buttons call this before uploading.
Body:

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

Response:

{
  "success": true,
  "pluginName": "calendly-plugin",
  "requiredAuthProviders": ["calendly"],
  "signIns": [{ "id": "calendly", "source": "shared" }],
  "signInErrors": [],
  "signInPublishErrors": [],
  "signInWarnings": [],
  "publishable": true
}

source is plugin (bundled in manifest.auth), shared, unresolved (only its author could connect it) or unknown (the shared list could not be read). publishable is false when the marketplace would refuse the plugin and null when it could not be told locally.

Plugin sign-ins and publishing

A plugin may only be published when anyone who installs it can connect every sign-in it needs. The marketplace refuses a package when:

a tool's authProvider is neither declared in the plugin's manifest.auth nor a shared AGNT sign-in;
a manifest.auth id is a shared sign-in's id (use the shared sign-in instead);
a manifest.auth entry carries a credential (clientSecret, apiKey, token, password, also inside authorizationParams), or is malformed.

The refusal lists each reason in details. Bundle a sign-in the service does not share in manifest.auth: an API key each user pastes, or OAuth (authorization code with PKCE; ship only a public clientId, or none). Do not create a sign-in on the AGNT server for a plugin: it is private to the account that made it.

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"]
  }
}

Plugins & MCP