API Documentation

A small, script-friendly endpoint for sending public firmware and system component source URLs to FTVDB without pasting them into the web form one at a time.

Overview

The API exists for contributors who already collect update source URLs from normal device behavior and want to hand them off efficiently. It does one thing: accept a single public URL and queue it for review. There is no authentication and no client library to install — a plain HTTP request is enough.

Submitting a URL does not guarantee it will be published. Every submission is validated, may be normalized or grouped with an existing device record, and is rejected if it is not a relevant public update link. See the manual for what makes a good submission.

Submissions must be public, unauthenticated, non-tokenized URLs observed through normal device update behavior. Do not submit private logs, credentials, generated URLs, guessed URLs, account-specific URLs, or URLs obtained through bypassing access controls.

Endpoint

Submit one URL per request, using whichever method fits your workflow.

GET — simplest for a URL you already have in hand:

GET https://api.ftvdb.com/submit-url?url=ENCODED_URL

POST — cleaner when your tool already produces JSON:

POST https://api.ftvdb.com/submit-url
Content-Type: application/json

{ "url": "https://example.com/update.bin" }

Request

url (string, required) — the public source URL observed on a device. For GET requests it must be percent-encoded so that characters like :, /, and ? inside the link do not break the query string.

Send one URL per request. If you have many, iterate over them and submit each in turn rather than combining them into a single value.

Response

Both methods return a JSON object with two fields:

error (boolean) — false when the URL was accepted, true when it was not.
message (string) — a short human-readable status. The exact wording can change, so show or log it rather than matching on it.

The response has this shape, with placeholder message text:

{ "error": false, "message": "..." }

Branch on error. Treat error: true as “not added” rather than a hard failure — a duplicate or out-of-scope link is a normal outcome, not a bug.

Examples

A one-off GET request with curl:

curl "https://api.ftvdb.com/submit-url?url=https%3A%2F%2Fexample.com%2Fupdate.bin"

The equivalent POST:

curl -X POST "https://api.ftvdb.com/submit-url" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/update.bin" }'

Submitting every URL from a file, one per line:

while IFS= read -r url; do
  [ -n "$url" ] || continue
  curl -s -X POST "https://api.ftvdb.com/submit-url" \
    -H "Content-Type: application/json" \
    -d "{\"url\":\"$url\"}"
  echo
done < urls.txt

Best Practices

Submit only links observed on real devices. De-duplicate locally first, keep your original logs private unless a reviewer asks for narrow context, and avoid generated or guessed paths — they create review noise without adding value.

Please Don't

Send private links, account-specific URLs, authentication tokens, or large machine-generated lists that were never seen on a device. Do not submit URLs obtained by bypassing technical controls. Submissions like these are rejected and slow down review for everyone.

Open Data

If you would rather read the database than write to it, full snapshots live in the FTVDB GitHub repository in a simple, scriptable structure.