# Channel API Reference

OpenAPI source: https://api.are.na/v3/openapi.json

## GET /v3/channels/{id}

- Label: Get a channel
- Docs: https://www.are.na/developers/explore/channel
- Markdown: https://www.are.na/developers/explore/channel.md
- Requires resource id: yes
- Response content type: application/json

Returns detailed information about a specific channel by its ID or slug. Respects visibility rules and user permissions.

Response schema:
```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "slug",
    "title",
    "state",
    "visibility",
    "created_at",
    "updated_at",
    "owner",
    "counts",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "nullable": false,
      "description": "Unique identifier for the channel",
      "example": 12345
    },
    "type": {
      "type": "string",
      "nullable": false,
      "description": "Channel type",
      "enum": [
        "Channel"
      ],
      "example": "Channel"
    },
    "slug": {
      "type": "string",
      "nullable": false,
      "description": "Channel URL slug",
      "example": "my-collection-abc123"
    },
    "title": {
      "type": "string",
      "nullable": false,
      "description": "Channel title",
      "example": "My Collection"
    },
    "description": {
      "type": "oneOf",
      "description": "Channel description with multiple renderings",
      "variants": [
        {
          "type": "object",
          "description": "Markdown content with multiple renderings",
          "required": [
            "markdown",
            "html",
            "plain"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "nullable": false,
              "description": "Original markdown value",
              "example": "This is **only** a [test](https://example.com)."
            },
            "html": {
              "type": "string",
              "nullable": false,
              "description": "HTML rendering of the markdown",
              "example": "<p>This is <strong>only</strong> a <a href=\"https://example.com\" target=\"_blank\" rel=\"nofollow noopener\">test</a>.</p>"
            },
            "plain": {
              "type": "string",
              "nullable": false,
              "description": "Plain text rendering of the markdown",
              "example": "This is only a test (https://example.com)."
            }
          },
          "refName": "MarkdownContent"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "state": {
      "type": "string",
      "nullable": false,
      "description": "Lifecycle state of a channel.\n- `available`: Active and accessible\n- `deleted`: Soft deleted\n",
      "enum": [
        "available",
        "deleted"
      ],
      "refName": "ChannelState"
    },
    "visibility": {
      "type": "string",
      "nullable": false,
      "description": "Visibility level of a channel:\n- `public`: Anyone can view and connect to the channel\n- `private`: Only the owner and collaborators can view\n- `closed`: Anyone can view, but only collaborators can add content\n",
      "enum": [
        "public",
        "private",
        "closed"
      ],
      "refName": "ChannelVisibility"
    },
    "created_at": {
      "type": "string",
      "nullable": false,
      "description": "When the channel was created",
      "format": "date-time",
      "example": "2023-01-15T10:30:00Z"
    },
    "updated_at": {
      "type": "string",
      "nullable": false,
      "description": "When the channel was last updated",
      "format": "date-time",
      "example": "2023-01-15T14:45:00Z"
    },
    "metadata": {
      "type": "oneOf",
      "description": "Custom key-value metadata",
      "variants": [
        {
          "type": "object",
          "description": "Arbitrary key-value pairs stored on an entity.\nKeys are alphanumeric/underscore, max 40 characters.\nValues are scalars (string, number, boolean). Max 50 keys, 32KB total.\n",
          "required": [],
          "properties": {},
          "additionalProperties": {
            "type": "oneOf",
            "variants": [
              {
                "type": "string",
                "nullable": false
              },
              {
                "type": "number",
                "nullable": false
              },
              {
                "type": "boolean",
                "nullable": false
              }
            ]
          },
          "refName": "Metadata"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "owner": {
      "type": "oneOf",
      "description": "Channel owner (User or Group)",
      "variants": [
        {
          "type": "object",
          "description": "Embedded user representation (used when user is nested in other resources)",
          "required": [
            "id",
            "type",
            "name",
            "slug",
            "avatar",
            "initials"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the user",
              "example": 12345
            },
            "type": {
              "type": "string",
              "nullable": false,
              "description": "User type",
              "enum": [
                "User"
              ],
              "example": "User"
            },
            "name": {
              "type": "string",
              "nullable": false,
              "description": "User's display name",
              "example": "John Doe"
            },
            "slug": {
              "type": "string",
              "nullable": false,
              "description": "URL-safe identifier (use this in API paths)",
              "example": "john-doe"
            },
            "avatar": {
              "type": "string",
              "nullable": true,
              "description": "URL to user's avatar image",
              "format": "uri",
              "example": "https://d2w9rnfcy7mm78.cloudfront.net/12345/avatar.jpg"
            },
            "initials": {
              "type": "string",
              "nullable": false,
              "description": "User's initials",
              "example": "JD"
            }
          },
          "refName": "EmbeddedUser"
        },
        {
          "type": "object",
          "description": "Embedded group representation (used when group is nested in other resources)",
          "required": [
            "id",
            "type",
            "name",
            "slug",
            "avatar",
            "initials"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the group",
              "example": 67890
            },
            "type": {
              "type": "string",
              "nullable": false,
              "description": "Group type",
              "enum": [
                "Group"
              ],
              "example": "Group"
            },
            "name": {
              "type": "string",
              "nullable": false,
              "description": "Group's name",
              "example": "Design Team"
            },
            "slug": {
              "type": "string",
              "nullable": false,
              "description": "Group's URL slug",
              "example": "design-team-abc123"
            },
            "avatar": {
              "type": "string",
              "nullable": true,
              "description": "URL to group's avatar image",
              "format": "uri",
              "example": "https://d2w9rnfcy7mm78.cloudfront.net/groups/67890/avatar.jpg"
            },
            "initials": {
              "type": "string",
              "nullable": false,
              "description": "Group's initials",
              "example": "DT"
            }
          },
          "refName": "EmbeddedGroup"
        }
      ],
      "refName": "ChannelOwner"
    },
    "counts": {
      "type": "object",
      "description": "Counts of various items in the channel",
      "required": [
        "blocks",
        "channels",
        "contents",
        "collaborators"
      ],
      "properties": {
        "blocks": {
          "type": "integer",
          "nullable": false,
          "description": "Number of blocks in the channel",
          "example": 42
        },
        "channels": {
          "type": "integer",
          "nullable": false,
          "description": "Number of channels connected to this channel",
          "example": 8
        },
        "contents": {
          "type": "integer",
          "nullable": false,
          "description": "Total number of contents (blocks + channels)",
          "example": 50
        },
        "collaborators": {
          "type": "integer",
          "nullable": false,
          "description": "Number of collaborators on the channel",
          "example": 3
        }
      },
      "refName": "ChannelCounts"
    },
    "collaborators": {
      "type": "array",
      "description": "Collaborators on this channel (users and groups).\nOnly present when channel is returned as a full resource, not when embedded.\n",
      "items": {
        "type": "oneOf",
        "description": "Channel collaborator (User or Group)",
        "variants": [
          {
            "type": "object",
            "description": "Embedded user representation (used when user is nested in other resources)",
            "required": [
              "id",
              "type",
              "name",
              "slug",
              "avatar",
              "initials"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "nullable": false,
                "description": "Unique identifier for the user",
                "example": 12345
              },
              "type": {
                "type": "string",
                "nullable": false,
                "description": "User type",
                "enum": [
                  "User"
                ],
                "example": "User"
              },
              "name": {
                "type": "string",
                "nullable": false,
                "description": "User's display name",
                "example": "John Doe"
              },
              "slug": {
                "type": "string",
                "nullable": false,
                "description": "URL-safe identifier (use this in API paths)",
                "example": "john-doe"
              },
              "avatar": {
                "type": "string",
                "nullable": true,
                "description": "URL to user's avatar image",
                "format": "uri",
                "example": "https://d2w9rnfcy7mm78.cloudfront.net/12345/avatar.jpg"
              },
              "initials": {
                "type": "string",
                "nullable": false,
                "description": "User's initials",
                "example": "JD"
              }
            },
            "refName": "EmbeddedUser"
          },
          {
            "type": "object",
            "description": "Embedded group representation (used when group is nested in other resources)",
            "required": [
              "id",
              "type",
              "name",
              "slug",
              "avatar",
              "initials"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "nullable": false,
                "description": "Unique identifier for the group",
                "example": 67890
              },
              "type": {
                "type": "string",
                "nullable": false,
                "description": "Group type",
                "enum": [
                  "Group"
                ],
                "example": "Group"
              },
              "name": {
                "type": "string",
                "nullable": false,
                "description": "Group's name",
                "example": "Design Team"
              },
              "slug": {
                "type": "string",
                "nullable": false,
                "description": "Group's URL slug",
                "example": "design-team-abc123"
              },
              "avatar": {
                "type": "string",
                "nullable": true,
                "description": "URL to group's avatar image",
                "format": "uri",
                "example": "https://d2w9rnfcy7mm78.cloudfront.net/groups/67890/avatar.jpg"
              },
              "initials": {
                "type": "string",
                "nullable": false,
                "description": "Group's initials",
                "example": "DT"
              }
            },
            "refName": "EmbeddedGroup"
          }
        ],
        "refName": "ChannelCollaborator"
      }
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "description": "A hypermedia link containing the URL of a linked resource.\nThe relationship type is expressed by the key in the parent _links object.\n",
          "required": [
            "href"
          ],
          "properties": {
            "href": {
              "type": "string",
              "nullable": false,
              "description": "The URL of the linked resource",
              "format": "uri",
              "example": "https://api.are.na/v3/blocks/12345"
            }
          },
          "refName": "Link"
        }
      },
      "required": [
        "self"
      ],
      "description": "HATEOAS links for navigation and discovery.\nFollows HAL (Hypertext Application Language) format where link relationships \nare expressed as object keys (e.g., \"self\", \"user\", \"channels\").\n"
    },
    "connection": {
      "type": "oneOf",
      "description": "Connection context (only present when channel is returned as part of another channel's contents).\nContains position, pinned status, and information about who connected the channel.\n",
      "variants": [
        {
          "type": "object",
          "description": "Embedded connection representation used when connection is nested in other resources",
          "required": [
            "id",
            "position",
            "pinned",
            "connected_at",
            "connected_by"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the connection",
              "example": 98765
            },
            "position": {
              "type": "integer",
              "nullable": false,
              "description": "Position of the item within the channel (1-indexed)",
              "example": 1
            },
            "pinned": {
              "type": "boolean",
              "nullable": false,
              "description": "Whether the item is pinned",
              "example": false
            },
            "metadata": {
              "type": "oneOf",
              "description": "Custom key-value metadata",
              "variants": [
                {
                  "type": "object",
                  "description": "Arbitrary key-value pairs stored on an entity.\nKeys are alphanumeric/underscore, max 40 characters.\nValues are scalars (string, number, boolean). Max 50 keys, 32KB total.\n",
                  "…": "see OpenAPI spec for full schema"
                },
                {
                  "type": "unknown",
                  "nullable": true
                }
              ]
            },
            "connected_at": {
              "type": "string",
              "nullable": false,
              "description": "When the item was connected",
              "format": "date-time",
              "example": "2023-01-15T10:30:00Z"
            },
            "connected_by": {
              "type": "oneOf",
              "description": "User who created this connection",
              "variants": [
                {
                  "type": "object",
                  "description": "Embedded user representation (used when user is nested in other resources)",
                  "…": "see OpenAPI spec for full schema"
                },
                {
                  "type": "unknown",
                  "nullable": true
                }
              ]
            }
          },
          "refName": "EmbeddedConnection"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "can": {
      "type": "oneOf",
      "description": "Actions the current user can perform on this channel.\nOnly present when channel is returned as a full resource, not when embedded.\n",
      "variants": [
        {
          "type": "object",
          "description": "Actions the current user can perform on the channel",
          "required": [
            "add_to",
            "update",
            "destroy",
            "manage_collaborators"
          ],
          "properties": {
            "add_to": {
              "type": "boolean",
              "nullable": false,
              "description": "Whether the user can add blocks to this channel",
              "example": true
            },
            "update": {
              "type": "boolean",
              "nullable": false,
              "description": "Whether the user can update this channel",
              "example": false
            },
            "destroy": {
              "type": "boolean",
              "nullable": false,
              "description": "Whether the user can delete this channel",
              "example": false
            },
            "manage_collaborators": {
              "type": "boolean",
              "nullable": false,
              "description": "Whether the user can add/remove collaborators",
              "example": false
            }
          },
          "refName": "ChannelAbilities"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    }
  },
  "refName": "Channel"
}
```