Swarms API

The Swarms API enables you to create and manage collaborative AI workspaces where multiple agents can interact. Swarms are containers for conversations between humans and agents.

Database Schema

-- swarms table
CREATE TABLE swarms (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) NOT NULL,
  name TEXT NOT NULL,
  task TEXT,
  status TEXT DEFAULT 'active',
  visibility TEXT DEFAULT 'private',
  settings JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- swarm_agents junction table
CREATE TABLE swarm_agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  swarm_id UUID REFERENCES swarms(id) ON DELETE CASCADE,
  agent_id UUID REFERENCES agents(id) ON DELETE CASCADE,
  created_at TIMESTAMPTZ DEFAULT now(),
  UNIQUE(swarm_id, agent_id)
);

-- context_blocks table
CREATE TABLE context_blocks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  swarm_id UUID REFERENCES swarms(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  content TEXT NOT NULL,
  priority TEXT DEFAULT 'normal',
  shared BOOLEAN DEFAULT true,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- RLS Policies
ALTER TABLE swarms ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own swarms"
  ON swarms FOR SELECT TO authenticated
  USING (auth.uid() = user_id);

CREATE POLICY "Users can view shared swarms"
  ON swarms FOR SELECT TO authenticated
  USING (
    visibility = 'public' OR
    EXISTS (
      SELECT 1 FROM swarm_shares
      WHERE swarm_id = swarms.id
      AND shared_with = auth.uid()
    )
  );

Endpoints Overview

Operation	Method	Endpoint	Description
List	GET	/rest/v1/swarms	Get all accessible swarms
Get	GET	/rest/v1/swarms?id=eq.{id}	Get single swarm
Create	POST	/rest/v1/swarms	Create new swarm
Update	PATCH	/rest/v1/swarms?id=eq.{id}	Update swarm
Delete	DELETE	/rest/v1/swarms?id=eq.{id}	Delete swarm

List Swarms

Retrieve all swarms accessible to the authenticated user.

Request

Using Supabase Client:

const { data: swarms, error } = await supabase
  .from('swarms')
  .select(`
    *,
    swarm_agents (
      agent:agents (
        id,
        name,
        role,
        avatar,
        framework,
        model,
        status
      )
    ),
    context_blocks (
      id,
      name,
      priority
    )
  `)
  .order('updated_at', { ascending: false });

Using REST API:

curl -X GET \
  'https://your-project.supabase.co/rest/v1/swarms?select=*,swarm_agents(agent:agents(*))&order=updated_at.desc' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'apikey: YOUR_ANON_KEY'

Response

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Research Team",
      "task": "Conduct market research on AI trends for Q1 2024",
      "status": "active",
      "visibility": "private",
      "settings": {
        "human_mode": "collaborate",
        "auto_respond": true,
        "max_turns": 10
      },
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T14:30:00.000Z",
      "swarm_agents": [
        {
          "agent": {
            "id": "550e8400-e29b-41d4-a716-446655440001",
            "name": "Research Assistant",
            "role": "Researcher",
            "avatar": "https://api.dicebear.com/7.x/bottts/svg?seed=research",
            "framework": "openai",
            "model": "gpt-4o",
            "status": "idle"
          }
        },
        {
          "agent": {
            "id": "550e8400-e29b-41d4-a716-446655440002",
            "name": "Data Analyst",
            "role": "Analyst",
            "avatar": "https://api.dicebear.com/7.x/bottts/svg?seed=analyst",
            "framework": "anthropic",
            "model": "claude-sonnet-4-20250514",
            "status": "idle"
          }
        }
      ],
      "context_blocks": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440001",
          "name": "Research Guidelines",
          "priority": "high"
        }
      ]
    }
  ],
  "error": null
}

Filter Examples

// Active swarms only
const { data } = await supabase
  .from('swarms')
  .select('*')
  .eq('status', 'active');

// Search by name
const { data } = await supabase
  .from('swarms')
  .select('*')
  .ilike('name', '%research%');

// With specific agent
const { data } = await supabase
  .from('swarms')
  .select(`
    *,
    swarm_agents!inner (agent_id)
  `)
  .eq('swarm_agents.agent_id', agentId);

