{ "openapi": "3.1.0", "info": { "title": "PaperJet", "description": "Self-hosted PDF editor API", "version": "0.1.0" }, "paths": { "/api/v1/auth/status": { "get": { "tags": [ "auth" ], "summary": "Get Auth Status", "description": "Check if app requires setup and if user is logged in.", "operationId": "get_auth_status_api_v1_auth_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthStatusResponse" } } } } } } }, "/api/v1/auth/setup": { "post": { "tags": [ "auth" ], "summary": "Setup Password", "description": "First-run setup.", "operationId": "setup_password_api_v1_auth_setup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Setup Password Api V1 Auth Setup Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Login", "description": "Validate password and issue session cookie.", "operationId": "login_api_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Login Api V1 Auth Login Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Logout", "description": "Clear session cookie.", "operationId": "logout_api_v1_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Logout Api V1 Auth Logout Post" } } } } } } }, "/api/v1/auth/password": { "put": { "tags": [ "auth" ], "summary": "Change Password", "description": "Change an existing password.", "operationId": "change_password_api_v1_auth_password_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Change Password Api V1 Auth Password Put" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents": { "get": { "tags": [ "documents" ], "summary": "List Documents", "description": "List non-trashed documents.", "operationId": "list_documents_api_v1_documents_get", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Query" } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Skip" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "documents" ], "summary": "Upload Document", "description": "Upload a new PDF document.", "operationId": "upload_document_api_v1_documents_post", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_document_api_v1_documents_post" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentMeta" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/trash": { "get": { "tags": [ "documents" ], "summary": "List Trash", "description": "List trashed documents.", "operationId": "list_trash_api_v1_documents_trash_get", "parameters": [ { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Skip" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{id}": { "get": { "tags": [ "documents" ], "summary": "Get Document", "operationId": "get_document_api_v1_documents__id__get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentMeta" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "documents" ], "summary": "Update Document", "operationId": "update_document_api_v1_documents__id__patch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentMeta" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "documents" ], "summary": "Delete Document", "description": "Soft delete by default. Hard delete if permanent=True AND already in trash.", "operationId": "delete_document_api_v1_documents__id__delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } }, { "name": "permanent", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Permanent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{id}/restore": { "post": { "tags": [ "documents" ], "summary": "Restore Document", "operationId": "restore_document_api_v1_documents__id__restore_post", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentMeta" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/bulk-delete": { "post": { "tags": [ "documents" ], "summary": "Bulk Delete", "operationId": "bulk_delete_api_v1_documents_bulk_delete_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/bulk-restore": { "post": { "tags": [ "documents" ], "summary": "Bulk Restore", "operationId": "bulk_restore_api_v1_documents_bulk_restore_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRestoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/trash/empty": { "post": { "tags": [ "documents" ], "summary": "Empty Trash", "operationId": "empty_trash_api_v1_documents_trash_empty_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/documents/{id}/file": { "get": { "tags": [ "documents" ], "summary": "Get Document File", "operationId": "get_document_file_api_v1_documents__id__file_get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{id}/thumbnail": { "get": { "tags": [ "documents" ], "summary": "Get Document Thumbnail", "operationId": "get_document_thumbnail_api_v1_documents__id__thumbnail_get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{id}/assets": { "post": { "tags": [ "Assets" ], "summary": "Upload Asset", "description": "Upload a PNG, JPEG, GIF, or WebP annotation asset.", "operationId": "upload_asset_api_v1_documents__id__assets_post", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_asset_api_v1_documents__id__assets_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Upload Asset Api V1 Documents Id Assets Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{id}/assets/{ref}": { "get": { "tags": [ "Assets" ], "summary": "Get Asset", "description": "Serve an annotation asset to an authenticated session.", "operationId": "get_asset_api_v1_documents__id__assets__ref__get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "title": "Id" } }, { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "title": "Ref" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{document_id}/annotations": { "get": { "tags": [ "annotations" ], "summary": "Get Annotations", "operationId": "get_annotations_api_v1_documents__document_id__annotations_get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationStateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "annotations" ], "summary": "Update Annotations", "operationId": "update_annotations_api_v1_documents__document_id__annotations_put", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationStateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnotationStateUpdateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{document_id}/versions": { "get": { "tags": [ "versions" ], "summary": "List Versions", "operationId": "list_versions_api_v1_documents__document_id__versions_get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "versions" ], "summary": "Create Version", "operationId": "create_version_api_v1_documents__document_id__versions_post", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionMeta" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{document_id}/versions/{version_id}": { "get": { "tags": [ "versions" ], "summary": "Get Version", "operationId": "get_version_api_v1_documents__document_id__versions__version_id__get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionDataResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "versions" ], "summary": "Delete Version", "operationId": "delete_version_api_v1_documents__document_id__versions__version_id__delete", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{document_id}/versions/{version_id}/restore": { "post": { "tags": [ "versions" ], "summary": "Restore Version", "operationId": "restore_version_api_v1_documents__document_id__versions__version_id__restore_post", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRestoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/documents/{document_id}/export": { "post": { "tags": [ "export" ], "summary": "Export Document", "description": "Export the working layer or a selected version as a downloadable PDF.", "operationId": "export_document_api_v1_documents__document_id__export_post", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/health": { "get": { "tags": [ "health" ], "summary": "Health Check", "description": "Return service health status and version.", "operationId": "health_check_api_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Health Check Api V1 Health Get" } } } } } } } }, "components": { "schemas": { "AnnotationStateResponse": { "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "data", "updatedAt" ], "title": "AnnotationStateResponse" }, "AnnotationStateUpdateRequest": { "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "baseUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Baseupdatedat" } }, "type": "object", "required": [ "data" ], "title": "AnnotationStateUpdateRequest" }, "AnnotationStateUpdateResponse": { "properties": { "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "updatedAt" ], "title": "AnnotationStateUpdateResponse" }, "AuthStatusResponse": { "properties": { "setupRequired": { "type": "boolean", "title": "Setuprequired" }, "loggedIn": { "type": "boolean", "title": "Loggedin" } }, "type": "object", "required": [ "setupRequired", "loggedIn" ], "title": "AuthStatusResponse" }, "Body_upload_asset_api_v1_documents__id__assets_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_asset_api_v1_documents__id__assets_post" }, "Body_upload_document_api_v1_documents_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_document_api_v1_documents_post" }, "BulkDeleteRequest": { "properties": { "ids": { "items": { "type": "string" }, "type": "array", "title": "Ids" } }, "type": "object", "required": [ "ids" ], "title": "BulkDeleteRequest" }, "BulkRestoreRequest": { "properties": { "ids": { "items": { "type": "string" }, "type": "array", "title": "Ids" } }, "type": "object", "required": [ "ids" ], "title": "BulkRestoreRequest" }, "ChangePasswordRequest": { "properties": { "current_password": { "type": "string", "title": "Current Password" }, "new_password": { "type": "string", "minLength": 8, "title": "New Password" } }, "type": "object", "required": [ "current_password", "new_password" ], "title": "ChangePasswordRequest" }, "DocumentListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DocumentMeta" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "items", "total" ], "title": "DocumentListResponse" }, "DocumentMeta": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "filename": { "type": "string", "title": "Filename" }, "mime_type": { "type": "string", "title": "Mime Type" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "in_trash": { "type": "boolean", "title": "In Trash" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "deleted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deleted At" } }, "type": "object", "required": [ "id", "title", "filename", "mime_type", "size_bytes", "in_trash", "created_at", "updated_at", "deleted_at" ], "title": "DocumentMeta" }, "DocumentUpdateRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "in_trash": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "In Trash" } }, "type": "object", "title": "DocumentUpdateRequest" }, "ExportRequest": { "properties": { "versionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Versionid" }, "flatten": { "type": "boolean", "title": "Flatten", "default": true } }, "type": "object", "title": "ExportRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LoginRequest": { "properties": { "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "password" ], "title": "LoginRequest" }, "SetupRequest": { "properties": { "password": { "type": "string", "minLength": 8, "title": "Password" } }, "type": "object", "required": [ "password" ], "title": "SetupRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VersionCreateRequest": { "properties": { "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Label" }, "kind": { "type": "string", "enum": [ "manual", "auto" ], "title": "Kind", "default": "manual" } }, "type": "object", "title": "VersionCreateRequest" }, "VersionDataResponse": { "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/VersionMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "VersionDataResponse" }, "VersionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/VersionMeta" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "VersionListResponse" }, "VersionMeta": { "properties": { "id": { "type": "string", "title": "Id" }, "documentId": { "type": "string", "title": "Documentid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "kind": { "type": "string", "enum": [ "manual", "auto" ], "title": "Kind" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "annotationCount": { "type": "integer", "title": "Annotationcount" } }, "type": "object", "required": [ "id", "documentId", "label", "kind", "createdAt", "annotationCount" ], "title": "VersionMeta" }, "VersionRestoreResponse": { "properties": { "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "updatedAt" ], "title": "VersionRestoreResponse" } } } }