openapi: 3.1.0
info:
  title: pasteToPrint Agent Import API
  version: 1.16.0
  description: >-
    Creates a short-lived link that opens generated text, safe HTML with CSS,
    or image Data URLs in pasteToPrint. The link expires after 15 minutes.
    The user always reviews the content and explicitly confirms whether it
    should replace or be appended to the current document. After confirmation,
    the user can draw directly on the selected paper format, add shapes, manage
    vector or raster layers and edit images. New structured
    integrations use PTDF 1.0 through Document API v2; its stable wire
    identifier is ptp.document/1.
  contact:
    url: https://www.pastetoprint.com/
  license:
    name: All rights reserved
    identifier: LicenseRef-Proprietary
servers:
  - url: https://www.pastetoprint.com
security: []
paths:
  /api/v1/document:
    x-legacy-path: /api/agent-import/index.php
    get:
      operationId: describePasteToPrintAgentImport
      summary: Describe the agent import service
      description: >-
        Returns service metadata and current limits when called without a
        token. The pasteToPrint application uses the optional token internally
        to retrieve temporary content.
      parameters:
        - name: t
          in: query
          required: false
          description: Temporary import token used internally by pasteToPrint.
          schema:
            type: string
            pattern: "^[a-f0-9]{64}$"
      responses:
        "200":
          description: Service metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceDescription"
        "400":
          description: Invalid temporary import token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      operationId: createPasteToPrintDocument
      summary: Create a temporary pasteToPrint document
      description: >-
        Store generated document content temporarily and return importUrl plus
        a friendly HTTPS deep link in url. Give or open one of those values for
        the user. Do not attempt to print or accept the import on the user's
        behalf.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDocumentRequest"
            examples:
              formattedDocument:
                summary: A formatted price offer
                value:
                  title: Price offer
                  mode: replace
                  items:
                    - kind: html
                      html: "<h1>Price offer</h1><p>Prepared for review.</p>"
                      css: "h1 { color: #205bd4; }"
      responses:
        "201":
          description: Temporary import created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateDocumentResponse"
        "400":
          $ref: "#/components/responses/InvalidJson"
        "413":
          $ref: "#/components/responses/TooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "422":
          $ref: "#/components/responses/InvalidDocument"
        "429":
          $ref: "#/components/responses/RateLimited"
  /open/protocol:
    get:
      operationId: openPasteToPrintPwaDeepLink
      summary: Resolve an installed-PWA protocol link
      description: >-
        Validates a web+pastetoprint protocol URL and redirects to the same
        fragment-based review flow used by the HTTPS editor link. This endpoint
        does not accept the reserved native pastetoprint scheme.
      parameters:
        - name: url
          in: query
          required: true
          description: Percent-encoded web+pastetoprint://open/{documentId} URL.
          schema:
            type: string
            pattern: "^web\\+pastetoprint://open/[a-f0-9]{64}/?$"
      responses:
        "302":
          description: Redirect to the fragment-based document review flow.
          headers:
            Location:
              required: true
              schema:
                type: string
                format: uri-reference
        "400":
          description: Missing, malformed, or unsupported protocol URL.
          content:
            text/html:
              schema:
                type: string
        "405":
          description: Use GET or HEAD.
    head:
      operationId: inspectPasteToPrintPwaDeepLink
      summary: Validate a PWA protocol link without a response body
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            pattern: "^web\\+pastetoprint://open/[a-f0-9]{64}/?$"
      responses:
        "302":
          description: The protocol URL is valid.
          headers:
            Location:
              required: true
              schema:
                type: string
                format: uri-reference
        "400":
          description: Missing, malformed, or unsupported protocol URL.
