PRODUCTION REST API · v1

Build downloads with Insto

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 Insto website.

JSON over HTTPSAsynchronous jobsScoped API keysSigned downloads

Quick start

All production requests use the central API host https://web.ytsave.app or the assigned tenant host with an operator-issued credential.

Tenant URLhttps://insto.app

AuthenticationX-API-Key: ys_live_…

Content typeapplication/json

API versionv1

curl -X POST https://insto.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"}'

Keep the key on your server. Never place it in browser JavaScript, a mobile bundle, a public repository or a client-visible log.

Resolve a link

Detect the source and receive only formats actually returned for that exact public link.

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
}

Store the returned format.id unchanged. Do not invent quality identifiers: availability varies by link, source, region and current upstream response.

Create and follow a download job

Preparation is asynchronous so your HTTP worker never has to remain open while media is fetched or merged.

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://insto.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 job.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://insto.app/v1/jobs/JOB_ID \
  -H "X-API-Key: $YTSAVE_API_KEY"

Poll after 1 second, then use a capped 2–5 second backoff. Signed links and prepared files are temporary; download promptly and do not cache them as permanent media URLs.

Predictable errors

Non-2xx responses use one envelope with a request ID suitable for support.

{
  "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

Limits are assigned during review and protect both your integration and upstream platforms.

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.

Machine-readable schemas and an interactive explorer are available in the OpenAPI reference. Authentication and assigned limits still apply there.

OPERATOR-REVIEWED ACCESS

Request your API key

Tell us your product, expected monthly volume, required platforms and whether you need analysis, jobs or both. After approval, the key is shown once and only its secure hash is retained.

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