Preview only — activation required

Build downloads with Insts

The Insts workbench below is documentation for a prospective client. Operator review comes before any executable credential or call allowance is created.

InstsConnectJSON over HTTPSAsynchronous jobsScoped credentials

Quick start

API host starts with support-activated credentials on Insts. The next view covers an assigned tenant endpoint. The page keeps a server-only call path visible.

Tenant URLhttps://insts.io

AuthenticationX-API-Key: pending_activation_…

Client profileInstsConnect

API versionv1

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

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

Server-side secret storage is the starting point for Credential safety on Insts. An inspection bench then presents no client bundle embedding and explains no public logs or repositories.

Resolve a link

Resolve operation starts with source detection on Insts. The next view covers formats from one submitted URL. The page keeps no invented outputs visible.

POST/v1/resolveScope: resolve

Field	Type	Required	Description
`shared_post`	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
}

The returned value unchanged is the starting point for Format identifier on Insts. An inspection bench then presents per-link availability and explains no guessed quality label.

Create and follow a download job

Insts makes Job creation easy to scan. The page starts with asynchronous preparation, moves to a short HTTP request, and clearly states bounded worker execution.

POST/v1/jobsScope: jobs

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

curl -X POST https://insts.io/v1/jobs \
  -H "X-API-Key: $INSTS_CONNECT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"shared_post":"https://www.youtube.com/watch?v=VIDEO_ID","asset_option":"18"}'

1202 AcceptedSave connect_job.

2Poll statusGET /v1/jobs/{connect_job} 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://insts.io/v1/jobs/CONNECT_JOB \
  -H "X-API-Key: $INSTS_CONNECT_SECRET"

For Job polling, Insts checks one-second initial wait before capped backoff. This inspection bench also makes temporary signed delivery clear.

Predictable errors

Error contract begins with one non-2xx envelope on Insts. This inspection bench then presents a support request ID. The final fact is predictable client handling.

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

Insts establishes rate boundaries at review time to protect the inspection workspace and every provider route.

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.

Schema access starts with activation before exploration on Insts. The next view covers assigned authentication. The page keeps documented request shapes visible.

OPERATOR-REVIEWED ACCESS

Activate through support

Share the workbench use case, estimated call count and services under inspection. Insts reviews that boundary before a tenant credential is displayed once and reduced to a stored hash.

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