Create a share link

Módulo Platform

POST/share-linksshareLinks.create

Makes a link to the current clean version of a file the caller can read, through app.create_share_link. The database applies Section 8.6: Public files may omit `expires_at`; Internal files need one within 90 days; Confidential files need `data.export.confidential`, `expires_at` within 30 days and `recipient_email`, and always get an access code; Restricted files are refused (422 `share_link_restricted`). A Confidential PDF, or an image other than PNG or JPEG, cannot carry the viewer watermark and is refused (422 `share_link_watermark_unsupported`). Answers 201 with the token and access code, shown once. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Requiere la capacidad data.export.run.
Alcances de OAuth: data.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Cuerpo de la solicitud: ShareLinkCreate

shareLinks.create: ShareLinkCreate
Campo	Tipo	Obligatorio	Descripción
attachment_id	string (uuid)	Sí	Identifier of the file the link shares.
access_code_required	boolean	No	True when the link asks for a 6-digit access code; always true for a Confidential file.
recipient_email	string (email) \| null	No	Who the link is for, lowercased. Required for a Confidential file.
note	string \| null	No	What the link is for.Restricciones: length 1 to 200
expires_at	string (date-time) \| null	No	When the link stops opening: within 90 days, 30 for a Confidential file. Null only for a Public file.

{
  "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "access_code_required": false,
  "recipient_email": "alex.rivera@northwindlive.example",
  "note": "Stage plot for the venue",
  "expires_at": "2026-10-08T14:30:00Z"
}

Respuesta 201: ShareLinkToken

shareLinks.create: ShareLinkToken
Campo	Tipo	Obligatorio	Descripción
share_link_id	string (uuid)	Sí	The new link.
token	string	Sí	The link token. The link is `{Atlas origin}/share/{token}`. Shown once; only its hash is stored.Restricciones: pattern ^xshr_[0-9a-f]{64}$
access_code	string \| null	Sí	The 6-digit access code, or null when the link asks for none. Shown once; send it apart from the link.Restricciones: pattern ^[0-9]{6}$
classification	Classification	Sí	Column classification (Section 8.3).Restricciones: one of "Public", "Internal", "Confidential", "Restricted"
expires_at	string (date-time) \| null	Sí	When the link stops opening.

{
  "share_link_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "token": "xshr_0000000000000000000000000000000000000000000000000000000000000000",
  "access_code": "042424",
  "classification": "Restricted",
  "expires_at": "2026-10-08T14:30:00Z"
}

Ejemplos de código

curl -X POST "$XOS_BASE_URL/share-links" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"attachment_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","access_code_required":false,"recipient_email":"alex.rivera@northwindlive.example","note":"Stage plot for the venue","expires_at":"2026-10-08T14:30:00Z"}'

const { data } = await xos.shareLinks.create({
    "attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "access_code_required": false,
    "recipient_email": "alex.rivera@northwindlive.example",
    "note": "Stage plot for the venue",
    "expires_at": "2026-10-08T14:30:00Z"
  });

response = xos.share_links.create({"attachment_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "access_code_required": False, "recipient_email": "alex.rivera@northwindlive.example", "note": "Stage plot for the venue", "expires_at": "2026-10-08T14:30:00Z"})

xos share-links create --data '{"attachment_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","access_code_required":false,"recipient_email":"alex.rivera@northwindlive.example","note":"Stage plot for the venue","expires_at":"2026-10-08T14:30:00Z"}'