Create a document

Create a document from a previously-uploaded file (via POST /v1/documents/upload-url using `upload_id`), an external file URL (`source_url`), or a non-file source via `type` + `external_url` (`link` for any external page, `notion` for a public Notion page).

Authorization

bearerAuth documents.write

AuthorizationBearer <token>

Dashboard-issued token (pm_live_...) or OAuth-issued access token.

In: header

Scope: documents.write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length

type?string

Create a non-file document from external_url: link stores an external HTTPS URL, notion stores a publicly-accessible Notion page. Omit for file-based documents created from upload_id or source_url — their type is inferred from the file's content type.

Value in"link" | "notion"

upload_id?string

Opaque upload handle returned from POST /v1/documents/upload-url. Content type comes from the upload session, not this request.

Length1 <= length

source_url?string

Publicly-accessible HTTPS URL. Content type is inferred from the response Content-Type header; the URL must return a supported document MIME type. The file is downloaded and stored — for non-file link/notion documents, use external_url.

Formaturi

external_url?string

HTTPS URL for a link document (any external page) or notion document (a publicly-accessible Notion page). Required when type is set; not allowed otherwise. The URL is stored as-is and never downloaded.

Formaturi

folder_id?string

ID of an existing folder (in the team library) to place this document into. Folders must be created beforehand via POST /v1/folders — paths are derived server-side and not accepted from clients. Omit to upload to the library root.

create_link?boolean

If true, also create a default share link for this document.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://api.papermark.com/v1/documents" \  -H "Content-Type: application/json" \  -d '{    "name": "pitch-deck-q4.pdf"  }'

{
  "id": "clxy9abc1234567890",
  "object": "document",
  "name": "pitch-deck-q4.pdf",
  "type": "pdf",
  "content_type": "application/pdf",
  "url": null,
  "num_pages": 12,
  "folder_id": null,
  "created": "2026-04-17T10:00:00.000Z",
  "updated_at": "2026-04-17T10:00:00.000Z"
}

{
  "error": {
    "code": "bad_request",
    "message": "The request body is not valid JSON.",
    "doc_url": "https://www.papermark.com/docs/api/errors#bad_request",
    "details": null
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing bearer token. Include an `Authorization: Bearer <token>` header.",
    "doc_url": "https://www.papermark.com/docs/api/errors#unauthorized",
    "details": null
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Token is missing required scope: links.write.",
    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
    "details": null
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Link link_abcd1234 not found.",
    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
    "details": null
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Invalid request body.",
    "doc_url": "https://www.papermark.com/docs/api/errors#unprocessable_entity",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "expires_at": [
          "Invalid datetime"
        ]
      }
    }
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 30s.",
    "doc_url": "https://www.papermark.com/docs/api/errors#rate_limit_exceeded",
    "details": null
  }
}

Create a document

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`