Youtarr External API
/external-api/v1 is Youtarr's constrained integration boundary for approved
clients. It is disabled by default and never accepts a Youtarr browser session
or a legacy download key. Set EXTERNAL_API_ENABLED=true only after the
external trust boundary and proxy rules have been reviewed.
Enablement and authentication
Create an external-role key through the session-authenticated management API
described below. The key is revealed once. Send it only in the x-api-key header over
HTTPS. Set EXTERNAL_API_ENABLED=true and restart Youtarr to enable the
namespace; leave it unset or set to false to keep it disabled.
Existing keys migrate as legacy_download. They continue to work only with
POST /api/videos/download. Conversely, external-role keys cannot use that
legacy endpoint, so its direct-download behavior cannot bypass external
policies or approval.
Every external key includes catalog and owner-request reads. Request capabilities are independently configurable:
| Permission | Added scope |
|---|---|
| Request videos | video:request |
| Request channels | channel:request |
| Delete downloaded videos | video:delete |
The role value remains as a backward-compatible summary for older clients,
but capabilities.scopes is authoritative. Clients must not infer a
permission that is absent from the scopes array. admin remains a policy
summary only and does not authorize remote approval. Review always requires a
normal Youtarr administrator session.
Policy and grants
Every external key has:
- independent video-request, channel-request, and downloaded-video-deletion permissions; catalog and owner-status reads are always included;
- a maximum allowed movie/TV rating;
- an allow/disallow decision for unrated or unrecognized ratings;
- allowed media types (
video,short, and/orlivestream); - separate auto-approval decisions that are valid only when their parent permission is enabled;
- durable workload ceilings, defaulting to 5 active jobs, 30 accepted writes
per UTC hour, and 200 per UTC day (administrators may select lower values);
active jobs are the key's
approvedandprocessingrequests; - an explicit set of granted Youtarr channel database IDs.
The HTTP contract uses a compact maxRatingLevel value with these rating ceilings:
| Level | Administrator label | Movie ratings | TV ratings |
|---|---|---|---|
| 1 | General audiences | G | TV-Y, TV-G |
| 2 | Parental guidance | PG | TV-Y7, TV-PG |
| 3 | Teen | PG-13 | TV-14 |
| 4 | Mature | R, NC-17 | TV-MA |
YouTube usually does not supply a useful content rating. Youtarr therefore
uses the video's explicit/manual rating when present, then the channel's
manually assigned default rating. If neither is recognized, the key's
allowUnrated decision applies. The same calculation is used for catalog
visibility, counts, assets, catalog rows, request creation, and approval
revalidation.
Youtarr applies one server-side eligibility decision to lists, counts, direct IDs, assets, catalog feeds, request creation, and approval revalidation. Disabled or terminated channels never qualify. A missing grant is treated the same as a nonexistent target.
Error contract
All JSON responses under /external-api/*, including feature-off and
unknown-route responses, use private, no-store cache headers and vary on
x-api-key. Errors use:
{
"error": {
"code": "not_found",
"message": "External API route not found",
"requestId": "server-generated-identifier"
}
}
Clients must treat unknown additive fields and unknown enum values as forward-compatible. They must not infer target existence from 403/404 differences.
The standardized statuses are 400 (malformed or invalid request), 401 (authentication), 403 (missing scope), 404 (unknown or hidden resource), 405 (method), 409 (idempotency key reused for a different target), 413 (body size), 415 (content type), 429 (rate/quota), 500 (unexpected failure), and 503 (bounded downstream capacity). Compressed request bodies are not accepted. CORS is disabled.
The sanitized cross-client decoding fixture is
fixtures/external-api-v1/contract.json; its reviewable checksum is recorded
beside it in SHA256SUMS. Fixture version 5 covers capabilities, channels,
cursor-paginated mixed-media catalog pages, rich and sparse video details,
every request type and status, video-request outcomes, and forward-compatible
unknown enum samples. The fixture contains no credentials or private
deployment address. Consumer repositories should vendor the JSON and checksum
unchanged and pin the producing Youtarr commit used for synchronization.
Endpoints
Capabilities
GET /external-api/v1/capabilities
Returns the API/server version, effective role/scopes, policy, feature flags, and effective quota limits/remaining allowance. Clients should call this before presenting optional actions.
Granted catalog
GET /external-api/v1/channels
Query parameters:
cursor(opaque) orpage(default 1), pluspageSize(1–100);search(maximum 200 characters);subfolder(exact match, maximum 255 characters);sortBy:title,videoCount,downloadedCount, orid;sortOrder:ascordesc.
GET /external-api/v1/channels/{channelDatabaseId}/videos
Query parameters:
cursor(preferred) orpage(compatibility only), pluspageSizeandsearch;tabType:videos,shorts, orstreams;status:all,requestable,available,downloaded, orrequested;minDuration,maxDuration,dateFrom, anddateTo;sortBy:date,title, orduration;sortOrder:ascordesc.
Video status has these exact meanings:
all(or omitted): every policy-eligible cached row;requestable: not downloaded and without apending,approved, orprocessingvideo request owned by the calling key;available: not downloaded, including rows with an active request;downloaded: aVideosrow exists withremoved=false;requested: an active request exists for the calling key.
Responses include an opaque nextCursor while more rows remain. Video cursors
are stable keyset cursors bound to the calling key, endpoint, filters, and
sorting used to create them. A client must restart at the first page after
changing any filter, sort, or page size. Cursors avoid offset drift but do not
freeze a database snapshot, so a newly indexed or state-changing row may
appear only on a later refresh.
Existing numeric page parameters remain supported through page 100 for
compatibility. Use cursors whenever completeness matters. Clients must not use
total to preallocate a fixed snapshot. Catalog endpoints read Youtarr's cache
and do not trigger YouTube network fetches.
Cross-channel video catalog
GET /external-api/v1/videos
Returns the complete policy-filtered catalog across every channel granted to
the calling key. One cursor chain combines dozens of channels; clients must not
list channels and request each channel's videos unless they are rendering
channel-specific screens. pageSize is limited to 100. It accepts search,
tabType, status, duration/date bounds, sortBy, and sortOrder with the
same meanings as the channel video catalog.
Complete catalog traversal:
GET /external-api/v1/videos?pageSize=100
GET /external-api/v1/videos?pageSize=100&cursor={nextCursor}
Only immediately requestable videos:
GET /external-api/v1/videos?status=requestable&pageSize=100
Not downloaded, including pending/approved/processing requests:
GET /external-api/v1/videos?status=available&pageSize=100
Downloaded inventory:
GET /external-api/v1/videos?status=downloaded&pageSize=100
Pass each response's nextCursor back with the same filters and sorting until
it is null. Request creation remains idempotent and revalidates current
download/request state, closing the race between reading a page and submitting
a request.
Youtarr supplies candidates only. Client-side history, scoring signals, and ranking state remain outside Youtarr and must never be sent to it.
Video detail
GET /external-api/v1/videos/{youtubeId}
Returns one policy-filtered video with the catalog identity and request status
plus the full curated metadata used by Youtarr's video detail modal. This
includes the complete description, engagement counts, tags, categories,
availability, upload data, technical video fields, related-file summaries, and
available resolutions. Metadata is read only from Youtarr's local cache (the
.info.json written when the video was downloaded or opened in Youtarr); this
endpoint never contacts YouTube and never writes to Youtarr's database. When
nothing is cached, metadata contains only the stored description, or is
null when there is none. The lookup is intentionally one video at a time,
shares Youtarr's bounded external-work queue, and returns 503 when that queue
is full.
Downloaded-video details include timestamps, sizes, protection state, and resolution. Youtarr filesystem paths are never exposed because they are neither safe nor usable by a remote client. Missing, hidden, ungranted, and policy-ineligible videos all return the same 404 contract.
Assets
GET /external-api/v1/assets/channels/{channelDatabaseId}/thumbnailGET /external-api/v1/assets/videos/{youtubeId}/thumbnail
Local assets require the same key, grant, channel state, rating, and media policy as their catalog row. Youtarr rejects unsafe identifiers, traversal, symlinks, and resources outside its image directory. Responses are private and do not redirect.
Catalog responses always return these Youtarr API asset paths, never a direct
Google/YouTube image URL. The client fetches the image bytes with the same
x-api-key header used for JSON requests. Youtarr serves its optimized local
JPEG when available; otherwise the video asset endpoint securely fetches an
allow-listed YouTube/Google thumbnail without redirecting the client. Upstream
responses are bounded by timeout, content type, and size.
Create requests
Video:
POST /external-api/v1/requests/videos
{
"youtubeId": "abcdefghijk",
"channelId": 8,
"idempotencyKey": "optional, 1–200 characters"
}
A video request never uses the owner's channel memberships: even when Youtarr's cookies belong to a member, members-only videos are skipped, as in a run without cookies. See Members-Only Videos.
Channel:
POST /external-api/v1/requests/channels
{
"channelUrl": "https://www.youtube.com/@example",
"idempotencyKey": "optional, 1–200 characters"
}
Only canonical YouTube handle, /channel/, /c/, and /user/ URLs are
accepted. Approval provisions the channel, or re-enables it when it was
previously unsubscribed, and keeps its saved settings. By default it also
grants the resulting channel to the requesting key; the administrator may turn
that off during approval. That decision is stored with the request so an
idempotent recovery cannot broaden the grant after interrupted execution. A
key with channel auto-approval skips the administrator entirely: its requests
are subscribed, re-enabled, and granted to the key with no review, so enable
it only for fully trusted clients. A channel YouTube reports as terminated
fails with Channel is unavailable. Uncached channel metadata resolution
terminates after two minutes.
Downloaded-video deletion:
POST /external-api/v1/requests/delete-videos
{
"youtubeId": "abcdefghijk",
"channelId": 8,
"idempotencyKey": "optional, 1–200 characters"
}
Deletion applies only to the downloaded video asset. It never removes or
disables a channel subscription. A video that is not currently downloaded
returns 404. If the video is removed by other means before the request runs,
the request completes with Video is already deleted and keeps its record for
audit.
Created requests return HTTP 202 and outcome: "created", with status
approved when the key auto-approves that request type and pending
otherwise. Duplicates return HTTP 200 with duplicate, and a video request
for a video that is already downloaded returns HTTP 200 with
already_downloaded. Reusing an idempotencyKey for a different target
returns 409.
Owner-scoped request reads
GET /external-api/v1/requestsGET /external-api/v1/requests/{requestId}
Reads expose only records owned by the calling key. List paging accepts either
an opaque cursor or the compatible page parameter, is limited to 100 rows,
rejects pages beyond 100, and accepts an exact status filter.
Statuses are pending, approved, processing, completed, rejected,
failed, or cancelled. Reads never change a request; they report the state
Youtarr's background executor has recorded.
The lifecycle is:
pending: waiting for an administrator (keys without auto-approval).approved: approved by the key's auto-approval or by an administrator, and waiting for the background executor. The executor runs about once a minute and immediately after each approval.processing: the executor has claimed the request. A video request is queued as a normal Youtarr download job; channel and deletion requests run in the bounded external-work queue.completedorfailed: a video request completes when its job ends with the video on disk. Transient 403 and cookie-related retries keep the same requestprocessing, dedupe key, and quota charge; the executor follows persisted retry job identities, including after a restart. Only the final attempt failing without a downloaded video producesDownload did not complete.
An approved request can stay approved with an explanatory message while it
waits: Waiting for downloads to resume while Youtarr's storage guard has
paused downloads, and Waiting for another download of this video to finish
when the video is already in another download. A deletion refused by the library
root/subfolder check stays approved with Waiting for the downloads folder to become available, retaining its dedupe key and quota charge. Held work rotates
behind other approved work so downloads waiting for storage cannot block
deletions that free space. Before every attempt, the executor
reloads the key and target; a request whose key, permission, grant, or policy
no longer allows it fails with Request is no longer eligible. Requests
interrupted by a restart return to approved after a five-minute stale window
and rerun through their idempotent operation.
The current API Keys & Bookmarklet screen hides revoked keys after deletion; management responses retain those records for audit history.
Administrator review
Administrator clients use endpoints under /api/external-requests. They use
Youtarr's normal admin authentication and reject every API key, including
external keys, with 403:
- list with
status,requestType, andapiKeyIdfilters; - request detail;
- approve;
- reject with a 1–300 character reason.
Approval locks the key before the request, reloads the current key policy,
checks the key's active-job capacity, and revalidates the target. It then marks
the request approved and hands it to the background executor, so the
approve call returns without waiting for a download, channel fetch, or
deletion. Approving an already-approved request again is a no-op; approving it
with a different channel-grant decision returns 409. The executor revalidates
authorization and target state again immediately before running, so
revocation or a policy/grant change still takes effect before any work starts.
Rate limits
External reads are limited to 120 requests per minute per key. Request writes are limited to 10 per minute per key. Review actions have a separate session-only limit of 30 per minute.
Deployment and operations
Youtarr authenticates every external request with x-api-key and enforces the
key's role, independent request permissions, channel grants, content policy,
quotas, and request limits. External-key authentication remains active when
AUTH_ENABLED=false; browser sessions, legacy download keys,
Authorization, and x-access-token do not authenticate this namespace.
The operator owns TLS, the public hostname, firewalling the Youtarr origin,
and the reverse proxy. Keep the Youtarr origin port private and publish only
/external-api/v1 and its descendants. Do not expose the complete application
port: that would also publish the SPA, setup and health routes, Swagger,
images, WebSocket, session management, and legacy APIs.
Set TRUST_PROXY to the exact trusted proxy hop or subnet. Never use an
unrestricted setting on an origin reachable by untrusted clients.
The proxy must:
- allow only
GET,HEAD, andPOSTfor/external-api/v1paths; - limit request bodies to 16 KiB and enforce connection/header/read timeouts;
- forward
x-api-keyandContent-Type, while removingCookie,Authorization, andx-access-token; - reject WebSocket upgrades, unmatched hosts, other versions, and all other application paths;
- disable response caching and hide
Set-Cookie; - apply TLS, connection, and edge rate limits appropriate for the deployment.
Start with auto-approval disabled, a database and configuration backup, and a
view-only key with the minimum channel grants. Confirm the private Youtarr
application and proxy rules before exposing the service. Revoke a compromised
key immediately. Keep the namespace disabled unless the external trust boundary
and proxy rules have been reviewed. To enable it, set
EXTERNAL_API_ENABLED=true and restart Youtarr.
Each key defaults to at most 5 active jobs, 30 accepted writes per UTC hour,
and 200 per UTC day. Administrators may select lower limits. A shared
application ceiling also bounds downloader, deletion, and channel-provisioning
work. /external-api/v1/capabilities reports effective limits and remaining
allowance.
Monitor 401, 403, 404, 429, 500, and 503 rates without logging API keys. Youtarr sanitizes downloader command logging, including proxy credentials, cookies, headers, and paths; rotate credentials and expire older logs if they may contain secrets.
Configuration and administration
This runtime includes the management APIs. The external-access editor and request-review UI are a separate follow-up in PR #809.
-
Create an external key with session-authenticated
POST /api/keysand save the returned raw secret; it is shown only once. Omittingpolicycreates a legacy download key. For example, a body for a read-only external key is:{"name":"Catalog reader","policy":{"role":"view","maxRatingLevel":2,"allowUnrated":false,"allowedMediaTypes":["video"]},"channelIds":[12]}Use
x-access-tokenwith an administrator session for management calls. Obtain channel database IDs fromGET /getchannels(database_id), not its YouTubechannel_id. Do not copy the example ID without checking your channels. -
The session-authenticated
GET /api/keysmanagement response includeschannel_grant_count: the number of grants whose channels are currently enabled and non-terminated. It is not part of the/external-api/v1contract. -
Choose the smallest request permissions, rating ceiling, media types, quotas, and enabled channel grants.
-
Review pending requests using
GET /api/external-requestsandPOST /api/external-requests/{id}/approveor/reject(a rejection requires a JSONreason). Policy and grants can be replaced atomically withPUT /api/keys/{id}/external-accessand a{ "policy": ..., "channelIds": [...] }body.
GET /getconfig reports the effective feature flag in
isPlatformManaged.externalApiEnabled; clients should use this value when
deciding whether to offer external API controls.
When the shared work queue is full, writes return 503 while retaining the accepted request and its idempotency key. Retry the same body to resume it without charging another accepted write. Completed video, channel, and deletion requests return their original result on an idempotent retry.
Saving an external key with zero approved channels is intentional and does not backfill or grant access. That key fails closed: catalog reads and requests return no granted content until an administrator adds enabled, non-terminated channel grants.
Existing keys migrate as legacy_download and remain limited to
POST /api/videos/download. They cannot use /external-api/v1. External
keys cannot use the legacy direct-download endpoint.
Synthetic consumer contract
Database integration and query plans
npm run test:external-api-database runs the migration lifecycle and runtime
regressions against a real local database. CI runs both MariaDB 10.3 and
MySQL 8.0; the default backend suite excludes these files instead of skipping
tests. The tests create and remove disposable databases and use synthetic data.
Configure DB_HOST, DB_PORT, DB_USER, DB_PASSWORD and, if different,
DB_ADMIN_USER / DB_ADMIN_PASSWORD. The administrator needs database
creation and removal privileges.
npm run test:external-index-plans creates 300,000 cached videos, 1,000 channels,
30,000 request records, and 10 channel grants in a disposable local database.
It executes the actual catalog and management service methods, captures their
SQL, compares results before and after the runtime migration, and records
EXPLAIN plans in /tmp/youtarr-external-index-plans.json. Set
EXTERNAL_API_INDEX_REPORT to choose another report path. CI uploads this report
for each engine. No YouTube or media-server calls are made.
Only two indexes are added, both on external_requests:
external_requests_catalog_status_idx:(api_key_id, request_type, youtube_id, created_at, id, status). Latest request status is fetched in a batch for the displayed page usingROW_NUMBER(), avoiding a correlated history scan for every candidate video.external_requests_management_idx:(request_type, status, created_at, id)supports the filtered administrator queue.
Measured plans on the synthetic fixture (estimated rows for the request-table access, not actual rows returned):
| Engine | Query | Before index | After index |
|---|---|---|---|
| MariaDB 10.3.39 | Latest status for displayed videos | 14,935 | 500, covering catalog-status index |
| MySQL 8.0.46 | Latest status for displayed videos | 19,923 | 50, covering catalog-status index |
| MariaDB 10.3.39 | Video requests, pending | 29,870, table scan | 1,500, management index |
| MySQL 8.0.46 | Video requests, pending | 39,847, table scan | 1,500, management index |
The four service reads took 119 → 25 ms on MariaDB and 180 → 64 ms on MySQL with the batched lookup; building both indexes took 168 ms and 255 ms respectively in this local run. These are fixture measurements, not deployment guarantees. MySQL still sorts the joined management result. Existing channel lookup indexes already cover granted-channel joins; this migration adds no catalog-table indexes and does not consolidate duplicate channels. Equivalent indexes under other names are retained, and rollback removes only matching definitions under the migration's own index names.
HTTP fixture
The canonical, production-free consumer dataset lives in
fixtures/external-api-v1/contract.json. Validate its published checksum with
npm run test:external-fixture.
Its representativeProfile records only sanitized structural observations
from a deployed catalog: channel/page scale, media-type mix, common rating and
nullability patterns, and authenticated artwork URL shape. It contains no
production titles, identifiers, descriptions, request records, or credentials.
The ordinary catalog rows follow that profile; deliberately unusual enum,
duration, rating, sparse-detail, and failure cases remain separate edge data.
Fixture tests derive the profile back from the rows and fail when they drift.
Run the lightweight contract server with:
npm run test:external-contract-server
The executable mounts the real /external-api/v1 router and authentication
middleware with deterministic catalog, request, quota, and artwork adapters.
It prints a JSON object containing its loopback base URL and synthetic API key;
it never starts the full Youtarr application or requires MySQL. Route tests
exercise the same server and keep the fixture, checksum, response envelopes,
query validation, headers, status codes, and request behavior release-gated.
The /__contract/scenario and /__contract/state endpoints exist only on this
test executable. They let consumer UI suites select deterministic empty,
safety-filtered, unauthorized, transport, unsupported-version, malformed,
delayed, and server-error responses and inspect accepted synthetic writes. They
are not mounted by Youtarr itself.
For normal Youtarr API integrations such as bookmarklets and mobile shortcuts, see API Integration. This document is the authoritative reference for the versioned external API contract, endpoint behavior, and deployment requirements.