pdfdancer-client-typescript 1.0.13 → 1.0.14

package/docs/openapi.yml

@@ -172,8 +172,46 @@ paths:
             application/json:
               schema:
                 type: string
+  /keys/anon:
+    post:
+      operationId: issueAnonymousKey
+      parameters:
+      - name: X-Fingerprint
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: v
+        in: query
+        description: API version
+        schema:
+          type: string
+      - name: api-version
+        in: query
+        description: API version
+        schema:
+          type: string
+      - name: X-API-VERSION
+        in: header
+        description: API version
+        schema:
+          type: string
+      - name: Accept-Version
+        in: header
+        description: API version
+        schema:
+          type: string
+      responses:
+        "200":
+          description: issueAnonymousKey 200 response
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiTokenCreateResponse"
   /me/tenant:
     get:
+      summary: Get current user's tenant information.
+      description: Get current user's tenant information.
       operationId: getTenant
       parameters:
       - name: v
@@ -198,13 +236,15 @@ paths:
           type: string
       responses:
         "200":
-          description: getTenant 200 response
+          description: User's tenant with role
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/UserTenantResponse"
   /me/tokens:
     get:
+      summary: List all API tokens for user's tenant.
+      description: List all API tokens for user's tenant.
       operationId: listTokens
       parameters:
       - name: v
@@ -229,7 +269,7 @@ paths:
           type: string
       responses:
         "200":
-          description: listTokens 200 response
+          description: List of API tokens (without raw token values)
           content:
             application/json:
               schema:
@@ -237,6 +277,8 @@ paths:
                 items:
                   $ref: "#/components/schemas/ApiTokenListResponse"
     post:
+      summary: Create a new API token for user's tenant.
+      description: Create a new API token for user's tenant.
       operationId: createToken
       parameters:
       - name: v
@@ -260,6 +302,7 @@ paths:
         schema:
           type: string
       requestBody:
+        description: token creation request
         content:
           application/json:
             schema:
@@ -267,17 +310,20 @@ paths:
         required: true
       responses:
         "200":
-          description: createToken 200 response
+          description: Created token with raw token value (shown only once)
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ApiTokenCreateResponse"
   /me/tokens/{tokenId}:
     get:
+      summary: Get a single API token by ID.
+      description: Get a single API token by ID.
       operationId: getToken
       parameters:
       - name: tokenId
         in: path
+        description: token ID to retrieve
         required: true
         schema:
           type: string
@@ -303,16 +349,19 @@ paths:
           type: string
       responses:
         "200":
-          description: getToken 200 response
+          description: Token details (without raw token value)
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ApiTokenListResponse"
     delete:
+      summary: Revoke an API token.
+      description: Revoke an API token.
       operationId: revokeToken
       parameters:
       - name: tokenId
         in: path
+        description: token ID to revoke
         required: true
         schema:
           type: string
@@ -338,13 +387,18 @@ paths:
           type: string
       responses:
         "200":
-          description: revokeToken 200 response
+          description: 204 No Content on success
   /pdf/add:
     post:
+      summary: Adds new objects to the PDF document.
+      description: "Adds new objects to the PDF document. This operation creates new\
+        \ PDF content elements such as text, images, forms, or other objects at specified\
+        \ positions within the document."
       operationId: addObject
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -369,6 +423,8 @@ paths:
         schema:
           type: string
       requestBody:
+        description: "addition specifications including object type, content, and\
+          \ positioning"
         content:
           application/json:
             schema:
@@ -376,17 +432,23 @@ paths:
         required: true
       responses:
         "200":
-          description: addObject 200 response
+          description: HTTP response indicating whether the addition operation was
+            successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/delete:
     delete:
+      summary: Removes specified objects from the PDF document.
+      description: "Removes specified objects from the PDF document. This operation\
+        \ permanently deletes PDF objects such as text elements, images, forms, or\
+        \ other content based on the provided deletion criteria."
       operationId: deleteObject
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -411,6 +473,7 @@ paths:
         schema:
           type: string
       requestBody:
+        description: deletion criteria specifying which objects to remove
         content:
           application/json:
             schema:
@@ -418,22 +481,31 @@ paths:
         required: true
       responses:
         "200":
-          description: deleteObject 200 response
+          description: HTTP response indicating whether the deletion operation was
+            successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/document/snapshot:
     get:
+      summary: Retrieves a complete snapshot of the entire PDF document.
+      description: "Retrieves a complete snapshot of the entire PDF document. This\
+        \ endpoint returns all pages with their elements, document metadata, and font\
+        \ catalog in a single response, significantly reducing API overhead compared\
+        \ to requesting each element type separately per page."
       operationId: getDocumentSnapshot
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
       - name: types
         in: query
+        description: "optional comma-separated list of object types to include (e.g.,\
+          \ \"PARAGRAPH,IMAGE\")"
         explode: false
         schema:
           type: string
@@ -460,17 +532,23 @@ paths:
           type: string
       responses:
         "200":
-          description: getDocumentSnapshot 200 response
+          description: HTTP response containing the complete document snapshot
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/DocumentSnapshot"
   /pdf/find:
     post:
