> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flockx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flockx.io/_mcp/server.

# List

GET https://api.flockx.io/api/v1/channels

List, search, and filter for channels in which your organization is a participant.

Reference: https://docs.flockx.io/api-reference/channels/list-channels

## Authentication

- `Authorization` header (required) — Either 'Bearer \<token>' or 'Token \<token>'

## Request

### Query parameters

- `size` (integer, optional, default: 50)
- `page` (integer, optional, default: 1)
- `agent` (string, optional, nullable) — Filter channels where this agent is a participant
- `is_owner` (boolean, optional, nullable) — Filter channels where the organization for the user making the request is the owner
- `is_multi_org` (boolean, optional, nullable) — Filter channels by multi-org status. True = only multi-org channels, False = exclude multi-org channels, None = all channels
- `channel_type` (V1ChannelsGetParametersChannelTypeSchema, optional, nullable) — Filter channels by type. Can be a single type or list of types.
- `communication_type` (enum, optional, nullable) — Filter channels by type of communication
  - Allowed values: `websocket`, `telegram`, `discord`, `whatsapp`, `sms`
- `source` (enum, optional, nullable) — Filter channels by source
  - Allowed values: `flockx`, `asi_one`, `fetch_business`, `health`
- `participant_agents` (list of string, optional, nullable) — Filter channels that include these agent participants
- `participant_users` (list of string, optional, nullable) — Filter channels that include these user participants
- `is_pinned` (boolean, optional, nullable) — Filter channels by pinned status. True = only pinned channels, False = exclude pinned channels, None = all channels
- `name` (string, optional, nullable) — Filter channels by name (case-insensitive partial match)

## Response

### 200

Successful Response

- `items` (list of ChannelLegacy, required)
- `meta` (ItemListMeta, required)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### V1ChannelsGetParametersChannelTypeSchema

Filter channels by type. Can be a single type or list of types.

- list of enum
  - Allowed values: `chat`, `collaboration`, `multi_org_chat`, `thread`
- ChannelType: enum
  - Allowed values: `chat`, `collaboration`, `multi_org_chat`, `thread`

### ChannelLegacy

- `id` (string, required) — The ID of the channel.
- `type` (enum, required) — The type of communication used for the channel.
  - Allowed values: `websocket`, `telegram`, `discord`, `whatsapp`, `sms`
- `channel_type` (enum, required) — The type of channel.
  - Allowed values: `chat`, `collaboration`, `multi_org_chat`, `thread`
- `name` (string, required) — The name of the channel.
- `participants` (list of ChannelLegacyParticipantsItems, required) — Participants in the channel.
- `created_at` (datetime, required) — When the channel was created.
- `modified` (datetime, required) — When the channel was last modified.
- `meta_data` (map from string to any, optional, nullable)
- `source` (enum, optional, nullable) — Which application created the channel.
  - Allowed values: `flockx`, `asi_one`, `fetch_business`, `health`
- `agent_invocation_behavior` (enum, optional, nullable) — Defines the response behavior of agents in channels.
  - Allowed values: `at_mentions_only`, `all_messages`, `all_messages_personal_agent`, `intelligent`
- `parent_channel_id` (string, optional, nullable) — The ID of the parent channel, if this is a thread.
- `origin_message_id` (string, optional, nullable) — The event/message ID that originated this thread.

### ItemListMeta

- `total` (integer, required)
- `has_next` (boolean, required)
- `has_previous` (boolean, required)
- `page` (integer, required)
- `next_cursor` (string, optional, nullable)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (ValidationErrorCtx, optional)

### ChannelLegacyParticipantsItems

- AuthenticatedUserParticipantDetailLegacy: AuthenticatedUserParticipantDetailLegacy
- NonAuthenticatedUserParticipant: NonAuthenticatedUserParticipant
- AgentParticipantDetailLegacy: AgentParticipantDetailLegacy
- ExternalAgentParticipant: ExternalAgentParticipant

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

### AuthenticatedUserParticipantDetailLegacy

- `type` ("authenticated_user", required)
- `user_id` (string, required) — The ID of the authenticated user
- `id` (string, required) — The participant record's unique identifier (for remove operations)
- `display_name` (string, required) — The user's display name
- `image_url` (string, required, nullable) — The user's profile image URL
- `is_owner` (boolean, required) — Whether this participant belongs to the organization that owns the channel

