Integrations

Integrations define the approved API registry for agent tasks. The platform operates on a default-deny model: agents can only make outbound HTTP requests to domains that belong to a registered, active integration. Any request to an unregistered domain is blocked before it leaves the executor.

What Integrations Are

An integration is a pre-configured API target that tells the platform:

• Which domains are allowed (e.g., api.coingecko.com).

• What authentication method the API expects (bearer token, custom header, query parameter).

• What credential key template to use (e.g., COINGECKO_API_KEY).

• How to set up the credential (documentation link, setup instructions).

Integrations serve two purposes:

1. Security boundary -- they form the URL whitelist that restricts where agents can send HTTP requests. Without an approved integration covering the target domain, the request is blocked.

2. Configuration template -- they provide defaults for auth type and header names so users do not need to configure these manually for common APIs.

Integration Schema

Each integration is a Firestore document in the platform_integrations collection:

{
  "id": "coingecko",
  "name": "CoinGecko",
  "description": "Crypto prices, market data, exchange info",
  "category": "finance",
  "status": "approved",
  "icon_url": "https://...",
  "allowed_domains": ["api.coingecko.com", "pro-api.coingecko.com"],
  "default_auth_type": "header",
  "default_auth_header": "x-cg-demo-api-key",
  "credential_key_template": "COINGECKO_API_KEY",
  "docs_url": "https://docs.coingecko.com/reference/introduction",
  "setup_instructions": "1. Sign up at coingecko.com\n2. Go to Developer Dashboard\n3. Create an API key",
  "partner": false,
  "monthly_active_tasks": 0,
  "added_at": "2026-02-25T00:00:00Z",
  "added_by": "system"
}

Field Reference

Field	Type	Description
id	string	Unique identifier, lowercase snake_case (e.g., coingecko, google_sheets)
name	string	Human-readable display name
description	string	What the API provides
category	string	Grouping: analytics, social, email, productivity, finance, data, search, dev, cms, webhook
status	string	approved (active) or deprecated (kill-switched)
icon_url	string	Icon for the integration card in the UI
allowed_domains	array	Domain patterns that agents can reach (supports *. wildcard prefix)
default_auth_type	string	Default auth method: bearer, header, or query_param
default_auth_header	string	Default header name for header auth type (e.g., X-Api-Key)
credential_key_template	string	Suggested credential key name (e.g., SLACK_BOT_TOKEN)
docs_url	string	Link to the API's developer documentation
setup_instructions	string	Step-by-step credential setup guide
partner	boolean	Whether this is a partner integration (shown first in UI)
monthly_active_tasks	integer	Usage counter (updated by the executor)
added_at	timestamp	When the integration was created
added_by	string	Admin UID or system for pre-seeded integrations

Available Integrations

The platform ships with pre-seeded integrations across multiple categories. Administrators can add new integrations at any time.

Analytics

ID	Name	Domains	Auth	Description
lunarcrush	LunarCrush	api.lunarcrush.com	Bearer	Social intelligence for crypto -- Galaxy Score, sentiment, trending coins

Social

ID	Name	Domains	Auth	Description
twitter	Twitter / X	api.twitter.com, api.x.com	Bearer	Post tweets, read timelines, search, manage lists
linkedin	LinkedIn	api.linkedin.com	Bearer	Post updates, manage company pages, retrieve analytics
hootsuite	Hootsuite	platform.hootsuite.com	Bearer	Schedule and publish social media posts across platforms
buffer	Buffer	api.bufferapp.com	Bearer	Social media scheduling and analytics
telegram	Telegram	api.telegram.org	Bearer	Send messages, manage bots, group administration
reddit	Reddit	oauth.reddit.com, www.reddit.com	Bearer	Post content, read subreddits, manage comments
discord	Discord	discord.com, discordapp.com	Header (Authorization: Bot)	Post messages, manage channels, webhooks

Email

ID	Name	Domains	Auth	Description
sendgrid	SendGrid	api.sendgrid.com	Bearer	Transactional and marketing email delivery
mailchimp	Mailchimp	*.api.mailchimp.com	Bearer	Email marketing campaigns, audience management

The Mailchimp integration uses a wildcard domain (*.api.mailchimp.com) because Mailchimp API endpoints are region-prefixed (e.g., us1.api.mailchimp.com, us21.api.mailchimp.com).

Productivity

ID	Name	Domains	Auth	Description
slack	Slack	slack.com, api.slack.com, hooks.slack.com	Bearer	Post messages, manage channels, receive events
notion	Notion	api.notion.com	Bearer	Create and update pages, databases, blocks
airtable	Airtable	api.airtable.com	Bearer	Read/write records, manage bases and tables
google_sheets	Google Sheets	sheets.googleapis.com	Bearer	Read/write spreadsheet data, manage sheets

Finance

ID	Name	Domains	Auth	Description
coinmarketcap	CoinMarketCap	pro-api.coinmarketcap.com	Header (X-CMC_PRO_API_KEY)	Crypto market data, rankings, metadata
coingecko	CoinGecko	api.coingecko.com, pro-api.coingecko.com	Header (x-cg-pro-api-key)	Crypto prices, market data, exchange info
alpha_vantage	Alpha Vantage	www.alphavantage.co	Query Param (apikey)	Stock, forex, and crypto market data

Data

ID	Name	Domains	Auth	Description
openweather	OpenWeather	api.openweathermap.org	Query Param (appid)	Current weather, forecasts, historical data
newsapi	NewsAPI	newsapi.org	Header (X-Api-Key)	News headlines, article search, source discovery

Search

