# SPDX-License-Identifier: MIT
openapi: 3.1.0
info:
  title: pasteToPrint Public PTDF Session API
  version: 1.2.0
  description: >-
    Creates anonymous, short-lived pasteToPrint editor sessions from PTDF 1.0.
    No account, API key, or payment card is required. The user must review and
    confirm the import. Sessions are temporary and are deleted after expiry or
    through the management endpoint documented in the response.
  contact:
    url: https://www.pastetoprint.com/
  license:
    name: MIT
    identifier: MIT
  x-license-scope: https://www.pastetoprint.com/PTDF-LICENSE.md
externalDocs:
  description: Public session API guide
  url: https://www.pastetoprint.com/PUBLIC-SESSIONS-API.md
servers:
  - url: https://www.pastetoprint.com
security: []
paths:
  /api/v1/public/sessions:
    get:
      operationId: describePublicPtdfSessions
      summary: Describe the public service and its current limits
      responses:
        "200":
          description: Public endpoint metadata and limits.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceDescription"
    post:
      operationId: createPublicPtdfSession
      summary: Create a temporary PTDF editor session without authentication
      description: >-
        Accepts either a PTDF 1.0 document directly or an envelope containing
        document and session. The request is limited to 100 KiB and one IP may
        create at most five sessions in a one-hour window.
      requestBody:
        required: true
        content:
          application/vnd.pastetoprint.ptdf+json:
            schema:
              $ref: /api/document-schema/v1/schema.json
            examples:
              order:
                $ref: "#/components/examples/Order"
              landscape:
                summary: Current-revision landscape document
                externalValue: https://www.pastetoprint.com/api/document-schema/v1/landscape-example.json
              coloringDrawing:
                summary: Coloring template with a rasterized drawing
                externalValue: https://www.pastetoprint.com/api/document-schema/v1/coloring-drawing-example.json
          application/json:
            schema:
              oneOf:
                - $ref: /api/document-schema/v1/schema.json
                - $ref: "#/components/schemas/PublicSessionEnvelope"
            examples:
              envelope:
                value:
                  document:
                    schemaVersion: ptp.document/1
                    title: Objednávka revíznych prác
                    locale: sk-SK
                    template: order
                    blocks:
                      - type: paragraph
                        text: Objednávame vykonanie revíznych prác.
                  session:
                    expiresIn: 3600
                    allowEditing: true
                    allowExport: true
      responses:
        "201":
          description: A temporary session was created.
          headers:
            Location:
              description: Friendly HTTPS URL for user review.
              schema:
                type: string
                format: uri
            X-Document-TTL-Applied:
              schema:
                type: integer
                minimum: 300
                maximum: 3600
            X-RateLimit-Limit:
              schema:
                type: integer
                const: 5
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
                maximum: 4
            X-RateLimit-Reset:
              description: Unix timestamp at which the current window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSessionResponse"
        "400":
          description: The request body is not valid JSON.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: The request exceeds 100 KiB.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "415":
          description: Use application/vnd.pastetoprint.ptdf+json or application/json.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: The PTDF document or session options are invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Five sessions were already created from this IP in the current hour.
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Temporary storage is unavailable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    options:
      operationId: preflightPublicPtdfSessions
      summary: CORS preflight
      responses:
        "204":
          description: Preflight accepted.
components:
  examples:
    Order:
      value:
        schemaVersion: ptp.document/1
        title: Objednávka revíznych prác
        locale: sk-SK
        paper:
          size: A4
          orientation: portrait
        template: order
        blocks:
          - type: heading
            level: 1
            text: Objednávka revíznych prác
          - type: paragraph
            text: Termín vykonania je do 30 dní.
  schemas:
    PublicSessionEnvelope:
      type: object
      additionalProperties: false
      required:
        - document
      properties:
        document:
          $ref: /api/document-schema/v1/schema.json
        session:
          type: object
          additionalProperties: false
          properties:
            expiresIn:
              type: integer
              minimum: 300
              maximum: 3600
              default: 3600
            allowEditing:
              type: boolean
              default: true
            allowExport:
              type: boolean
              default: true
    CreateSessionResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - sessionId
        - documentId
        - sessionUrl
        - sessionToken
        - editorUrl
        - viewUrl
        - importUrl
        - viewImportUrl
        - schemaVersion
        - formatName
        - formatVersion
        - expiresAt
        - expiresInSeconds
        - sessionTtlSeconds
        - permissions
        - temporary
        - requiresUserConfirmation
      properties:
        success:
          type: boolean
          const: true
        sessionId:
          type: string
          pattern: "^[a-f0-9]{64}$"
        documentId:
          type: string
          pattern: "^[a-f0-9]{64}$"
        sessionUrl:
          type: string
          format: uri
        sessionToken:
          type: string
          pattern: "^ptp_session_[A-Za-z0-9_-]{43}$"
          readOnly: true
          description: Send only in X-Session-Token to the v2 session management endpoint.
        editorUrl:
          type: string
          format: uri
        viewUrl:
          type: string
          format: uri
        importUrl:
          type: string
          format: uri-reference
        viewImportUrl:
          type: string
          format: uri-reference
        schemaVersion:
          type: string
          const: ptp.document/1
        formatName:
          type: string
          const: PTDF
        formatVersion:
          type: string
          const: "1.0"
        expiresAt:
          type: string
          format: date-time
        expiresInSeconds:
          type: integer
          minimum: 0
          maximum: 3600
        sessionTtlSeconds:
          type: integer
          minimum: 300
          maximum: 3600
        permissions:
          type: object
          additionalProperties: false
          required:
            - allowEditing
            - allowExport
          properties:
            allowEditing:
              type: boolean
            allowExport:
              type: boolean
        temporary:
          type: boolean
          const: true
        requiresUserConfirmation:
          type: boolean
          const: true
    ServiceDescription:
      type: object
      additionalProperties: true
      required:
        - success
        - name
        - version
        - endpoint
        - schemaVersion
        - contractRevision
        - schemaUrl
        - capabilitiesUrl
        - templatesUrl
        - limits
      properties:
        success:
          type: boolean
          const: true
        name:
          type: string
        version:
          type: string
        endpoint:
          type: string
          format: uri
        schemaVersion:
          type: string
          const: ptp.document/1
        contractRevision:
          type: string
          const: "2026-08-01"
        schemaUrl:
          type: string
          format: uri
        capabilitiesUrl:
          type: string
          format: uri
        templatesUrl:
          type: string
          format: uri
        limits:
          type: object
    Error:
      type: object
      additionalProperties: true
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
        message:
          type: string