+      summary: Searches for PDF objects within the document based on specified criteria.
+      description: "Searches for PDF objects within the document based on specified\
+        \ criteria. This operation allows finding various types of PDF objects (text,\
+        \ images, forms, etc.) using flexible search parameters including object type,\
+        \ getPosition, and hints."
       operationId: findObject
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -495,6 +573,8 @@ paths:
         schema:
           type: string
       requestBody:
+        description: "search criteria specifying object type, getPosition filters,\
+          \ and search hints"
         content:
           application/json:
             schema:
@@ -502,7 +582,8 @@ paths:
         required: true
       responses:
         "200":
-          description: findObject 200 response
+          description: HTTP response containing list of object references matching
+            the search criteria
           content:
             application/json:
               schema:
@@ -595,10 +676,15 @@ paths:
                 type: boolean
   /pdf/move:
     put:
+      summary: Moves PDF objects to new positions within the document.
+      description: "Moves PDF objects to new positions within the document. This operation\
+        \ relocates existing PDF objects (text, images, etc.) to different coordinates\
+        \ or pages while preserving their content and properties."
       operationId: moveObject
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -623,6 +709,8 @@ paths:
         schema:
           type: string
       requestBody:
+        description: movement specifications including object reference and target
+          getPosition
         content:
           application/json:
             schema:
@@ -630,17 +718,22 @@ paths:
         required: true
       responses:
         "200":
-          description: moveObject 200 response
+          description: HTTP response indicating whether the move operation was successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/page/add:
     post:
+      summary: Adds a new blank page to the end of the PDF document.
+      description: Adds a new blank page to the end of the PDF document. This operation
+        creates a new page within the PDF and returns a reference that can be used
+        for subsequent operations on the created page.
       operationId: addPage
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -664,19 +757,31 @@ paths:
         description: API version
         schema:
           type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AddPageRequest"
+        required: true
       responses:
         "200":
-          description: addPage 200 response
+          description: HTTP response containing the object reference for the newly
+            created page
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/PageRef"
   /pdf/page/delete:
     delete:
+      summary: Removes a page from the PDF document entirely.
+      description: "Removes a page from the PDF document entirely. This operation\
+        \ permanently deletes the specified page and all its content from the PDF\
+        \ document, updating page numbering for subsequent pages."
       operationId: deletePage
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -701,6 +806,7 @@ paths:
         schema:
           type: string
       requestBody:
+        description: reference to the page object to be deleted
         content:
           application/json:
             schema:
@@ -708,22 +814,28 @@ paths:
         required: true
       responses:
         "200":
-          description: deletePage 200 response
+          description: HTTP response indicating whether the deletion was successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/page/find:
     post:
+      summary: Searches for pages within the PDF document based on optional criteria.
+      description: Searches for pages within the PDF document based on optional criteria.
+        This operation can return either a specific page by number or all pages in
+        the document if no page number is specified.
       operationId: findPage
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
       - name: pageIndex
         in: query
+        description: optional specific page number to retrieve (null returns all pages)
         explode: false
         schema:
           type: integer
@@ -751,7 +863,8 @@ paths:
           type: string
       responses:
         "200":
-          description: findPage 200 response
+          description: HTTP response containing list of object references for matching
+            pages
           content:
             application/json:
               schema:
@@ -760,10 +873,15 @@ paths:
                   $ref: "#/components/schemas/PageRef"
   /pdf/page/modify:
     put:
+      summary: Modifies page-level properties and metadata within the PDF document.
+      description: "Modifies page-level properties and metadata within the PDF document.\
+        \ This operation handles page-specific modifications including dimensions,\
+        \ rotation, media box settings, and other page-level attributes."
       operationId: modifyPage
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -788,6 +906,7 @@ paths:
         schema:
           type: string
       requestBody:
+        description: modification specifications for page-level changes
         content:
           application/json:
             schema:
@@ -795,17 +914,22 @@ paths:
         required: true
       responses:
         "200":
-          description: modifyPage 200 response
+          description: HTTP response indicating whether the modification was successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/page/move:
     put:
+      summary: Moves a page to a different getPosition within the PDF document.
+      description: "Moves a page to a different getPosition within the PDF document.\
+        \ This operation reorders pages within the document, updating the page sequence\
+        \ according to the specified move request parameters."
       operationId: movePage
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
@@ -830,6 +954,7 @@ paths:
         schema:
           type: string
       requestBody:
+        description: move request containing source page reference and target getPosition
         content:
           application/json:
             schema:
@@ -837,28 +962,35 @@ paths:
         required: true
       responses:
         "200":
-          description: movePage 200 response
+          description: HTTP response indicating whether the move operation was successful
           content:
             application/json:
               schema:
                 type: boolean
   /pdf/page/{pageIndex}/snapshot:
     get:
+      summary: Retrieves a snapshot of a single PDF page.
+      description: "Retrieves a snapshot of a single PDF page. This endpoint returns\
+        \ the page metadata and all elements in a single response, reducing the number\
+        \ of API calls needed compared to requesting each element type separately."
       operationId: getPageSnapshot
       parameters:
       - name: X-Session-Id
         in: header
