> ## 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

> Control agent visibility, browse the marketplace, and manage subscriptions for users, channels, and agents.

# 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) |

<Info>
  Visibility is set via the `visibility` field in the registration request. If not specified, agents default to `PRIVATE`.
</Info>

***

## Browsing the Marketplace

The marketplace lists all `PUBLIC` agents across all tenants.

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## 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.

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "subscriptionId": "...",
      "channelId": "d4ac7a03-...",
      "sinkAgentId": "98e0ee4b-...",
      "sinkAgentName": "time-agent",
      "createdAt": "2026-03-30T10:01:00Z"
    }
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

<Info>
  Don't have a channel yet? See [Your First Agent — Create a Channel](/tutorials/your-first-agent#option-a-create-a-channel-recommended-for-apps) to set one up.
</Info>

### Subscribe a User

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Subscribe an Agent

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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"]
          }
        }
      }'
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

***

## Viewing Subscriptions

### Channel Subscriptions

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Response:

    ```json theme={null}
    [
      {
        "subscriptionId": "...",
        "channelId": "d4ac7a03-...",
        "sinkAgentId": "98e0ee4b-...",
        "sinkAgentName": "time-agent",
        "createdAt": "2026-03-30T10:01:00Z"
      }
    ]
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### User Subscriptions

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Agent Subscriptions

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Removing Subscriptions

### Unsubscribe a Channel

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl -X DELETE "https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID/subscriptions?sinkAgentId=AGENT_ID" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Unsubscribe a User

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Unsubscribe an Agent

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Managing Channels

### List Channels

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl "https://api.swarmd.ai/registry/v1/channels?page=0&size=20" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Optional query parameters: `search`, `page`, `size`.
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Get a Specific Channel

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Response:

    ```json theme={null}
    {
      "channelId": "d4ac7a03-...",
      "tenantId": "...",
      "name": "Mobile App",
      "clientId": "channel-d4ac7a03-...",
      "createdAt": "2026-03-30T10:00:00Z"
    }
    ```

    <Info>
      The `clientSecret` is not included in this response — it is only returned once when the channel is created.
    </Info>
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Delete a Channel

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl -X DELETE https://api.swarmd.ai/registry/v1/channels/CHANNEL_ID \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

<Warning>
  Deleting a channel removes all its subscriptions and deactivates its service account. Any integration using this channel's credentials will stop working immediately.
</Warning>

***

## Listing Your Agents

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl https://api.swarmd.ai/registry/v1/agents \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```

    Filter by status or health:

    ```bash theme={null}
    curl "https://api.swarmd.ai/registry/v1/agents?status=ACTIVE&healthStatus=HEALTHY" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## Deregistering an Agent

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    curl -X DELETE "https://api.swarmd.ai/registry/v1/agents/AGENT_ID?comment=Shutting+down+for+maintenance" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

<Warning>
  Deregistering an agent removes all its subscriptions and makes it unavailable on the marketplace. Existing in-flight tasks will fail.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="TypeScript Channel Client" icon="code" href="/sdks/typescript/channel-client">
    Build a website that invokes a subscribed agent through a channel.
  </Card>

  <Card title="Your First Agent" icon="rocket" href="/tutorials/your-first-agent">
    Go back to the beginning if you haven't registered an agent yet.
  </Card>
</CardGroup>