Skip to main content

The Video Controls Plus API

The API reads and changes your own library over HTTPS with an access key. Every address starts with:

https://gjajgvsjhdbtrpvfiuwl.supabase.co/functions/v1/api/v1

The machine-readable description is the OpenAPI 3.1 document at /openapi.json, with a Markdown copy at /openapi.md. Neither needs a key.

The examples below keep the start of the address and the key in two shell variables:

export VCP_API="https://gjajgvsjhdbtrpvfiuwl.supabase.co/functions/v1/api/v1"
export VCP_KEY="vcp_pat_..."

Signing requests​

Send the key as a bearer token on every request, and send bodies as JSON:

curl "$VCP_API/notes" \
-H "Authorization: Bearer $VCP_KEY"

A token from a connected assistant works here too. A website sign-in does not: the API answers 401 and asks for an access key or an assistant's token.

Each request acts as you. Our database decides every row with your own permissions, so a key can never return a row you couldn't open on the website.

What comes back​

One item:

{ "data": { "id": "0b6f3c1e-8a2d-4f5b-9c7e-1d2a3b4c5d6e", "label": "Proof of the second lemma" } }

A list:

{ "data": [ { "id": "…" }, { "id": "…" } ], "meta": { "next_cursor": "eyJyIjoi…", "limit": 20 } }

A failure:

{ "error": { "code": "scope_required", "message": "This credential needs the notes:write permission.", "details": { "scope": "notes:write" }, "correlation_id": "req_9c41b27d58e0f3a6" } }

Times are ISO 8601. Ids are UUIDs, except where a part below says otherwise. Answers that carry your data are never cached.

Errors​

StatuscodeWhat happened
400invalid_requestA field, filter, sort or cursor isn't valid. details.issues lists each field.
401invalid_tokenThe key is missing, wrong, expired or removed.
403scope_requiredThe key wasn't given this permission. details.scope names it.
404not_foundNothing at this address for this key. Another person's item looks the same as a missing one.
405method_not_allowedThis part doesn't take that method, such as a change to watch history.
409conflictIt already exists, or one of our rules refused it. The message says which.
413payload_too_largeThe body is over 65,536 bytes.
429rate_limitedToo many requests. Wait for the reset time.
500internalSomething went wrong on our side. Send us the correlation_id.

Pages of results​

A list returns 20 items unless you ask for limit, from 1 to 50. When there are more, meta.next_cursor holds a cursor; send it back as cursor with the same filters and sort to get the next page. A cursor lasts 15 minutes and works only for the query that made it. When next_cursor is null, you have everything.

curl "$VCP_API/bookmarks?limit=50" -H "Authorization: Bearer $VCP_KEY"
curl "$VCP_API/bookmarks?limit=50&cursor=eyJyIjoi…" -H "Authorization: Bearer $VCP_KEY"

Filters are query parameters named <field>.<operator>, from the short list each part allows below: eq is equal, lte is on or before, and cs means the tags contain every value in a comma list. Sort is sort=<field>, with a leading - for newest or largest first, from the part's list; the first one listed is the default.

Rate limits​

Each key gets 120 requests a minute. On top of that, your plan sets requests a day for all your keys and assistants together: 5,000 on Free, 50,000 on Pro and 100,000 for each Team member, starting again at midnight UTC. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds), for whichever limit is closer. A 429 adds Retry-After.

Removing​

DELETE needs the part's Delete tick. With an access key it removes the item at once and answers 204 with no body.

With an assistant's token it removes nothing yet. It answers 202 with a link the person opens on the website to say yes, valid for ten minutes:

{ "data": { "status": "pending_confirmation", "confirm_url": "https://vcpeai.aoneahsan.com/developers/confirm/4e2b…", "expires_at": "2026-11-21T09:24:03.000Z" } }

The extension removes it on every browser the next time it syncs, as if you had removed it there.

Your library​

Every part below takes GET /<part> for a list and GET /<part>/{id} for one item, unless it says otherwise. POST /<part> makes one, PATCH /<part>/{id} changes the fields you send, and DELETE /<part>/{id} removes it. Fields not listed as yours to set are shown and never written.

