PRODUCTION REST API · v1

Build downloads with YTSave

Resolve a public media URL, select an exact format, create an asynchronous job and hand the signed result to your user. The same bounded production pipeline powers the YTSave website.

YTSaveClientJSON over HTTPSAsynchronous jobsScoped credentials

Quick start

YTSave handles API host by first identifying support-activated credentials. It follows with an assigned tenant endpoint and keeps a server-only call path in view.

Tenant URLhttps://ytsave.app

AuthenticationX-API-Key: ys_live_…

Client profileYTSaveClient

API versionv1

# Available only after support activation
export YTSAVE_API_KEY="issued-after-review"

curl -X POST https://ytsave.app/v1/resolve \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}'

To explain Credential safety, YTSave separates server-side secret storage from no client bundle embedding. An evidence record gives no public logs or repositories its own place.

Resolve a link

YTSave handles Resolve operation by first identifying source detection. It follows with formats from one submitted URL and keeps no invented outputs in view.

POST/v1/resolveScope: resolve

Field	Type	Required	Description
`url`	HTTPS URL	Yes	Public or authorized media page to analyze.
`tenant`	string	No	Assigned tenant domain. Usually omitted.

{
  "success": true,
  "platform": "youtube",
  "title": "Example video",
  "formats": [
    {"id":"18","type":"video","quality":"360p","container":"mp4"}
  ],
  "cached": false
}

To explain Format identifier, YTSave separates the returned value unchanged from per-link availability. An evidence record gives no guessed quality label its own place.

Create and follow a download job

For Job creation, YTSave begins with asynchronous preparation. Its evidence record pairs that with a short HTTP request and ends with bounded worker execution.

POST/v1/jobsScope: jobs

Field	Type	Required	Description
`url`	HTTPS URL	Yes	The same normalized source submitted to resolve.
`format_id`	string	Yes	An exact ID from the resolve response.
`tenant`	string	No	Assigned tenant domain. Usually omitted.

curl -X POST https://ytsave.app/v1/jobs \
  -H "X-API-Key: $YTSAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","format_id":"18"}'

1202 AcceptedSave job_id.

2Poll statusGET /v1/jobs/{job_id} with the same key.

3ReadyOpen the signed download URL.

Status	Meaning	Client action
`queued`	Admitted to the bounded queue.	Poll again with backoff.
`extracting`	Refreshing source metadata or route.	Continue polling.
`processing`	Downloading, remuxing or merging.	Display server progress.
`ready`	Signed download is available.	Send the URL to the user.
`failed`	Terminal structured error.	Read `error_code`. Retry only when advised.
`expired`	Temporary output was removed.	Create a new job.

curl https://ytsave.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

YTSave makes Job polling easy to scan. The page starts with one-second initial wait, moves to capped backoff, and clearly states temporary signed delivery.

Predictable errors

For Error contract, YTSave checks one non-2xx envelope before a support request ID. This evidence record also makes predictable client handling clear.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "category": "rate_limited",
    "message": "Too many requests. Please try again shortly.",
    "retryable": true,
    "details": {"retry_after_seconds": 20}
  },
  "request_id": "…"
}

HTTP	Typical meaning	Action
400	Invalid URL, body or unavailable format.	Correct the request. Resolve again for formats.
401	Missing, invalid, expired or wrong-scope key.	Check the server-side credential.
403	Tenant or source policy rejected the request.	Do not bypass the policy. Contact support.
404	Unknown or expired job.	Create a new job if appropriate.
429	Request or active-job limit reached.	Honor `retry_after_seconds`.
503	Queue/capacity or upstream temporarily unavailable.	Retry with exponential backoff and jitter.

Operational contract

YTSave issues an operational quota with each approval to safeguard the API consumer and upstream media services.

Use idempotent application logic and never start duplicate jobs for the same user click.
Cache resolve metadata briefly, but always treat signed download URLs as expiring.
Use bounded exponential backoff with jitter for 429, 503 and retryable errors.
Process only public media or media you are authorized to access. DRM and access controls are not bypassed.
Keep request IDs and job IDs in private operational logs. Do not log submitted URLs unnecessarily.

YTSave handles Schema access by first identifying activation before exploration. It follows with assigned authentication and keeps documented request shapes in view. OpenAPI reference

OPERATOR-REVIEWED ACCESS

Request your API key

Document the API consumer, its monthly request estimate and supported platform requirements. YTSave reviews whether resolve, job submission or both are justified before issuing a once-visible key.

Request API access Keys are tenant-scoped, revocable and issued through the Contact form. Anonymous scripts cannot execute downloader work.