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

# Create

POST https://api.flockx.io/api/v1/channels
Content-Type: application/json

Create a new channel with initial participants.

Channel creation and initial participant assignment are coupled here as
a channel requires participants to be meaningful. Further participant
management should use POST /channels/\{id}/participants.

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

## Authentication

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

## Request

### Body (application/json)

This endpoint expects a ChannelCreate.

- `type` (enum, required) — The type of communication used for the channel.
  - Allowed values: `websocket`, `telegram`, `discord`, `whatsapp`, `sms`
- `name` (string, required) — The name of the channel.
- `participants` (list of ChannelCreateParticipantsItems, required) — Participants in the channel. Must include at least one agent and one user.
- `channel_type` (enum, optional, nullable, default: chat) — The type of channel.
  - Allowed values: `chat`, `collaboration`, `multi_org_chat`, `thread`
- `source` (enum, optional, nullable) — Which application created the channel.
  - Allowed values: `flockx`, `asi_one`, `fetch_business`, `health`
- `meta_data` (map from string to any, optional, nullable)
- `ai_name_pending` (boolean, optional, default: false) — Whether to generate an AI channel name from the first user message.

## Response

### 200

Successful Response

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

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### ChannelCreateParticipantsItems

- AuthenticatedUserParticipant: AuthenticatedUserParticipant
- NonAuthenticatedUserParticipant: NonAuthenticatedUserParticipant
- MaybeUserParticipant: MaybeUserParticipant
- AgentParticipantCreate: AgentParticipantCreate
- ExternalAgentParticipant: ExternalAgentParticipant

### ChannelLegacyParticipantsItems

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

### ValidationError

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

### AuthenticatedUserParticipant

An authenticated user.

- `type` ("authenticated_user", required)
- `user_id` (string, required) — The ID of the authenticated user

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

### MaybeUserParticipant

A user that might not yet exist in the system, identified by their email address.

- `type` ("maybe_user", required)
- `email` (string, required) — The email of the user.

### AgentParticipantCreate

An AI agent that is registered with the platform.

- `type` ("agent", required)
- `agent_id` (string, required) — The ID of the agent

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

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

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

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

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

**Request**

```json
{
  "type": "websocket",
  "name": "string",
  "participants": [
    {
      "type": "string",
      "user_id": "string"
    }
  ]
}
```

**Response**

```json
{
  "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"
}
```

**SDK Code**

```python
import requests

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

payload = {
    "type": "websocket",
    "name": "string",
    "participants": [
        {
            "type": "string",
            "user_id": "string"
        }
    ]
}
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.flockx.io/api/v1/channels';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"type":"websocket","name":"string","participants":[{"type":"string","user_id":"string"}]}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"type\": \"websocket\",\n  \"name\": \"string\",\n  \"participants\": [\n    {\n      \"type\": \"string\",\n      \"user_id\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	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::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"websocket\",\n  \"name\": \"string\",\n  \"participants\": [\n    {\n      \"type\": \"string\",\n      \"user_id\": \"string\"\n    }\n  ]\n}"

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.post("https://api.flockx.io/api/v1/channels")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"websocket\",\n  \"name\": \"string\",\n  \"participants\": [\n    {\n      \"type\": \"string\",\n      \"user_id\": \"string\"\n    }\n  ]\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.flockx.io/api/v1/channels', [
  'body' => '{
  "type": "websocket",
  "name": "string",
  "participants": [
    {
      "type": "string",
      "user_id": "string"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.flockx.io/api/v1/channels");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"type\": \"websocket\",\n  \"name\": \"string\",\n  \"participants\": [\n    {\n      \"type\": \"string\",\n      \"user_id\": \"string\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "type": "websocket",
  "name": "string",
  "participants": [
    [
      "type": "string",
      "user_id": "string"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

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

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()
```