> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Test a Workflow

> Use this endpoint to test a stored workflow in any status. It needs no `Idempotency-Key`. Reads run for real. A step that writes sends nothing: the test stops at it and shows the request it would have sent. Each wait passes once. The body is the same as for a manual run (`inputData` and an optional `triggerNodeId`), with the same 1 MB limit. A test run is hidden from execution lists unless the request sets `testRun=true`, and it expires 24 hours after it starts. A refusal creates no test run. It answers 404 for an unknown workflow, 422 `FLK-0515` for a missing or ambiguous trigger, 422 `FLK-0935` or 503 `FLK-0720` for the input contract, 403 `FLK-0524` under the partner rule, 403 `FLK-0519` when an application is outside the workflow's allowed callers, and 403 `FLK-0365` when an application tests a workflow that uses a protected provider. An unquoted number that a float64 cannot keep exactly answers 400 `FLK-0001` and names the field. Send such a number as a string.



## OpenAPI

````yaml /en/openapi/v3-current/flowker.yaml post /v1/workflows/{workflowId}/test-runs
openapi: 3.1.0
info:
  description: >-
    Complete API reference for Flowker workflow orchestration services including
    catalog management, workflow definitions, provider configurations, and
    workflow executions.
  title: Flowker API
  version: 1.7.0
servers:
  - url: https://flowker.sandbox.lerian.net
security:
  - BearerAuth: []
tags:
  - name: Catalog API
    description: >-
      Browse built-in providers, executors, and triggers available in the
      Flowker catalog.
  - name: Workflows API
    description: >-
      Create, update, activate, deactivate, clone, and delete workflow
      definitions.
  - name: Executions API
    description: Start workflow executions and track their status and results.
  - name: Provider Configurations API
    description: >-
      Create, update, enable, and disable the provider configurations that
      workflow nodes call through.
  - name: Dashboard API
    description: >-
      Retrieve aggregated summaries of workflows and executions for operational
      dashboards.
  - name: Webhooks API
    description: >-
      Receive webhook callbacks from external systems to trigger workflow
      executions.
  - name: Schedule API
    description: >-
      Inspect a workflow's upcoming, skipped, and parked scheduled occurrences,
      and run or discard the parked ones.
  - name: OpenAPI Schemas API
    description: >-
      Upload, inspect, and delete the tenant's external OpenAPI schemas, and
      derive the contract of a single operation.
  - name: XSD Schemas API
    description: >-
      Upload, inspect, and delete the tenant's XSD schemas used to validate XML
      webhook payloads.
  - name: Settings API
    description: >-
      Read and set per-client settings, such as how long Flowker keeps finished
      executions.
paths:
  /v1/workflows/{workflowId}/test-runs:
    post:
      tags:
        - Executions API
      summary: Test a Workflow
      description: >-
        Use this endpoint to test a stored workflow in any status. It needs no
        `Idempotency-Key`. Reads run for real. A step that writes sends nothing:
        the test stops at it and shows the request it would have sent. Each wait
        passes once. The body is the same as for a manual run (`inputData` and
        an optional `triggerNodeId`), with the same 1 MB limit. A test run is
        hidden from execution lists unless the request sets `testRun=true`, and
        it expires 24 hours after it starts. A refusal creates no test run. It
        answers 404 for an unknown workflow, 422 `FLK-0515` for a missing or
        ambiguous trigger, 422 `FLK-0935` or 503 `FLK-0720` for the input
        contract, 403 `FLK-0524` under the partner rule, 403 `FLK-0519` when an
        application is outside the workflow's allowed callers, and 403
        `FLK-0365` when an application tests a workflow that uses a protected
        provider. An unquoted number that a float64 cannot keep exactly answers
        400 `FLK-0001` and names the field. Send such a number as a string.
      operationId: startTestRun
      parameters:
        - description: Unique identifier of the workflow.
          in: path
          name: workflowId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteWorkflowInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionCreateOutput'
          description: Indicates that the test run started.
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Indicates that the caller is not allowed to test this workflow.
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Indicates that the requested resource could not be found.
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Indicates that the request body is larger than the limit.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Indicates that the request could not be processed.
        '500':
          description: >-
            Indicates an unexpected internal error. If this persists, please
            contact support.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ExecuteWorkflowInput:
      properties:
        inputData:
          additionalProperties:
            type: object
          description: >-
            Input data passed to the workflow. Available to all nodes during
            execution. Maximum payload size is 1 MB.
          example:
            transactionId: txn-98765
            amount: 1500
            currency: BRL
            customerId: cust-12345
            message: Payment received
          type: object
        triggerNodeId:
          type: string
          description: >-
            Trigger node the execution starts at. Required when the workflow has
            several triggers; without it, or with a node that is not one of its
            triggers, the call answers 422 `FLK-0515`.
          example: trigger-1
      required:
        - inputData
      type: object
    ExecutionCreateOutput:
      properties:
        executionId:
          description: Unique identifier of the execution.
          example: f7e6d5c4-b3a2-1098-7654-321fedcba098
          format: uuid
          type: string
        startedAt:
          description: Timestamp when the execution started.
          example: '2026-03-17T14:35:00Z'
          format: date-time
          type: string
        status:
          description: Status of the execution.
          example: running
          type: string
        workflowId:
          description: ID of the workflow being executed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          format: uuid
          type: string
        definitionDigest:
          description: Digest of the workflow definition that the run used.
          type: string
        operationKey:
          description: >-
            Identity of the operation that the run admits, built from the
            `admission.keyFields` of the workflow. Absent without admission.
          type: string
        operationReplayed:
          description: True when the answer replays the first run of the same operation.
          type: boolean
        testRun:
          description: >-
            True for a test run: reads run for real, writes stop, and the record
            expires 24 hours after it started.
          example: true
          type: boolean
      type: object
    ErrorResponse:
      properties:
        code:
          description: Stable, machine-readable Flowker error code.
          example: FLK-0001
          type: string
        detail:
          description: >-
            Human-readable explanation of this occurrence. Responses with a
            status of 500 or above carry a fixed generic message.
          example: name is a required field
          type: string
        errors:
          description: Per-field entries for a request that failed validation.
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        instance:
          description: URI reference identifying this specific occurrence.
          example: /v1/workflows
          format: uri
          type: string
        status:
          description: HTTP status code.
          example: 400
          type: integer
        title:
          description: >-
            Standard HTTP reason phrase for the status. It does not change per
            error code.
          example: Bad Request
          type: string
        type:
          description: >-
            URI reference identifying the error. Always the error catalog base
            followed by the code.
          example: https://errors.lerian.studio/v1/FLK-0001
          format: uri
          type: string
      type: object
    ErrorDetail:
      properties:
        location:
          description: Where the problem is, such as body.nodes or path.id.
          example: body.nodes
          type: string
        message:
          description: Description of the field-level problem.
          example: expected array length >= 1
          type: string
        value:
          description: The value that caused the error, when it is safe to echo.
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT bearer token issued by the identity provider. Send it in the
        Authorization header as `Bearer <token>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.