SoftSync AI Workspace Workflows API

openapi: 3.2.0
info:
  title: Softsync Workspace Workflows 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: Workspace Workflows
paths:
  /workflow/workspace:
    get:
      description: Returns every workflow in the workspace, switched on or off. Each entry has its `workflowName`, `version`, `triggerType` (`manual` workflows are the ones people start by hand) and `enabled`. Use `workflowName` with startWorkflowRun.
      operationId: listWorkspaceWorkflows
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceWorkflowSummaryDto'
      security:
      - bearer: []
      summary: List all workflows installed/created in the workspace
      tags:
      - Workspace Workflows
      x-feature: workflows
  /workflow/workspace/{name}:
    get:
      description: Returns one workflow with its full `definition`. The input it expects is described under `definition.schemas.input` (a JSON Schema), when the workflow declares one.
      operationId: getWorkspaceWorkflow
      parameters:
      - name: name
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceWorkflowDetailDto'
      security:
      - bearer: []
      summary: Get a workspace workflow by name (latest version)
      tags:
      - Workspace Workflows
      x-feature: workflows
  /workflow/workspace/{name}/versions/{version}/exposure:
    post:
      description: 'Publishing gives the workflow a `slug` so it can be run with runPublishedWorkflow and appears in listPublishedWorkflows. Send `apiEnabled: true` together with an `apiSlug` (letters, digits, hyphens and underscores). Requires the Editor or Admin role, and you must be the workflow''s author or an admin.'
      operationId: setWorkspaceWorkflowExposure
      parameters:
      - name: name
        required: true
        in: path
        schema:
          type: string
      - name: version
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetWorkflowExposureDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowExposureDto'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorDto'
      security:
      - bearer: []
      summary: Publish/unpublish a workflow as a typed API endpoint and/or MCP tool
      tags:
      - Workspace Workflows
      x-feature: workflows
  /workflow/workspace/{name}/versions/{version}/webhook-secret/rotate:
    post:
      description: For a workflow that starts from an incoming webhook. Creates a new signing secret and returns it as `webhookSecret` this one time only; store it straight away. The old secret stops working. Requires the Editor or Admin role, and you must be the workflow's author or an admin.
      operationId: rotateWorkflowWebhookSecret
      parameters:
      - name: name
        required: true
        in: path
        schema:
          type: string
      - name: version
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowExposureDto'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowErrorDto'
      security:
      - bearer: []
      summary: Rotate the webhook signing secret (the cleartext is returned once)
      tags:
      - Workspace Workflows
      x-feature: workflows
components:
  schemas:
    WorkspaceWorkflowDetailDto:
      type: object
      properties:
        id:
          type: string
        workspaceId:
          type: string
        workflowName:
          type: string
        version:
          type: string
        displayName:
          type: string
        description:
          type: string
        source:
          type: string
          enum:
          - platform
          - installed
          - custom
        sourceTemplateId:
          type: string
        triggerType:
          type: string
          enum:
          - manual
          - cron
          - event
        enabled:
          type: boolean
        definition:
          type: object
          description: Full workspace-local definition graph (JSONB)
        definitionHash:
          type: string
        canChange:
          type: boolean
          description: 'Whether the requester may edit, switch on/off or delete it: its author or an admin'
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - workspaceId
      - workflowName
      - version
      - source
      - triggerType
      - enabled
      - definition
      - definitionHash
      - canChange
      - createdAt
      - updatedAt
    WorkflowErrorDto:
      type: object
      properties:
        code:
          allOf:
          - $ref: '#/components/schemas/WorkflowErrorCode'
        message:
          type: string
      required:
      - code
      - message
    SetWorkflowExposureDto:
      type: object
      properties:
        apiEnabled:
          type: boolean
          description: Publish the workflow as a typed public API endpoint
        apiSlug:
          type: string
          description: URL slug for the published endpoint (required when enabling; unique per workspace)
        mcpEnabled:
          type: boolean
          description: Additionally expose the workflow as a per-workspace MCP tool
    WorkspaceWorkflowSummaryDto:
      type: object
      properties:
        id:
          type: string
        workspaceId:
          type: string
        workflowName:
          type: string
        version:
          type: string
        displayName:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        source:
          type: string
          enum:
          - platform
          - installed
          - custom
        triggerType:
          type: string
          enum:
          - manual
          - cron
          - event
        enabled:
          type: boolean
        nodeCount:
          type: number
        canChange:
          type: boolean
          description: Whether the requester may edit, switch on/off or delete it
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - workspaceId
      - workflowName
      - version
      - source
      - triggerType
      - enabled
      - nodeCount
      - createdAt
      - updatedAt
    WorkflowExposureDto:
      type: object
      properties:
        workflowName:
          type: string
        version:
          type: string
        apiEnabled:
          type: boolean
        apiSlug:
          type: string
        mcpEnabled:
          type: boolean
        webhookSlug:
          type: string
          description: Webhook slug when the workflow has a webhook trigger
        webhookSecret:
          type: string
          description: Newly rotated webhook signing secret — only returned once, on rotation
      required:
      - workflowName
      - version
      - apiEnabled
      - mcpEnabled
    WorkflowErrorCode:
      type: string
      enum:
      - workflow_already_exists
      - workflow_invalid_definition
      - workflow_invalid_api_slug
      - workflow_api_slug_required
      - workflow_mcp_requires_api
      - workflow_no_webhook_trigger
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key