components:
  schemas:
    TextItem:
      type: object
      additionalProperties: false
      required:
        - kind
        - text
      properties:
        kind:
          const: text
        text:
          type: string
          minLength: 1
          maxLength: 500000
          description: Plain text. Line breaks are preserved.
    HtmlItem:
      type: object
      additionalProperties: false
      required:
        - kind
        - html
      properties:
        kind:
          const: html
        html:
          type: string
          minLength: 1
          maxLength: 500000
          description: >-
            Formatted HTML. pasteToPrint removes unsupported or dangerous
            elements, attributes, and URLs before inserting it.
        css:
          type: string
          maxLength: 100000
          description: >-
            Optional CSS for this HTML item. Safe declarations are converted to
            inline styles; remote URLs, imports, positioning, and active content
            are removed.
    ImageItem:
      type: object
      additionalProperties: false
      required:
        - kind
        - dataUrl
      properties:
        kind:
          const: image
        dataUrl:
          type: string
          maxLength: 1500000
          pattern: "^data:image/(png|jpeg|jpg|webp|gif|bmp);base64,"
          description: PNG, JPEG, WEBP, GIF, or BMP encoded as a base64 Data URL.
        mime:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/jpg
            - image/webp
            - image/gif
            - image/bmp
        name:
          type: string
          maxLength: 160
        alt:
          type: string
          maxLength: 300
    DocumentItem:
      oneOf:
        - $ref: "#/components/schemas/TextItem"
        - $ref: "#/components/schemas/HtmlItem"
        - $ref: "#/components/schemas/ImageItem"
      discriminator:
        propertyName: kind
    CreateDocumentRequest:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        title:
          type: string
          maxLength: 200
          description: Suggested document title.
        mode:
          type: string
          enum:
            - replace
            - append
          default: replace
          description: Preferred action. The user can choose either action in the review dialog.
        imageScale:
          type: integer
          enum:
            - 25
            - 50
            - 75
            - 100
          default: 100
          description: Initial image scale percentage.
        items:
          type: array
          minItems: 1
          maxItems: 12
          items:
            $ref: "#/components/schemas/DocumentItem"
    CreateDocumentResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - id
        - token
        - importUrl
        - url
        - openUrl
        - nativeDeepLink
        - pwaDeepLink
        - expiresAt
        - expiresInSeconds
        - requiresUserConfirmation
      properties:
        ok:
          const: true
        id:
          type: string
          pattern: "^[a-f0-9]{64}$"
          description: Stable alias of token for clients expecting an id.
        token:
          type: string
          pattern: "^[a-f0-9]{64}$"
        importUrl:
          type: string
          format: uri
          description: Privacy-oriented fragment link. Open or give it to the user.
        url:
          type: string
          format: uri
          description: Friendly HTTPS deep link in the form /open/{id}.
        openUrl:
          type: string
          format: uri
          description: Alias of url with an explicit field name.
        nativeDeepLink:
          type: string
          format: uri
          pattern: "^pastetoprint://open/[a-f0-9]{64}$"
          description: Native link requiring an installed desktop protocol handler.
        pwaDeepLink:
          type: string
          format: uri
          pattern: "^web\\+pastetoprint://open/[a-f0-9]{64}$"
          description: Link handled by an installed compatible pasteToPrint PWA.
        expiresAt:
          type: string
          format: date-time
        expiresInSeconds:
          type: integer
        requiresUserConfirmation:
          const: true
    ServiceDescription:
      type: object
      required:
        - ok
        - name
        - version
        - editorCapabilities
        - publicSessions
        - createDocument
        - openapi
      properties:
        ok:
          const: true
        name:
          type: string
        version:
          type: string
        description:
          type: string
        editorCapabilities:
          type: object
          required:
            - documentation
            - directDrawingOnSelectedPaperFormat
            - inputMethods
            - drawingTools
            - precisionTools
            - layers
            - imageTools
            - undoRedo
            - editableAfterSave
          properties:
            documentation:
              type: string
              format: uri
            directDrawingOnSelectedPaperFormat:
              const: true
            inputMethods:
              type: array
              items:
                type: string
                enum:
                  - mouse
                  - touch
                  - pen
            drawingTools:
              type: array
              minItems: 7
              items:
                type: string
            precisionTools:
              type: array
              minItems: 5
              items:
                type: string
            layers:
              type: array
              minItems: 2
              items:
                type: string
            imageTools:
              type: array
              minItems: 5
              items:
                type: string
            undoRedo:
              const: true
            editableAfterSave:
              const: true
        preferredCreateDocument:
          type: object
          properties:
            method:
              const: POST
            url:
              type: string
              format: uri
            contentType:
              const: application/json
            acceptedContentTypes:
              type: array
              items:
                type: string
                enum:
                  - application/json
                  - application/vnd.pastetoprint.ptdf+json
            schemaVersion:
              const: ptp.document/1
            formatName:
              const: PTDF
            formatVersion:
              const: "1.0"
            formatSpecification:
              type: string
              format: uri
            idempotencyHeader:
              const: Idempotency-Key
            ttlHeader:
              const: X-Document-TTL
            openapi:
              type: string
              format: uri
            templates:
              type: string
              format: uri
        publicSessions:
          type: object
          required:
            - method
            - url
            - authenticationRequired
            - acceptedContentTypes
            - schemaVersion
            - contractRevision
            - capabilities
            - defaultTtlSeconds
            - maxRequestBytes
            - rateLimit
            - rateWindowSeconds
            - openapi
            - documentation
          properties:
            method:
              const: POST
            url:
              type: string
              format: uri
            authenticationRequired:
              const: false
            acceptedContentTypes:
              type: array
              items:
                type: string
                enum:
                  - application/json
                  - application/vnd.pastetoprint.ptdf+json
            schemaVersion:
              const: ptp.document/1
            contractRevision:
              const: "2026-08-01"
            capabilities:
              type: string
              format: uri
            defaultTtlSeconds:
              type: integer
              const: 3600
            maxRequestBytes:
              type: integer
              const: 102400
            rateLimit:
              type: integer
              const: 5
            rateWindowSeconds:
              type: integer
              const: 3600
            openapi:
              type: string
              format: uri
            documentation:
              type: string
              format: uri
        createDocument:
          type: object
        openapi:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        documentApiV2Documentation:
          type: string
          format: uri
        templateCatalogDocumentation:
          type: string
          format: uri
        documentApiAuthenticationDocumentation:
          type: string
          format: uri
        documentFormat:
          type: object
          required:
            - name
            - version
            - contractRevision
            - fullName
            - wireIdentifier
            - mediaType
            - fileExtensions
            - specification
            - jsonSchema
            - capabilities
          properties:
            name:
              const: PTDF
            version:
              const: "1.0"
            contractRevision:
              const: "2026-08-01"
            fullName:
              const: pasteToPrint Document Format
            wireIdentifier:
              const: ptp.document/1
            mediaType:
              const: application/vnd.pastetoprint.ptdf+json
            fileExtensions:
              type: array
              prefixItems:
                - const: .ptdf
                - const: .ptdf.json
              minItems: 2
              maxItems: 2
            specification:
              type: string
              format: uri
            jsonSchema:
              type: string
              format: uri
            capabilities:
              type: string
              format: uri
        mcp:
          type: object
          required:
            - transport
            - requiresLocalInstallation
            - documentation
            - tools
          properties:
            transport:
              const: stdio
            requiresLocalInstallation:
              const: true
            overview:
              type: string
              format: uri
            documentation:
              type: string
              format: uri
            tools:
              type: array
              items:
                type: string
                enum:
                  - list_templates
                  - create_document
        deepLinks:
          type: object
          required:
            - documentation
            - httpsPattern
            - nativePattern
            - nativeRequiresInstalledHandler
            - pwaPattern
            - pwaProtocol
            - pwaManifest
            - pwaHandler
          properties:
            documentation:
              type: string
              format: uri
            httpsPattern:
              type: string
            nativePattern:
              type: string
            nativeRequiresInstalledHandler:
              const: true
            pwaPattern:
              type: string
            pwaProtocol:
              const: web+pastetoprint
            pwaManifest:
              type: string
              format: uri
            pwaHandler:
              type: string
        authentication:
          type: object
          properties:
            optional:
              type: boolean
            scheme:
              const: Bearer
            requiredScopeForCreate:
              const: document:create
            supportedScopes:
              type: array
              items:
                type: string
        ttlTiers:
          type: object
        documentSchemas:
          type: object
          properties:
            ptp.document/1:
              type: string
              format: uri
        documentCapabilities:
          type: object
          properties:
            ptp.capabilities/1:
              type: string
              format: uri
        templateCatalogs:
          type: object
          properties:
            ptp.templates/1:
              type: string
              format: uri
        limits:
          type: object
    Error:
      type: object
      required:
        - ok
        - error
        - message
      properties:
        ok:
          const: false
        error:
          type: string
        message:
          type: string
        field:
          type: string
        retryAfter:
          type: integer
  responses:
    InvalidJson:
      description: Invalid JSON request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooLarge:
      description: Request or document content is too large
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnsupportedMediaType:
      description: Content-Type must be application/json
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InvalidDocument:
      description: The document does not match the supported schema
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    RateLimited:
      description: Too many temporary imports were created
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