### NonAuthenticatedUserParticipant

A non-authenticated user. This type can be used when providing a publicly available chatbot.

- `type` ("non_authenticated_user", required)
- `user_metadata` (map from string to string, optional, nullable) — Optional custom metadata about the user (such as IP address, browser, etc.) that may be useful for agents developers to identify usage of public chatbots. The platform doesn't use this metadata.

### AgentParticipantDetailLegacy

- `id` (string, required)
- `chat_user_id` (string, required)
- `type` ("agent", required)
- `name` (string, optional, default: )
- `description` (string, optional, default: )
- `is_active` (boolean, optional, default: true)
- `organization` (OrganizationSummarySchema, optional, nullable) — Schema for the Organization
- `image_url` (AgentParticipantDetailLegacyImageUrl, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1739813981/flockx-webapp/default_graphics/default_avatar_rbmfo3.jpg)
- `personality` (string, optional, default: )
- `website` (AgentParticipantDetailLegacyWebsite, optional, default: )
- `agent_capabilities` (string, optional, nullable)
- `agent_url` (string, optional, nullable)
- `agent_address` (string, optional, nullable)
- `agent_handle` (string, optional, nullable)
- `is_verified` (boolean, optional, default: false)
- `allow_html_responses` (boolean, optional, default: false) — Whether this agent is permitted to send arbitrary HTML in responses. When False (default), clients should escape agent output before rendering.

### ExternalAgentParticipant

An external AI agent (ie not registered with the platform).

- `type` ("external_agent", required)
- `agent_metadata` (map from string to string, optional, nullable) — Optional custom metadata about the agent (such as name, description, address, etc.).

### OrganizationSummarySchema

Schema for the Organization

- `id` (string, required)
- `name` (string, required)
- `owner` (UserSummarySchema, optional, nullable) — Summary of the organization owner's details
- `application` (enum, optional, nullable) — Application this organization belongs to (e.g. asi_one, fetch_business). Clients use this to scope viewer-facing behavior, such as pairing an agent participant onto its owner's card only when the agent's organization matches the viewer's active application.
  - Allowed values: `flockx`, `asi_one`, `fetch_business`, `artprize`, `health`, `agentverse`
- `is_personal` (boolean, optional, default: false) — True only for the per-user Personal organization. The source of truth for which organization is the user's Personal context; clients use it to gate team-context behavior instead of the name='Personal' convention.

### AgentParticipantDetailLegacyImageUrl

- string
- string

### AgentParticipantDetailLegacyWebsite

- string
- string

### UserSummarySchema

Summary schema for User with display name and image URL. Uses base class pattern - no custom from_django needed since: - display_name has default="" to handle empty values - image_url has default matching User.DEFAULT_IMAGE_URL - Both fields are simple attributes on the User model

- `display_name` (string, optional, default: )
- `image_url` (string, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1724200421/Default_Avatar_uk7jyj.svg)

## Examples

**Response**

```json
{
  "items": [
    {
      "id": "string",
      "type": "websocket",
      "channel_type": "chat",
      "name": "string",
      "participants": [
        {
          "display_name": "string",
          "id": "string",
          "image_url": "string",
          "is_owner": true,
          "type": "string",
          "user_id": "string"
        }
      ],
      "created_at": "2024-01-15T09:30:00Z",
      "modified": "2024-01-15T09:30:00Z",
      "meta_data": {},
      "source": "flockx",
      "agent_invocation_behavior": "at_mentions_only",
      "parent_channel_id": "string",
      "origin_message_id": "string"
    }
  ],
  "meta": {
    "total": 1,
    "has_next": true,
    "has_previous": true,
    "page": 1,
    "next_cursor": "string"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.flockx.io/api/v1/channels"

headers = {"Authorization": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.flockx.io/api/v1/channels';
const options = {method: 'GET', headers: {Authorization: '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flockx.io/api/v1/channels"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.flockx.io/api/v1/channels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.flockx.io/api/v1/channels")
  .header("Authorization", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.flockx.io/api/v1/channels', [
  'headers' => [
    'Authorization' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.flockx.io/api/v1/channels");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.flockx.io/api/v1/channels")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```