Skip to main content
POST
manage public links

Authorizations

Authorization
string
header
required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key
string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id
string

The workspace this one call acts in, when it is not the key's own.

Body

application/json
action
enum<string>
required
Available options:
create,
list,
get,
update,
publish,
unpublish,
duplicate,
delete,
activity

Link id, slug or title, required for everything but create and list. Slug and title are matched against the 100 most recent links; older ones need their id.

items
string[]

create: the items on the link, in order.

Required array length: 1 - 200 elements

An item ref, item id, or the job id that made it.

title
string | null

create: the link's title. update: its new title. duplicate: the copy's title. The name it is filed under, not what the page says.

heading
string | null

update: the heading the page carries, and the title a pasted link previews with. Null puts the link's own name back on the page.

description
string | null

update: issue a fresh link; the old one stops working. For revoking a link that leaked.

enabled
boolean

update: whether the link answers at all.

allow_comments
boolean

update: visitors can leave comments.

permissions
object
add_items
string[]

update: append these to the link's layout without touching the rest of it, live after the next publish. Audio joins the page's playlist when it has one with room; everything else lands in a gallery or file list.

An item ref, item id, or the job id that made it.

remove_items
string[]

update: take these out of the layout; they leave the live link and its grant at the next publish.

An item ref, item id, or the job id that made it.

style
object
blocks
object[]

update: the whole layout, replacing what is there; get first and pass revision. Each block has a type and, to keep a block from get, its id: {type: "heading", level: 1|2|3, text}; {type: "text", text} (markdown); {type: "divider"}; {type: "items", items: [{ref, size?: "s"|"m"|"l", note?, download?, show_id?}], align?: "left"|"center"} (one picture stands alone, several become a gallery, audio a player, a CSV a table, the rest a download row); {type: "embed", url, note?} (YouTube, Vimeo, Loom, Figma, Spotify). A bad block is refused by its position.

Maximum array length: 300
revision
integer

update with blocks: the revision from get. A stale one refuses rather than overwriting.

context
string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

ok
any
required
data
object
required
meta
object
required
media
object[]