+        description: unique identifier for the user session containing the PDF
         required: true
         schema:
           type: string
       - name: pageIndex
         in: path
+        description: zero-based index of the page to retrieve
         required: true
         schema:
           type: integer
           format: int32
       - name: types
         in: query
+        description: optional comma-separated list of object types to include
         explode: false
         schema:
           type: string
@@ -885,7 +1017,7 @@ paths:
           type: string
       responses:
         "200":
-          description: getPageSnapshot 200 response
+          description: HTTP response containing the page snapshot
           content:
             application/json:
               schema:
@@ -976,6 +1108,10 @@ paths:
                 $ref: "#/components/schemas/CommandResult"
   /ping:
     get:
+      summary: Basic health check endpoint that confirms server availability.
+      description: Basic health check endpoint that confirms server availability.
+        This endpoint provides a simple way for monitoring systems to verify that
+        the API server is running and capable of handling requests.
       operationId: index
       parameters:
       - name: v
@@ -1000,7 +1136,7 @@ paths:
           type: string
       responses:
         "200":
-          description: index 200 response
+          description: a simple "Pong" response indicating the server is operational
           content:
             text/plain:
               schema:
@@ -1107,6 +1243,12 @@ paths:
                 $ref: "#/components/schemas/Product"
   /session/create:
     post:
+      summary: Creates a new session by uploading and processing a PDF document.
+      description: "Creates a new session by uploading and processing a PDF document.\
+        \ This operation validates the uploaded file, creates a unique session identifier,\
+        \ processes the PDF structure for manipulation, and stores the session for\
+        \ future operations. The PDF is analyzed to extract its internal structure\
+        \ and prepare it for editing."
       operationId: createSession
       parameters:
       - name: v
@@ -1137,6 +1279,7 @@ paths:
               properties:
                 pdf:
                   type: string
+                  description: uploaded PDF file from the multipart request
                   format: binary
             encoding:
               pdf:
@@ -1145,13 +1288,18 @@ paths:
         required: true
       responses:
         "200":
-          description: createSession 200 response
+          description: HTTP response containing the generated session ID for subsequent
+            operations
           content:
             application/json:
               schema:
                 type: string
   /session/new:
     post:
+      summary: Creates a new session with a blank PDF document.
+      description: "Creates a new session with a blank PDF document. This operation\
+        \ creates a new PDF with the specified page size, orientation, and page count,\
+        \ then initializes a session for manipulation operations just like createSession."
       operationId: createBlankPdf
       parameters:
       - name: v
@@ -1175,6 +1323,8 @@ paths:
         schema:
           type: string
       requestBody:
+        description: "parameters for the blank PDF (page size, orientation, initial\
+          \ page count)"
         content:
           application/json:
             schema:
@@ -1182,17 +1332,23 @@ paths:
         required: true
       responses:
         "200":
-          description: createBlankPdf 200 response
+          description: HTTP response containing the generated session ID for subsequent
+            operations
           content:
             application/json:
               schema:
                 type: string
   /session/{sessionId}:
     delete:
+      summary: Deletes an existing session and cleans up associated resources.
+      description: Deletes an existing session and cleans up associated resources.
+        This operation removes the session from the store and should also clean up
+        temporary files and release any held resources.
       operationId: deleteSession
       parameters:
       - name: sessionId
         in: path
+        description: unique identifier of the session to delete
         required: true
         schema:
           type: string
@@ -1218,17 +1374,26 @@ paths:
           type: string
       responses:
         "200":
-          description: deleteSession 200 response
+          description: HTTP response indicating whether the session was successfully
+            deleted
           content:
             application/json:
               schema:
                 type: boolean
   /session/{sessionId}/pdf:
     get:
+      summary: Retrieves the current state of the PDF document from the specified
+        session.
+      description: "Retrieves the current state of the PDF document from the specified\
+        \ session. This operation builds and streams the PDF with all applied modifications,\
+        \ generating the final PDF output that reflects all changes made during the\
+        \ session. The PDF is built asynchronously and streamed to avoid memory issues\
+        \ with large files."
       operationId: getSessionPdf_1
       parameters:
       - name: sessionId
         in: path
+        description: unique identifier of the session containing the PDF
         required: true
         schema:
           type: string
@@ -1254,7 +1419,8 @@ paths:
           type: string
       responses:
         "200":
-          description: getSessionPdf_1 200 response
+          description: HTTP response containing the streamed PDF file with all modifications
+            applied
           content:
             application/pdf:
               schema:
@@ -1262,6 +1428,12 @@ paths:
                 format: binary
   /test:
     get:
+      summary: Authenticated test endpoint that verifies API token authentication
+        is working.
+      description: Authenticated test endpoint that verifies API token authentication
+        is working. This endpoint requires a valid API token (Bearer) and serves as
+        a way to test that the authentication mechanism is functioning properly without
+        affecting any actual application data.
       operationId: test
       parameters:
       - name: v
@@ -1286,7 +1458,7 @@ paths:
           type: string
       responses:
         "200":
