Skip to main content
GET /v1/resolve recognizes a URL locally. It tells you which platform it belongs to, whether it names one item or an account, its stable identifier, and whether a lookup or an import would accept it. It reads nothing durable, writes nothing, and never charges.
url is the link you sent, normalized by the URL parser with any fragment removed. canonicalUrl is the platform’s own form of that object, without tracking parameters — a YouTube Shorts link canonicalizes to its /watch?v= form — and is null when the link names no single object. target is item, account, or null. supported is true exactly when reason is null, and it means an item lookup accepts this link, not that the item itself is public or still online. Only a lookup can tell you that.

​
Why a URL is unsupported

Recognition matches the item lookup exactly, form for form. A URL that resolves as supported is one lookup accepts, and a URL lookup rejects never resolves as supported.

​
Identifiers

id is a natural key: the platform’s own identifier, namespaced by platform, such as tiktok:7437269251355921707 or youtube:UC0123456789abcdefghijk. It is the same key an item carries in its id and author.id, so you can use it to deduplicate links before you look anything up. id is null whenever the URL does not carry the identifier the object is known by:
  • A handle-only account link. https://www.tiktok.com/@creator resolves with target: "account" and id: null. A handle is a different key space from the numeric author id an item carries, and returning one for the other would be a false match. A YouTube /channel/UC… link or an Ad Library ?view_all_page_id= link does carry a stable account id, so those return one.
  • Every Meta Ad Library ad link. The id in the URL is a deeplink id, and the page resolves it to the ad_archive_id an item is identified by. Returning the deeplink id would put two different identifiers in one key space, so an ad link resolves as supported: true, target: "item", id: null. Look the ad up and read id and ad.deeplinkId from the item to join the two.
vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…, and instagram.com/share/… links hide the real URL behind a redirect, and following it would be a network request. Resolution stays free and local, so these report reason: "short_link". Open one in a browser, or follow the redirect yourself, and pass the URL it lands on.

​
Errors

An unknown query key is named in details.field, with details.reason set to unknown_parameter. It is usually the tail of a link sent without URL-encoding: an unencoded &t=10s ends url before it and arrives as a key t. Encode the value, as --data-urlencode does. An unsupported URL is not an error here: it is a 200 with supported: false and a reason. Resolve is authenticated like every other workspace route, so it is not an unauthenticated data endpoint.

​
Next

  • Look up an item for the item itself, with freshness and credits.
  • Import a URL when you want media bytes and a reference you can keep.