Documentation/Integrations/API Integrations

API Integrations

Connect third-party services — email, SMS, chat, payments, CRM, dev tools, cloud storage, and more — to your Supero app through one managed API. Wire your own custom HTTP endpoints when the catalog does not cover a provider yet.

Overview

Supero ships with a managed Services Catalog: dozens of pre-built integrations across email, SMS/WhatsApp, push, chat, payments, CRM, social, developer tools, cloud storage, calendar, search, and AI/LLM. This is the primary, supported way to connect a third-party provider — Supero owns the provider handshake, retries, and circuit breaking, and every call is logged as a CRUD record you can query later.

If a provider is not in the catalog, the Plugin Registry lets you register your own HTTP endpoint (with header-based auth, retries, and a circuit breaker) as a secondary path. Registered plugins are invoked from your workflows and event bindings — they are not called through a separate public "invoke" endpoint.

•Managed Services Catalog (primary): browse, import, configure, and execute pre-built provider integrations through one endpoint
•Plugin Registry (secondary): register a custom HTTP endpoint for a provider the catalog does not cover
•Every call creates a CRUD record — query it later like any other domain object
•Automatic retry with exponential backoff and a circuit breaker on both paths

Quick Start

Authenticate, then call the execute endpoint with a service_id and operation. This example sends a transactional email through the catalog's email service.

bash

# 1. Authenticate
curl -X POST https://api.supero.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "my-company",
    "email": "[email protected]",
    "password": "your-password"
  }'

# Response includes auth.access_token — use it as a Bearer token below

# 2. Execute a service operation
curl -X POST https://api.supero.dev/api/v1/services/execute \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "email",
    "operation": "send_email",
    "input": {
      "to_email": "[email protected]",
      "subject": "Welcome to Our App",
      "body_html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
    }
  }'

json

{
  "success": true,
  "service_id": "email",
  "operation": "send_email",
  "output": {
    "record_uuid": "emsg-a1b2c3d4-...",
    "provider_message_id": "sg-abc123def456",
    "status": "sent"
  }
}

ℹ️ Two ways to authenticate

Use Authorization: Bearer <jwt> for a logged-in user session, or the X-API-Key header with a domain/project-scoped API key (starts ak_...) for server-to-server calls. Never send an API key as a Bearer token. Your domain and project are resolved from the credential — you generally do not need to pass them explicitly.

Managed Services Catalog

Before a service can be executed in a project, it must be imported and, for most providers, configured with credentials. Browse what is available, then import and configure the ones you need.

Endpoint	Method	Purpose
/api/v1/services/catalog	GET	List every service available in the catalog
/api/v1/services/catalog/{service_id}	GET	Get one service's operations and config fields
/api/v1/services/status	GET	List services already imported into the current project
/api/v1/services/import	POST	Import a catalog service into the current project
/api/v1/services/import	DELETE	Remove an imported service from the project
/api/v1/services/{service_id}/config	GET / PUT	Read or set a service's configuration (API keys, account IDs, etc.)
/api/v1/services/{service_id}/operations	GET	List the operations a service supports
/api/v1/services/execute	POST	Run one operation on an imported, configured service

bash

# Import a service into the current project
curl -X POST https://api.supero.dev/api/v1/services/import \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"service_id": "github"}'

# Configure it with provider credentials
curl -X PUT https://api.supero.dev/api/v1/services/github/config \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{"github_access_token": "ghp_..."}'

If you switch between multiple projects in the same domain, services are imported per-project — make sure the JWT or API key you are using is scoped to the project where the service was imported before calling execute.

Available Integrations

A sample of the catalog by category. Use GET /api/v1/services/catalog for the full, current list — new services are added over time.

Category	service_id examples	What it does
Email	email, email_smtp	Transactional email via a managed provider or your own SMTP server
Messaging	sms, whatsapp, push_notification	SMS, WhatsApp business messaging, and mobile push notifications
Chat / ops	slack	Post messages, rich Block-Kit messages, and create channels
Payments	billing, billing_paypal, billing_razorpay, stripe_checkout, apple_pay, google_pay	Customers, invoices, orders, and hosted checkout sessions
Banking	plaid	Bank account linking and balance/transaction retrieval
CRM	salesforce	Leads, contacts, opportunities, and cases
Accounting	quickbooks	Accounting and invoicing sync
Social	instagram, linkedin, x_social, tiktok, facebook, google_reviews	Publish posts, reply to comments, and read reviews
Dev tools	github, bitbucket	Issues, pull requests, comments, and repositories
Cloud storage	amazon_s3, google_drive	Presigned uploads/downloads and file management
Calendar / search / video	google_calendar, google_search, youtube	Events with video-call links, web/image search, and video metadata/playlists
ITSM	servicenow	Incidents, change requests, and work notes
Ads / analytics	google_ads, datadog	Campaign and observability integrations
Identity	okta, google_oauth	Single sign-on and OAuth connections
AI / LLM	ai	Chat and text-completion calls using your own provider API key

Executing Operations

Every service operation — regardless of provider — goes through the same endpoint and request/response shape.

Field	Type	Required	Description
service_id	string	Yes	Which service, e.g. email, sms, github, billing
operation	string	Yes	Which operation, e.g. send_email, create_issue, create_customer
input	object	Yes	Operation-specific input fields

