REST API: data room HTTP reference

Read full docsBuild with the full REST API. Endpoints, schemas, auth

Base URL & authentication

Base URLtext

https://api.papermark.com/v1

All requests require a bearer token. Mint one at app.papermark.com/settings/tokens ↗. See authentication for token formats and scopes.

Headerhttp

Authorization: Bearer pm_live_…

Response shape

Successful responses return a stable envelope:

Successjson

{
  "ok": true,
  "data": { … },
  "meta": { "next_cursor": "cur_01HX7…" }
}

Errorjson

{
  "ok": false,
  "error": {
    "code": "invalid_scope",
    "message": "Token is missing required scope: datarooms.write",
    "request_id": "req_01HX7…"
  }
}

Resources

Six resources. CRUD on all of them. Relations expressed via foreign keys.

Resource	ID prefix	Notes
dataroom	`dr_`	Access boundary; holds documents + folders
document	`doc_`	Versioned. Live in folders or datarooms
folder	`fld_`	Organize documents outside datarooms
link	`lnk_`	Public-facing share URL
visitor	`vis_`	Identified by email when gating is on
view	`vw_`	Single session of a visitor on a link

Datarooms

http

POST   /v1/datarooms
GET    /v1/datarooms
GET    /v1/datarooms/:id
PATCH  /v1/datarooms/:id
DELETE /v1/datarooms/:id

POST   /v1/datarooms/:id/documents
GET    /v1/datarooms/:id/documents
DELETE /v1/datarooms/:id/documents/:document_id

POST   /v1/datarooms/:id/folders
GET    /v1/datarooms/:id/folders
PATCH  /v1/datarooms/:id/folders/:folder_id
DELETE /v1/datarooms/:id/folders/:folder_id

Createbash

curl -X POST https://api.papermark.com/v1/datarooms \
  -H "Authorization: Bearer $PAPERMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Series A. Acme",
    "description": "Investor materials"
  }'

Documents

http

POST   /v1/documents          # upload (multipart) or register (presigned)
GET    /v1/documents
GET    /v1/documents/:id
PATCH  /v1/documents/:id
DELETE /v1/documents/:id

POST   /v1/documents/:id/versions
GET    /v1/documents/:id/versions
POST   /v1/documents/:id/versions/:version_id/promote

Links

http

POST   /v1/links
GET    /v1/links
GET    /v1/links/:id
PATCH  /v1/links/:id
DELETE /v1/links/:id    # revokes immediately

GET    /v1/links/:id/views      # paginated view events
GET    /v1/links/:id/analytics  # aggregated

Create a gated linkbash

curl -X POST https://api.papermark.com/v1/links \
  -H "Authorization: Bearer $PAPERMARK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataroom_id": "dr_01HX7…",
    "password": "pelican-42",
    "expires_at": "2026-12-31T23:59:59Z",
    "require_email": true,
    "allow_download": false,
    "watermark": "{{email}} · {{timestamp}}"
  }'

Folders

http

POST   /v1/folders
GET    /v1/folders
GET    /v1/folders/:id
PATCH  /v1/folders/:id
POST   /v1/folders/:id/move
DELETE /v1/folders/:id

Visitors & views

http

GET    /v1/visitors
GET    /v1/visitors/:id
GET    /v1/visitors/:id/views

Analytics

Aggregates per dataroom, link, document, or visitor. With per-page breakdowns.

http

GET    /v1/datarooms/:id/analytics
GET    /v1/links/:id/analytics
GET    /v1/documents/:id/analytics
GET    /v1/views/:id        # single-session detail

Errors

Status	Code	Meaning
400	`invalid_request`	Validation failed
401	`invalid_token`	Bad or revoked token
403	`invalid_scope`	Token lacks required scope
404	`not_found`	Resource missing or hidden by ACL
409	`conflict`	e.g. name already taken
429	`rate_limited`	Retry after `Retry-After` header
5xx	`internal_error`	Include `request_id` when reporting