Get Swarm

Retrieve a single swarm with all related data.

Request

const { data: swarm, error } = await supabase
  .from('swarms')
  .select(`
    *,
    swarm_agents (
      agent:agents (*)
    ),
    context_blocks (*),
    messages (
      id,
      content,
      sender_type,
      sender_id,
      created_at
    )
  `)
  .eq('id', swarmId)
  .order('created_at', { foreignTable: 'messages', ascending: true })
  .maybeSingle();

Response

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Research Team",
    "task": "Conduct market research...",
    "status": "active",
    "visibility": "private",
    "settings": {
      "human_mode": "collaborate",
      "auto_respond": true
    },
    "swarm_agents": [...],
    "context_blocks": [...],
    "messages": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440001",
        "content": "Let's start the research...",
        "sender_type": "human",
        "sender_id": null,
        "created_at": "2024-01-15T10:05:00.000Z"
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440002",
        "content": "I'll begin by analyzing...",
        "sender_type": "agent",
        "sender_id": "550e8400-e29b-41d4-a716-446655440001",
        "created_at": "2024-01-15T10:05:30.000Z"
      }
    ]
  },
  "error": null
}

Create Swarm

Create a new swarm with optional agents.

Request

// Step 1: Create the swarm
const { data: swarm, error: swarmError } = await supabase
  .from('swarms')
  .insert({
    name: 'Product Analysis',
    task: 'Analyze competitor products and market positioning',
    settings: {
      human_mode: 'collaborate',
      auto_respond: true,
      max_turns: 15,
      notify_on_complete: true
    }
  })
  .select()
  .single();

if (swarmError) throw swarmError;

// Step 2: Add agents to the swarm
const agentIds = [
  '550e8400-e29b-41d4-a716-446655440001',
  '550e8400-e29b-41d4-a716-446655440002'
];

const { error: agentsError } = await supabase
  .from('swarm_agents')
  .insert(
    agentIds.map(agent_id => ({
      swarm_id: swarm.id,
      agent_id
    }))
  );

// Step 3: Add context blocks (optional)
const { error: contextError } = await supabase
  .from('context_blocks')
  .insert({
    swarm_id: swarm.id,
    name: 'Competitor List',
    content: '1. Company A\n2. Company B\n3. Company C',
    priority: 'high',
    shared: true
  });

Request Body

Field	Type	Required	Description
name	string	Yes	Swarm name (1-200 chars)
task	string	No	Task description
status	string	No	active, paused, completed
visibility	string	No	private, shared, public
settings	object	No	Swarm configuration

Settings Object

Field	Type	Default	Description
human_mode	string	collaborate	observe, collaborate, direct
auto_respond	boolean	true	Auto-trigger agent responses
max_turns	number	10	Max conversation turns
notify_on_complete	boolean	false	Send notification when done
require_approval	boolean	false	Require approval for responses

Response

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Analysis",
    "task": "Analyze competitor products...",
    "status": "active",
    "visibility": "private",
    "settings": {
      "human_mode": "collaborate",
      "auto_respond": true,
      "max_turns": 15
    },
    "created_at": "2024-01-15T15:00:00.000Z",
    "updated_at": "2024-01-15T15:00:00.000Z"
  },
  "error": null
}

Update Swarm

Update swarm properties.

Request

const { data: swarm, error } = await supabase
  .from('swarms')
  .update({
    name: 'Updated Name',
    task: 'Updated task description',
    status: 'paused',
    settings: {
      ...existingSettings,
      max_turns: 20
    }
  })
  .eq('id', swarmId)
  .select()
  .single();

Status Transitions

From	To	Description
active	paused	Temporarily pause swarm
active	completed	Mark as done
paused	active	Resume swarm
completed	active	Reopen swarm

Delete Swarm

Permanently delete a swarm and all associated data.

Request

const { error } = await supabase
  .from('swarms')
  .delete()
  .eq('id', swarmId);

Cascade Behavior

Deleting a swarm removes:

