Integrations

An agent is only as useful as what it can reach. Integrations are how an agent gets at your other tools: a repository, a chat workspace, a calendar, a payments account. Each one is a connection your company owns, with its credentials stored on the platform, and you decide which agents may use each one.

Two ideas carry the whole page:

• A connection belongs to the company, not to an agent. You connect a service once, then decide which agents may use it.
• Connecting is not the same as working. A test call tells you whether the stored credentials still reach the provider.

The catalog of connectors

A connector is a kind of service the platform knows how to talk to. The catalog lists every connector that is switched on for your deployment:

curl https://api.snaga.ai/api/v1/integrations/catalog \
  -H "Authorization: Bearer $SNAGA_API_KEY"

Each entry carries an id (for example github, hubspot, telegram), a name, a description, an icon, an auth_type (api_key, oauth2, webhook or none) and a config_schema describing the settings it needs. An OAuth connector that signs in through a shared provider names it in oauth_provider (Google Drive names google) and lists required_oauth_scopes, so you can see what access a Connect button will ask for before the provider's consent screen.

Connecting with OAuth

Most services connect by signing in at the provider. The flow has three steps, and only the middle one happens outside Snaga:

1. Start. POST /api/v1/integrations/{provider}/oauth/start builds the provider's authorize URL and returns auth_url and state. For a shared provider such as Google, send connector_id (for example google_calendar) so the right scopes are requested. A started flow is kept for 10 minutes.
2. Sign in at the provider. Open auth_url in a browser. The provider redirects back to GET /api/v1/integrations/{provider}/oauth/callback. This is the one integrations route that needs no API key: it checks code and state, then sends the browser on to the web app. No tokens are exchanged here.
3. Complete. POST /api/v1/integrations/{provider}/oauth/complete with state, code and agent_id exchanges the code for tokens and creates the connection. A state works once: a replay answers 400.

curl -X POST https://api.snaga.ai/api/v1/integrations/github/oauth/start \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<agent_id>"}'

In the web app all of this sits behind a single Connect button; the API steps matter when you build your own client.

Connecting with a key or settings

Connectors that take an API key or settings rather than a sign-in are created directly:

curl -X POST https://api.snaga.ai/api/v1/integrations \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector_id": "<connector_id>", "name": "Support inbox", "config": { }}'

connector_id and a non-empty name are required, and config must pass the connector's own validation (422 otherwise). The answer is 201 with secrets masked — stored secrets are never returned.

Connectors that can move money are treated more strictly: creating one, or changing its settings, needs an owner or admin, because its settings carry the spending limit.

Giving an integration to agents

Who may use an integration is set by its assigned_agent_ids:

Assign integrations to one agent with:

curl -X PUT https://api.snaga.ai/api/v1/agents/<agent_id>/integrations \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"integration_ids": ["<integration_id>"]}'

This replaces the agent's whole set: an id you leave out is unassigned from this agent. Other agents' explicit grants are untouched — but read the warning below. Ids the company does not have come back under diff.unknown rather than failing the call. Assignment is an owner or admin decision.

Watch out for an unset list. PUT on an integration whose list is unset writes [<that agent>] — which narrows it from every agent to that one, and takes it away from all the others.

GET /api/v1/agents/{agentId}/integrations lists only explicit grants to that agent; an integration open to every agent through an unset list does not appear there. GET /api/v1/integrations lists every integration in the company, assigned or not, in one unpaginated answer with a total.

Testing a connection

curl -X POST https://api.snaga.ai/api/v1/integrations/<integration_id>/test \
  -H "Authorization: Bearer $SNAGA_API_KEY"

The test reaches the real provider with the stored settings. Read success, not the status code: a failed test still answers 200, with success: false and a message saying why. Nothing is written by a test.

Changing and removing

• PATCH /api/v1/integrations/{integrationId} changes name and config. config is merged into what is stored; send a field as the literal [stored] to keep its stored secret. Pointing a connection at a new endpoint while relying on a masked secret is refused (422) — credentials do not follow a connection to a new address. Fixing the settings of an integration in error sets it back to active.
• DELETE /api/v1/integrations/{integrationId} removes the connection for the whole company; agents that had it simply stop seeing it.
• DELETE /api/v1/agents/{agentId}/integrations/{integrationId} also deletes the company-wide record, not just this agent's assignment. To take an integration away from one agent only, send a new set with PUT instead.

Creating, changing and deleting integrations needs a key with agents:write; reading needs agents:read. Every change is recorded in the audit log.

Related

• MCP — connect tool servers that speak the Model Context Protocol.
• Agents — what an agent is and how it uses tools.
• API reference — every integrations operation in full.