On success the response includes output with at least a record_uuid plus provider-specific fields (message IDs, URLs, status). On failure:

json

{
  "success": false,
  "error": "Plugin invocation failed: Service unavailable",
  "service_id": "email",
  "operation": "send_email"
}

Every call becomes a CRUD record

Execute validates your input, creates a CRUD record for the operation, calls the provider, then updates the record with the result. Query it later with the standard CRUD API:

bash

curl "https://api.supero.dev/api/v1/crud/my-company/email:message?limit=10" \
  -H "Authorization: Bearer eyJhbG..."

service_id	CRUD types
email	email:message, email:template, email:campaign
sms	sms:message
slack	slack:message, slack:channel
billing	billing:customer, billing:invoice, billing:billing_subscription
github	github:issue, github:pull_request, github:comment, github:repository
amazon_s3	s3:object
google_drive	gdrive:file
stripe_checkout	checkout:session, checkout:payment_link
google_calendar	gcal:event
salesforce	sfdc:lead, sfdc:contact, sfdc:opportunity, sfdc:case_record

Common Errors

Error	Meaning	What to do
"Service 'x' not imported"	Service not enabled for this project	Import it first via POST /api/v1/services/import
"Operation 'x' not found"	Wrong operation name	Check GET /api/v1/services/{service_id}/operations
"Plugin invocation failed"	External provider error	Check provider credentials via the config endpoint
"Missing required field: x"	Input validation failed	Add the required field
"Config not active"	Service not configured	Configure it via PUT /api/v1/services/{service_id}/config

Python SDK

Install the Python SDK, then use ServiceLib for a typed shortcut to the execute API. It authenticates with an API key and resolves your domain and project automatically.

bash

pip install supero

python

from supero import ServiceLib

sl = ServiceLib(
    api_key="ak_...",
    domain="my-company",
    project_uuid="your-project-uuid",
)

# Typed accessors for common services
result = sl.email.send("[email protected]", "Welcome!", body_html="<h1>Hi!</h1>")
sl.sms.send("+14155551234", "Your code is 847291")
sl.slack.message("#order-alerts", "New order received")

# Generic call for any service/operation not covered by a typed accessor
result = sl.exec("github", "create_issue", {
    "repo_owner": "my-org",
    "repo_name": "my-repo",
    "title": "Bug: API returns 500 on empty input",
})
print(result["output"]["html_url"])

exec() (and the typed accessors that call it) never raises on a provider failure — it returns the same {success, output} / {success, error} shape as the REST response, or None if the SDK could not reach the API at all.

Custom HTTP Endpoints (Plugin Registry)

For a provider that is not in the managed catalog, register your own HTTP endpoint as a plugin. Plugins are project-scoped and get Supero's reliability layer (retry, circuit breaker) for free, but — unlike catalog services — they are invoked from your workflows and event bindings rather than called directly by your app.

bash

curl -X POST https://api.supero.dev/api/v1/plugins/register \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "your-project-uuid",
    "plugin_name": "internal-fulfillment-hook",
    "endpoint_url": "https://fulfillment.example.com/webhook",
    "http_method": "POST",
    "auth_type": "header",
    "auth_header_name": "Authorization",
    "auth_header_value": "Bearer your-secret-token",
    "timeout_seconds": 30,
    "max_retries": 3,
    "circuit_breaker_threshold": 5
  }'

Field	Description
endpoint_url	Full https:// URL of your endpoint
http_method	POST, PUT, or PATCH (default POST)
auth_type	none or header (default none)
auth_header_name / auth_header_value	Header name/value sent on every call when auth_type is header; the value is stored securely and never returned in API responses
custom_headers	Additional static headers as a JSON object
timeout_seconds	Request timeout, default 30, max 300
max_retries / retry_backoff_seconds	Retry attempts and initial exponential backoff, defaults 3 and 2
circuit_breaker_threshold / circuit_breaker_timeout_seconds	Failures before the circuit opens and cooldown before it half-opens, defaults 5 and 60

Endpoint	Method	Purpose
/api/v1/plugins/register	POST	Register a new plugin in a project
/api/v1/plugins?project_uuid=...	GET	List plugins in a project
/api/v1/plugins/{plugin_uuid}	GET	Get plugin details
/api/v1/plugins/{plugin_uuid}/status	PUT	Enable or disable a plugin
/api/v1/plugins/{plugin_uuid}	DELETE	Delete a plugin
/api/v1/plugins/{plugin_uuid}/health	GET	Health status and invocation statistics

health_status on a plugin is one of unknown (not yet health-checked), healthy, unhealthy, or circuit_open. The GET .../health response also returns total_invocations, success_count, failure_count, and average_latency_ms.

⚠️ Retry-safe operations only

Only rely on automatic retries for idempotent operations. For anything with a side effect that should not repeat (like charging a card), use your own idempotency key on the receiving endpoint.

Next steps

•CRUD API Reference — the record shape and query options every service execution and plugin invocation writes into
•Authentication — JWT vs. API key, token lifetimes, and refresh/logout flows
•Python SDK Reference — the full CrudManager, query builder, and ServiceLib surface
•Roles and Permissions — which roles can import, configure, and execute services in a project

← PreviousLive Data, Read-Only & Security Next →Webhooks & Events

On this page