-          description: test 200 response
+          description: a confirmation message indicating successful authentication
           content:
             text/plain:
               schema:
@@ -1392,6 +1564,20 @@ paths:
                 format: binary
 components:
   schemas:
+    AddPageRequest:
+      required:
+      - orientation
+      - pageIndex
+      - pageSize
+      type: object
+      properties:
+        pageIndex:
+          type: integer
+          format: int32
+        orientation:
+          $ref: "#/components/schemas/Orientation"
+        pageSize:
+          $ref: "#/components/schemas/PageSize"
     AddRequest:
       required:
       - object
@@ -1399,6 +1585,10 @@ components:
       properties:
         object:
           $ref: "#/components/schemas/PDFObject"
+      description: "Request record for adding new PDF objects to a document. This\
+        \ immutable record encapsulates the data needed to add new content elements\
+        \ to a PDF document, including the complete object specification with getPosition,\
+        \ properties, and content data."
     ApiTokenCreateRequest:
       required:
       - expiresAt
@@ -1409,6 +1599,7 @@ components:
           type: string
         expiresAt:
           type: string
+      description: Request to create a new API token.
     ApiTokenCreateResponse:
       required:
       - metadata
@@ -1419,6 +1610,8 @@ components:
           type: string
         metadata:
           $ref: "#/components/schemas/ApiTokenCreateResponse.ApiTokenMetadata"
+      description: Response when creating a new API token. Contains the raw token
+        (shown only once) plus metadata.
     ApiTokenCreateResponse.ApiTokenMetadata:
       required:
       - createdAt
@@ -1460,6 +1653,7 @@ components:
           type: string
         expiresAt:
           type: string
+      description: Response for listing API tokens (does not include the raw token).
     Authentication:
       required:
       - attributes
@@ -1477,6 +1671,41 @@ components:
             type: array
             items:
               type: string
+    Bezier:
+      required:
+      - p0
+      - p1
+      - p2
+      - p3
+      type: object
+      description: "Represents a cubic Bezier curve path segment defined by four control\
+        \ points. This class implements a cubic Bezier curve with start point, two\
+        \ control points, and end point, providing smooth curved path segments for\
+        \ complex vector graphics. Includes mathematical evaluation methods for point\
+        \ calculation along the curve."
+      allOf:
+      - $ref: "#/components/schemas/PathSegment"
+      - $ref: "#/components/schemas/PDFObject"
+      - type: object
+        properties:
+          p0:
+            description: Returns the starting point p0 of this Bezier segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          p1:
+            description: Returns the first control point p1 of this Bezier segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          p2:
+            description: Returns the second control point p2 of this Bezier segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          p3:
+            description: Returns the ending point p3 of this Bezier segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          objectType:
+            $ref: "#/components/schemas/ObjectType"
     BoundingRect:
       required:
       - height
@@ -1486,19 +1715,31 @@ components:
       type: object
       properties:
         origin:
-          $ref: "#/components/schemas/Point"
+          description: Returns the origin point of this bounding rectangle. The origin
+            represents the bottom-left corner in PDF coordinate system.
+          allOf:
+          - $ref: "#/components/schemas/Point"
         x:
           type: number
+          description: X-coordinate of the rectangle's origin (left edge).
           format: double
         "y":
           type: number
+          description: Y-coordinate of the rectangle's origin (bottom edge in PDF
+            coordinates).
           format: double
         width:
           type: number
+          description: Width of the rectangle extending rightward from the origin.
           format: double
         height:
           type: number
+          description: Height of the rectangle extending upward from the origin.
           format: double
+      description: "Represents a rectangular area defined by getPosition and dimensions.\
+        \ This class encapsulates bounding box information for PDF objects, providing\
+        \ spatial extent data used for positioning, collision detection, and layout\
+        \ operations within PDF documents."
     ChangeFormFieldRequest:
       required:
       - ref
@@ -1514,16 +1755,26 @@ components:
       properties:
         red:
           type: integer
+          description: Red color component (0-255).
           format: int32
         green:
           type: integer
+          description: Green color component (0-255).
           format: int32
         blue:
           type: integer
+          description: Blue color component (0-255).
           format: int32
         alpha:
           type: integer
+          description: "Alpha (transparency) component (0-255, where 255 is fully\
+            \ opaque)."
           format: int32
+      description: "Represents color information using RGBA (Red, Green, Blue, Alpha)\
+        \ color model. This class encapsulates color data for PDF objects, supporting\
+        \ both opaque and transparent colors with integer values ranging from 0-255\
+        \ for each component. Provides convenient constructors and utility methods\
+        \ for color manipulation."
     CommandResult:
       required:
       - commandName
@@ -1557,6 +1808,7 @@ components:
         initialPageCount:
           type: integer
           format: int32
+      description: Request to create a new blank PDF session.
     DeleteRequest:
       required:
       - objectRef
@@ -1564,6 +1816,19 @@ components:
       properties:
         objectRef:
           $ref: "#/components/schemas/ObjectRef"
