Developers/API Reference/Plugins API

Plugins API

REST API reference for the Plugin Registry — register your own HTTP endpoint as a project-scoped plugin, invoke it through the platform gateway, and monitor its health.

Overview

The Plugin Registry lets a project register an arbitrary external HTTP endpoint and call it through the platform gateway, which adds authentication-header injection, timeouts, retries with backoff, and circuit breaking. It is the path to reach for when you need to wire up a service that is not already in the managed catalog.

For providers Supero already knows how to talk to (payments, email, SMS, and similar), prefer the managed services catalog — GET /api/v1/services/catalog, POST /api/v1/services/import, PUT /api/v1/services/{id}/config, POST /api/v1/services/execute — described on Managed Integrations & Provider Catalog. Reach for the Plugin Registry when you're wiring up your own custom HTTP endpoint that has no catalog entry.

Base URL and authentication

All endpoints below are relative to https://api.supero.dev. Authenticate with a user session token (Authorization: Bearer <jwt>) or a project/domain-scoped API key (X-API-Key: ak_...). Plugins are project-scoped: register and list calls take a project_uuid, and the calling identity must have access to that project.

bash

curl https://api.supero.dev/api/v1/plugins?project_uuid=6f1e2a3b-...-9c0d \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Action	Method & path	Permission required
Register a plugin	POST /api/v1/plugins/register	plugin:create
List plugins	GET /api/v1/plugins	plugin:list
Get plugin details	GET /api/v1/plugins/{plugin_uuid}	plugin:read
Enable / disable a plugin	PUT /api/v1/plugins/{plugin_uuid}/status	plugin:update
Delete a plugin	DELETE /api/v1/plugins/{plugin_uuid}	plugin:delete
Get plugin health	GET /api/v1/plugins/{plugin_uuid}/health	plugin:read
Invoke a plugin	POST /api/v1/plugins/invoke/{object_type}	operational:create

ℹ️ Domain admins

domain_admin (and platform-level roles) are implicitly granted every plugin permission within their own domain. Other roles need the specific plugin:* / operational:create permission granted through your access policy.

Register a Plugin

POST /api/v1/plugins/register

Registers a new external HTTP endpoint under a project. plugin_name only needs to be unique within that project.

json

{
  "project_uuid": "6f1e2a3b-7c4d-4e11-9a2f-3d5b8e9c0d1a",
  "plugin_name": "twilio-sms",
  "endpoint_url": "https://api.twilio.com/2010-04-01/Accounts/AC.../Messages.json",
  "http_method": "POST",
  "auth_type": "header",
  "auth_header_name": "Authorization",
  "auth_header_value": "Basic dGVzdDp0ZXN0",
  "custom_headers": { "X-Source": "supero" },
  "timeout_seconds": 30,
  "max_retries": 3,
  "retry_backoff_seconds": 2,
  "circuit_breaker_threshold": 5,
  "circuit_breaker_timeout_seconds": 60
}

Field	Type	Required	Default	Notes
project_uuid	string	Yes	—	Parent project the plugin belongs to.
plugin_name	string	Yes	—	Unique within the project; used to invoke by name.
endpoint_url	string	Yes	—	Full http:// or https:// URL of your endpoint.
http_method	string	No	POST	One of POST, PUT, PATCH — the method used to call endpoint_url.
auth_type	string	No	none	One of none, header.
auth_header_name	string	No	—	Header name to send, e.g. Authorization or X-API-Key.
auth_header_value	string	No	—	Header value. Stored securely and redacted in API responses.
custom_headers	object	No	—	Additional static headers sent on every invocation.
timeout_seconds	integer	No	30	Request timeout, up to 300.
max_retries	integer	No	3	Retry attempts on failure.
retry_backoff_seconds	integer	No	2	Initial backoff delay, applied exponentially.
circuit_breaker_threshold	integer	No	5	Consecutive failures before the circuit opens.
circuit_breaker_timeout_seconds	integer	No	60	Time before the circuit tries half-open.

Response — 201 Created

json

{
  "success": true,
  "message": "Plugin registered successfully",
  "plugin": {
    "plugin_uuid": "9b2c1e4a-...-1f2a3b4c",
    "plugin_name": "twilio-sms",
    "endpoint_url": "https://api.twilio.com/2010-04-01/Accounts/AC.../Messages.json",
    "enabled": true,
    "health_status": "healthy"
  }
}

⚠️ Missing fields

project_uuid, plugin_name, and endpoint_url are all required — a request missing any of them returns 400 with a message listing the missing fields.

List and Get Plugins

GET /api/v1/plugins

Lists plugins for a project. project_uuid can be passed as a query parameter or, if omitted, is read from the caller's JWT. Pass enabled_only=true to return only enabled plugins.

