Extending Supero: your own endpoints, your own logic, your own UI

The question every evaluator asks second

Teams hand-roll a cart because they did not know cart existed. They register a plugin for Stripe that the catalog already has. They fork the whole UI to change one card layout. Each is the same mistake made at a different altitude, and it is the mistake this article exists to prevent: Supero has four extension points, and the useful part is not the list, it is knowing which one a given problem calls for.

The first question anyone asks is "can it build my app". The second — the one that actually decides the purchase — is "what happens when it cannot". Every platform has a wall; what matters is whether the wall has a door, and whether going through it costs you the platform's guarantees.

Work down the list, and stop at the first yes

The plugin registry — your endpoint, with guardrails

A plugin is a record of one HTTP endpoint plus the retry and breaker behaviour you would otherwise write yourself: method, timeout, an optional auth header held on the platform side, retry counts and circuit-breaker thresholds. Plugins live at the domain level — you register one against a project you have access to, and every project in that domain can then resolve and invoke it by name.

curl -X POST https://api.supero.dev/api/v1/plugins/register \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "8f14e45f-2d3a-4b1c-9e6a-1234567890ab",
    "plugin_name":  "internal-sms-gateway",
    "endpoint_url": "https://sms.example.com/api/send",
    "http_method":  "POST",
    "auth_type":    "header",
    "auth_header_name":  "X-Api-Key",
    "auth_header_value": "REDACTED"
  }'

# then, from anywhere: object_type is just a label for the logs
curl -X POST https://api.supero.dev/api/v1/plugins/invoke/sms_notification \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "plugin_name": "internal-sms-gateway",
        "to": "+15551234567", "body": "Your order has shipped" }'

A GET on the plugin also returns what you would otherwise have to instrument yourself: health_status, total_invocations, success_count, failure_count, last_invocation_at and average_latency_ms. GET /api/v1/plugins/{uuid}/health gives the same picture plus the circuit-breaker configuration.

The UI — declarative, then hand-built, never both

Supero renders an app's UI one of two ways, and a single app uses exactly one. The declarative path is a UI_SCHEMAS list in ui_schemas.py — pure data extending the platform's UI grammar, covering per-entity admin screens, dashboard widgets, landing pages and the app shell. The SDK renders all of it; ui/app.js becomes a thin shim.

The hand-built path drops ui_schemas.py and writes ui/app.js yourself — either calling AppShell.render({tabs, appName, theme, …}) with your own tab definitions, or mounting your own React tree for full control.

Whichever path you take, the primitives underneath are the same: the same data client, the same services.* calls, the same access rules. Hand-building the UI does not opt you out of tenancy or RBAC — those are enforced server-side, so a hand-rolled screen is exactly as governed as a generated one.

Your own fields, including on the platform's own objects

extends is the extension point people notice last and use most. It works in two directions.

• Down from a service base — extends: "cart:base_cart" inherits a whole lifecycle and lets you add your own fields on top. This is how you get a state machine you did not write; the transactional catalog lists the base schema for every service.
• Onto a system object — extends: "general:project" adds custom fields to a platform entity without touching the base. Your own metadata on a project, tenant or user, carried through the same APIs as everything else.
• Between your own schemas — put shared fields on a base of your own and inherit from it. Resolution is server-side, so clients never walk the chain; they see the merged shape.

Your own logic — and where it should run

There are three honest places to put business logic, and the choice is mostly about who has to be able to change it.

For AI-shaped logic inside your own features — a "summarise this" button, a draft-reply field, a classification step — services.ai is the catalog entry to import. Keep it distinct from the in-app agent: the agent is a finished surface for end users, services.ai is a raw call for your code, and wiring one through the other only adds a failure mode.

Adding your first plugin, end to end

curl https://api.supero.dev/api/v1/services/catalog \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# and, for one entry's operations and config fields
curl https://api.supero.dev/api/v1/services/catalog/email \
  -H "Authorization: Bearer $ACCESS_TOKEN"

What extending does not get you

• There is no plugin step type in workflows. A service_call step resolves against the managed services catalog, so a data-triggered call to your own endpoint needs a workflow step that calls code of yours, which then invokes the plugin. This is the limitation you will actually hit.
• Plugins are outbound HTTP calls with POST, PUT or PATCH. They are not a way to host arbitrary code inside the platform.
• A plugin is registered once per domain and is resolvable by name from any project in it — convenient, but it means the name is a domain-wide namespace, not a per-project one.
• The runtime UI files are regenerated on every run. If you find yourself editing them, you are on the wrong path — move the change into ui/app.js or ui_schemas.py.
• Extending a base schema inherits its state machine, which means you also inherit its rules. If your lifecycle genuinely differs, model your own entity rather than fighting a base that nearly fits.

A door in the wall, not a cliff

The usual failure of an application platform is binary: inside the box everything is fast, and one step outside you are writing a second system with none of the guarantees. What makes extension work here is that the escape hatches keep the foundation — a plugin call still has its credential managed for you, a hand-written screen is still tenant-isolated and role-enforced, a custom field on a system object still travels the same APIs.

Which means the honest advice is not "use the platform for everything". It is: work down the list, stop at the first yes, and know that going one level lower costs you convention rather than governance.