A video is named by four fields across these parts: platform (the site, such as youtube, netflix or linkedin), video_id (the video's own id on that site), video_url (the address of the video page) and video_title.

Bookmarks​

Moments you saved in a video: the time, a label, a note and a colour.

Methodslist, get, create, change, delete
You setvideo_id, video_url and label (required), position_seconds (required, seconds from the start), platform, video_title, note, color, tags, folder
Filtersplatform.eq, video_id.eq, tags.cs
Sort-created_at
Permissionbookmarks
curl -X POST "$VCP_API/bookmarks" \
-H "Authorization: Bearer $VCP_KEY" -H "Content-Type: application/json" \
-d '{"platform":"youtube","video_id":"aircAruvnKk","video_url":"https://www.youtube.com/watch?v=aircAruvnKk","position_seconds":754,"label":"Where gradient descent starts","tags":["ml","week-3"]}'

The time in the video is set when the bookmark is saved, as in the extension.

Notes​

Notes you wrote at a time in a video, with a category and tags.

Methodslist, get, create, change, delete
You setvideo_id, video_url and content (required), position_seconds, platform, video_title, category (important, question, summary, action or custom), custom_category_name, color, tags
Filtersplatform.eq, video_id.eq
Sort-created_at
Permissionnotes
curl "$VCP_API/notes?video_id.eq=aircAruvnKk" -H "Authorization: Bearer $VCP_KEY"

Collections and their videos​

collections are your video collections, newest change first. collection_videos are the videos in them; a video is added or removed, never changed, as in the extension.

collectionscollection_videos
Methodslist, get, create, change, deletelist, get, create, delete
You setname (required), description, is_publiccollection_id, video_id and video_url (required), platform, video_title, thumbnail, duration_seconds
Filterscollection_id.eq
Sort-updated_at-added_at
Permissioncollectionscollections

A public collection can be opened by anyone with its link. collection_id has to be one of your collections.

curl -X POST "$VCP_API/collection_videos" \
-H "Authorization: Bearer $VCP_KEY" -H "Content-Type: application/json" \
-d '{"collection_id":"7d1e4c2a-5b3f-4a6e-8c9d-0e1f2a3b4c5d","platform":"youtube","video_id":"aircAruvnKk","video_url":"https://www.youtube.com/watch?v=aircAruvnKk"}'

Flashcards​

Your flashcards from videos: front, back, tags and when each card is due.

Methodslist, get, create, change, delete
You setvideo_id, video_url, front and back (required), position_seconds, platform, video_title, tags, and the review schedule: ease_factor (1.3 to 10), interval_days, repetitions, next_review_at, last_reviewed_at
Filtersplatform.eq, video_id.eq, tags.cs, next_review_at.lte
Sortnext_review_at, -created_at
Permissionflashcards

A new card is due now. Changing the review schedule is how a review is recorded, as it is in the extension. Cards due by the end of today:

curl "$VCP_API/flashcards?next_review_at.lte=2026-11-21T23:59:59Z&sort=next_review_at" \
-H "Authorization: Bearer $VCP_KEY"

Learning paths and their videos​

learning_paths are your paths, newest change first. path_videos are the videos in each path, in order, and which you finished.

learning_pathspath_videos
Methodslist, get, create, change, deletelist, get, create, change, delete
You settitle (required), description, is_public, estimated_minutespath_id, video_id and video_url (required), platform, video_title, video_thumbnail, video_duration_seconds, position, is_completed, notes
Shown onlyactual_minutes, last_accessed_at (counted by the extension)
Filterspath_id.eq
Sort-updated_atposition, -created_at
Permissionpathspaths
curl -X PATCH "$VCP_API/path_videos/3c9e1a7b-2d4f-4b8e-a1c6-5f7e9d0b2a4c" \
-H "Authorization: Bearer $VCP_KEY" -H "Content-Type: application/json" \
-d '{"is_completed":true}'

Watch history​

Videos you watched with Watch History on: where you stopped and how long you watched. Only the extension adds to it, so the API reads and removes, and never changes a row.

Methodslist, get, delete
Shownthe video fields, video_thumbnail, video_duration_seconds, channel_name, last_position_seconds, watch_count, total_watch_seconds, first_watched_at, last_watched_at
Filtersplatform.eq, video_id.eq
Sort-last_watched_at
Permissionhistory (read and delete)
curl -X DELETE "$VCP_API/watch_history/9a2c4e6f-1b3d-4f5a-8c7e-0d2f4a6b8c1e" \
-H "Authorization: Bearer $VCP_KEY"

Watch later​

Your watch later list, in your order, with priority and notes.

Methodslist, get, create, change, delete
You setvideo_id and video_url (required), platform, video_title, video_thumbnail, video_duration_seconds, channel_name, position, priority (high, normal or low), notes
Sortposition, -added_at
Permissionlater
curl -X POST "$VCP_API/watch_later" \
-H "Authorization: Bearer $VCP_KEY" -H "Content-Type: application/json" \
-d '{"platform":"youtube","video_id":"IHZwWFHWa-w","video_url":"https://www.youtube.com/watch?v=IHZwWFHWa-w","priority":"high"}'

Transcripts​

transcripts lists the transcripts you saved, with language and format, newest first, and leaves the text out so a page stays small. transcript_texts reads one transcript with its text and timed lines, by the same id, or saves a new one.

transcriptstranscript_texts
Methodslist, get, deleteget, create
You setvideo_id, video_url and content (required), platform, video_title, language, language_code, is_auto_generated, format (srt, vtt, txt or json), segments
Shownthe video fields, language, language_code, is_auto_generated, format, file_size, downloaded_atthe same, plus content and segments
Sort-downloaded_at
Permissiontranscriptstranscripts
curl "$VCP_API/transcript_texts/5e7a9c1b-3d5f-4a2e-9b8c-1f3a5c7e9d0b" \
-H "Authorization: Bearer $VCP_KEY"

A request body is at most 65,536 bytes, so a longer transcript can't be saved from outside.

Screenshots​

Frames you saved from videos, with the time in the video and the image size. Read only: a screenshot is removed in the extension.

Methodslist, get
Shownthe video fields, position_seconds, image_url, format (png, jpeg or webp), width, height, created_at
Sort-created_at
Permissionscreenshots (read)
curl "$VCP_API/screenshots?limit=10" -H "Authorization: Bearer $VCP_KEY"

Settings and shortcuts​

Your synced extension settings and keyboard shortcuts: one item, whose id is your account's. settings and keyboard_bindings are objects in the shape the extension stores them.

Methodslist, get, create, change
You setsettings, keyboard_bindings
Shownsettings_updated_at, keyboard_bindings_updated_at, updated_at
Permissionsettings (read and change)

The list holds your one item, or nothing before you first sync. A save keeps the newer copy, as sync between your browsers does.

curl "$VCP_API/settings" -H "Authorization: Bearer $VCP_KEY"

Devices​

Browsers the extension is connected on. They are added only by connecting the extension; here you rename or remove them. Removing one signs the extension out on that browser.

Methodslist, get, change, delete
You setdevice_name
Showndevice_id, browser, platform, extension_version, last_seen_at, created_at
Sort-last_seen_at
Permissiondevices
curl -X PATCH "$VCP_API/devices/2b4d6f8a-1c3e-4a5b-9d7f-0e2a4c6e8b1d" \
-H "Authorization: Bearer $VCP_KEY" -H "Content-Type: application/json" \
-d '{"device_name":"Work laptop, Firefox"}'

Shared, read only​

These involve other people, so the API reads them and never writes them, whatever a key says. They send no webhook events.

PartWhat it holdsFilterSortPermission
watch_partiesParties you host or joined: the video, is_host, when it started, ends and ended. The join code is left out, because it is the invitation.-created_atparties:read
party_membersHow many people are in each of your parties and when they joined. is_you marks you; nobody's name, photo or account is included, and id is a handle for the membership, not the person.party_id.eqjoined_atparties:read
site_fixesPlayer fixes people shared for websites, approved ones and your own while they wait, with is_yours. The contributor isn't named.hostname.eq-created_atfixes:read
feature_requestsThe public board: title, description, category, status, votes and is_yours. The author isn't named.-created_at, -upvotesrequests:read
request_votesYour own votes: 1 up, -1 down. A vote's id is the request it is on.-created_atrequests:read
curl "$VCP_API/site_fixes?hostname.eq=www.coursera.org" -H "Authorization: Bearer $VCP_KEY"

Your plan and use​

GET /account returns one item: your plan, its AI runs a day and today's, your cloud storage and what you use of it, and other_apps, which holds your four limits from the plan table with requestsToday. Every key reads it, with no tick.

curl "$VCP_API/account" -H "Authorization: Bearer $VCP_KEY"

What the API never serves​

Fields are an allowlist: a column not named on this page never leaves our database. Beyond the list in What it never reaches, that also keeps out the extension's own sync keys, the stored-file record behind a screenshot, the device that last saved your settings, and the separate sittings inside your watch history. There is no calendar feed.