ID	Name	Domains	Auth	Description
perplexity	Perplexity (Sonar)	api.perplexity.ai	Bearer	AI-powered search and research via the Sonar API

Developer Tools

ID	Name	Domains	Auth	Description
github	GitHub	api.github.com	Bearer	Repository management, issues, pull requests, actions, releases

Content Management

ID	Name	Domains	Auth	Description
wordpress	WordPress	*.wordpress.com, public-api.wordpress.com	Bearer	Create and manage posts, pages, comments, media
webflow	Webflow	api.webflow.com	Bearer	CMS collections, site publishing, form submissions

Custom

ID	Name	Domains	Auth	Description
webhook	Webhook	User-specified	None	POST to user-registered URLs (max 3 per task, HTTPS only)

The webhook integration is special: it does not have fixed domains. Instead, it validates that the target URL matches one of the task's pre-registered webhook_urls. This allows agents to send data to arbitrary HTTPS endpoints that the user has explicitly approved.

Integration Summary

Category	Integrations	Count
Analytics	LunarCrush	1
Social	Twitter/X, LinkedIn, Hootsuite, Buffer, Telegram, Reddit, Discord	7
Email	SendGrid, Mailchimp	2
Productivity	Slack, Notion, Airtable, Google Sheets	4
Finance	CoinMarketCap, CoinGecko, Alpha Vantage	3
Data	OpenWeather, NewsAPI	2
Search	Perplexity (Sonar)	1
Developer Tools	GitHub	1
Content Management	WordPress, Webflow	2
Custom	Webhook	1
Total		24

How Integrations Connect to Tools

Integrations define where an agent can make requests. Tools define how the agent makes them. The connection is enforced at execution time:

Agent invokes tool:     api_call(url="https://api.coingecko.com/...", credential="COINGECKO_API_KEY")
                                        |
                                        v
Tool handler:           Extract domain from URL -> "api.coingecko.com"
                                        |
                                        v
URL validation:         Is "coingecko" in task.integrations?
                        Is "api.coingecko.com" in coingecko.allowed_domains?
                                        |
                                 +------+------+
                                 |             |
                                Yes           No
                                 |             |
                          Continue         BLOCKED
                          with request     (error returned to LLM)

All 4 tools (api_call, http_get, http_post, webhook) perform this validation before executing any HTTP request. The only exception is the webhook tool, which validates against the task's webhook_urls list instead of the integration domain registry.

Integration + Credential + Tool Relationship

Integration (platform-level)
  |-- Defines: allowed domains, default auth type
  |
  +-- Credential (task-level)
  |     |-- Stores: encrypted API key/token
  |     |-- Defines: auth_type, auth_header_name
  |
  +-- Tool (execution-level)
        |-- api_call: uses credential, validates domain against integration
        |-- http_get: no credential, validates domain against integration
        |-- http_post: no credential, validates domain against integration
        |-- webhook: no credential, validates URL against task.webhook_urls

Using Integrations in Tasks

To enable an integration for a task, add its id to the task's integrations array:

{
  "integrations": ["coingecko", "slack", "lunarcrush"]
}

The agent can then make HTTP requests to any domain registered under those integrations. Requests to domains not covered by the listed integrations are blocked.

If an integration requires authentication (most do), you must also store the corresponding credential in the task's credential subcollection. See Credentials for details.

Domain Matching

When the executor validates a URL, it extracts the hostname and checks it against the allowed_domains array of each integration listed in the task's integrations field.

Domain matching supports two patterns:

Pattern	Example	Matches
Exact match	api.coingecko.com	api.coingecko.com only
Wildcard prefix	*.api.mailchimp.com	us1.api.mailchimp.com, us21.api.mailchimp.com, etc.

Subdomains of exact-match domains are also matched. For example, if slack.com is in the allowed list, both slack.com and api.slack.com will match.

Administration

Adding Integrations

Platform administrators can add new integrations by creating a document in the platform_integrations collection via the create_integration() function or direct Firestore write. Required fields:

• id -- unique, lowercase, snake_case identifier.

• name -- human-readable display name.

• allowed_domains -- array of allowed domain patterns.

• status -- set to approved.

New integrations are cached in memory and become available to all users immediately. The in-memory cache is also refreshed from Firestore hourly.

Deprecating Integrations (Kill Switch)

To revoke access to an API, an administrator sets the integration's status to deprecated. Deprecated integrations:

• Are removed from the in-memory cache immediately.

• Cannot be added to new tasks.

• Cause active executions to fail if they attempt to reach the deprecated API's domains.

• Trigger an integration_deprecated warning in the execution record.

This serves as an admin kill switch: deprecating an integration immediately prevents all agents across the platform from reaching that API. See Security for how this fits into the defense-in-depth model.

User-Requested Integrations

Users can request new integrations through the platform UI. Requests are stored in the integration_requests collection with status: pending and reviewed by administrators who assess the API's suitability, security posture, and domain patterns before approval.

{
  "uid": "user_abc123",
  "service_name": "Stripe",
  "api_url": "https://api.stripe.com",
  "description": "Payment processing and billing automation",
  "status": "pending",
  "created_at": "2026-02-25T12:00:00Z"
}

Registry Caching

The integration registry is loaded from Firestore into an in-memory cache on executor startup and refreshed hourly. This avoids a Firestore read on every tool call while keeping the registry reasonably current. Changes made by administrators (adding or deprecating integrations) take effect within one hour, or immediately if the cache is manually refreshed.

The cache is synchronized with the security module via set_registry_cache(), ensuring that URL validation always uses the latest approved integration data.