Public links

These endpoints share one resource from your library with someone who has no Mereon account. The link expires, can require a password, and can be turned off. You can also send it by email or text.

They need a token granted the public-link:write scope, which is an OAuth path today. A personal access token cannot hold it. Anyone who can read content in the organization can be granted it, except an external account. The person behind the token must also be allowed to do the act in Mereon, checked on every call.

A link’s address is the secret that opens the resource. Listing links, reading who a link was sent to, and reading a generated password sit on this scope for the same reason. A token that only reads cannot call them.

Most of these are limited to 30 calls a minute and 300 an hour. Sending a link is limited to 6 a minute and 60 an hour.

POST /v1/public-links

{
  "contentId": "…",
  "expiry": { "kind": "days", "days": 14 },
  "useSuggestedPassword": true
}

Field	Type	Notes
`contentId`	string	The resource id from `GET /v1/content`. Required.
`expiry`	object	When the link stops working. Leave it out for 30 days. `kind` is `never`, `days` (with `days`, from 1 to 365) or `at` (with `at`, an ISO instant). `never` is refused when the organization caps how long a link may last. A longer choice is shortened to that cap.
`password`	string	A password you choose, 8 to 200 characters of letters, numbers and ordinary punctuation.
`useSuggestedPassword`	boolean	Ask the server to generate a password.

A password you choose and useSuggestedPassword cannot both be set. The resource has to be one you can read. An external account is refused.

{
  "link": {
    "id": "…",
    "url": "https://…/shared/…",
    "contentId": "…",
    "resourceTitle": "Lockout procedure",
    "live": true,
    "hasPassword": true,
    "hasRetrievablePassword": true
  },
  "suggestedPassword": "…"
}

suggestedPassword is present when the server generated one. A password you supplied is stored as a hash and comes back as null here. The generated password can be read again from the password endpoint below. link.live says whether the link would open right now.

List every link in the organization

GET /v1/public-links

Every link in the organization, including ones that no longer open. Each row carries its address, and live with notLiveReason when it would not open. Needs permission to update the organization, which owners and admins have.

Turn off several links

POST /v1/public-links/revoke

{ "ids": ["…"] }

Field	Type	Notes
`ids`	string[]	1 to 200 link ids. Required.

{ "revoked": 1 }

revoked is how many changed. A link that was already off stays off, and the call still succeeds. Only the person who created a link, or an admin, can turn it off. The record stays, so the list can still explain what happened.

Organization settings

GET /v1/public-links/settings

Whether links are on, whether a resource shared with only some teams can be shared this way, the longest a link may last, and whether a new link must have a password. Needs permission to update the organization.

POST /v1/public-links/settings

{ "publicLinksEnabled": false }

Field	Type	Notes
`publicLinksEnabled`	boolean	Whether anyone can share a resource this way. Turning this off suspends every existing link.
`publicLinksAllowTeamRestricted`	boolean	Whether a resource shared with only some teams can have a public link.
`publicLinkMaxDurationDays`	number or null	The longest a link may last, in days, from 1 to 365. `null` clears the cap. Leave it out to keep the current cap.
`publicLinkPasswordRequired`	boolean	Whether a new link must have a password.

Only the fields you send change. The same permission as the read.

Whether a resource can be shared

GET /v1/public-links/eligibility/{contentId}

{ "shareable": true, "reason": null, "maxDurationDays": 30 }

shareable says whether you could share this resource right now. maxDurationDays is the organization’s cap, or null when there is none, so a link with no expiry is allowed. When shareable is false, reason is one of FEATURE_DISABLED, RESOURCE_BLOCKED, ADMINS_ONLY, TEAM_RESTRICTED_NOT_ALLOWED, RESOURCE_NOT_VIEWABLE, NOT_FOUND or SENDER_NOT_ALLOWED. A resource you cannot read is a 404.

Links for one resource

GET /v1/public-links/resource/{contentId}

Every link pointing at one resource, including ones that no longer open. Needs permission to read the resource. A resource you cannot read is a 404.

Bar one resource

POST /v1/public-links/blocked/{contentId}

{ "blocked": true }

Stops new links to this resource. blocked set to false lifts that bar. Existing links stay, and whether they still open is decided when someone opens them. Needs permission to update the resource. Someone who can read it and cannot update it gets a 403. Someone who cannot read it gets a 404.

{ "blocked": true }

Replace a link’s address

POST /v1/public-links/{id}/rotate

The previous address stops working. History, password and expiry stay. Each call mints a new address. Only the person who created the link, or an admin, can replace it.

{ "url": "https://…/shared/…" }

Turn off one link

POST /v1/public-links/{id}/revoke

The same result as turning off several, for one id. A link that was already off returns { "revoked": 0 }.

Send a link

POST /v1/public-links/{id}/share

{ "emails": ["ada@example.com"], "phones": [] }

Field	Type	Notes
`emails`	string[]	Email addresses.
`phones`	string[]	Phone numbers, 7 to 20 characters.

Send at least one address, and at most 20. There is no field for a message of your own. The text is the organization template. Anyone who can read the resource can send, and an external account cannot. A send that reaches some of the addresses and misses others succeeds, and names the ones that did not go out.

{
  "emailsSent": 1,
  "textsSent": 0,
  "failed": []
}

failed entries carry channel (email or sms) and the address as you typed it. Limited to 6 calls a minute and 60 an hour.

Who a link was sent to

GET /v1/public-links/{id}/recipients

Each row is one send: channel, address, status, failureReason when it failed, who sent it, and when. Needs permission to read the resource.

Read a generated password

GET /v1/public-links/{id}/password

{ "password": "…" }

The password the server generated. password is null when you supplied your own, because that one is stored only as a hash. Needs permission to read the resource.