SoftSync AI Files API

openapi: 3.2.0
info:
  title: Softsync Files API
  description: '## Introduction


    The Softsync Platform API


    This API lets you read and write your Softsync data from your own applications. Authenticate with a personal API key created in **Settings → API Keys**, sent as the `x-api-key` header.


    **New here?** Read **Concepts** first, then **Authentication**, then **Quickstart: full cycle** — it walks the whole thing end to end. **Objects**, **Records**, **Groups & Views** and **Notes** cover each area in depth, and **Code Generation** shows how to turn this document into a typed client.


    To try a request from this page, paste your API key into the **Authentication** panel on the right.


    ## Support


    If you need help with API access or integration details, contact contact@softsync.ai.'
  version: 0.1.0
  contact: {}
servers: []
security:
- x-api-key: []
tags:
- name: Files
paths:
  /files/signing-field-kinds:
    get:
      operationId: getSigningFieldRules
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningFieldRulesDto'
      security:
      - bearer: []
      summary: The kinds of signing field, their starting sizes and who fills each
      tags:
      - Files
      x-feature: files
  /files/records/{recordId}:
    get:
      operationId: listRecordFiles
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileItemDto'
      security:
      - bearer: []
      summary: 'Everything kept on a record: folders, files and documents'
      tags:
      - Files
      x-feature: files
  /files/records/{recordId}/folders:
    post:
      operationId: createRecordFolder
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItemDto'
      security:
      - bearer: []
      summary: Add a folder to a record
      tags:
      - Files
      x-feature: files
  /files/records/{recordId}/uploads:
    post:
      operationId: addRecordUploads
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddUploadsDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileItemDto'
      security:
      - bearer: []
      summary: Keep uploaded files on a record (upload them with POST /file/workspace/upload…
      tags:
      - Files
      x-feature: files
  /files/records/{recordId}/generate:
    post:
      operationId: generateRecordFile
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateIntoFolderDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentDto'
      security:
      - bearer: []
      summary: Make a template's PDF for a record into a folder; built in the background
      tags:
      - Files
      x-feature: documents
  /files/records/{recordId}/documents:
    post:
      operationId: createRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: recordId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecordDocumentDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItemDto'
      security:
      - bearer: []
      summary: Write a document for a record, blank or starting from a template
      tags:
      - Files
      x-feature: documents
  /files/{id}:
    patch:
      operationId: updateRecordFile
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileItemDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItemDto'
      security:
      - bearer: []
      summary: Rename or move a file or folder
      tags:
      - Files
      x-feature: files
    delete:
      operationId: deleteRecordFile
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Moved to the bin
      security:
      - bearer: []
      summary: Move a file, or a folder and what is in it, to the bin
      tags:
      - Files
      x-feature: files
  /files/{id}/document:
    get:
      operationId: getRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocumentDto'
      security:
      - bearer: []
      summary: A record document with its design and fields
      tags:
      - Files
      x-feature: files
    put:
      operationId: saveRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveRecordDocumentDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocumentDto'
      security:
      - bearer: []
      summary: Save a draft document's design
      tags:
      - Files
      x-feature: files
  /files/{id}/preview:
    post:
      operationId: previewRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
      security:
      - bearer: []
      summary: A draft document as a PDF (nothing is saved)
      tags:
      - Files
      x-feature: files
  /files/{id}/finalize:
    post:
      operationId: finalizeRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocumentDto'
      security:
      - bearer: []
      summary: Make the PDF of a draft document and lock it for printing and signing
      tags:
      - Files
      x-feature: files
  /files/{id}/reopen:
    post:
      operationId: reopenRecordDocument
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocumentDto'
      security:
      - bearer: []
      summary: Turn a finished document back into a draft
      tags:
      - Files
      x-feature: files
  /files/{id}/fields:
    put:
      operationId: saveSigningFields
      parameters:
      - name: x-workspace-id
        in: header
        description: Workspace ID
        required: true
        schema:
          type: string
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveSigningFieldsDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordDocumentDto'
      security:
      - bearer: []
      summary: Place the fields each party fills when signing a PDF
      tags:
      - Files
      x-feature: files
components:
  schemas:
    DocumentDto:
      type: object
      properties:
        id:
          type: string
        templateId:
          type: string
        recordId:
          type: string
        status:
          allOf:
          - $ref: '#/components/schemas/DocumentStatus'
        error:
          type: string
          description: Why the PDF could not be made
        file:
          $ref: '#/components/schemas/FileAttachment'
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
      required:
      - id
      - templateId
      - recordId
      - status
      - createdAt
    CreateFolderDto:
      type: object
      properties:
        name:
          type: string
        parentId:
          type: string
          description: Folder to create it in; root when empty
      required:
      - name
    CreateRecordDocumentDto:
      type: object
      properties:
        name:
          type: string
        templateId:
          type: string
          description: Template whose design is copied; blank when empty
        parentId:
          type: string
      required:
      - name
    SigningFieldKindDto:
      type: object
      properties:
        kind:
          allOf:
          - $ref: '#/components/schemas/SigningFieldKind'
        w:
          type: number
          description: Starting width in points
        h:
          type: number
          description: Starting height in points
        auto:
          type: boolean
          description: Filled in by the server when the person signs, never typed
        mark:
          type: boolean
          description: Drawn as the person's adopted signature or initials
      required:
      - kind
      - w
      - h
      - auto
      - mark
    DocumentStatus:
      type: string
      enum:
      - queued
      - done
      - failed
    FileItemKind:
      type: string
      enum:
      - folder
      - upload
      - document
    AddUploadsDto:
      type: object
      properties:
        files:
          description: Files from POST /file/workspace/upload
          type: array
          items:
            $ref: '#/components/schemas/UploadedFileDto'
        parentId:
          type: string
      required:
      - files
    DocumentPageDto:
      type: object
      properties:
        size:
          allOf:
          - $ref: '#/components/schemas/PaperSize'
        landscape:
          type: boolean
        margin:
          $ref: '#/components/schemas/DocumentMarginDto'
        header:
          type: string
        footer:
          type: string
        pageNumbers:
          type: boolean
    SigningFieldDto:
      type: object
      properties:
        id:
          type: string
        role:
          type: string
          description: 'Who fills it: a party role, "Sender" or "Record"'
        kind:
          allOf:
          - $ref: '#/components/schemas/SigningFieldKind'
        page:
          type: number
          description: 0-based page index
        x:
          type: number
        y:
          type: number
        w:
          type: number
        h:
          type: number
        required:
          type: boolean
        label:
          type: string
        fontSize:
          type: number
        options:
          description: Choices of a select
          type: array
          items:
            type: string
        value:
          type: string
          description: What a field filled from the record prints, as Liquid
      required:
      - id
      - role
      - kind
      - page
      - x
      - y
      - w
      - h
      - required
    SaveSigningFieldsDto:
      type: object
      properties:
        fields:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Fields in PDF points from the top-left of each page as shown
      required:
      - fields
    PaperSize:
      type: string
      enum:
      - a4
      - a5
      - us-letter
      - us-legal
    SigningFieldRulesDto:
      type: object
      properties:
        kinds:
          type: array
          items:
            $ref: '#/components/schemas/SigningFieldKindDto'
        senderRole:
          type: string
          description: The role the sender fills when sending
        recordRole:
          type: string
          description: The role printed from the record, which only templates have
      required:
      - kinds
      - senderRole
      - recordRole
    RecordDocumentDto:
      type: object
      properties:
        id:
          type: string
        recordId:
          type: string
        parentId:
          type:
          - string
          - 'null'
        kind:
          allOf:
          - $ref: '#/components/schemas/FileItemKind'
        name:
          type: string
        file:
          $ref: '#/components/schemas/FileAttachment'
        state:
          allOf:
          - $ref: '#/components/schemas/FileItemState'
        sourceId:
          type: string
        envelopeId:
          type: string
        fieldCount:
          type: number
          description: How many signing fields are placed on it
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
        content:
          $ref: '#/components/schemas/DocumentContentDto'
        page:
          $ref: '#/components/schemas/DocumentPageDto'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/SigningFieldDto'
      required:
      - id
      - recordId
      - parentId
      - kind
      - name
      - state
      - fieldCount
      - createdAt
      - content
      - page
      - fields
    DocumentMarginDto:
      type: object
      properties:
        top:
          type: number
        right:
          type: number
        bottom:
          type: number
        left:
          type: number
    UpdateFileItemDto:
      type: object
      properties:
        name:
          type: string
        parentId:
          type:
          - object
          - 'null'
          description: Folder to move it to; null moves it to the root
    FileItemDto:
      type: object
      properties:
        id:
          type: string
        recordId:
          type: string
        parentId:
          type:
          - string
          - 'null'
        kind:
          allOf:
          - $ref: '#/components/schemas/FileItemKind'
        name:
          type: string
        file:
          $ref: '#/components/schemas/FileAttachment'
        state:
          allOf:
          - $ref: '#/components/schemas/FileItemState'
        sourceId:
          type: string
        envelopeId:
          type: string
        fieldCount:
          type: number
          description: How many signing fields are placed on it
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
      required:
      - id
      - recordId
      - parentId
      - kind
      - name
      - state
      - fieldCount
      - createdAt
    FileAttachment:
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        fileName:
          type: string
        fileSize:
          type: number
        mime:
          type: string
        isInline:
          type: boolean
        contentId:
          type: string
        url:
          type: string
      required:
      - id
      - path
      - fileName
      - fileSize
      - mime
    GenerateIntoFolderDto:
      type: object
      properties:
        templateId:
          type: string
        parentId:
          type: string
      required:
      - templateId
    FileItemState:
      type: string
      enum:
      - draft
      - final
      - sending
      - signed
      - declined
      - voided
      - expired
    UploadedFileDto:
      type: object
      properties:
        path:
          type: string
        fileName:
          type: string
        fileSize:
          type: number
        mime:
          type: string
        id:
          type: string
        url:
          type: string
        uploadedAt:
          type: string
        uploadedBy:
          type: string
        workspaceId:
          type: string
      required:
      - path
      - fileName
      - fileSize
      - mime
    SaveRecordDocumentDto:
      type: object
      properties:
        name:
          type: string
        content:
          $ref: '#/components/schemas/DocumentContentDto'
        page:
          $ref: '#/components/schemas/DocumentPageDto'
      required:
      - content
    SigningFieldKind:
      type: string
      enum:
      - signature
      - initials
      - date_signed
      - full_name
      - email
      - text
      - number
      - checkbox
      - select
    DocumentContentDto:
      type: object
      properties:
        blocks:
          type: array
          items:
            type: object
            additionalProperties: true
        settings:
          type: object
        pdf:
          type: object
      required:
      - blocks
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key