Add asset permalinks
add_asset_permalinksGive assets a permalink: a permanent, PUBLIC URL that needs no login and never expires, unlike the signed display_url, which dies at the end of the next day. Use it when a URL has to keep working — an external site, a deck, a doc, a hand-off to another system. Publishing is the point: the file is copied to a public bucket and anyone holding the URL can fetch it, so a sensitive file becomes public. It serves files, not web pages: an HTML file behind a permalink is sandboxed and its scripts never run, so never use it to host a page or app — deploy_app is for that. The copy runs in the background. This call waits up to about 20 seconds for it and returns the finished URLs under created; anything still copying comes back under pending with no URL. Read those with get_asset_permalinks shortly after — never publish them again; a URL does not work until it is reported there. A large video can take minutes. Assets that already have one are left untouched and are NOT in created — they are listed under already_had_permalink; read their URL with get_asset_permalinks. Assets that all already have one publish nothing and come back listed under already_had_permalink, not as a failure. A permalink only exists for real uploaded files: a link asset, a note, a colour swatch, or an upload still ingesting (is_skeleton: true) is listed under no_file_to_publish and nothing is created — poll get_asset until the upload finishes before asking. failed_to_publish means the file could not be copied at all and the permalink was withdrawn; retrying will not help. Capped per plan (10 Free, 100 on trials, 1,000 Pro, 5,000 Team/Business); going over returns 422 and publishes NOTHING — the whole batch is refused, not the overflow, and the count is taken before the unpublishable assets are skipped, so near the cap send only real files. If the call fails partway, the response still reports what was published or queued plus a remaining list — call again with exactly that list, never with the original one. Send the whole set in one call, up to 200 tokens. The response reports quota after the writes, and list_organizations reports the same headroom without publishing anything, so check it there before a batch you are not sure fits. Requires write scope and update permission on every asset; one unknown token fails the whole call.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"asset_tokens": "<asset_tokens>"
},
"name": "add_asset_permalinks"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| asset_tokens | Yes | Asset tokens to give a permalink (max 200 per call). Tokens that already have one are skipped. If the response carries `remaining`, call again with exactly those tokens. | |
| organization | No | Workspace slug, as returned by list_organizations. Omit it when the account has a single workspace — it is then resolved from your token. Pass it only when the account has several, or when you mean a workspace other than the obvious one. |