+      description: Request record for deleting PDF objects from a document. This immutable
+        record encapsulates the object reference needed to identify and remove specific
+        PDF objects from a document during editing operations.
+    DocumentFontInfoDto:
+      required:
+      - documentFontName
+      - systemFontName
+      type: object
+      properties:
+        documentFontName:
+          type: string
+        systemFontName:
+          type: string
     DocumentSnapshot:
       required:
       - fonts
@@ -1577,11 +1842,15 @@ components:
         fonts:
           type: array
           items:
-            $ref: "#/components/schemas/FontRecommendationDto"
+            $ref: "#/components/schemas/DocumentFontInfoDto"
         pages:
           type: array
           items:
             $ref: "#/components/schemas/PageSnapshot"
+      description: "Represents a complete snapshot of a PDF document including metadata\
+        \ and all pages. This response provides document-level information and aggregates\
+        \ all page snapshots, allowing clients to retrieve the entire document structure\
+        \ in a single API call."
     FindRequest:
       required:
       - hint
@@ -1595,30 +1864,27 @@ components:
           $ref: "#/components/schemas/Position"
         hint:
           type: string
+      description: "Request record for searching PDF objects within a document. This\
+        \ immutable record encapsulates search criteria for locating PDF objects based\
+        \ on type, getPosition constraints, and optional search hints, enabling flexible\
+        \ and efficient object discovery within PDF documents."
     Font:
       type: object
       properties:
         name:
           type: string
+          description: "Font family name (e.g., \"Arial\", \"Times New Roman\", \"\
+            Helvetica\")."
         size:
           type: number
+          description: Font size in points.
           format: double
         embedded:
           type: boolean
-    FontRecommendationDto:
-      required:
-      - fontName
-      - fontType
-      - similarityScore
-      type: object
-      properties:
-        fontName:
-          type: string
-        fontType:
-          $ref: "#/components/schemas/FontType"
-        similarityScore:
-          type: number
-          format: double
+      description: "Represents font properties for text rendering in PDF documents.\
+        \ This class encapsulates font characteristics including typeface name, size,\
+        \ and styling attributes such as bold, italic, and underline formatting. Used\
+        \ throughout the API for consistent text formatting and style management."
     FontType:
       type: string
       enum:
@@ -1627,45 +1893,114 @@ components:
       - EMBEDDED
     Form:
       type: object
+      description: "Represents an interactive form field within a PDF document. This\
+        \ class encapsulates form field properties including type, value, appearance,\
+        \ and behavior for various interactive PDF form elements such as text fields,\
+        \ checkboxes, radio buttons, and dropdowns."
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
         properties:
           name:
             type: string
+            description: Field name identifier used in form processing.
           type:
-            $ref: "#/components/schemas/Form.FormType"
+            description: Type of form field determining its behavior and appearance.
+            allOf:
+            - $ref: "#/components/schemas/Form.FormType"
           value:
             type: string
+            description: Current value or content of the form field.
           size:
-            $ref: "#/components/schemas/Size"
+            description: Dimensions of the form field's visual representation.
+            allOf:
+            - $ref: "#/components/schemas/Size"
           font:
-            $ref: "#/components/schemas/Font"
+            description: Font properties for text-based form fields.
+            allOf:
+            - $ref: "#/components/schemas/Font"
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this form field.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
     Form.FormType:
       type: string
+      description: Enumeration of supported PDF form field types.
+      x-enum-descriptions:
+      - Single-line or multi-line text input field
+      - Checkbox for binary selections
+      - Radio button for mutually exclusive selections
+      - Dropdown list with selectable options
+      - Clickable button element
       enum:
       - TEXT_FIELD
       - CHECKBOX
       - RADIO_BUTTON
       - DROPDOWN
       - BUTTON
+    FormFieldRef:
+      required:
+      - name
+      - value
+      type: object
+      allOf:
+      - $ref: "#/components/schemas/ObjectRef"
+      - type: object
+        properties:
+          name:
+            type: string
+          value:
+            type: string
     Image:
       type: object
+      description: "Represents an image object within a PDF document. This class encapsulates\
+        \ image data, format information, and dimensional properties for embedded\
+        \ or overlaid images in PDF documents. Supports various image formats and\
+        \ provides utilities for loading images from files."
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
         properties:
           format:
             type: string
+            description: "Image format (e.g., \"JPEG\", \"PNG\", \"GIF\")."
           size:
-            $ref: "#/components/schemas/Size"
+            description: Dimensions of the image in PDF coordinate units.
+            allOf:
+            - $ref: "#/components/schemas/Size"
           data:
             type: string
+            description: Raw image data bytes.
             format: byte
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this image.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
+    Line:
+      required:
+      - p0
+      - p1
+      type: object
+      description: "Represents a straight line path segment between two points. This\
+        \ class defines a linear path element connecting two coordinate points, commonly\
+        \ used in vector graphics and geometric shapes within PDF documents."
+      allOf:
+      - $ref: "#/components/schemas/PathSegment"
+      - $ref: "#/components/schemas/PDFObject"
+      - type: object
+        properties:
+          p1:
+            description: Returns the ending point of this line segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          p0:
+            description: Returns the starting point of this line segment.
+            allOf:
+            - $ref: "#/components/schemas/Point"
+          objectType:
+            description: Returns the object type for this line segment.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
     ModifyRequest:
       required:
       - newObject
