Skip to main content

​
Integrations API

The Integrations API enables connection and management of third-party services including OAuth integrations, MCP servers, and custom integrations.

​
Integration Types

GAIA supports three types of integrations:

​
Platform Integrations

Pre-configured integrations managed by GAIA (Gmail, Calendar, Notion, Slack, etc.)

​
MCP Integrations

Model Context Protocol servers for extending AI capabilities

​
Custom Integrations

User-created MCP integrations for personal or team use

​
Integration Object

​
integration_id
string
Unique integration identifier
​
name
string
Integration display name
​
description
string
Integration description
​
category
string
Category: productivity, communication, developer, etc.
​
managed_by
string
Management type: self, composio, mcp, or internal
​
source
string
Source: platform (pre-configured) or custom (user-created)
​
requires_auth
boolean
Whether authentication is required
​
auth_type
string
Authentication type: none, oauth, or bearer
​
is_featured
boolean
Whether integration is featured in marketplace
​
tools
array
Array of available tools/capabilities

​
Endpoints

​
List Marketplace Integrations

Get available integrations from marketplace. 
GET /api/v1/integrations/marketplace
​
category
string
Filter by category
​
search
string
Search query
Response
{
  "featured": [
    {
      "integration_id": "gmail",
      "name": "Gmail",
      "description": "Send and manage emails",
      "category": "communication",
      "managed_by": "composio",
      "source": "platform",
      "requires_auth": true,
      "auth_type": "oauth",
      "is_featured": true,
      "tools": [
        {"name": "send_email", "description": "Send an email"},
        {"name": "search_emails", "description": "Search emails"}
      ]
    }
  ],
  "integrations": [...],
  "total": 50
}

​
List User Integrations

Get integrations added to user’s workspace. 
GET /api/v1/integrations
Response
{
  "integrations": [
    {
      "integration_id": "gmail",
      "status": "connected",
      "created_at": "2026-02-15T10:00:00Z",
      "connected_at": "2026-02-15T10:05:00Z",
      "integration": {
        "integration_id": "gmail",
        "name": "Gmail",
        "description": "Send and manage emails",
        "category": "communication",
        "managed_by": "composio",
        "requires_auth": true
      }
    }
  ],
  "total": 5
}

​
Add Integration

Add an integration to user’s workspace. 
POST /api/v1/integrations
Request
{
  "integration_id": "notion"
}
Response
{
  "integration_id": "notion",
  "status": "created",
  "message": "Integration added. Connect to start using."
}

​
Connect Integration

Connect/authenticate an integration. 
POST /api/v1/integrations/{integration_id}/connect
Request
{
  "redirect_path": "/integrations",
  "bearer_token": "optional_api_key"
}
For OAuth integrations, response includes redirect URL:
Response
{
  "status": "redirect",
  "integration_id": "gmail",
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}
For bearer token integrations, connection is immediate:
Response
{
  "status": "connected",
  "integration_id": "custom_mcp",
  "tools_count": 5
}

​
Disconnect Integration

Disconnect an integration. 
POST /api/v1/integrations/{integration_id}/disconnect

​
Remove Integration

Remove integration from workspace. 
DELETE /api/v1/integrations/{integration_id}

​
Custom MCP Integrations

​
Create Custom Integration

Create a custom MCP integration. 
POST /api/v1/integrations/custom
Request
{
  "name": "My API",
  "description": "Custom API integration",
  "category": "custom",
  "server_url": "https://mcp.example.com",
  "requires_auth": true,
  "auth_type": "bearer",
  "bearer_token": "api_key_12345",
  "is_public": false
}
​
name
string
required
Integration name (1-100 characters)
​
server_url
string
required
MCP server URL
​
requires_auth
boolean
default:"false"
Whether authentication is required
​
auth_type
string
Authentication type: none, oauth, or bearer
​
bearer_token
string
Bearer token/API key (for bearer auth)
​
is_public
boolean
default:"false"
Publish to community marketplace

​
Update Custom Integration

Update a custom integration. 
PUT /api/v1/integrations/custom/{integration_id}
Request
{
  "name": "Updated Name",
  "description": "Updated description",
  "server_url": "https://new-url.example.com"
}

​
Delete Custom Integration

Delete a custom integration. 
DELETE /api/v1/integrations/custom/{integration_id}

​
Community Marketplace

​
Browse Community Integrations

Get public integrations shared by the community. 
GET /api/v1/integrations/community
​
category
string
Filter by category
​
search
string
Search query
​
sort
string
Sort by: popular, recent, name

​
Get Public Integration

Get details of a public integration. 
GET /api/v1/integrations/public/{slug}

​
Clone Integration

Clone a public integration to your workspace. 
POST /api/v1/integrations/public/{integration_id}/clone

​
Integration Status

Integrations can have two status values:
  • created - Added to workspace but not authenticated
  • connected - Authenticated and ready to use

​
OAuth Flow

For OAuth integrations:
  1. Call /integrations/{id}/connect
  2. Redirect user to redirect_url from response
  3. User authenticates with provider
  4. Provider redirects to GAIA callback
  5. Integration status updates to connected

​
MCP Protocol

Custom MCP integrations must implement the Model Context Protocol specification:
  • /tools endpoint - List available tools
  • /call endpoint - Execute tool calls
  • Health check endpoint
See MCP Documentation for details.

​
Integration Tools

Once connected, integrations provide tools that can be used by the AI: 
// Example: Using integration tool via chat
{
  "message": "Search my Notion for project notes",
  // AI automatically uses notion.search_pages tool
}

​
Rate Limiting

Integration connection operations are rate limited:
  • Free: 10 connections/hour
  • Pro: 50 connections/hour
  • Team: 200 connections/hour
See Rate Limits for details.

​
Next Steps

Chat API

Use integrations in chat

Workflows API

Build integration workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us