SoftSync AI Workflow API

openapi: 3.2.0
info:
  title: Softsync Workflow 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: Workflow
paths:
  /workflow/runs/start:
    post:
      description: Starts any enabled workflow in the workspace by its `workflowName`, with an optional `input` object. Responds with a `runId` and a status straight away; the work happens in the background, so poll getWorkflowRun for the result. To start a workflow you published under a slug and wait for its answer in one call, use runPublishedWorkflow instead. A workflow made for one person can only be started by that person, and email campaigns can only be started by an Editor or Admin.
      operationId: startWorkflowRun
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartWorkflowRunDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartWorkflowRunResponseDto'
      security:
      - bearer: []
      summary: Start a workflow run
      tags:
      - Workflow
      x-feature: workflows
  /workflow/runs:
    post:
      description: Lists runs newest first. Filter with `workflowName`, `status` or `parentRunId` (the runs started by another run, such as one run per recipient of an email campaign). `limit` defaults to 50 and is at most 200; page with `offset`. Only a workspace admin can list another person's runs; email campaign runs are visible only to the person who sent them and to admins.
      operationId: listWorkflowRuns
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryWorkflowRunsDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowRunViewDto'
      security:
      - bearer: []
      summary: List workflow runs in workspace
      tags:
      - Workflow
      x-feature: workflows
  /workflow/runs/{runId}:
    get:
      description: Returns the status, input, output and error of one run, plus its working `state`. For an email campaign's per-recipient runs, `state` holds the sent, opened, clicked, replied and bounced details. An email campaign that someone else sent reads as not found unless you are a workspace admin.
      operationId: getWorkflowRun
      parameters:
      - name: runId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunViewDto'
      security:
      - bearer: []
      summary: Get workflow run details
      tags:
      - Workflow
      x-feature: workflows
  /workflow/runs/{runId}/cancel:
    post:
      description: Stops a run that has not finished, along with every run it started. Work already done is not undone. Allowed for the person who started the run, the person who made the workflow, or a workspace admin.
      operationId: cancelWorkflowRun
      parameters:
      - name: runId
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelWorkflowRunResponseDto'
      security:
      - bearer: []
      summary: Cancel workflow run
      tags:
      - Workflow
      x-feature: workflows
components:
  schemas:
    WorkflowRunStatus:
      type: string
      enum:
      - pending
      - running
      - waiting_timer
      - waiting_external
      - completed
      - failed
      - cancelled
      description: Filter runs by status
    QueryWorkflowRunsDto:
      type: object
      properties:
        workflowName:
          type: string
          description: Only runs of this workflow.
        workflowNames:
          description: Workflow names for multi-workflow listing
          type: array
          items:
            type: string
        parentRunId:
          type: string
          description: Filter runs by a single parent run id
        parentRunIds:
          description: Parent run ids for multi-parent fan-in listing
          type: array
          items:
            type: string
        userId:
          type: string
        status:
          description: Filter runs by status
          allOf:
          - $ref: '#/components/schemas/WorkflowRunStatus'
        limit:
          type: number
          default: 50
          minimum: 1
          maximum: 200
        offset:
          type: number
          default: 0
          minimum: 0
    WorkflowRunViewDto:
      type: object
      properties:
        id:
          type: string
        workspaceId:
          type: string
        userId:
          type: string
        parentRunId:
          type: string
        workflowName:
          type: string
        workflowVersion:
          type: string
        displayName:
          type: string
        outcome:
          type: string
        status:
          type: string
        currentNodeId:
          type: string
        input:
          type: object
        output:
          type: object
        state:
          type: object
        metadata:
          type: object
        lastError:
          type: string
        dryRun:
          type: boolean
        createdAt:
          type: string
        startedAt:
          type: string
        completedAt:
          type: string
      required:
      - id
      - workflowName
      - workflowVersion
      - status
      - createdAt
    StartWorkflowRunDto:
      type: object
      properties:
        workflowName:
          type: string
          description: Name of the workflow to run, as returned by listWorkspaceWorkflows.
        workflowVersion:
          type: string
          description: Version to run. Defaults to the installed version.
        input:
          type: object
          description: Input values for the workflow, as a JSON object.
        metadata:
          type: object
        userId:
          type: string
          description: Override user id for system starts
        dryRun:
          type: boolean
          description: 'Run in dry-run mode: pull data from external systems but skip writing to workspace records'
      required:
      - workflowName
    StartWorkflowRunResponseDto:
      type: object
      properties:
        runId:
          type: string
          description: Identifier to poll with getWorkflowRun.
        status:
          type: string
          description: 'Run status: pending, running, waiting_timer, waiting_external, completed, failed or cancelled.'
      required:
      - runId
      - status
    CancelWorkflowRunResponseDto:
      type: object
      properties:
        cancelled:
          type: boolean
          description: True once the stop request was accepted.
      required:
      - cancelled
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key