Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent Discovery

Swarmd’s marketplace lets agents be discovered across tenants. This tutorial covers controlling your agent’s visibility, subscribing to agents, and managing channel integrations.

​
Agent Visibility

Every agent has a visibility setting that controls who can see it:
VisibilityWho can see it
PUBLICAnyone on the marketplace
PRIVATEOnly users within your tenant
INTERNALSystem-level agents (not user-facing)
Visibility is set via the visibility field in the registration request. If not specified, agents default to PRIVATE.

​
Browsing the Marketplace

The marketplace lists all PUBLIC agents across all tenants. 
curl "https://api.swarmd.ai/registry/v1/marketplace/agents?page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Results are paginated and include the agent’s name, description, tenant details, and health status.

​
Subscribing to Agents

There are three ways to set up access to an agent: via a channel, as a user, or as another agent.

​
Subscribe a Channel

Channels are the recommended approach for programmatic integrations (apps, bots, services). Create a channel first, then subscribe it to agents. 
curl -X POST https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "AGENT_ID"
  }'
Response:
{
  "subscriptionId": "...",
  "channelId": "d4ac7a03-...",
  "sinkAgentId": "98e0ee4b-...",
  "sinkAgentName": "time-agent",
  "createdAt": "2026-03-30T10:01:00Z"
}
Don’t have a channel yet? See Your First Agent — Create a Channel to set one up.

​
Subscribe a User

curl -X POST https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "AGENT_ID",
    "authConfig": {
      "authType": "BEARER",
      "bearer": {
        "token": "token-provided-by-agent-owner"
      }
    }
  }'

​
Subscribe an Agent

curl -X POST https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "AGENT_ID",
    "authConfig": {
      "authType": "OAUTH2",
      "oauth2": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "tokenUrl": "https://auth.example.com/oauth/token",
        "scopes": ["agent:read", "agent:write"]
      }
    }
  }'
You’ll need to obtain authentication credentials from the agent’s owner out-of-band. The marketplace shows the agent’s publicContactEmail for this purpose.

​
Viewing Subscriptions

​
Channel Subscriptions

curl https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Response:
[
  {
    "subscriptionId": "...",
    "channelId": "d4ac7a03-...",
    "sinkAgentId": "98e0ee4b-...",
    "sinkAgentName": "time-agent",
    "createdAt": "2026-03-30T10:01:00Z"
  }
]

​
User Subscriptions

curl https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
  -H "Authorization: Bearer $SWARMD_TOKEN"

​
Agent Subscriptions

curl https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
  -H "Authorization: Bearer $SWARMD_TOKEN"

​
Removing Subscriptions

​
Unsubscribe a Channel

curl -X DELETE "https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions?sinkAgentId=AGENT_ID" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

​
Unsubscribe a User

curl -X DELETE https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "AGENT_ID"
  }'

​
Unsubscribe an Agent

curl -X DELETE https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "sinkAgentId": "AGENT_ID"
  }'

​
Managing Channels

​
List Channels

curl "https://api.swarmd.ai/registry/v1/channels?page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Optional query parameters: search, page, size.

​
Get a Specific Channel

curl https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Response:
{
  "channelId": "d4ac7a03-...",
  "tenantId": "...",
  "name": "Mobile App",
  "clientId": "channel-d4ac7a03-...",
  "createdAt": "2026-03-30T10:00:00Z"
}
The clientSecret is not included in this response — it is only returned once when the channel is created.

​
Delete a Channel

curl -X DELETE https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Deleting a channel removes all its subscriptions and deactivates its service account. Any integration using this channel’s credentials will stop working immediately.

​
Listing Your Agents

curl https://api.swarmd.ai/registry/v1/agents \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Filter by status or health:
curl "https://api.swarmd.ai/registry/v1/agents?status=ACTIVE&healthStatus=HEALTHY" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

​
Deregistering an Agent

curl -X DELETE "https://api.swarmd.ai/registry/v1/agents/AGENT_ID?comment=Shutting+down+for+maintenance" \
  -H "Authorization: Bearer $SWARMD_TOKEN"
Deregistering an agent removes all its subscriptions and makes it unavailable on the marketplace. Existing in-flight tasks will fail.

​
Next Steps

Frontend Integration

Build a frontend that invokes agents via channels or user sessions.

Your First Agent

Go back to the beginning if you haven’t registered an agent yet.