Plugins – ProteusAI Reference

🚫

Internal use only!

A plugin extends the functionality of the ProteusAI platform by allowing (third-party) developers to plug in custom code into specific points in the platform. On ProteusAI plugins typically run in response to system events. Plugins also receive tokens that grant them permission to make changes on the platform.

One typical use case of plugins on ProteusAI is to extend the capabilities of Agents. Agents created on ProteusAI can be powered by any AI model (including Large Language Models) as long as there is a plugin for that model.

Plugins work by registering webhooks to which events can be posted. A plugin lists the events it's interested in and the webhook to which the events are dispatched. The webhook has to be verified for the plugin to be usable. Verification involves dispatching a special event to the webhook and verifying the response. Events are dispatched to the webhook as HTTP POST requests. When a plugin is installed, an access token for that particular installation is generated and sent to the webhook. This token is expected to be stored securely and used whenever the plugin needs to perform actions that require the permissions in the token.

Create Plugin

POST /api/plugins

curl https://management-api.useproteus.ai/api/plugins \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
        "name": "GPT-4o Message Processor",
        "description": "This plugin helps an agent process messages and generate responses using GPT-4o",
        "events": ["AGENT_MESSAGE_RECEIVED"],
        "inputsSchema": {
            "type": "object",
            "properties": {
                "apiKey": {
                    "type": "string",
                    "description": "OpenAI API key"
                }
            },
            "required": [ "apiKey" ]
        },
        "isPublic": true,
        "orgId": "6816330b6f46b5afc080fbf7",
        "scopes": ["AGENT_MESSAGE_WRITE"],
        "tags": ["OpenAI", "GPT-4o"],
        "type": "AGENT_EVENT_HANDLER",
        "webhookUrl": "https://myplugins.com/agent-event-handlers/gpt-4o-processor/webhook"
    }'

Input schema should be a valid JSON schema (opens in a new tab).

You can also create plugins via the orgs API POST: /api/orgs/:orgId/plugins. You will not be able to supply an orgId field in the request body.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/plugins \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
        "name": "Private GPT-4o Message Processor",
        "description": "This plugin helps an agent process messages and generate responses using GPT-4o",
        "events": ["AGENT_MESSAGE_RECEIVED"],
        "inputsSchema": {
            "type": "object",
            "properties": {
                "apiKey": {
                    "type": "string",
                    "description": "OpenAI API key"
                }
            },
            "required": [ "apiKey" ]
        },
        "scopes": ["AGENT_MESSAGE_WRITE"],
        "tags": ["OpenAI", "GPT-4o"],
        "type": "AGENT_EVENT_HANDLER",
        "webhookUrl": "https://myplugins.com/agent-event-handlers/gpt-4o-processor/webhook"
    }'

Get Plugin

GET /api/plugins/:pluginId

This endpoint returns a plugin.

curl https://management-api.useproteus.ai/api/plugins/681f69ca8578a3668292d2ce \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

You have to be a member of an organization to view a non-public plugins in that organization.

curl https://management-api.useproteus.ai/api/agents/681998f5474dbe26fe2e7f5f \
    -H "Authorization: Bearer user-73dd22b0c07a542d080d48a2.9e0ac60c1472a5f2949f8978e82d2582.dfbaf5a25782b0608e173d295e977259.2a52f18cf2ce3d84872ae7fc73c60822ad6fe0ad7dc21f58"

You do not have to be a member of an organization to view a public plugin in that organization.

curl https://management-api.useproteus.ai/api/plugins/681f23cc38780a323859233f \
    -H "Authorization: Bearer user-73dd22b0c07a542d080d48a2.9e0ac60c1472a5f2949f8978e82d2582.dfbaf5a25782b0608e173d295e977259.2a52f18cf2ce3d84872ae7fc73c60822ad6fe0ad7dc21f58"

List Org Plugins

GET /api/orgs/:orgId/plugins

This endpoint fetches the plugins in an organization.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/plugins \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

If the current user is not a member of this organization, only public plugins are listed.

curl https://management-api.useproteus.ai/api/orgs/6816330b6f46b5afc080fbf7/plugins \
    -H "Authorization: Bearer user-73dd22b0c07a542d080d48a2.9e0ac60c1472a5f2949f8978e82d2582.dfbaf5a25782b0608e173d295e977259.2a52f18cf2ce3d84872ae7fc73c60822ad6fe0ad7dc21f58"

Update Plugin

PUT /api/plugins/:pluginId

This endpoint updates a plugin. The current user must be a member of the org with a role of MEMBER or OWNER.

curl https://management-api.useproteus.ai/api/plugins/681f21534b399d4b19757b6b \
    -X PUT \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0" \
    -d '{
            "name": "Updated name",
            "description": "Updated description",
            "webhookUrl": "https://myplugins.com/agent-event-handlers/gpt-4o-processor/updated-webhook"
        }'

Note that updating the webhookUrl property sets webhookUrlIsVerified to false. You'd need to verify the new webhook URL.

Delete Plugin

DELETE /api/plugins/:pluginId

This endpoint deletes a plugin. The current user must be a member of the org with a role of OWNER.

curl https://management-api.useproteus.ai/api/plugins/681f21534b399d4b19757b6b \
    -X DELETE \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

Verify Plugin Webhook

POST /api/plugins/:pluginId/verify-webhook

This endpoint verifies the webhook of a plugin. The current user must be a member of the org with a role of MEMBER or OWNER.

curl https://management-api.useproteus.ai/api/plugins/681f23cc38780a323859233f/verify-webhook \
    -X POST \
    -H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f.ede04d00e4b168bed35d9fcde8c2f92f.00d7fecf89201691f94b01e5b294da65.e7ea4c191b2c9a059ce5658deb7349c26a931ed8b7a04bf0"

This API call dispatches the WEBHOOK_CHALLENGE event to the webhook being verified as a HTTP POST request.

Plugin Instance

A plugin is like a blueprint/template; it is not used directly, but instances of the plugin are created and used at various points of the system.

{
    "id": "6823341466b90fb047739892",
    "agentId": "6819a0e484df0fc342cea506",
    "createdAt": "2025-05-13T11:59:16.426Z",
    "entityId": "6819a0e484df0fc342cea506",
    "entityType": "AGENT",
    "eventDispatchCondition": null,
    "eventDispatchMode": "SYNC",
    "events": [
        "AGENT_MESSAGE_RECEIVED"
    ],
    "inputs": {
        "apiKey": "sk-proj-your-api-key"
    },
    "name": "GPT-4o Message Processor",
    "orgId": "6816330b6f46b5afc080fbf7",
    "pluginId": "681f23cc38780a323859233f",
    "scopes": [
        "AGENT_MESSAGE_WRITE"
    ],
    "updatedAt": "2025-05-13T11:59:16.426Z"
}

A plugin instance may contain one or more tokens that give it the permission to make ProteusAI API calls on behalf of the agent or app to which it is assigned. Whenever a plugin instance is created, a PLUGIN_INSTALLED event is dispatched to the webhook of the plugin as a HTTP POST request.

Several instances of a plugin may be active simultaneously, even within a single organization.

Agents Events