{
  "openapi": "3.1.0",
  "info": {
    "title": "Papermark Public API",
    "version": "1.0.0",
    "description": "Papermark's public REST API. All endpoints require a bearer token created in Settings → API Tokens, or issued via OAuth 2.1.",
    "contact": {
      "name": "Papermark",
      "url": "https://www.papermark.com"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://www.papermark.com/license"
    }
  },
  "servers": [
    {
      "url": "https://api.papermark.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000/api",
      "description": "Local development (no subdomain rewrite)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "Upload and manage documents."
    },
    {
      "name": "Folders",
      "description": "Organize documents into folders outside of any dataroom."
    },
    {
      "name": "Links",
      "description": "Create and manage share links."
    },
    {
      "name": "Datarooms",
      "description": "Create and manage virtual datarooms."
    },
    {
      "name": "Visitors",
      "description": "Persistent visitors and their view history."
    },
    {
      "name": "Analytics",
      "description": "Aggregate analytics backed by Tinybird. Subject to a tighter per-minute rate limit."
    }
  ],
  "paths": {
    "/v1/documents": {
      "get": {
        "summary": "List documents",
        "description": "Returns a paginated list of documents for the authenticated team.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "folderId",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a document",
        "description": "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).",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/documents/{id}": {
      "get": {
        "summary": "Get a document",
        "description": "Returns metadata for a single document — name, type, content type, page count, folder, and timestamps.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a document",
        "description": "Edit document metadata: rename it, or move it to a different team-library folder. Replacing the file content is a separate operation — use POST /v1/documents/{id}/versions.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a document",
        "description": "Permanently deletes a document by id.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "The deleted document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/documents/{id}/versions": {
      "get": {
        "summary": "List versions of a document",
        "description": "Returns every version recorded for a document, newest first. Exactly one version has `is_primary: true`.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Versions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentVersionList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Add a new version of a document",
        "description": "Record a new version of a document. For file documents, upload a replacement file (`upload_id`/`source_url`) — conversion / pre-processing jobs are triggered to match the dashboard's version-upload flow. For `link`/`notion` documents, pass `external_url` to repoint them at a new URL. Either way the new version becomes primary and the previous primary is demoted in the same transaction.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDocumentVersionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Version created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentVersion"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/documents/{id}/versions/{vid}": {
      "get": {
        "summary": "Get a document version",
        "description": "Returns a single version of a document.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "vid",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentVersion"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Promote a version to primary",
        "description": "Set `is_primary: true` to promote this version. The previously-primary version is demoted in the same transaction. The only valid body is `{ \"is_primary\": true }`; demoting without promoting another version is not supported.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "vid",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromoteDocumentVersionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Promoted version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentVersion"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/documents/search": {
      "get": {
        "summary": "Search documents",
        "description": "Case-insensitive substring match against document name. Returns up to `limit` most-recent matches.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string",
              "minLength": 1,
              "example": "pitch deck"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/documents/upload-url": {
      "post": {
        "summary": "Generate a presigned upload URL",
        "description": "Step 1 of the document upload flow. Returns a presigned S3 PUT URL and an opaque one-time `upload_id`. Upload the file bytes directly to `upload_url`, then call POST /v1/documents with that `upload_id`.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadUrlRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadUrlResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/folders": {
      "get": {
        "summary": "List folders",
        "description": "Returns folders in the team library. Use `parent_id=root` to list top-level folders, or `parent_id=<id>` for direct children of a specific folder. Without `parent_id` returns every folder in the team.",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "parent_id",
            "description": "When provided, returns only direct children of this folder. Use the literal string `root` to list top-level folders.",
            "schema": {
              "type": "string",
              "description": "When provided, returns only direct children of this folder. Use the literal string `root` to list top-level folders."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of folders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FolderList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a folder",
        "description": "Create a folder in the team library. The folder's `path` is derived server-side from its name and parent — clients never set it. If a sibling already has the chosen name, a numeric suffix is appended (e.g. `Pitches (1)`).",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFolderRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Folder created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Folder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/folders/{id}": {
      "get": {
        "summary": "Get a folder",
        "description": "Returns a single folder by id.",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Folder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a folder",
        "description": "Rename the folder or update its icon/color. Renaming rewrites the `path` of this folder and every descendant in a single transaction.",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFolderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Folder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a folder",
        "description": "Delete a folder. Refuses non-empty folders unless `cascade=true`, in which case every descendant folder and document is deleted.",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "cascade",
            "description": "When `true`, deletes the folder and every nested folder + document inside it. Without `cascade=true` a non-empty folder returns 409.",
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "true"
                },
                {
                  "type": "string",
                  "const": "false"
                }
              ],
              "default": "false",
              "description": "When `true`, deletes the folder and every nested folder + document inside it. Without `cascade=true` a non-empty folder returns 409."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The deleted folder.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "409": {
            "description": "Folder is not empty and `cascade=true` was not provided."
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/folders/{id}/move": {
      "post": {
        "summary": "Move a folder",
        "description": "Reparent a folder. Refuses moves into the folder itself or any of its descendants, and refuses if the target parent already has a sibling with the same slug. Descendant `path`s are rewritten in a single transaction.",
        "tags": [
          "Folders"
        ],
        "security": [
          {
            "bearerAuth": [
              "documents.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MoveFolderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Moved folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Folder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/links": {
      "get": {
        "summary": "List share links",
        "description": "Paginated list of share links for the team. Filter by `document_id` or `dataroom_id`.",
        "tags": [
          "Links"
        ],
        "security": [
          {
            "bearerAuth": [
              "links.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "document_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataroom_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of links",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a share link",
        "description": "Creates a share link for a document or dataroom. Optional password, expiry, email allowlist, and other access controls. Pass `domain` + `slug` together to host the link on a verified custom domain.",
        "tags": [
          "Links"
        ],
        "security": [
          {
            "bearerAuth": [
              "links.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLinkRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Link created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Link"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict — slug already in use",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "The slug `q4-acme-ventures` is already in use on domain `dataroom.acme.com`.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#conflict",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/links/{id}": {
      "get": {
        "summary": "Get a share link",
        "description": "Returns a single share link with its access controls and the public URL.",
        "tags": [
          "Links"
        ],
        "security": [
          {
            "bearerAuth": [
              "links.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Link"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a share link",
        "description": "Partial update — only the fields you pass are changed. Useful for rotating passwords, updating expiry, or changing access controls. Pass `domain` + `slug` together to move the link onto a verified custom domain.",
        "tags": [
          "Links"
        ],
        "security": [
          {
            "bearerAuth": [
              "links.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLinkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Link"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict — slug already in use",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "The slug `q4-acme-ventures` is already in use on domain `dataroom.acme.com`.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#conflict",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Revoke a share link (soft delete)",
        "description": "Soft-deletes the link. The public URL stops resolving immediately; the row is kept in the database for audit.",
        "tags": [
          "Links"
        ],
        "security": [
          {
            "bearerAuth": [
              "links.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "The deleted link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/links/{id}/views": {
      "get": {
        "summary": "List views for a share link",
        "description": "Returns cursor-paginated view records for a link in reverse-chronological order.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": [
              "analytics.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of views",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms": {
      "get": {
        "summary": "List datarooms",
        "description": "Paginated list of datarooms for the authenticated team.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of datarooms",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a dataroom",
        "description": "Create a new dataroom. Documents are added separately.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDataroomRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dataroom created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataroom"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}": {
      "get": {
        "summary": "Get a dataroom",
        "description": "Returns dataroom metadata including document and folder counts. Accepts either the internal id or the `dr_…` public id.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Dataroom",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataroom"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a dataroom",
        "description": "Partial update of dataroom metadata. Documents are managed via the dataroom-documents endpoints, not here.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDataroomRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated dataroom",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataroom"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a dataroom",
        "description": "Permanently deletes a dataroom and its document/folder mapping. The underlying documents are not deleted — only the dataroom and its membership rows.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The deleted dataroom.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/documents": {
      "post": {
        "summary": "Attach an existing document to a dataroom",
        "description": "Add an already-uploaded document to a dataroom, optionally placing it inside a dataroom folder. The document must belong to the same team as the dataroom; cross-team attaches are refused. Frozen datarooms refuse new attachments.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AttachDataroomDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document attached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomItem"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List documents in a dataroom",
        "description": "Returns DataroomDocument rows (the join between a dataroom and an underlying Document), ordered by folder then orderIndex.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "folder_id",
            "description": "Filter to documents inside a specific folder.",
            "schema": {
              "type": "string",
              "description": "Filter to documents inside a specific folder."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of dataroom documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomItemList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/documents/{ddId}": {
      "delete": {
        "summary": "Detach a document from a dataroom",
        "description": "Remove a single document's attachment to this dataroom, identified by the DataroomDocument id (`ddId`) returned when the document was attached or listed. The underlying document in the team library — and any attachment to other datarooms — is left intact. Frozen datarooms refuse detaches.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "ddId",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "The detached dataroom document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/documents/{ddId}/move": {
      "post": {
        "summary": "Move a document to another folder within a dataroom",
        "description": "Move a dataroom document (identified by its DataroomDocument id `ddId`) into a different folder of the same dataroom, or to the dataroom root with `folder_id: null`. Only the attachment's placement changes — the underlying document and its attachments to other datarooms are untouched. Frozen datarooms refuse moves.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "ddId",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MoveDataroomDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Moved dataroom document",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomItem"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/folders": {
      "get": {
        "summary": "List folders in a dataroom",
        "description": "Returns folders inside a dataroom. Use `parent_id=root` to list top-level folders, or `parent_id=<id>` for direct children of a specific folder. Without `parent_id` returns every folder in the dataroom.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "parent_id",
            "description": "When provided, returns only direct children of this folder. Use the literal `root` to list top-level folders. Without `parent_id`, returns every folder in the dataroom.",
            "schema": {
              "type": "string",
              "description": "When provided, returns only direct children of this folder. Use the literal `root` to list top-level folders. Without `parent_id`, returns every folder in the dataroom."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of dataroom folders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomFolderList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a dataroom folder",
        "description": "Create a folder inside a dataroom. Path is derived server-side from name + parent. On sibling-name collision a numeric suffix is appended. Default permissions (matching the dashboard's create flow) are applied.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDataroomFolderRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Folder created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomFolder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/folders/{fid}": {
      "get": {
        "summary": "Get a dataroom folder",
        "description": "Returns a single folder inside a dataroom.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "fid",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomFolder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a dataroom folder",
        "description": "Rename a folder or update its icon/color. Renaming rewrites the `path` of this folder and every descendant in a single transaction.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "fid",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDataroomFolderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomFolder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a dataroom folder",
        "description": "Delete a folder inside a dataroom. Refuses non-empty folders unless `cascade=true`. Cascade deletes nested folders and detaches every dataroom-document inside them — the underlying documents in the team library are kept.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "fid",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "query",
            "name": "cascade",
            "description": "When `true`, deletes the folder and every nested folder + dataroom-document attachment beneath it. The underlying documents in the team library are NOT deleted — only their attachments to this dataroom.",
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "true"
                },
                {
                  "type": "string",
                  "const": "false"
                }
              ],
              "default": "false",
              "description": "When `true`, deletes the folder and every nested folder + dataroom-document attachment beneath it. The underlying documents in the team library are NOT deleted — only their attachments to this dataroom."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The deleted dataroom folder.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedObject"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "409": {
            "description": "Folder is not empty and `cascade=true` was not provided."
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/datarooms/{id}/folders/{fid}/move": {
      "post": {
        "summary": "Move a dataroom folder",
        "description": "Reparent a folder within a dataroom. Refuses moves into the folder itself or one of its descendants, and refuses if the target parent already has a sibling with the same slug. Descendant `path`s are rewritten in a single transaction.",
        "tags": [
          "Datarooms"
        ],
        "security": [
          {
            "bearerAuth": [
              "datarooms.write"
            ]
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "in": "path",
            "name": "fid",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MoveDataroomFolderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Moved folder",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomFolder"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/visitors": {
      "get": {
        "summary": "List visitors",
        "description": "Paginated list of persistent visitors for the team (rows in the Viewer table). Anonymous views that were never tied to a Viewer record are available via GET /v1/links/{id}/views instead.",
        "tags": [
          "Visitors"
        ],
        "security": [
          {
            "bearerAuth": [
              "visitors.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "email",
            "description": "Exact email match (case-insensitive) — e.g. ?email=jane@acme.com",
            "schema": {
              "type": "string",
              "description": "Exact email match (case-insensitive) — e.g. ?email=jane@acme.com"
            }
          },
          {
            "in": "query",
            "name": "dataroom_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of visitors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/visitors/{id}": {
      "get": {
        "summary": "Get a visitor",
        "description": "Returns a single persistent visitor (Viewer row) with their email, verification state, dataroom association, and view count.",
        "tags": [
          "Visitors"
        ],
        "security": [
          {
            "bearerAuth": [
              "visitors.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Visitor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Visitor"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/visitors/{id}/views": {
      "get": {
        "summary": "List a visitor's views",
        "description": "All view events tied to this visitor, newest first.",
        "tags": [
          "Visitors"
        ],
        "security": [
          {
            "bearerAuth": [
              "visitors.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of views",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitorViewList"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/documents/{id}": {
      "get": {
        "summary": "Document analytics",
        "description": "Aggregate analytics for a single document: total views, unique viewers, total read time, per-page average duration. Backed by Tinybird — subject to a tighter per-minute rate limit than other endpoints.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": [
              "analytics.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "description": "Unix milliseconds — start of window (default: 30 days ago)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — start of window (default: 30 days ago)",
              "example": 1734567890000
            }
          },
          {
            "in": "query",
            "name": "until",
            "description": "Unix milliseconds — end of window (default: now)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — end of window (default: now)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document analytics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/links/{id}": {
      "get": {
        "summary": "Link analytics",
        "description": "Aggregate analytics for a single share link: total views, total read time, unique viewers. Backed by Tinybird — tighter rate limit.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": [
              "analytics.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "description": "Unix milliseconds — start of window (default: 30 days ago)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — start of window (default: 30 days ago)",
              "example": 1734567890000
            }
          },
          {
            "in": "query",
            "name": "until",
            "description": "Unix milliseconds — end of window (default: now)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — end of window (default: now)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link analytics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/datarooms/{id}": {
      "get": {
        "summary": "Dataroom analytics",
        "description": "Aggregate analytics across all documents in a dataroom: total views, unique viewers, total read time. Backed by Tinybird — tighter rate limit.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": [
              "analytics.read"
            ]
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "description": "Unix milliseconds — start of window (default: 30 days ago)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — start of window (default: 30 days ago)",
              "example": 1734567890000
            }
          },
          {
            "in": "query",
            "name": "until",
            "description": "Unix milliseconds — end of window (default: now)",
            "schema": {
              "type": "integer",
              "description": "Unix milliseconds — end of window (default: now)"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataroom analytics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataroomAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/views/{id}": {
      "get": {
        "summary": "Per-view breakdown",
        "description": "Page-by-page duration, viewer location, and client info for a single view event. Backed by Tinybird — tighter rate limit.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": [
              "analytics.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "View analytics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ViewAnalytics"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "403": {
            "description": "Token lacks required scope or team access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Token is missing required scope: links.write.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#forbidden",
                    "details": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Link link_abcd1234 not found.",
                    "doc_url": "https://www.papermark.com/docs/api/errors#not_found",
                    "details": null
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "papermark-token",
        "description": "Dashboard-issued token (`pm_live_...`) or OAuth-issued access token."
      }
    },
    "schemas": {
      "DocumentList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890"
          },
          "object": {
            "type": "string",
            "const": "document",
            "description": "String representing the object's type. Always `document`."
          },
          "name": {
            "type": "string",
            "example": "pitch-deck-q4.pdf"
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "example": "pdf"
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ],
            "example": "application/pdf"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "For `link` and `notion` documents, the external target URL the document points to. `null` for file-based documents (their bytes live in storage, not at a public URL).",
            "example": null
          },
          "num_pages": {
            "type": [
              "integer",
              "null"
            ],
            "example": 12
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-17T10:00:00.000Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-04-17T10:00:00.000Z"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "type",
          "content_type",
          "url",
          "num_pages",
          "folder_id",
          "created",
          "updated_at"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "bad_request",
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "unprocessable_entity",
                  "rate_limit_exceeded",
                  "internal_server_error"
                ],
                "example": "unauthorized"
              },
              "message": {
                "type": "string",
                "example": "Missing bearer token."
              },
              "doc_url": {
                "type": "string",
                "format": "uri",
                "example": "https://www.papermark.com/docs/api/errors#unauthorized"
              },
              "details": {}
            },
            "required": [
              "code",
              "message",
              "doc_url"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "CreateDocumentRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "example": "pitch-deck-q4.pdf"
          },
          "type": {
            "type": "string",
            "enum": [
              "link",
              "notion"
            ],
            "description": "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.",
            "example": "link"
          },
          "upload_id": {
            "type": "string",
            "minLength": 1,
            "description": "Opaque upload handle returned from POST /v1/documents/upload-url. Content type comes from the upload session, not this request.",
            "example": "upload_3xA5v7r8K9mN2pQ4sT6uVwXy"
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "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`."
          },
          "external_url": {
            "type": "string",
            "format": "uri",
            "description": "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.",
            "example": "https://example.com/page"
          },
          "folder_id": {
            "type": "string",
            "description": "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.",
            "example": "clxy9abc1234567890"
          },
          "create_link": {
            "type": "boolean",
            "default": false,
            "description": "If true, also create a default share link for this document."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "UpdateDocumentRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ID of an existing team-library folder to move this document into, or null to move it to the library root."
          }
        },
        "additionalProperties": false
      },
      "DeletedObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890"
          },
          "object": {
            "type": "string",
            "enum": [
              "document",
              "folder",
              "link",
              "dataroom",
              "dataroom_folder",
              "dataroom_document"
            ],
            "description": "The type of object that was deleted.",
            "example": "document"
          },
          "deleted": {
            "type": "boolean",
            "const": true,
            "description": "Always `true`. Confirms the object was deleted."
          }
        },
        "required": [
          "id",
          "object",
          "deleted"
        ]
      },
      "DocumentVersionList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentVersion"
            }
          }
        },
        "required": [
          "data"
        ]
      },
      "DocumentVersion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9ver1234567890"
          },
          "object": {
            "type": "string",
            "const": "document_version",
            "description": "String representing the object's type. Always `document_version`."
          },
          "version_number": {
            "type": "integer",
            "example": 2
          },
          "is_primary": {
            "type": "boolean",
            "example": true
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "example": "pdf"
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ],
            "example": "application/pdf"
          },
          "num_pages": {
            "type": [
              "integer",
              "null"
            ],
            "example": 12
          },
          "file_size": {
            "type": [
              "integer",
              "null"
            ],
            "example": 2048576
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "version_number",
          "is_primary",
          "type",
          "content_type",
          "num_pages",
          "file_size",
          "created",
          "updated_at"
        ]
      },
      "CreateDocumentVersionRequest": {
        "type": "object",
        "properties": {
          "upload_id": {
            "type": "string",
            "minLength": 1,
            "description": "Opaque upload handle returned from POST /v1/documents/upload-url. Content type, size, and page count come from the upload session / file inspection — not this request."
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Publicly-accessible HTTPS URL. Content type is inferred from the response Content-Type header."
          },
          "external_url": {
            "type": "string",
            "format": "uri",
            "description": "Repoint a `link`/`notion` document at a new URL. Only valid when the document is already a `link` or `notion` document; the type is preserved. The URL is stored as-is (not downloaded) and becomes the new primary version. Not allowed for file-based documents — use `upload_id`/`source_url` for those."
          }
        },
        "additionalProperties": false
      },
      "PromoteDocumentVersionRequest": {
        "type": "object",
        "properties": {
          "is_primary": {
            "type": "boolean",
            "const": true,
            "description": "Set to `true` to promote this version. The previous primary is demoted in the same transaction."
          }
        },
        "required": [
          "is_primary"
        ],
        "additionalProperties": false
      },
      "UploadUrlRequest": {
        "type": "object",
        "properties": {
          "file_name": {
            "type": "string",
            "minLength": 1,
            "example": "pitch-deck.pdf"
          },
          "content_type": {
            "type": "string",
            "minLength": 1,
            "example": "application/pdf"
          },
          "content_length": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "File size in bytes. Papermark rejects requests above the team's file-size limit before returning a presigned URL. The actual uploaded object size is verified when the upload_id is redeemed.",
            "example": 2048576
          }
        },
        "required": [
          "file_name",
          "content_type",
          "content_length"
        ],
        "additionalProperties": false
      },
      "UploadUrlResponse": {
        "type": "object",
        "properties": {
          "upload_url": {
            "type": "string",
            "format": "uri",
            "description": "Presigned S3 URL. PUT the file bytes to this URL.",
            "example": "https://s3.eu-central-1.amazonaws.com/..."
          },
          "upload_id": {
            "type": "string",
            "description": "Opaque one-time upload handle to pass back in POST /v1/documents `upload_id`.",
            "example": "upload_3xA5v7r8K9mN2pQ4sT6uVwXy"
          },
          "required_headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "HTTP headers the client MUST include in the PUT request — these are part of the signed request and an omission produces a 403.",
            "example": {
              "Content-Type": "application/pdf",
              "Content-Disposition": "attachment; filename=\"pitch.pdf\"; filename*=UTF-8''pitch.pdf"
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "upload_url",
          "upload_id",
          "required_headers",
          "expires_at"
        ]
      },
      "FolderList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Folder"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "Folder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890"
          },
          "object": {
            "type": "string",
            "const": "folder",
            "description": "String representing the object's type. Always `folder`."
          },
          "name": {
            "type": "string",
            "example": "Pitches"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "path": {
            "type": "string",
            "example": "/pitches",
            "description": "Server-derived path of slugified folder names. Read-only — never accepted from clients."
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "document_count": {
            "type": "integer",
            "example": 0
          },
          "child_folder_count": {
            "type": "integer",
            "example": 0
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "parent_id",
          "path",
          "icon",
          "color",
          "document_count",
          "child_folder_count",
          "created",
          "updated_at"
        ]
      },
      "CreateFolderRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "example": "Pitches"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional parent folder id. Omit or pass null to create at the team-library root."
          },
          "icon": {
            "type": "string",
            "enum": [
              "folder",
              "folder-open",
              "briefcase",
              "archive",
              "box",
              "file",
              "book",
              "bookmark",
              "star",
              "heart",
              "lock",
              "shield",
              "users",
              "settings",
              "tag",
              "layers",
              "globe",
              "home",
              "mail",
              "image",
              "video",
              "music",
              "palette",
              "pen-tool",
              "lightbulb",
              "zap",
              "wrench",
              "sparkles",
              "cloud",
              "flag",
              "award",
              "flame",
              "bell",
              "sun",
              "hash"
            ],
            "description": "Allowed folder icon name."
          },
          "color": {
            "type": "string",
            "enum": [
              "gray",
              "red",
              "orange",
              "yellow",
              "green",
              "blue",
              "black"
            ],
            "description": "Allowed folder color token."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "UpdateFolderRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "folder",
              "folder-open",
              "briefcase",
              "archive",
              "box",
              "file",
              "book",
              "bookmark",
              "star",
              "heart",
              "lock",
              "shield",
              "users",
              "settings",
              "tag",
              "layers",
              "globe",
              "home",
              "mail",
              "image",
              "video",
              "music",
              "palette",
              "pen-tool",
              "lightbulb",
              "zap",
              "wrench",
              "sparkles",
              "cloud",
              "flag",
              "award",
              "flame",
              "bell",
              "sun",
              "hash",
              null
            ],
            "description": "Allowed folder icon name."
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "gray",
              "red",
              "orange",
              "yellow",
              "green",
              "blue",
              "black",
              null
            ],
            "description": "Allowed folder color token."
          }
        },
        "additionalProperties": false
      },
      "MoveFolderRequest": {
        "type": "object",
        "properties": {
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target parent folder id, or null to move to the root."
          }
        },
        "required": [
          "parent_id"
        ],
        "additionalProperties": false
      },
      "LinkList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Link"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "Link": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxabc1234567890"
          },
          "object": {
            "type": "string",
            "const": "link",
            "description": "String representing the object's type. Always `link`."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Q4 pitch — Acme Ventures"
          },
          "target_type": {
            "type": "string",
            "enum": [
              "document",
              "dataroom"
            ],
            "example": "document",
            "description": "The kind of resource this link points at. The matching `document_id` / `dataroom_id` field is populated; the other is null."
          },
          "document_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "clxdoc0987654321"
          },
          "dataroom_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "description": "The public view URL for this link.",
            "example": "https://www.papermark.com/view/clxabc1234567890"
          },
          "domain": {
            "type": [
              "string",
              "null"
            ],
            "description": "Custom domain the link is hosted on. The same value accepted as `domain` on create/update. Null when the link uses the default papermark.com URL.",
            "example": "dataroom.acme.com"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ],
            "example": "q4-acme-ventures"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "is_password_protected": {
            "type": "boolean",
            "description": "True if a password is set. The password itself is never returned."
          },
          "email_protected": {
            "type": "boolean"
          },
          "email_authenticated": {
            "type": "boolean"
          },
          "allow_download": {
            "type": "boolean"
          },
          "allow_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Email or domain allow list (e.g., ['@acme.com', 'bob@example.com'])."
          },
          "deny_list": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enable_watermark": {
            "type": "boolean"
          },
          "watermark_config": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/WatermarkConfig"
              },
              {
                "type": "null"
              }
            ],
            "description": "Watermark configuration applied when `enable_watermark` is true. Null when no config has been set; the viewer falls back to safe defaults."
          },
          "enable_feedback": {
            "type": "boolean"
          },
          "enable_screenshot_protection": {
            "type": "boolean"
          },
          "enable_confidential_view": {
            "type": "boolean"
          },
          "enable_agreement": {
            "type": "boolean",
            "description": "Whether viewers must accept an agreement (NDA) before viewing. Requires `agreement_id`. Available on the Data Rooms plan and above."
          },
          "agreement_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ID of the Agreement viewers must accept. Null when no agreement is required."
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "target_type",
          "document_id",
          "dataroom_id",
          "url",
          "domain",
          "slug",
          "expires_at",
          "is_password_protected",
          "email_protected",
          "email_authenticated",
          "allow_download",
          "allow_list",
          "deny_list",
          "enable_watermark",
          "watermark_config",
          "enable_feedback",
          "enable_screenshot_protection",
          "enable_confidential_view",
          "enable_agreement",
          "agreement_id",
          "created",
          "updated_at"
        ]
      },
      "WatermarkConfig": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "example": "Confidential — {{email}} — {{date}}",
            "description": "Watermark text. Supports tokens that are interpolated per view: `{{email}}`, `{{date}}`, `{{time}}`, `{{link}}`, `{{ipAddress}}`."
          },
          "is_tiled": {
            "type": "boolean",
            "description": "When true, tile the watermark across the page instead of rendering it once at `position`."
          },
          "position": {
            "type": "string",
            "enum": [
              "top-left",
              "top-center",
              "top-right",
              "middle-left",
              "middle-center",
              "middle-right",
              "bottom-left",
              "bottom-center",
              "bottom-right"
            ],
            "example": "middle-center",
            "description": "Anchor position of the watermark on each page."
          },
          "rotation": {
            "anyOf": [
              {
                "type": "number",
                "const": 0
              },
              {
                "type": "number",
                "const": 30
              },
              {
                "type": "number",
                "const": 45
              },
              {
                "type": "number",
                "const": 90
              },
              {
                "type": "number",
                "const": 180
              }
            ],
            "example": 45,
            "description": "Rotation in degrees. One of 0, 30, 45, 90, 180."
          },
          "color": {
            "type": "string",
            "pattern": "^#([0-9A-Fa-f]{3}){1,2}$",
            "example": "#000000",
            "description": "Text color as `#RGB` or `#RRGGBB`."
          },
          "font_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 96,
            "example": 24,
            "description": "Font size in points. 1–96."
          },
          "opacity": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0.5,
            "description": "Opacity from 0 (invisible) to 1 (fully opaque)."
          }
        },
        "required": [
          "text",
          "is_tiled",
          "position",
          "rotation",
          "color",
          "font_size",
          "opacity"
        ]
      },
      "CreateLinkRequest": {
        "type": "object",
        "properties": {
          "document_id": {
            "type": "string"
          },
          "dataroom_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "password": {
            "type": "string",
            "minLength": 1
          },
          "email_protected": {
            "type": "boolean",
            "default": true
          },
          "email_authenticated": {
            "type": "boolean",
            "default": false
          },
          "allow_download": {
            "type": "boolean",
            "default": false
          },
          "allow_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "deny_list": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "enable_watermark": {
            "type": "boolean",
            "default": false
          },
          "watermark_config": {
            "$ref": "#/components/schemas/WatermarkConfig",
            "description": "Watermark configuration. Only applied when `enable_watermark` is true. Optional even when watermark is enabled; omitting it stores no config and the viewer renders with defaults."
          },
          "enable_screenshot_protection": {
            "type": "boolean",
            "default": false
          },
          "enable_confidential_view": {
            "type": "boolean",
            "default": false
          },
          "enable_agreement": {
            "type": "boolean",
            "default": false,
            "description": "Require viewers to accept an agreement (NDA) before viewing. Set together with `agreement_id`. Available on the Data Rooms plan and above."
          },
          "agreement_id": {
            "type": "string",
            "description": "ID of the Agreement viewers must accept. Required when `enable_agreement` is true."
          },
          "domain": {
            "type": "string",
            "description": "Custom domain to host the link on. Must be a verified domain connected to your team and must be sent together with `slug`. Requires the Business plan for document links or the Data Rooms plan for dataroom links. Omit to use the default `papermark.com` view URL.",
            "example": "docs.acme.com"
          },
          "slug": {
            "type": "string",
            "description": "Path segment for the custom-domain URL. Must be sent together with `domain` and be unique within that domain.",
            "example": "acme-ventures"
          }
        },
        "additionalProperties": false
      },
      "UpdateLinkRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "password": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Pass null to remove the password."
          },
          "email_protected": {
            "type": "boolean"
          },
          "email_authenticated": {
            "type": "boolean"
          },
          "allow_download": {
            "type": "boolean"
          },
          "allow_list": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "deny_list": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enable_watermark": {
            "type": "boolean"
          },
          "watermark_config": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/WatermarkConfig"
              },
              {
                "type": "null"
              }
            ],
            "description": "Watermark configuration. Pass an object to replace the existing config, or `null` to clear it. Omit to leave it unchanged."
          },
          "enable_screenshot_protection": {
            "type": "boolean"
          },
          "enable_confidential_view": {
            "type": "boolean"
          },
          "enable_agreement": {
            "type": "boolean",
            "description": "Require viewers to accept an agreement (NDA) before viewing. Set together with `agreement_id` when enabling. Available on the Data Rooms plan and above."
          },
          "agreement_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ID of the Agreement viewers must accept. Pass null to clear."
          },
          "domain": {
            "type": "string",
            "description": "Custom domain to host the link on. Must be a verified domain connected to your team and must be sent together with `slug`. Requires the Business plan for document links or the Data Rooms plan for dataroom links.",
            "example": "docs.acme.com"
          },
          "slug": {
            "type": "string",
            "description": "Path segment for the custom-domain URL. Must be sent together with `domain` and be unique within that domain.",
            "example": "acme-ventures"
          }
        },
        "additionalProperties": false
      },
      "ViewList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/View"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "View": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxview1234567890"
          },
          "object": {
            "type": "string",
            "const": "view",
            "description": "String representing the object's type. Always `view`."
          },
          "link_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "document_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "dataroom_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "viewer_email": {
            "type": [
              "string",
              "null"
            ],
            "example": "jane@acme.com"
          },
          "view_type": {
            "type": [
              "string",
              "null"
            ],
            "example": "DOCUMENT_VIEW"
          },
          "viewed_at": {
            "type": "string",
            "format": "date-time"
          },
          "downloaded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "download_type": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "object",
          "link_id",
          "document_id",
          "dataroom_id",
          "viewer_email",
          "view_type",
          "viewed_at",
          "downloaded_at",
          "download_type"
        ]
      },
      "DataroomList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataroom"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "Dataroom": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890"
          },
          "object": {
            "type": "string",
            "const": "dataroom",
            "description": "String representing the object's type. Always `dataroom`."
          },
          "pid": {
            "type": "string",
            "example": "dr_abc123def456",
            "description": "Stripe-style public ID, suitable for URLs and user references"
          },
          "name": {
            "type": "string",
            "example": "Acme Series A"
          },
          "internal_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "acme-series-a",
            "description": "Private alias visible only to the team"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "example": "Due-diligence materials"
          },
          "document_count": {
            "type": "integer",
            "example": 12
          },
          "folder_count": {
            "type": "integer",
            "example": 3
          },
          "conversations_enabled": {
            "type": "boolean",
            "example": false
          },
          "agents_enabled": {
            "type": "boolean",
            "example": false
          },
          "allow_bulk_download": {
            "type": "boolean",
            "example": true
          },
          "is_frozen": {
            "type": "boolean",
            "example": false
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "pid",
          "name",
          "internal_name",
          "description",
          "document_count",
          "folder_count",
          "conversations_enabled",
          "agents_enabled",
          "allow_bulk_download",
          "is_frozen",
          "created",
          "updated_at"
        ]
      },
      "CreateDataroomRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "example": "Acme Series A"
          },
          "internal_name": {
            "type": "string",
            "example": "acme-series-a"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "UpdateDataroomRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "internal_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "allow_bulk_download": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "AttachDataroomDocumentRequest": {
        "type": "object",
        "properties": {
          "document_id": {
            "type": "string",
            "minLength": 1,
            "description": "ID of an existing document in the same team to attach to this dataroom.",
            "example": "clxyabc1234567890"
          },
          "folder_id": {
            "type": "string",
            "description": "Optional id of a dataroom folder (created via POST /v1/datarooms/{id}/folders) to place this attachment under. Folder must belong to this dataroom."
          }
        },
        "required": [
          "document_id"
        ],
        "additionalProperties": false
      },
      "DataroomItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890",
            "description": "DataroomDocument id (the link between a document and the dataroom)"
          },
          "object": {
            "type": "string",
            "const": "dataroom_document",
            "description": "String representing the object's type. Always `dataroom_document`."
          },
          "document_id": {
            "type": "string",
            "example": "clxyabc1234567890"
          },
          "document_name": {
            "type": "string",
            "example": "pitch-deck-q4.pdf"
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "example": "pdf"
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "For `link` and `notion` documents, the external target URL the document points to. `null` for file-based documents.",
            "example": null
          },
          "num_pages": {
            "type": [
              "integer",
              "null"
            ]
          },
          "folder_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "folder_path": {
            "type": [
              "string",
              "null"
            ],
            "example": "/Legal/Contracts"
          },
          "order_index": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "document_id",
          "document_name",
          "type",
          "content_type",
          "url",
          "num_pages",
          "folder_id",
          "folder_path",
          "order_index",
          "created"
        ]
      },
      "DataroomItemList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataroomItem"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "MoveDataroomDocumentRequest": {
        "type": "object",
        "properties": {
          "folder_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target dataroom folder id to move this document into, or null to move it to the dataroom root. Folder must belong to this dataroom."
          }
        },
        "required": [
          "folder_id"
        ],
        "additionalProperties": false
      },
      "DataroomFolderList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataroomFolder"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "DataroomFolder": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxy9abc1234567890"
          },
          "object": {
            "type": "string",
            "const": "dataroom_folder",
            "description": "String representing the object's type. Always `dataroom_folder`."
          },
          "name": {
            "type": "string",
            "example": "Legal"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "path": {
            "type": "string",
            "example": "/legal",
            "description": "Server-derived path of slugified folder names. Read-only — never accepted from clients."
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "document_count": {
            "type": "integer",
            "example": 0
          },
          "child_folder_count": {
            "type": "integer",
            "example": 0
          },
          "order_index": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "name",
          "parent_id",
          "path",
          "icon",
          "color",
          "document_count",
          "child_folder_count",
          "order_index",
          "created",
          "updated_at"
        ]
      },
      "CreateDataroomFolderRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional parent folder id. Omit or pass null to create at the dataroom root."
          },
          "icon": {
            "type": "string",
            "enum": [
              "folder",
              "folder-open",
              "briefcase",
              "archive",
              "box",
              "file",
              "book",
              "bookmark",
              "star",
              "heart",
              "lock",
              "shield",
              "users",
              "settings",
              "tag",
              "layers",
              "globe",
              "home",
              "mail",
              "image",
              "video",
              "music",
              "palette",
              "pen-tool",
              "lightbulb",
              "zap",
              "wrench",
              "sparkles",
              "cloud",
              "flag",
              "award",
              "flame",
              "bell",
              "sun",
              "hash"
            ],
            "description": "Allowed folder icon name."
          },
          "color": {
            "type": "string",
            "enum": [
              "gray",
              "red",
              "orange",
              "yellow",
              "green",
              "blue",
              "black"
            ],
            "description": "Allowed folder color token."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "UpdateDataroomFolderRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "folder",
              "folder-open",
              "briefcase",
              "archive",
              "box",
              "file",
              "book",
              "bookmark",
              "star",
              "heart",
              "lock",
              "shield",
              "users",
              "settings",
              "tag",
              "layers",
              "globe",
              "home",
              "mail",
              "image",
              "video",
              "music",
              "palette",
              "pen-tool",
              "lightbulb",
              "zap",
              "wrench",
              "sparkles",
              "cloud",
              "flag",
              "award",
              "flame",
              "bell",
              "sun",
              "hash",
              null
            ],
            "description": "Allowed folder icon name."
          },
          "color": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "gray",
              "red",
              "orange",
              "yellow",
              "green",
              "blue",
              "black",
              null
            ],
            "description": "Allowed folder color token."
          }
        },
        "additionalProperties": false
      },
      "MoveDataroomFolderRequest": {
        "type": "object",
        "properties": {
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target parent folder id within the same dataroom, or null for root."
          }
        },
        "required": [
          "parent_id"
        ],
        "additionalProperties": false
      },
      "VisitorList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Visitor"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "Visitor": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "clxyvwr1234567890"
          },
          "object": {
            "type": "string",
            "const": "visitor",
            "description": "String representing the object's type. Always `visitor`."
          },
          "email": {
            "type": "string",
            "example": "jane@acme.com"
          },
          "verified": {
            "type": "boolean",
            "example": true
          },
          "dataroom_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "If the visitor is tied to a specific dataroom (invitation or group member), this is its id"
          },
          "invited_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "total_views": {
            "type": "integer",
            "example": 14
          },
          "last_viewed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "email",
          "verified",
          "dataroom_id",
          "invited_at",
          "total_views",
          "last_viewed_at",
          "created",
          "updated_at"
        ]
      },
      "VisitorViewList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VisitorView"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "data",
          "next_cursor"
        ]
      },
      "VisitorView": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "visitor_view",
            "description": "String representing the object's type. Always `visitor_view`."
          },
          "link_id": {
            "type": "string"
          },
          "document_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "dataroom_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "view_type": {
            "type": "string"
          },
          "viewed_at": {
            "type": "string",
            "format": "date-time"
          },
          "downloaded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "is_archived": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "object",
          "link_id",
          "document_id",
          "dataroom_id",
          "view_type",
          "viewed_at",
          "downloaded_at",
          "is_archived"
        ]
      },
      "DocumentAnalytics": {
        "type": "object",
        "properties": {
          "document_id": {
            "type": "string"
          },
          "total_views": {
            "type": "integer"
          },
          "unique_viewers": {
            "type": "integer"
          },
          "total_duration_seconds": {
            "type": "number"
          },
          "avg_page_duration_seconds": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "page_number": {
                  "type": "integer"
                },
                "avg_duration_seconds": {
                  "type": "number"
                }
              },
              "required": [
                "page_number",
                "avg_duration_seconds"
              ]
            }
          },
          "since": {
            "type": "string",
            "format": "date-time"
          },
          "until": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "document_id",
          "total_views",
          "unique_viewers",
          "total_duration_seconds",
          "avg_page_duration_seconds",
          "since",
          "until"
        ]
      },
      "LinkAnalytics": {
        "type": "object",
        "properties": {
          "link_id": {
            "type": "string"
          },
          "total_views": {
            "type": "integer"
          },
          "total_duration_seconds": {
            "type": "number"
          },
          "unique_viewers": {
            "type": "integer"
          },
          "since": {
            "type": "string",
            "format": "date-time"
          },
          "until": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "link_id",
          "total_views",
          "total_duration_seconds",
          "unique_viewers",
          "since",
          "until"
        ]
      },
      "DataroomAnalytics": {
        "type": "object",
        "properties": {
          "dataroom_id": {
            "type": "string"
          },
          "total_views": {
            "type": "integer"
          },
          "unique_viewers": {
            "type": "integer"
          },
          "total_duration_seconds": {
            "type": "number"
          },
          "since": {
            "type": "string",
            "format": "date-time"
          },
          "until": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "dataroom_id",
          "total_views",
          "unique_viewers",
          "total_duration_seconds",
          "since",
          "until"
        ]
      },
      "ViewAnalytics": {
        "type": "object",
        "properties": {
          "view_id": {
            "type": "string"
          },
          "document_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "viewer_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "viewed_at": {
            "type": "string",
            "format": "date-time"
          },
          "page_durations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "page_number": {
                  "type": "integer"
                },
                "duration_seconds": {
                  "type": "number"
                }
              },
              "required": [
                "page_number",
                "duration_seconds"
              ]
            }
          },
          "total_duration_seconds": {
            "type": "number"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "country",
              "city"
            ]
          },
          "client": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "browser": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "os": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "device": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "browser",
              "os",
              "device"
            ]
          }
        },
        "required": [
          "view_id",
          "document_id",
          "viewer_email",
          "viewed_at",
          "page_durations",
          "total_duration_seconds",
          "location",
          "client"
        ]
      }
    }
  }
}