Share links

A citation points at a page. A share link is how you actually fetch that page's image — a signed URL that works without an API key and stops working on a clock.

You mostly do not call these endpoints

Share links arrive attached to things you already fetched. Every file and file item response and every search match carries a share object with a url, a token and an expiresAt. Those endpoints take an expiresInSeconds parameter, which is how you set the lifetime in passing.

POST …/share/:fileItemId below is for the case where you have an item id — a citation's page, say — and want a link without refetching the item.

Lifetime

Default 600 seconds (ten minutes).
Minimum 60 seconds, maximum 86,400 (one day). Values outside the range are clamped rather than rejected.

The lifetime is not a tier benefit and never was. Nothing about account standing decides how long a signed URL stays valid.

What a token is, and what it is not

The token is a signature over the page's id and the expiry — v1.<epoch seconds>.<signature>. It carries its own authority: nothing is written when one is minted, and nothing is looked up when one is redeemed.

Three consequences, and the third is the one that matters:

Minting is free and unmetered. Every listing hands out fresh ones.
The item id is inside the signature, so a token authorises exactly one page. It cannot be replayed against another.
An individual token cannot be revoked. There is no stored record to delete. A leaked link keeps working until it expires — which is the argument for keeping expiresInSeconds short and for never persisting one.

The exception, and it is a real one: deleting the document kills every live link to its pages immediately. The redemption path checks the parent file's deletion before serving bytes, rather than waiting for the background cleanup, so a link to a deleted document starts answering 404 the moment the delete returns.

Treat them as credentials

A share URL grants anyone holding it the bytes of a customer document page, with no sign-in and no audit of who they are. Put them in a page a browser is about to render; do not put them in a log, an email, an analytics event, or your own database.

Both outcomes of a redemption — served and refused — are recorded in the security trail, because a bearer URL that cannot be individually revoked makes "how many times, and from where, was this link used" the only question anyone can ask after a leak.

Mint a share link

POST/v2/workspaces/:workspaceId/share/:fileItemId

Requires Read on the workspace

A link to one page. Read access is enough — minting a link cannot reach anything the key could not already read, and it writes nothing.

Note the parameter is expiresIn here, while the listing endpoints spell the same thing expiresInSeconds. Both are seconds.

Parameters

`expiresIn`	numberSeconds. Clamped to 60–86,400; defaults to 600.

Request

curl -X POST https://api.ragextract.com/v2/workspaces/wks_7Kq2mB4nR8vXpL3d/share/dsx_R4hN9kP2sD6yF1cV \
  -H "x-api-key: $RAGEXTRACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"expiresIn": 3600}'

Response

{
  "success": true,
  "total": 1,
  "data": {
    "url": "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.1756285200.9XkQ2mB4nR8vXpL3dZf9tY1cH6sQwE0aN…",
    "token": "v1.1756285200.9XkQ2mB4nR8vXpL3dZf9tY1cH6sQwE0aN…",
    "expiresAt": 1756285200000
  }
}

Redeem a share link

GET/v2/share/:fileItemId

Requires None — no API key

The one unauthenticated endpoint in the API. No x-api-key, and no workspace in the path — the browser redeeming a link has neither. The signed token is the whole credential, which is why it is kept off the nested tree.

Returns the page's bytes, not JSON — an image for a jpg item, a single-page PDF for a pdf one. The response is Cache-Control: private with a max-age set to the token's remaining life, so no shared cache may hold it and no client cache outlives the authority that fetched it.

401 — the token does not verify, or has expired.
404 — the page does not exist, or its document has been deleted. A valid token against deleted data gets this, not 401.

Query parameters

`token`	string · requiredThe signed token, exactly as issued. 1–128 characters.

Request

curl -L "https://api.ragextract.com/v2/share/dsx_R4hN9kP2sD6yF1cV?token=v1.1756285200.9XkQ…" \
  -o page-31.jpg

Response

HTTP/1.1 200 OK
content-type: image/jpeg
content-disposition: inline; filename="dsx_R4hN9kP2sD6yF1cV"
x-content-type-options: nosniff
cache-control: private, max-age=3407, immutable

<binary image data>