@@ -1696,6 +2031,10 @@ components:
           $ref: "#/components/schemas/ObjectRef"
         newPosition:
           $ref: "#/components/schemas/Position"
+      description: "Request record for moving PDF objects to new positions within\
+        \ a document. This immutable record encapsulates both the object to be moved\
+        \ and its target getPosition, enabling precise repositioning operations during\
+        \ PDF editing."
     ObjectRef:
       required:
       - internalId
@@ -1705,16 +2044,66 @@ components:
       properties:
         internalId:
           type: string
+          description: Returns the internal identifier for the referenced object.
         position:
-          $ref: "#/components/schemas/Position"
+          description: Returns the current getPosition information for the referenced
+            object.
+          allOf:
+          - $ref: "#/components/schemas/Position"
         type:
-          $ref: "#/components/schemas/ObjectType"
+          description: Returns the type classification of the referenced object.
+          allOf:
+          - $ref: "#/components/schemas/ObjectType"
+      description: Lightweight reference to a PDF object providing identity and type
+        information. Object references enable efficient API operations by providing
+        a way to identify and reference PDF objects without transferring their complete
+        content. This design pattern reduces payload sizes and improves performance
+        for operations that only need object identification and basic properties.
+      discriminator:
+        propertyName: objectRefType
+        mapping:
+          CHECKBOX: "#/components/schemas/FormFieldRef"
+          FORM_FIELD: "#/components/schemas/FormFieldRef"
+          RADIO_BUTTON: "#/components/schemas/FormFieldRef"
+          PARAGRAPH: "#/components/schemas/TextTypeObjectRef"
+          TEXT_LINE: "#/components/schemas/TextTypeObjectRef"
+          PAGE: "#/components/schemas/PageRef"
+          TEXT_FIELD: "#/components/schemas/FormFieldRef"
+      oneOf:
+      - $ref: "#/components/schemas/TextTypeObjectRef"
+      - $ref: "#/components/schemas/PageRef"
+      - $ref: "#/components/schemas/FormFieldRef"
     ObjectType:
       type: string
+      description: "Enumeration of PDF object types supported by the PDFDancer API.\
+        \ This enum categorizes the different types of objects that can exist within\
+        \ a PDF document, enabling type-safe operations and filtering across the API.\
+        \ Each type represents a distinct category of PDF content with specific manipulation\
+        \ capabilities and properties."
+      x-enum-descriptions:
+      - Root PDF document object containing all pages and metadata
+      - Individual page within the PDF document
+      - Single character or glyph element
+      - Text paragraph or block element
+      - Embedded image or graphics element
+      - Vector path or shape element
+      - Linear path segment
+      - Rectangular shape element
+      - Bezier curve path element
+      - Clipping region or mask
+      - FormXObject container
+      - Interactive acroform field element
+      - ""
+      - ""
+      - ""
+      - ""
+      - ""
+      - ""
+      - ""
       enum:
       - PDF
       - PAGE
-      - CHARACTER
+      - TEXT_ELEMENT
       - PARAGRAPH
       - IMAGE
       - PATH
@@ -1728,9 +2117,15 @@ components:
       - TEXT_LINE
       - TEXT_FIELD
       - RADIO_BUTTON
-      - CHECK_BOX
+      - BUTTON
+      - DROPDOWN
+      - CHECKBOX
     Orientation:
       type: string
+      description: Enumeration of page orientations.
+      x-enum-descriptions:
+      - Portrait orientation (height \> width)
+      - Landscape orientation (width \> height)
       enum:
       - PORTRAIT
       - LANDSCAPE
@@ -1739,10 +2134,24 @@ components:
       properties:
         id:
           type: string
+          description: Returns the unique identifier for this PDF object.
         position:
-          $ref: "#/components/schemas/Position"
+          description: Returns the spatial getPosition information for this object.
+          allOf:
+          - $ref: "#/components/schemas/Position"
         objectType:
-          $ref: "#/components/schemas/ObjectType"
+          description: "Returns the specific object type for this PDF object. This\
+            \ method must be implemented by concrete subclasses to identify their\
+            \ specific type, enabling type-safe operations and filtering."
+          allOf:
+          - $ref: "#/components/schemas/ObjectType"
+      description: |-
+        Abstract base class for all PDF objects that can be manipulated within the API. This class provides the fundamental properties and behaviors shared by all PDF content elements, including getPosition tracking, identification, and object reference generation.
+
+
+        The class uses Jackson polymorphic serialization to handle different concrete types
+        during JSON serialization/deserialization, enabling type-safe API operations
+        while maintaining flexibility for different PDF object types.
       discriminator:
         propertyName: type
         mapping:
@@ -1774,6 +2183,10 @@ components:
         toPageIndex:
           type: integer
           format: int32