bash

curl "https://api.supero.dev/api/v1/plugins?project_uuid=6f1e2a3b-...-9c0d&enabled_only=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

json

{
  "project_uuid": "6f1e2a3b-...-9c0d",
  "total": 1,
  "plugins": [
    {
      "plugin_uuid": "9b2c1e4a-...-1f2a3b4c",
      "plugin_name": "twilio-sms",
      "endpoint_url": "https://api.twilio.com/2010-04-01/Accounts/AC.../Messages.json",
      "enabled": true,
      "health_status": "healthy",
      "total_invocations": 42,
      "success_count": 40,
      "failure_count": 2
    }
  ]
}

GET /api/v1/plugins/{plugin_uuid}

Returns the full registry record for a single plugin, keyed by its plugin_uuid. auth_header_value is never returned.

bash

curl https://api.supero.dev/api/v1/plugins/9b2c1e4a-...-1f2a3b4c \
  -H "Authorization: Bearer $ACCESS_TOKEN"

ℹ️ Keyed by UUID, not name

Get, status update, delete, and health all address the plugin by plugin_uuid in the path — not plugin_name. Look the UUID up via the list endpoint if you only know the name.

Enable, Disable, and Delete

PUT /api/v1/plugins/{plugin_uuid}/status

Toggles a plugin on or off without touching its other configuration. A disabled plugin is skipped by invoke calls and returns 503.

json

{
  "enabled": false
}

json

{
  "success": true,
  "message": "Plugin disabled successfully",
  "plugin_uuid": "9b2c1e4a-...-1f2a3b4c",
  "enabled": false
}

DELETE /api/v1/plugins/{plugin_uuid}

Permanently removes the plugin registration. There is no restore.

json

{
  "success": true,
  "message": "Plugin deleted successfully",
  "plugin_uuid": "9b2c1e4a-...-1f2a3b4c"
}

There is no endpoint to replace a plugin's full configuration in one call — to change endpoint_url, auth, retries, or breaker settings, delete the plugin and register it again.

Invoke a Plugin

POST /api/v1/plugins/invoke/{object_type}

Calls your registered endpoint through the gateway, applying the auth header, timeout, retries, and circuit breaker configured at registration. object_type is a label you choose (for example send_sms or send_email) that appears in logs — it does not need to match a schema type.

The request body must include either plugin_name or plugin_uuid to select the plugin; every other field is forwarded to your endpoint as the outbound request payload.

bash

curl -X POST https://api.supero.dev/api/v1/plugins/invoke/send_sms \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plugin_name": "twilio-sms",
    "to": "+14155551234",
    "body": "Your order has shipped"
  }'

The plugin is resolved within the project carried on the caller's JWT. To target a plugin in a different project you have access to, pass parent_uuid alongside plugin_name/plugin_uuid.

Response

On success, the response is whatever your endpoint returned, passed through by the gateway. Failures are normalized into the platform's standard error shape.

Status	Meaning
400	Neither plugin_name nor plugin_uuid was supplied.
404	No plugin with that name/UUID exists in the resolved project.
503	The plugin is disabled, or its circuit breaker is open (response includes retry_after).
504	The call to endpoint_url exceeded the plugin's timeout_seconds.
500	Any other failure calling the endpoint, after retries are exhausted.

Plugin Health

GET /api/v1/plugins/{plugin_uuid}/health

Returns current health status plus running invocation statistics and the plugin's circuit breaker configuration.

json

{
  "plugin_uuid": "9b2c1e4a-...-1f2a3b4c",
  "plugin_name": "twilio-sms",
  "health_status": "healthy",
  "enabled": true,
  "statistics": {
    "total_invocations": 142,
    "success_count": 138,
    "failure_count": 4,
    "success_rate_percent": 97.18,
    "average_latency_ms": 212,
    "last_invocation_at": "2026-07-15T09:12:44Z"
  },
  "circuit_breaker": {
    "threshold": 5,
    "timeout_seconds": 60
  }
}

health_status	Meaning
unknown	Newly registered — no health check has run yet.
healthy	Recent invocations are succeeding.
unhealthy	Recent invocations are failing.
circuit_open	The circuit breaker tripped after consecutive failures; invocations will fail fast with 503 until the timeout elapses.

Next steps

•Managed Integrations & Provider Catalog — the primary path for wiring up a supported provider without registering a raw HTTP endpoint.
•Plugin Registry — the conceptual guide to when to reach for a custom plugin versus the managed catalog.
•Authentication — how to obtain the Bearer token or API key used in the examples above.
•API Overview & Conventions — request/response conventions shared across every Supero API.

← PreviousDomains, Projects & Tenants API Next →AI Agent API

On this page