Integrations

An agent can inspect and manage its own integrations through the agent API — the same integrations you’d otherwise manage from the dashboard or the alfe integration CLI. For background on what integrations are and how their lifecycle works, see How integrations work.

All examples use the @alfe.ai/agent-api-client.

List effective integrations

integrations.ts

const { integrations } = await client.listIntegrations();
// GET /agent/integrations

Returns every integration in effect for the agent, marked by source:

• Explicit agent-scope installs (source: "explicit", scope: "agent") — the full install row with integrationId, statuses, version, and config.
• Driven activations (source: "driven-by-connection" / "driven-by-channel" / "driven-by-custom") — integrations like Xero, Google, or MYOB that activate whenever their backing connection or channel is active. They have no install row and carry no config; that’s normal, not a fault.
• Inherited installs (source: "explicit" with scope of org, team, or project) — installed at a broader scope, without config.

To tell them apart, check for config. Only agent-scope installs carry it.

Browse the registry

See the integration catalog. This route is public. The response can include entries that aren’t open for new setup, in which case installing one is refused.

const { integrations } = await client.getRegistry();
// GET /integrations/registry

Install an integration

const install = await client.installIntegration("github", {
  version: "1.2.0",             // optional — omit for latest
  config: { defaultBranch: "main" }, // optional initial config
});
// POST /agent/integrations

Read and update config

const config = await client.getIntegrationConfig("github");
// GET /agent/integrations/{integrationId}/config

await client.updateIntegrationConfig("github", { defaultBranch: "develop" });
// PATCH /agent/integrations/{integrationId}

If the integration isn’t installed, the client returns installed: false with empty config and configSchema rather than throwing. A successful read answers with installed plus the entry’s desiredStatus, source, and (for explicit installs) the scope the config lives at. A driven integration answers installed: true with empty config/configSchema — it’s active via its connection and has nothing to configure. An explicit install that has been soft-removed (desiredStatus: "removed", awaiting daemon reconciliation) answers installed: false even though its row still exists. Only scope: "agent" config is writable through updateIntegrationConfig; inherited org/team/project config is read-only from the agent API.

Remove an integration

const removed = await client.removeIntegration("github");
// DELETE /agent/integrations/{integrationId}

OAuth connect flows

Some integrations connect to a third-party account over OAuth. The agent can start that flow and check its result:

// Get an authorization URL to send the user to.
const { url, expiresIn } = await client.getOAuthUrl("github", ["repo", "read:org"]);
// GET /agent/integrations/oauth/url?provider=github&scopes=repo,read:org

// Later, check whether the account is connected.
const status = await client.getOAuthStatus("github");
// GET /agent/integrations/oauth/status?provider=github

{ "data": { "provider": "github", "connected": true } }

For Shopify, pass the store as client.getOAuthUrl("shopify", undefined, { shop }).

Once an account is connected, the agent can read its credentials to make API calls on the user’s behalf — see Connected accounts.

Calling without the client

List installs with curl:

curl https://api.alfe.ai/agent/integrations \
  -H "Authorization: Bearer $ALFE_API_KEY"

The result is wrapped in a data field, as with every agent API response.