DocsVidNext API

Channels, competitors and ideas

Run your channels from your code or AI agent — channel profiles and the AI analysis, competitors and their breakout videos, AI ideas, the ideas board, the calendar, and a video from an idea.

What the Planner does on a channel's pages works through the API and the MCP server too, with the same rules and the same prices. Each part below names the MCP tool and the REST endpoint.

Channels

Do	MCP	REST
List your channels — niche, language, posting schedule, default preset, counts	`list_channels`	`GET /v1/channels`
One channel, with its profile and the AI insights	`get_channel`	`GET /v1/channels/{id}`
Add a channel	`create_channel`	`POST /v1/channels`
Change a channel	`update_channel`	`PATCH /v1/channels/{id}`

The list shows active channels; send status (paused, archived or all) or q to search by name.

A channel's fields:

Field	What it is
`name`	The channel's name in VidNext.
`youtube_url`	Its YouTube channel — a link like `youtube.com/@name` or `youtube.com/channel/UC…`, or an `@handle`.
`niche`, `language`	A short niche label, and the language the channel speaks (`en`, `uk`…).
`default_preset`	The preset its videos use — an ID or the exact name; yours or one your team shares. `null` clears it.
`posting`	When it posts: `strategy` — `daily`, `weekly_3`, `weekly_2`, `twice_daily` or `weekdays` — or your own `days_of_week` (0 = Sunday) and `times_of_day` (`"18:00"`), with a `timezone` such as `Europe/Kyiv`.
`status`	`active`, `paused` or `archived`.
`profile`	The channel's "DNA" the AI writes ideas and videos from: `about`, `content_formats`, `content_pillars`, `tone_of_voice`, `keywords`, `avoid_topics`, `audience`, `geo` and `goals`.

An update changes only what you send — in profile too.

Analyze a channel

analyze_channel (REST: POST /v1/channels/analyze) reads a YouTube channel — its videos and numbers — and writes its profile and insights: strengths, weaknesses, opportunities and angles for new videos.

With channel_id, it fills the empty fields of your channel's profile; send "apply": false to only look.
With youtube_url, it analyzes any channel and shows what it would fill in. create_channel with "analyze": true adds a channel and analyzes it in one go.

A new analysis costs credits, like Analyze with AI in the app — the answer shows credits_charged. Asking again within a day is free ("refresh": true analyzes again), and you can analyze 20 channels a day. The answer comes within about 45 seconds; if the analysis takes longer, the status is running — ask again a minute later.

Competitors

Do	MCP	REST
The channel's competitors: subscribers, average views, 30-day trend, role (rival, watch, benchmark) and how beatable they are	`list_competitors`	`GET /v1/channels/{id}/competitors`
Their recent uploads, with breakouts — videos with three times their usual views	`list_competitors` with `activity_days`	`GET /v1/channels/{id}/competitors/activity`
Add one: a YouTube link or `@handle`, or a channel a search found	`add_competitor`	`POST /v1/channels/{id}/competitors`
Follow its uploads, or stop	`update_competitor`	`PATCH /v1/channels/{id}/competitors/{competitorId}`
Remove one	`remove_competitor`	`DELETE /v1/channels/{id}/competitors/{competitorId}`
Fresh numbers for the followed ones — free, 30 a day	`refresh_competitors`	`POST /v1/channels/{id}/competitors/refresh`

Find competitors with AI

find_competitors (REST: POST /v1/channels/{id}/competitor-searches) searches YouTube for channels like yours and picks the best matches, each with a reason. It takes 1–3 minutes, so it answers at once with a search ID; get_competitor_search (GET /v1/competitor-searches/{id}) then gives the top, rising and more channels with their numbers. To add one, send search_id and its youtube_channel_id as candidate_id to add_competitor.

A search costs credits, like Find competitors with AI in the app — 20 a day, one at a time for each channel.

Ideas

AI ideas

generate_ideas (REST: POST /v1/channels/{id}/idea-runs) — ideas from the channel's profile, its own results, its competitors, YouTube trends and the web. Options: count (up to 100), horizon_days, focus, formats, trending_share, language and sources. It takes 1–3 minutes and costs credits only when ideas come back; the answer shows the estimate.
get_idea_run (GET /v1/idea-runs/{id}) — the progress, then the ideas: title, hook, format and scores; detail: true adds the angle, key points, evidence and a thumbnail concept. more_ideas asks for more in the same run.
review_ideas (POST /v1/idea-runs/{id}/decisions) — approve, decline (with a reason) or keep for later.
save_ideas (POST /v1/idea-runs/{id}/save) — puts the approved ideas on the channel's board; "schedule": true also puts them on empty calendar slots.

A channel runs one idea run at a time, and an account three. set_idea_automation (PATCH /v1/channels/{id}/idea-automation) makes ideas daily or weekly by itself; get_idea_automation shows how it's set.

The ideas board and the calendar

Do	MCP	REST
The board: Ideas → Processing → Ready → Scheduled → Posted	`list_ideas`	`GET /v1/ideas`
Add your own — up to 50 at once	`add_ideas`	`POST /v1/channels/{id}/ideas`
Change the title, description, prompt, tags or priority	`update_idea`	`PATCH /v1/ideas/{id}`
Delete one (a video made from it stays)	`delete_idea`	`DELETE /v1/ideas/{id}`
Put it on a date — `"date": null` takes it off	`schedule_idea`	`POST /v1/ideas/{id}/schedule`
The calendar, up to 120 days	`get_calendar`	`GET /v1/calendar`

Filter the board by channel_id, status (idea, processing, ready, scheduled, posted) or words (q). Dates and times are in the channel's time zone: { "date": "2026-11-03", "time": "18:00" }.

A video from an idea

make_video_from_idea (REST: POST /v1/ideas/{id}/videos) does what Generate video does in the Planner: the idea's prompt in your preset's planner template — the preset you send, else the channel's default — on the idea's channel. Every option of Create a video works except channel_id and member, which come from the idea; a prompt you send replaces the composed one.

The video waits in line like any API video, and the idea moves to Processing when it starts. An idea that already has a video in progress answers 409 idea_already_started.