Preview only — activation required

Build downloads with downf.io

DownF keeps API execution disabled until an operator reviews the compatibility use case. The examples describe the planned contract, while real credentials and quotas arrive only through support activation.

DownfBridgeJSON over HTTPSAsynchronous jobsScoped credentials

Quick start

API host on DownF starts with support-activated credentials. It distinguishes an assigned tenant endpoint from a server-only call path.

Tenant URLhttps://downf.io

AuthenticationX-API-Key: pending_activation_…

Client profileDownfBridge

API versionv1

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

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

Credential safety on DownF starts with server-side secret storage. It distinguishes no client bundle embedding from no public logs or repositories.

Resolve a link

Resolve operation on DownF starts with source detection. It distinguishes formats from one submitted URL from no invented outputs.

POST/v1/resolveScope: resolve

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

Format identifier on DownF starts with the returned value unchanged. It distinguishes per-link availability from no guessed quality label.

Create and follow a download job

Job creation on DownF starts with asynchronous preparation. It distinguishes a short HTTP request from bounded worker execution.

POST/v1/jobsScope: jobs

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

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

1202 AcceptedSave transfer_ref.

2Poll statusGET /v1/jobs/{transfer_ref} 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://downf.io/v1/jobs/TRANSFER_REF \
  -H "X-API-Key: $DOWNF_ACCESS_TOKEN"

Job polling on DownF starts with one-second initial wait. It distinguishes capped backoff from temporary signed delivery.

Predictable errors

Error contract on DownF starts with one non-2xx envelope. It distinguishes a support request ID from 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

DownF assigns a request ceiling after reviewing the intended client, keeping its compatibility checks and upstream providers stable.

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 on DownF starts with activation before exploration. It distinguishes assigned authentication from documented request shapes.

OPERATOR-REVIEWED ACCESS

Activate through support

Describe the product, forecast its monthly calls and list the platforms it must analyze. DownF support will confirm the required scopes before issuing a one-time visible credential whose stored copy is only a hash.

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