+      description: "Request record for reordering pages within a PDF document. This\
+        \ immutable record specifies a page movement operation, defining which page\
+        \ should be moved and where it should be repositioned in the document's page\
+        \ sequence."
     PageRef:
       required:
       - orientation
@@ -1798,9 +2211,12 @@ components:
         height:
           type: number
           format: double
+      description: "Represents PDF page dimensions, supporting both standard sizes\
+        \ and custom dimensions. Dimensions are specified in points (1/72 inch)."
     PageSnapshot:
       required:
       - elements
+      - fonts
       - pageRef
       type: object
       properties:
@@ -1810,20 +2226,35 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ObjectRef"
+        fonts:
+          type: array
+          items:
+            $ref: "#/components/schemas/DocumentFontInfoDto"
+      description: "Represents a complete snapshot of a single PDF page including\
+        \ its metadata and all elements. This response aggregates page information\
+        \ and all contained objects (paragraphs, images, etc.) into a single response,\
+        \ reducing the number of API calls needed to retrieve page content."
     Paragraph:
       type: object
+      description: Represents a paragraph or text block within a PDF document. This
+        class encapsulates paragraph-level text content with unified formatting properties
+        and access to individual character elements for detailed manipulation. Provides
+        both block-level text operations and character-level granularity.
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
         properties:
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this paragraph.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
           lines:
             type: array
             items:
               $ref: "#/components/schemas/TextLine"
           lineSpacings:
             type: array
+            description: Gets the line spacing factors between consecutive lines.
             items:
               type: number
               format: double
@@ -1833,31 +2264,71 @@ components:
             type: string
     Path:
       type: object
+      description: "Represents a complex vector path consisting of multiple path segments.\
+        \ This class encapsulates vector graphics data within PDF documents, composed\
+        \ of various path elements like lines, curves, and shapes. Provides automatic\
+        \ getPosition calculation based on constituent segments."
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
         properties:
-          position:
-            $ref: "#/components/schemas/Position"
           pathSegments:
             type: array
+            description: Returns the list of path segments that compose this path.
             items:
               $ref: "#/components/schemas/PathSegment"
+          evenOddFill:
+            type: boolean
+            description: Returns whether even-odd fill rule should be used (true)
+              or nonzero (false). Null means default (nonzero).
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this path.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
     PathSegment:
       type: object
-      allOf:
-      - $ref: "#/components/schemas/PDFObject"
-      - type: object
-        properties:
-          strokeColor:
-            $ref: "#/components/schemas/Color"
-          fillColor:
-            $ref: "#/components/schemas/Color"
-          strokeWidth:
+      properties:
+        strokeColor:
+          description: Color used for drawing the segment's outline or stroke.
+          allOf:
+          - $ref: "#/components/schemas/Color"
+        fillColor:
+          description: Color used for filling the segment's interior area (if applicable).
+          allOf:
+          - $ref: "#/components/schemas/Color"
+        dashArray:
+          type: array
+          description: Dash pattern for stroking the path segment. Interpreted as
+            alternating on/off lengths. Null or empty means solid line. Values are
+            in user space units.
+          items:
             type: number
             format: double
+        dashPhase:
+          type: number
+          description: Dash phase (offset) into the dash pattern in user space units.
+            Null or zero means no offset.
+          format: double
+        strokeWidth:
+          type: number
+          description: Width of the stroke line in PDF coordinate units.
+          format: double
+      description: "Abstract base class for individual path segments within vector\
+        \ paths. This class provides common properties for path elements including\
+        \ stroke and fill colors, line width, and positioning. Concrete subclasses\
+        \ implement specific geometric shapes like lines, curves, and bezier segments."
+      discriminator:
+        propertyName: segmentType
+        mapping:
+          line: "#/components/schemas/Line"
+          LINE: "#/components/schemas/Line"
+          BEZIER: "#/components/schemas/Bezier"
+          bezier: "#/components/schemas/Bezier"
+      allOf:
+      - $ref: "#/components/schemas/PDFObject"
+      oneOf:
+      - $ref: "#/components/schemas/Line"
+      - $ref: "#/components/schemas/Bezier"
     Point:
       required:
       - x
@@ -1870,6 +2341,10 @@ components:
         "y":
           type: number
           format: double
+      description: "Immutable point record representing 2D coordinates. This record\
+        \ provides a simple and efficient way to represent coordinate pairs within\
+        \ PDF documents, with conversion utilities for interoperability with Java's\
+        \ standard geometry classes."
     Position:
       type: object
       properties:
@@ -1881,26 +2356,54 @@ components:
           type: string
         x:
           type: number
+          description: "Returns the X coordinate of this getPosition. If no bounding\
+            \ rectangle is defined, returns -1 as a sentinel value."
           format: double
         "y":
           type: number
+          description: "Returns the Y coordinate of this getPosition. If no bounding\
+            \ rectangle is defined, returns -1 as a sentinel value."
           format: double
         pageIndex:
           type: integer
+          description: Returns the page number where this getPosition is located.
           format: int32
         shape:
-          $ref: "#/components/schemas/Position.ShapeType"
+          description: Returns the geometric shape type of this getPosition.
+          allOf:
+          - $ref: "#/components/schemas/Position.ShapeType"
         mode:
