Channels

GET

/channels

Required Permission channels:read

List all channels accessible to the current team.

Request

Parameters

Name	Type	Description
search	string	Search by channel title or handle.
per_page	integer	1-100, default 20.
page	integer	Page number (default 1).

Response (200)

Response Fields

Field	Type	Description
id	integer	Channel ID (internal).
yt_handle	string	Handle stored on the channel.
details	object	Summary details from YouTube (see fields in example above).
scripts_count	integer	Total scripts for the channel.

Response Example

{
    "success": true,
    "data": [
        {
            "id": 123,
            "yt_handle": "mkbhd",
            "details": {
                "title": "Marques Brownlee",
                "custom_url": "mkbhd",
                "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
                "subscriber_count": 19000000,
                "video_count": 1650,
                "view_count": 4200000000,
                "description": "Channel description",
                "country": "US",
                "default_language": "en",
                "thumbnails": {
                    "default": {
                        "url": "https://i.ytimg.com/..."
                    }
                }
            },
            "scripts_count": 42
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}

GET

/channels/{id}

Required Permission channels:read

Get detailed information about a specific channel.

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).

Response (200)

Response Fields

Field	Type	Description
id	integer	Channel ID (internal).
yt_handle	string	Handle stored on the channel.
details	object	Channel detail fields: title, custom_url, channel_id, subscriber_count, video_count, view_count, description, country, default_language, thumbnails.
settings	object	Key-value settings map for the channel.
voice	object	Default channel voice (see voice fields below).
scripts_count	integer	Total scripts for the channel.
scripts_idea_count	integer	Scripts in idea status.
scripts_active_count	integer	Scripts in active status.

Response Example

{
    "success": true,
    "data": {
        "id": 123,
        "yt_handle": "mkbhd",
        "details": {
            "title": "Marques Brownlee",
            "custom_url": "mkbhd",
            "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
            "subscriber_count": 19000000,
            "video_count": 1650,
            "view_count": 4200000000,
            "description": "Channel description",
            "default_language": "en",
            "country": "US",
            "thumbnails": {
                "default": {
                    "url": "https://i.ytimg.com/..."
                }
            }
        },
        "settings": {
            "language": "English",
            "audience": "Tech enthusiasts"
        },
        "voice": {
            "id": 77,
            "name": "Default Voice",
            "instructions": "Voice instructions",
            "voice": "neutral"
        },
        "scripts_count": 42,
        "scripts_idea_count": 4,
        "scripts_active_count": 38
    }
}

GET

/channels/{id}/templates

Required Permission channels:read

List available templates for channel (system + custom).

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).

Response (200)

Response Fields

Field	Type	Description
default_template_id	integer	Default template ID for this channel.
templates	array	Array of template objects.
templates[].id	integer	Template ID.
templates[].name	string	Template name.
templates[].category	string	Template category.
templates[].description	string	Short description.
templates[].is_active	boolean	Whether this is the active template.
templates[].is_system	boolean	System template flag.

Response Example

{
    "success": true,
    "data": {
        "default_template_id": 22,
        "templates": [
            {
                "id": 22,
                "name": "Base Script",
                "category": "base",
                "description": "Standard outline",
                "is_active": true,
                "is_system": true
            }
        ]
    }
}

GET

/channels/{id}/voices

Required Permission channels:read

List available voices for channel and the default voice.

Request

Parameters

Name	Type	Description
id	integer	Channel ID (path parameter).

Response (200)

Response Fields

Field	Type	Description
default_voice_id	integer	Default voice ID for this channel.
voices	array	Array of voice objects.
voices[].id	integer	Voice ID.
voices[].name	string	Voice name.
voices[].instructions	string	Voice guidelines.
voices[].voice	string	Voice identifier.

Response Example

{
    "success": true,
    "data": {
        "default_voice_id": 77,
        "voices": [
            {
                "id": 77,
                "name": "Default Voice",
                "instructions": "Voice instructions",
                "voice": "neutral"
            }
        ]
    }
}

GET POST DELETE

/channels/{id}/competitors

Required Permission channels:read scripts:write

List, add, delete competitors. GET: returns competitors array. POST: request with identifier. DELETE: no body.

Request

Request Body

{
    "GET": "No body required",
    "POST": "JSON with identifier (URL or channel ID)",
    "DELETE": "No body required"
}

Response (GET) (200)

Response Example (GET)

{
    "success": true,
    "data": [
        {
            "channel_id": "UC123...",
            "title": "Competitor Channel",
            "custom_url": "competitor",
            "custom_url_with_at": "@competitor",
            "youtube_url": "https://youtube.com/@competitor",
            "thumbnails": {
                "default": {
                    "url": "https://i.ytimg.com/..."
                }
            },
            "subscriber_count": 500000,
            "video_count": 300,
            "view_count": 12000000
        }
    ]
}

Response (POST) (201)

Response Example (POST)

{
    "success": true,
    "data": {
        "channel_id": 123,
        "competitor": {
            "channel_id": "UC123...",
            "title": "Competitor Channel",
            "custom_url": "competitor",
            "custom_url_with_at": "@competitor",
            "youtube_url": "https://youtube.com/@competitor"
        }
    }
}

Response (DELETE) (200)

Response Example (DELETE)

{
    "success": true,
    "message": "Competitor removed."
}

Response Fields

Field	Type	Description
channel_id	string	YouTube channel ID.
title	string	Channel title.
custom_url	string	Handle without @.
custom_url_with_at	string	Handle with @.
youtube_url	string	Full YouTube URL.
thumbnails	object	Thumbnail images object.
subscriber_count	integer	YouTube subscriber count.
video_count	integer	Total video count.
view_count	integer	Total view count.