Connectors

Browse the connector catalog, start OAuth or API-key connections, and manage connection records.

A connector is a static integration definition (slug, name, auth type, available tools). A connection is a per-user instance of that connector, holding the OAuth tokens or API key needed to invoke it. The catalog endpoint is read-only; connections are CRUD-able by their owner.

Endpoints

Method	Path	Description
`GET`	`/api/v1/connectors`	List the connector catalog with availability flags.
`GET`	`/api/v1/connections`	List the caller's connections.
`POST`	`/api/v1/connections`	Start a new connection (returns next-step URL).
`GET`	`/api/v1/connections/:id`	Fetch one connection.
`DELETE`	`/api/v1/connections/:id`	Revoke and soft-delete a connection.
`POST`	`/api/v1/connections/:id/credentials`	Submit API-key credentials (for `api_key` connectors).
`GET`/`POST`	`/api/v1/connections/:id/oauth`	Drive the OAuth handshake.
`GET`	`/api/v1/connections/oauth/start`	Begin an OAuth flow by slug; `?selectAccount=1` forces the provider account picker.
`GET`	`/api/v1/connections/oauth/callback`	OAuth provider redirect target.
`POST`	`/api/v1/connectors/webhooks/:provider/:endpointId`	Public provider-event receiver used by connector setup commands such as Telegram `setup-webhook`.

OAuth completion

OAuth opens in a normal new tab (never a sized popup). When the provider redirects back, the originating dashboard tab refreshes through BroadcastChannel, localStorage, and status polling — blocked chat sessions resume automatically. See Connector OAuth. Use GET /api/v1/connections/oauth/start?selectAccount=1 to force the provider account picker.

List connectors

GET /api/v1/connectors returns the static catalog. Each item:

Field	Type	Description
`slug`	string	Stable connector ID.
`name`	string	Display name.
`description`	string	One-line summary.
`authType`	`"oauth"` \| `"api_key"` \| `"none"`	How the connector authenticates.
`configured`	boolean	True if env-level credentials (OAuth client, etc.) are set.
`availability`	string	`"available"`, `"coming_soon"`, etc.
`availabilityReason`	string \| undefined	Present when not available.
`tools`	`{ name, description }[]`	Operations exposed by the connector.
`credentialFields`	`{ key, label, required, ... }[]`	Only for `api_key` connectors.

List connections

GET /api/v1/connections returns the caller's non-deleted connections, newest first. Sensitive token fields are stripped by serializeConnectionRecord.

Start a connection

POST /api/v1/connections

Field	Type	Required	Description
`connectorSlug`	string	yes	Must exist in the catalog.
`label`	string	no	Display label for the connection.

The handler validates the connector, ensures OAuth credentials are configured when authType: "oauth", and creates a pending connection. The response varies:

Already connected (200): returns the existing connection plus credentialSubmitUrl for API-key connectors so credentials can be re-submitted.
OAuth pending (201): returns { connection, oauthUrl, credentialSubmitUrl: null }. Open oauthUrl in a normal browser tab to complete the handshake.
API-key pending (201): returns { connection, oauthUrl: null, credentialSubmitUrl }. POST the credential payload to that URL.

bash

curl -X POST https://alumia.com/api/v1/connections \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "connectorSlug": "github", "label": "Personal GitHub" }'

Fetch / revoke

GET /api/v1/connections/:id returns the serialized connection record.
DELETE /api/v1/connections/:id sets status: "revoked" and deletedAt. Returns { "deleted": true }.

:id must be a valid UUID; malformed IDs return BAD_REQUEST.

Running operations

Tool invocations against an established connection happen through the agent runtime, not through a public HTTP endpoint. From your application, run a chat turn (see Sessions) targeting an agent whose allowedConnectors includes the connector slug.

Inbound connector events

Provider-owned webhooks do not use the generic signed webhook API. They are provisioned by connector operations or controlled setup flows so the provider can use its native verification scheme. The shared receiver supports POST /api/v1/connectors/webhooks/:provider/:endpointId for Telegram, Slack, Discord, WhatsApp, Twilio, Gmail push, GitHub, Linear, and Stripe adapters. For Telegram, setup-webhook creates an Alumia endpoint at /api/v1/connectors/webhooks/telegram/:endpointId, stores the provider secret encrypted, calls Telegram setWebhook with secret_token, and routes verified updates into durable agent jobs. Duplicate provider event IDs are deduplicated per endpoint.

Production setup requires CONNECTOR_WEBHOOK_BASE_URL or an equivalent public HTTPS app URL so setup commands do not register localhost/internal callback URLs. Admins can inspect endpoint status, delivery counts, normalized event keys, and durable job state at /admin/connector-events.

Errors

Code	When
`UNAUTHORIZED`	No valid key.
`BAD_REQUEST`	Missing `connectorSlug`, unknown slug, OAuth not supported, connector not yet configured, or malformed connection ID.
`NOT_FOUND`	Connection does not belong to the caller.

Search docs