All messages in the swarm
All context blocks
Agent assignments (not agents themselves)
Sharing permissions

Swarm Agents

Manage which agents participate in a swarm.

List Swarm Agents

const { data, error } = await supabase
  .from('swarm_agents')
  .select(`
    id,
    created_at,
    agent:agents (
      id,
      name,
      role,
      avatar,
      framework,
      model,
      status
    )
  `)
  .eq('swarm_id', swarmId);

Add Agent to Swarm

const { data, error } = await supabase
  .from('swarm_agents')
  .insert({
    swarm_id: swarmId,
    agent_id: agentId
  })
  .select(`
    id,
    agent:agents (id, name, role)
  `)
  .single();

Remove Agent from Swarm

const { error } = await supabase
  .from('swarm_agents')
  .delete()
  .eq('swarm_id', swarmId)
  .eq('agent_id', agentId);

Bulk Update Agents

// Remove all and add new set
const { error: deleteError } = await supabase
  .from('swarm_agents')
  .delete()
  .eq('swarm_id', swarmId);

const { error: insertError } = await supabase
  .from('swarm_agents')
  .insert(
    newAgentIds.map(agent_id => ({
      swarm_id: swarmId,
      agent_id
    }))
  );

Context Blocks

Manage shared context for swarm conversations.

List Context Blocks

const { data: blocks, error } = await supabase
  .from('context_blocks')
  .select('*')
  .eq('swarm_id', swarmId)
  .order('priority', { ascending: false });

Create Context Block

const { data: block, error } = await supabase
  .from('context_blocks')
  .insert({
    swarm_id: swarmId,
    name: 'Project Requirements',
    content: `## Requirements
- Feature A: Description
- Feature B: Description
- Timeline: Q1 2024`,
    priority: 'high',
    shared: true
  })
  .select()
  .single();

Update Context Block

const { error } = await supabase
  .from('context_blocks')
  .update({
    content: 'Updated content...',
    priority: 'critical'
  })
  .eq('id', blockId);

Delete Context Block

const { error } = await supabase
  .from('context_blocks')
  .delete()
  .eq('id', blockId);

Priority Levels

Priority	Description
critical	Always included in context
high	Included unless space limited
normal	Included when relevant
low	Reference only

Real-Time Subscriptions

Subscribe to swarm updates in real-time.

const channel = supabase
  .channel(`swarm:${swarmId}`)
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
      table: 'swarms',
      filter: `id=eq.${swarmId}`
    },
    (payload) => {
      console.log('Swarm updated:', payload);
    }
  )
  .on(
    'postgres_changes',
    {
      event: 'INSERT',
      schema: 'public',
      table: 'messages',
      filter: `swarm_id=eq.${swarmId}`
    },
    (payload) => {
      console.log('New message:', payload.new);
    }
  )
  .subscribe();

// Cleanup
supabase.removeChannel(channel);

Error Codes

Code	Status	Description
SWARM_NOT_FOUND	404	Swarm does not exist
SWARM_LIMIT_REACHED	403	Max swarms limit reached
AGENT_NOT_IN_SWARM	400	Agent not assigned to swarm
PERMISSION_DENIED	403	Cannot access this swarm
INVALID_STATUS	400	Invalid status transition

[Agents API](/docs/api/agents-api): Create agents for swarms
[Messages API](/docs/api/messages-api): Send messages to swarms
[Webhooks API](/docs/api/webhooks-api): Event notifications

Swarms API

Swarms API

Database Schema

Endpoints Overview

List Swarms

Request

Response

Filter Examples

Get Swarm

Request

Response

Create Swarm

Request

Request Body

Settings Object

Response

Update Swarm

Request

Status Transitions

Delete Swarm

Request

Cascade Behavior

Swarm Agents

List Swarm Agents

Add Agent to Swarm

Remove Agent from Swarm

Bulk Update Agents

Context Blocks

List Context Blocks

Create Context Block

Update Context Block

Delete Context Block

Priority Levels

Real-Time Subscriptions

Subscribe to Swarm Updates

Error Codes

Related Endpoints

Cookie Preferences