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.
`GET`	`/api/v1/connections/oauth/callback`	OAuth provider redirect target.

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.

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.