DocsVidNext API
The Planner
Ask what's posting today, what to schedule and what to make next — then move, skip or add posting slots, mark videos posted, and read a channel's health and YouTube numbers.
What the Planner's calendar, board and channel pages show works through the API and the MCP server too. Each part names the MCP tool and the REST endpoint.
Dates and times are in each channel's time zone. "Today" is the day in your own time zone — the one your Planner emails use; send timezone, like Europe/Kyiv, to see the day somewhere else.
Today
get_today (REST: GET /v1/planner/today) shows what each channel posts today, slot by slot. Each slot has a state:
state | Means |
|---|---|
posted | It's posted. |
ready | The video is done — post it. |
making | The video is being made. |
needs_video | An idea without a video — make it. |
failed | The video failed or was canceled — make it again. |
empty | Nothing planned — schedule an idea. |
skipped | You left this posting out. |
overdue: true marks a slot whose time has passed. The answer also has what was missed in the last 14 days, tomorrow's slots, the next 7 days' gaps (needs_video, empty_slots), ready videos without a date, channels about to run out of videos (with their runway in days and why), and your unread notifications. Send date for another day, or channel_id for one channel.
What to schedule
suggest_schedule (REST: GET /v1/planner/schedule-suggestions) shows, for each active channel — or the one in channel_id — its free slots in the next days (14 unless you send another number), the ready videos and ideas without a date, and where each would go: ready videos first, ideas that must be out by a date before it, then by priority and idea score. It changes nothing.
schedule_ideas (REST: POST /v1/channels/{id}/schedule-ideas) puts them there — all of them, or the idea_ids you pick. It first adds the posting schedule's missing slots (send "create_slots": false to skip that). Slots that are already there, also ones you added by hand, always stay. To put one idea on another day, use schedule_idea (see The ideas board and the calendar).
What to make next
get_videos_to_start (REST: GET /v1/planner/videos-to-start) lists the scheduled ideas of the next days (7 unless you send another number) whose video is missing or failed, soonest first. Each has start_by — a day before its slot — and late: true once that time has passed. The videos being made now are listed too.
Start one with make_video_from_idea (A video from an idea). A video takes 30–60 minutes, a little more with thumbnails.
A channel's status
get_channel_status (REST: GET /v1/channels/{id}/status) shows one channel at a glance:
- Health —
healthy,warningorcritical, with the reasons, and the runway: how many days its ready and scheduled videos last at its posting rate. - The board — how many ideas, videos in the making, ready, scheduled and posted, and what's overdue.
- The schedule — when it posts, how full its calendar is, and the next slots with their state.
- The last posted videos with their views, the channel's YouTube numbers, and whether automatic ideas are on.
list_channels shows each channel's health too.
Posting slots
| Do | MCP | REST |
|---|---|---|
Add slots: one at date and time, or the posting schedule's missing ones for the next days | add_slots | POST /v1/channels/{id}/slots |
Move a slot to another date and time — its video goes with it | update_slot with "action": "move" | PATCH /v1/slots/{id} |
Skip it, with a reason — its video goes back to the board | update_slot with "action": "skip" | PATCH /v1/slots/{id} |
| Bring a skipped slot back | update_slot with "action": "restore" | PATCH /v1/slots/{id} |
| Delete a slot — its video goes back to the board | delete_slot | DELETE /v1/slots/{id} |
| Mark a video posted, with its YouTube link | mark_posted | POST /v1/ideas/{id}/posted |
Slot IDs (slot_id) come from get_today, get_calendar and suggest_schedule. A posted slot never changes — it answers 409 slot_posted — and a time that's already taken answers 409 time_taken with the taken times. Adding slots never deletes any.
YouTube numbers
get_youtube_stats (REST: GET /v1/channels/{id}/youtube-stats) shows the channel's subscribers over the last days (30 unless you send another number) and how much they changed, and its videos with their latest views, likes and comments — newest first, or "sort": "views"; only_vidnext: true keeps the videos made with VidNext. With video — a YouTube link or ID, or an idea ID — it shows that video's numbers over time.
The numbers come from VidNext's own stats tracking. refresh_youtube_stats (REST: POST /v1/channels/{id}/youtube-stats/refresh) scans the channel again, like Collect now on the Stats page: free, a few minutes, once every 30 minutes for each channel. The channel needs its YouTube link.