openapi: 3.1.0
info:
  title: TrueScreen API
  description: TrueScreen api for TrueFlow creation and Notarization
  version: 0.9.0
  termsOfService: https://truescreen.io/tos/
  contact:
    email: support@truescreen.app
    url: https://truescreen.io/
  license:
    name: Commercial
    url: https://truescreen.io/tos
servers:
  - url: https://api-stg.truescreen.io
  - url: https://api.truescreen.io
paths:
  /v1/templates:
    get:
      summary: List templates
      description: Returns a list of the flow templates available for the api key
      operationId: templatesGetAll
      tags:
        - Templates
      responses:
        '200':
          $ref: '#/components/responses/TemplatesGetAllResponse'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRfc'
              examples:
                serverError:
                  summary: Internal server error
                  value:
                    type: https://truescreen.redocly.app/errors/server-error
                    title: Internal server error
                    status: 500
                    detail: Invalid main filter conditions.
                    code: TS-501
  /v1/true-flows:
    post:
      summary: Create a TrueFlow
      description: Creates a new TrueFlow from a template
      operationId: trueFlowsPost
      tags:
        - TrueFlows
      requestBody:
        $ref: '#/components/requestBodies/CreateTrueFlowRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateTrueFlowResponse'
        '400':
          description: Validation error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRfc'
              examples:
                malformedPayload:
                  summary: Malformed payload or missing auth
                  value:
                    type: https://truescreen.redocly.app/errors/validation-error
                    title: Validation error
                    status: 400
                    detail: Malformed payload.
                    code: TS-001
                missingTemplateToken:
                  summary: Missing required field template_token
                  value:
                    type: https://truescreen.redocly.app/errors/validation-error
                    title: Validation error
                    status: 400
                    detail: must have required property 'template_token'.
                    code: TS-002
                flowTemplateNotFound:
                  summary: Flow template not found
                  value:
                    type: https://truescreen.redocly.app/errors/validation-error
                    title: Validation error
                    status: 400
                    detail: Flow template not found.
                    code: TS-003
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRfc'
              examples:
                serverError:
                  summary: Internal server error
                  value:
                    type: https://truescreen.redocly.app/errors/server-error
                    title: Internal server error
                    status: 500
                    detail: Internal server error.
                    code: TS-501
  /v1/true-flows-attachments:
    post:
      summary: Create trueflow attachment
      description: Create an Attachment for a TrueFlow
      operationId: trueFlowsAttachmentsPost
      tags:
        - TrueFlowsAttachments
      requestBody:
        $ref: '#/components/requestBodies/CreateTrueFlowAttachmentRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateTrueFlowAttachmentResponse'
        '400':
          description: Validation error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRfc'
              examples:
                malformedPayload:
                  summary: Malformed payload
                  value:
                    type: https://truescreen.redocly.app/errors/validation-error
                    title: Validation error
                    status: 400
                    detail: Malformed payload.
                    code: TS-001
                payloadValidation:
                  summary: Payload validation (e.g. missing file_name)
                  value:
                    type: https://truescreen.redocly.app/errors/validation-error
                    title: Validation error
                    status: 400
                    detail: must have required property 'file_name'.
                    code: TS-002
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponseRfc'
              examples:
                serverError:
                  summary: Internal server error
                  value:
                    type: https://truescreen.redocly.app/errors/server-error
                    title: Internal server error
                    status: 500
                    detail: Internal server error.
                    code: TS-501
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response
      properties:
        message:
          type: string
          example: Malformed payload.
        code:
          type: number
          example: 123
    ErrorResponseRfc:
      type: object
      description: >-
        RFC 9457 Problem Details for HTTP APIs with application-specific
        extensions.
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
          example: https://api.truescreen.io/errors/validation-error
        title:
          type: string
          description: Short, human-readable summary of the problem.
          example: Validation failed
        status:
          type: integer
          description: HTTP status code.
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: One or more fields have invalid values
        code:
          type: string
          description: Unique code to identify the error.
          example: TS-000
        instance:
          type: string
          format: uri
          description: URI reference that identifies the specific occurrence.
          example: https://api-stg-truescreen.io/special-events
      required:
        - title
        - code
    TemplatesGetResponse:
      type: object
      description: Flow Template item in the list
      properties:
        name:
          type: string
          description: Template name
        token:
          type: string
          description: Unique identifier for the flow template
        flow_data:
          type: object
          description: Normalized form schema
        sign_data:
          type: object
          description: Normalized sign data schema
      required:
        - name
        - token
        - flow_data
        - sign_data
    TrueFlow:
      type: object
      properties:
        token:
          type: string
          description: Unique identifier for the Attachment
        file_name:
          type: string
          description: Name of the uploaded file
        upload_url:
          type: string
          description: Upload url where to upload the file
      required:
        - token
        - file_name
        - upload_url
    TrueFlowsAttachmentsPostRequest:
      type: object
      description: Request payload for creating a TrueFlow attachment
      properties:
        file_name:
          type: string
          description: Name of the file to upload
      required:
        - file_name
      additionalProperties: false
    TrueFlowsPostRequest:
      type: object
      description: Request payload for creating a TrueFlow
      properties:
        name:
          type: string
          description: Name of the TrueFlow
        expires_at:
          type: string
          format: date-time
          description: Expiration date/time for the TrueFlow (ISO 8601)
        template_token:
          type: string
          description: Token of the flow template to use
        flow_data:
          type: object
          description: >-
            Key-value data for the flow form (keys and values depend on
            template)
        sign_data:
          type: array
          description: >-
            Array of signer data objects (e.g. signer_email, signer_name per
            item)
          items:
            type: object
      required:
        - template_token
      additionalProperties: false
    TrueFlowsPostResponse:
      type: object
      description: Created TrueFlow data
      properties:
        token:
          type: string
          description: Unique identifier for the TrueFlow
        trueLink:
          type: string
          description: Deep link url to the TrueFlow
      required:
        - token
        - trueLink
  requestBodies:
    CreateTrueFlowAttachmentRequest:
      description: Request payload for creating an attachment
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrueFlowsAttachmentsPostRequest'
          examples:
            default_example:
              $ref: '#/components/examples/CreateTrueFlowAttachmentRequestExample'
    CreateTrueFlowRequest:
      description: Request payload for creating a TrueFlow
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrueFlowsPostRequest'
          examples:
            Only template token:
              $ref: '#/components/examples/CreateTrueFlowRequestExampleBase'
            With flow data:
              $ref: '#/components/examples/CreateTrueFlowRequestExampleFlowData'
            With sign data:
              $ref: '#/components/examples/CreateTrueFlowRequestExampleSignData'
            Complete example:
              $ref: '#/components/examples/CreateTrueFlowRequestExampleComplete'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key passed in the Authorization header as a Bearer token
  examples:
    CreateTrueFlowAttachmentRequestExample:
      summary: Request an url to upload an attachment
      value:
        file_name: test.pdf
    CreateTrueFlowAttachmentResponseExample:
      summary: Update special event request
      value:
        token: a1b2c3d4e5f6g7h8i9j0k1
        file_name: test.pdf
        upload_url: https://s3./a1b2c3d4e5f6g7h8i9j0k1
    CreateTrueFlowRequestExampleBase:
      summary: Create TrueFlow with template token
      value:
        template_token: f6g7h8i9j0k1a1b2c3d4e5
        name: New True Flow
        expires_at: '2026-12-31T10:00:00+01:00'
    CreateTrueFlowRequestExampleFlowData:
      summary: Create TrueFlow with template token
      value:
        template_token: f6g7h8i9j0k1a1b2c3d4e5
        flow_data:
          first_name: John
          last_name: Doe
    CreateTrueFlowRequestExampleSignData:
      summary: Create TrueFlow with template token
      value:
        template_token: f6g7h8i9j0k1a1b2c3d4e5
        sign_data:
          - signer_email: john.doe@example.com
            signer_name: John Doe
    CreateTrueFlowRequestExampleComplete:
      summary: Create TrueFlow with template token
      value:
        template_token: f6g7h8i9j0k1a1b2c3d4e5
        name: New True Flow
        flow_data:
          first_name: John
          last_name: Doe
        sign_data:
          - signer_email: john.doe@example.com
            signer_name: John Doe
    CreateTrueFlowResponseExample:
      summary: Created TrueFlow (placeholder – complete with real values)
      value:
        token: ''
        trueLink: ''
    TemplatesGetAllResponseExample:
      summary: List of templates
      value:
        - name: Photo Acquisition
          token: f6g7h8i9j0k1a1b2c3d4e5
          flow_data:
            type: object
            required:
              - first_name
              - last_name
            properties:
              first_name:
                type: string
                format: hidden
                title: First Name
                readOnly: true
                minLength: 0
              last_name:
                type: string
                title: Last Name
                format: hidden
                readOnly: true
                minLength: 0
          sign_data:
            type: array
            items:
              type: object
              required:
                - signer_email
                - signer_name
              properties:
                signer_email:
                  type: string
                  title: E-mail
                  format: hidden
                signer_name:
                  type: string
                  title: First and last name
                  format: hidden
  responses:
    CreateTrueFlowAttachmentResponse:
      description: TrueFlows data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrueFlow'
          examples:
            default_example:
              $ref: '#/components/examples/CreateTrueFlowAttachmentResponseExample'
    CreateTrueFlowResponse:
      description: Created TrueFlow
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TrueFlowsPostResponse'
          examples:
            default_example:
              $ref: '#/components/examples/CreateTrueFlowResponseExample'
    TemplatesGetAllResponse:
      description: List of flow templates
      headers:
        X-Total-Count:
          schema:
            type: integer
          description: Total number of items
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TemplatesGetResponse'
          examples:
            default_example:
              $ref: '#/components/examples/TemplatesGetAllResponseExample'
tags:
  - name: Templates
    description: Flow templates list
  - name: TrueFlowsAttachments
    description: Attachment for a True Flow
  - name: TrueFlows
    description: True Flow
security:
  - ApiKeyAuth: []
