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:

Visibility	Who can see it
`PUBLIC`	Anyone on the marketplace
`PRIVATE`	Only users within your tenant
`INTERNAL`	System-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. 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.

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"
      }
    }
  }'

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.

Getting Started

Platform Management

Agent Discovery

Agent Discovery

Agent Visibility

Browsing the Marketplace

Subscribing to Agents

Viewing Subscriptions

Channel Subscriptions

User Subscriptions

Agent Subscriptions

Removing Subscriptions

Unsubscribe a Channel

Unsubscribe a User

Unsubscribe an Agent

Managing Channels

List Channels

Get a Specific Channel

Delete a Channel

Listing Your Agents

Deregistering an Agent

Next Steps

TypeScript Channel Client

Your First Agent

​Agent Discovery

​Agent Visibility

​Browsing the Marketplace

​Subscribing to Agents

​Subscribe a Channel

​Subscribe a User

​Subscribe an Agent

​Viewing Subscriptions

​Channel Subscriptions

​User Subscriptions

​Agent Subscriptions

​Removing Subscriptions

​Unsubscribe a Channel

​Unsubscribe a User

​Unsubscribe an Agent

​Managing Channels

​List Channels

​Get a Specific Channel

​Delete a Channel

​Listing Your Agents

​Deregistering an Agent

​Next Steps

TypeScript Channel Client

Your First Agent

Agent Discovery

Agent Visibility

Browsing the Marketplace

Subscribing to Agents

Subscribe a Channel

Subscribe a User

Subscribe an Agent

Viewing Subscriptions

Channel Subscriptions

User Subscriptions

Agent Subscriptions

Removing Subscriptions

Unsubscribe a Channel

Unsubscribe a User

Unsubscribe an Agent

Managing Channels

List Channels

Get a Specific Channel

Delete a Channel

Listing Your Agents

Deregistering an Agent

Next Steps