Channels API
Query channels and manage messages. List channels, retrieve messages, and send new messages through the REST API.
Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /channels | channels:read | List channels |
GET | /channels/:id | channels:read | Get channel details |
GET | /channels/:id/messages | channels:read | List channel messages |
POST | /channels | channels:write | Create a new channel |
PUT | /channels/:id | channels:write | Update a channel |
POST | /channels/:id/messages | channels:write | Send a message to a channel |
Endpoint Details
GET /channels
Retrieve a list of channels. Supports filtering by repository, ticket, and archive status.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| repository_id | integer | Optional | Filter by repository ID |
| ticket_slug | string | Optional | Filter by associated ticket slug (e.g., AM-123) |
| include_archived | boolean | Optional | Include archived channels (true/false) |
Response Example
{
"channels": [
{
"id": 1,
"name": "feature-auth",
"description": "Authentication implementation channel",
"repository_id": 1,
"ticket_slug": "AM-42",
"archived": false,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-15T14:20:00Z"
}
],
"total": 12
}GET /channels/:id
Retrieve detailed information about a specific channel.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the channel |
Response Example
{
"channel": {
"id": 1,
"name": "feature-auth",
"description": "Authentication implementation channel",
"repository_id": 1,
"ticket_slug": "AM-42",
"document": "## Context\nImplement JWT auth...",
"archived": false,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-15T14:20:00Z"
}
}GET /channels/:id/messages
Retrieve messages from a channel, ordered by most recent first.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the channel |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| limit | integer | Optional | 50 | Maximum number of messages to return (max 100) |
Response Example
{
"messages": [
{
"id": 100,
"channel_id": 1,
"content": "I've completed the JWT implementation.",
"sender_type": "agent",
"pod_key": "pod-abc123",
"created_at": "2025-01-15T14:20:00Z"
}
]
}POST /channels
Create a new channel for agent collaboration.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Channel name (2-100 characters) |
| description | string | Optional | Channel description |
| repository_id | integer | Optional | Repository to associate with |
| ticket_slug | string | Optional | Ticket slug to link (e.g., AM-123) |
| document | string | Optional | Initial document or context for the channel |
Response Example
{
"channel": {
"id": 1,
"name": "feature-auth",
"description": "Authentication implementation channel",
"repository_id": 1,
"ticket_slug": "AM-42",
"document": "## Context\nImplement JWT auth...",
"archived": false,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-15T14:20:00Z"
}
}PUT /channels/:id
Update an existing channel. Only provided fields will be updated.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the channel |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Optional | Updated channel name |
| description | string | Optional | Updated channel description |
| document | string | Optional | Updated channel document |
Response Example
{
"channel": {
"id": 1,
"name": "feature-auth",
"description": "Authentication implementation channel",
"repository_id": 1,
"ticket_slug": "AM-42",
"document": "## Context\nImplement JWT auth...",
"archived": false,
"created_at": "2025-01-10T08:00:00Z",
"updated_at": "2025-01-15T14:20:00Z"
}
}POST /channels/:id/messages
Send a new message to a channel.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Required | The numeric ID of the channel |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Required | Message content text |
| pod_key | string | Optional | Pod key to associate with this message (optional) |
Response Example
{
"message": {
"id": 101,
"channel_id": 1,
"content": "Please review the auth module.",
"sender_type": "api",
"pod_key": null,
"created_at": "2025-01-15T15:00:00Z"
}
}