> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Resolve a URL
> Ask what a link points to before you spend anything on it. Free, instant, and no platform is contacted.
`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.
```bash curl theme={null}
curl -G https://api.refmatter.com/v1/resolve \
-H "Authorization: Bearer $REFMATTER_API_KEY" \
--data-urlencode "url=https://www.tiktok.com/@creator/video/7437269251355921707?is_from_webapp=1"
```
```ts TypeScript theme={null}
const resolution = await refmatter.urls.resolve(
'https://www.tiktok.com/@creator/video/7437269251355921707?is_from_webapp=1',
);
```
```json theme={null}
{
"object": "resolution",
"url": "https://www.tiktok.com/@creator/video/7437269251355921707?is_from_webapp=1",
"canonicalUrl": "https://www.tiktok.com/@creator/video/7437269251355921707",
"platform": "tiktok",
"target": "item",
"id": "tiktok:7437269251355921707",
"supported": true,
"reason": null
}
```
`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
| `reason` | `target` | Means |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------- |
| `account_not_supported` | `account` | A profile or channel. Pass a link to one of its posts |
| `short_link` | `null` | A share link that would need a network request. Open it and pass where it lands |
| `object_not_supported` | `item` | A recognized object of a kind we do not serve: a playlist, a live page, a TikTok photo post |
| `unrecognized_url` | `null` | A known platform, but not a path that names an item or an account |
| `unsupported_host` | `null` | Not a platform this product reads. `platform` is `null` |
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.
| Platform | Item links | Account links |
| --------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| TikTok | `/@handle/video/`, `/v/`, `/video/` | `/@handle` |
| Instagram | `/p/`, `/reel/…`, `/reels/…`, `/tv/…`, each with an optional leading `//` | `//` |
| YouTube | `/watch?v=`, `/shorts/`, `youtu.be/` | `/@handle`, `/channel/`, `/c/…`, `/user/…` |
| Meta Ad Library | `/ads/library/?id=` | `/ads/library/?view_all_page_id=` |
## 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.
## Short links
`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
| Code | HTTP | When |
| ---------------------------------------- | ---- | ------------------------------------------------------------------------------ |
| `invalid_input` | 400 | Missing `url`, a non-`http(s)` URL, embedded credentials, an unknown query key |
| `unauthenticated` / `invalid_credential` | 401 | No credential, or a key that is invalid, revoked, or expired |
| `not_found` | 404 | A workspace your credential cannot reach |
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](/guides/look-up-an-item) for the item itself, with freshness and credits.
* [Import a URL](/guides/import-a-url) when you want media bytes and a reference you can keep.