YouTube Intel

POST

/intel/channels/lookup

Required Permission intel:read

Look up one or more YouTube channels by handle (with or without @), channel ID (UC…), or URL. Charges 1 team credit per request. Rate limit: 60 requests/minute (intel).

Rate limit: 60 requests per minute

Request

JSON body with 1–5 identifiers. Per-identifier failures appear in data.errors without failing the whole request (multi-ID only).

Request Body Fields

Field	Type	Required	Description
identifiers	array	Yes	1–5 strings. Handle, UC channel ID, or YouTube URL.

Example Request Body

{
    "identifiers": [
        "@mkbhd",
        "UCBJycsmduvYEL83R_U4JriQ"
    ]
}

Response (200)

Response Example

{
    "success": true,
    "data": {
        "channels": [
            {
                "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
                "handle": "mkbhd",
                "title": "Marques Brownlee",
                "description": "Channel description (truncated to 500 chars)",
                "thumbnails": {
                    "default": {
                        "url": "https://i.ytimg.com/..."
                    }
                },
                "subscriber_count": 19000000,
                "video_count": 1650,
                "view_count": 4200000000,
                "published_at": "2008-01-20T00:00:00Z",
                "country": "US"
            }
        ],
        "errors": []
    }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Response data containing channels and errors
data.channel_id	string	Single-ID response only — YouTube channel ID
data.handle	string	Single-ID response — handle without @
data.channels	array	Multi-ID response — successful lookups
data.channels[].channel_id	string	YouTube channel ID
data.channels[].handle	string	Handle without @ symbol
data.channels[].title	string	Channel title
data.channels[].description	string	Channel description (truncated to 500 chars)
data.channels[].thumbnails	object	Thumbnail URLs
data.channels[].subscriber_count	integer	Subscriber count
data.channels[].video_count	integer	Total videos
data.channels[].view_count	integer	Total views
data.channels[].published_at	string	Channel publish timestamp (ISO 8601)
data.channels[].country	string	Country code
data.errors	array	Array of lookup errors: identifier, error, error_type

Error Responses

Status	Error code	Description
403	Token does not have intel:read permission	Missing intel:read ability
422	(validation)	identifiers missing, empty, or more than 5 items
400	Channel lookup failed	Upstream lookup error (entire request)

Response shape: one vs many identifiers

With exactly one identifier, data is a flat channel object (channel_id, handle, title, …). With multiple identifiers, data is { channels: [...], errors: [...] } where errors lists per-identifier failures.

POST

/intel/channels/search

Required Permission intel:read

AI-powered YouTube channel search. Charges 2 team credits per request. Rate limit: 60 requests/minute (intel).

Rate limit: 60 requests per minute

Request

JSON body with natural-language query.

Request Body Fields

Field	Type	Required	Description
query	string	Yes	Search query. Max 255 characters.
limit	integer	No	1–20 results. Default 10.

Example Request Body

{
    "query": "tech reviews",
    "limit": 10
}

Response (200)

Response Example

{
    "success": true,
    "data": {
        "channels": [
            {
                "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
                "handle": "mkbhd",
                "title": "Marques Brownlee",
                "description": "Channel description (truncated to 500 chars)",
                "thumbnails": {
                    "default": {
                        "url": "https://i.ytimg.com/..."
                    }
                },
                "published_at": "2008-01-20T00:00:00Z",
                "subscriber_count": 19000000,
                "video_count": 1650,
                "view_count": 4200000000,
                "country": "US"
            }
        ],
        "query": "tech reviews",
        "total_results": 1,
        "message": "Channels found matching your criteria."
    }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data.channels[].channel_id	string	YouTube channel ID
data.channels[].handle	string	Handle without @
data.channels[].title	string	Channel title
data.channels[].description	string\|null	Channel description (nullable)
data.channels[].thumbnails	object\|null	Thumbnail URLs (nullable)
data.channels[].published_at	string	Channel publish timestamp
data.channels[].subscriber_count	integer	Subscriber count
data.channels[].video_count	integer	Total uploaded videos
data.channels[].view_count	integer	Total views
data.channels[].country	string\|null	Country code (nullable)
data.query	string	The search query used
data.total_results	integer	Total results found
data.message	string	Search completion message

Error Responses

Status	Error code	Description
403	Token does not have intel:read permission	Missing intel:read ability
422	(validation)	Invalid query or limit
400	Channel search failed	Search service error

POST

/intel/videos/lookup

Required Permission intel:read

Look up one or more YouTube videos by 11-character video ID or watch URL. Charges 1 team credit per request. Rate limit: 60 requests/minute (intel).

Rate limit: 60 requests per minute

Request

JSON body with 1–5 identifiers.

Request Body Fields

Field	Type	Required	Description
identifiers	array	Yes	1–5 video IDs or YouTube watch URLs.

Example Request Body

{
    "identifiers": [
        "dQw4w9WgXcQ",
        "https://youtube.com/watch?v=abc123"
    ]
}

Response (200)

Response Example

{
    "success": true,
    "data": {
        "videos": [
            {
                "video_id": "dQw4w9WgXcQ",
                "channel": {
                    "channel_id": "UCuAXFkgsw1L7xaCfnd5JJOw",
                    "handle": "RickAstleyVEVO",
                    "title": "Rick Astley"
                },
                "title": "Video Title",
                "description": "Video description",
                "published_at": "2009-10-25T06:57:33Z",
                "thumbnail_url": "https://i.ytimg.com/...",
                "duration": "PT3M33S",
                "view_count": 1000000,
                "like_count": 50000,
                "comment_count": 10000,
                "outlier_score": 1.25,
                "format": "Music",
                "topic": "Pop",
                "angle": "Nostalgia",
                "goals": "Entertainment"
            }
        ],
        "errors": []
    }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data.video_id	string	Single-ID response only
data.videos	array	Multi-ID response — successful lookups
data.videos[].video_id	string	YouTube video ID
data.videos[].channel	object	Channel summary with channel_id, handle, and title
data.videos[].title	string	Video title
data.videos[].description	string	Video description
data.videos[].published_at	string	Publish timestamp (ISO 8601)
data.videos[].thumbnail_url	string	Best available thumbnail URL
data.videos[].duration	string	ISO 8601 duration
data.videos[].view_count	integer	Total views
data.videos[].like_count	integer\|null	Total likes (nullable)
data.videos[].comment_count	integer\|null	Total comments (nullable)
data.videos[].outlier_score	float\|null	Performance vs channel baseline (nullable)
data.videos[].format	string\|null	Parsed format (nullable)
data.videos[].topic	string\|null	Parsed topic (nullable)
data.videos[].angle	string\|null	Parsed angle (nullable)
data.videos[].goals	string\|null	Parsed goals (nullable)
data.errors	array	Array of lookup errors: identifier, error, error_type

Error Responses

Status	Error code	Description
403	Token does not have intel:read permission	Missing intel:read ability
422	(validation)	identifiers invalid or over limit
400	Video lookup failed	Upstream lookup error

Response shape: one vs many identifiers

With one identifier, data is a flat video object. With multiple, data is { videos: [...], errors: [...] }.

POST

/intel/videos/search

Required Permission intel:read

AI-powered YouTube video search. Charges 2 team credits per request. Rate limit: 60 requests/minute (intel).

Rate limit: 60 requests per minute

Request

JSON body with natural-language query.

Request Body Fields

Field	Type	Required	Description
query	string	Yes	Search query. Max 255 characters.
limit	integer	No	1–20 results. Default 10.

Example Request Body

{
    "query": "iPhone 15 review",
    "limit": 20
}

Response (200)

Response Example

{
    "success": true,
    "data": {
        "videos": [
            {
                "video_id": "abc123",
                "channel": {
                    "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
                    "handle": "mkbhd",
                    "title": "Marques Brownlee"
                },
                "title": "iPhone 15 Review",
                "description": "Description (truncated to 300 chars)...",
                "published_at": "2026-01-01T00:00:00Z",
                "thumbnail_url": "https://i.ytimg.com/...",
                "view_count": 500000,
                "like_count": 15000,
                "comment_count": 1200,
                "duration": "PT12M",
                "format": "Review",
                "topic": "Smartphones",
                "angle": "Hands-on",
                "goals": "Inform",
                "outlier_score": 1.12
            }
        ],
        "query": "iPhone 15 review",
        "total_results": 1,
        "message": "Videos found matching your criteria."
    }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data.videos[].video_id	string	YouTube video ID
data.videos[].channel	object	Channel summary with channel_id, handle, and title
data.videos[].title	string	Video title
data.videos[].description	string	Truncated description (max 300 chars)
data.videos[].published_at	string	Publish timestamp
data.videos[].thumbnail_url	string	Best available thumbnail URL
data.videos[].view_count	integer	Total views
data.videos[].like_count	integer	Total likes
data.videos[].comment_count	integer	Total comments
data.videos[].duration	string	ISO 8601 duration
data.videos[].format	string\|null	Detected format (nullable)
data.videos[].topic	string\|null	Detected topic (nullable)
data.videos[].angle	string\|null	Detected angle (nullable)
data.videos[].goals	string\|null	Detected goals (nullable)
data.videos[].outlier_score	float\|null	Outlier score relative to channel baseline (nullable)
data.query	string	The search query used
data.total_results	integer	Total results found
data.message	string	Search completion message

Error Responses

Status	Error code	Description
403	Token does not have intel:read permission	Missing intel:read ability
422	(validation)	Invalid query or limit
400	Video search failed	Search service error

GET POST DELETE

/intel/bookmarks

Required Permission intel:read

Manage team Intel bookmarks. GET lists bookmarks (50 per page). POST creates a bookmark. DELETE removes by bookmark ID at `/intel/bookmarks/{bookmark}`.

Request

GET: optional page query. POST: JSON body below. DELETE: bookmark ID in path (not on /intel/bookmarks alone).

Parameters

Name	Type	Description
page	integer	GET only — page number (default 1, 50 per page)
bookmark	integer	DELETE only — bookmark ID at /intel/bookmarks/{bookmark}

Request Body Fields

Field	Type	Required	Description
type	string	Yes	POST only. channel or video
external_id	string	Yes	POST only. YouTube channel ID or video ID
title	string	Yes	POST only. Max 255 characters
url	string	Yes	POST only. Valid URL
notes	string	No	POST only. Max 1000 characters
tags	array	No	POST only. Tag strings max 50 chars; stored lowercase

Example Request Body

{
    "type": "channel",
    "external_id": "UCBJycsmduvYEL83R_U4JriQ",
    "title": "Competitor: MKBHD",
    "url": "https://youtube.com/@mkbhd",
    "notes": "Strong product review format",
    "tags": [
        "competitor",
        "tech"
    ]
}

Response (GET) (200)

Response Example (GET)

{
    "success": true,
    "data": [
        {
            "id": 321,
            "type": "channel",
            "external_id": "UCBJycsmduvYEL83R_U4JriQ",
            "title": "Competitor: MKBHD",
            "url": "https://youtube.com/@mkbhd",
            "notes": "Strong product review format",
            "tags": [
                "competitor",
                "tech"
            ]
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 50,
        "total": 1,
        "last_page": 1
    }
}

Response (POST) (201)

Response Example (POST)

{
    "success": true,
    "data": {
        "id": 321,
        "type": "channel",
        "external_id": "UCBJycsmduvYEL83R_U4JriQ",
        "title": "Competitor: MKBHD",
        "url": "https://youtube.com/@mkbhd",
        "notes": "Strong product review format",
        "tags": [
            "competitor",
            "tech"
        ]
    }
}

Response (DELETE) (200)

Response Example (DELETE)

{
    "success": true,
    "message": "Bookmark deleted successfully"
}

Response Fields

Field	Type	Description
success	boolean	Request success
data	array\|object	GET: bookmark array. POST: single bookmark
pagination	object	GET only — current_page, per_page (50), total, last_page
message	string	DELETE only

GET requires intel:read. POST and DELETE require intel:write.
POST does not consume Intel lookup credits.

Error Responses

Status	Error code	Description
403	Token does not have intel:write permission	POST/DELETE without intel:write
422	(validation)	Invalid body or duplicate external_id