-          $ref: "#/components/schemas/Position.PositionMode"
+          description: Returns the getPosition matching mode.
+          allOf:
+          - $ref: "#/components/schemas/Position.PositionMode"
         boundingRect:
-          $ref: "#/components/schemas/BoundingRect"
+          description: Returns the bounding rectangle defining the spatial extent
+            of this getPosition.
+          allOf:
+          - $ref: "#/components/schemas/BoundingRect"
+      description: "Represents spatial positioning and location information for PDF\
+        \ objects. This class encapsulates various ways to specify object locations\
+        \ within PDF documents, including page-based coordinates, bounding rectangles,\
+        \ and different positioning modes. It supports both precise coordinate positioning\
+        \ and area-based location specifications."
     Position.PositionMode:
       type: string
+      description: Defines how getPosition matching should be performed when searching
+        for objects.
+      x-enum-descriptions:
+      - Objects that intersect with the specified getPosition area
+      - Objects completely contained within the specified getPosition area
       enum:
       - INTERSECT
       - CONTAINS
     Position.ShapeType:
       type: string
+      description: Defines the geometric shape type used for getPosition specification.
+      x-enum-descriptions:
+      - Single point coordinate
+      - Linear shape between two points
+      - Circular area with radius
+      - Rectangular area with width and height
       enum:
       - POINT
       - LINE
@@ -1960,13 +2463,21 @@ components:
       properties:
         width:
           type: number
+          description: Returns the width dimension.
           format: double
         height:
           type: number
+          description: Returns the height dimension.
           format: double
         area:
           type: number
+          description: "Calculates and returns the total area. This method computes\
+            \ the area by multiplying width and height, useful for size comparisons\
+            \ and layout calculations."
           format: double
+      description: "Represents dimensional measurements with width and height properties.\
+        \ This class encapsulates size information for PDF objects (images, forms,\
+        \ etc.), providing both individual dimension access and calculated area methods."
     Subscription:
       required:
       - end
@@ -1984,22 +2495,38 @@ components:
           $ref: "#/components/schemas/Product"
     TextElement:
       type: object
+      description: "Represents a single character or glyph within a PDF document.\
+        \ This class encapsulates individual character properties including the character\
+        \ content, font styling, color, and getPosition for fine-grained text manipulation\
+        \ and character-level formatting operations."
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
         properties:
           text:
             type: string
+            description: The character or glyph content (typically a single character
+              string).
           font:
-            $ref: "#/components/schemas/Font"
+            description: Font properties for rendering this character.
+            allOf:
+            - $ref: "#/components/schemas/Font"
           color:
-            $ref: "#/components/schemas/Color"
+            description: Color properties for rendering this character.
+            allOf:
+            - $ref: "#/components/schemas/Color"
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this character.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
           status:
             $ref: "#/components/schemas/TextStatus"
     TextLine:
       type: object
+      description: Represents a paragraph or text block within a PDF document. This
+        class encapsulates paragraph-level text content with unified formatting properties
+        and access to individual character elements for detailed manipulation. Provides
+        both block-level text operations and character-level granularity.
       allOf:
       - $ref: "#/components/schemas/PDFObject"
       - type: object
@@ -2010,7 +2537,9 @@ components:
           fontName:
             type: string
           objectType:
-            $ref: "#/components/schemas/ObjectType"
+            description: Returns the object type for this paragraph.
+            allOf:
+            - $ref: "#/components/schemas/ObjectType"
           textElements:
             type: array
             items:
@@ -2021,7 +2550,6 @@ components:
             type: string
     TextStatus:
       required:
-      - fontRecommendation
       - fontType
       type: object
       properties:
@@ -2031,10 +2559,45 @@ components:
           type: boolean
         fontType:
           $ref: "#/components/schemas/FontType"
-        fontRecommendation:
-          $ref: "#/components/schemas/FontRecommendationDto"
+        fontInfoDto:
+          $ref: "#/components/schemas/DocumentFontInfoDto"
         warning:
           type: string
+    TextTypeObjectRef:
+      required:
+      - children
+      - color
+      - fontName
+      - fontSize
+      - lineSpacings
+      - status
+      - text
+      type: object
+      allOf:
+      - $ref: "#/components/schemas/ObjectRef"
+      - type: object
+        properties:
+          text:
+            type: string
+          fontName:
+            type: string
+          fontSize:
+            type: number
+            format: double
+          lineSpacings:
+            type: array
+            description: Gets the line spacing factors between consecutive lines.
+            items:
+              type: number
+              format: double
+          children:
+            type: array
+            items:
+              $ref: "#/components/schemas/TextTypeObjectRef"
+          color:
+            $ref: "#/components/schemas/Color"
+          status:
+            $ref: "#/components/schemas/TextStatus"
     TimeInterval:
       type: string
       enum:
@@ -2064,6 +2627,7 @@ components:
           type: string
         status:
           type: string
+      description: Response containing user's tenant information with their role.
     VersionResponse:
       required:
       - color