openapi: 3.2.0 info: title: MindCloud Public Runs API version: 2.0.0 description: REST surface under /v2. Authenticate with a company-scoped API key sent as a bearer token. Each key holds a set of permissions; each operation lists the ones it requires as the apiKey security roles. A request may use a permission only while the user who created the key also holds it. servers: - url: https://connect.mindcloud.co security: - apiKey: [] tags: - name: Runs paths: /v2/runs/{runId}: get: operationId: v2-get-run summary: Get one workflow run, including its summary and, while running, the active step… description: 'Get one workflow run, including its summary and, while running, the active step and message. Requires the API key permission log:view.' tags: - Runs security: - apiKey: - log:view parameters: - name: runId in: path required: true schema: type: string minLength: 1 - $ref: '#/components/parameters/CompanyId' responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/RunDetail' meta: type: object description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.' required: - success - data '403': description: An Embedded end user's or installation's run cannot be used under X-Company-Id (CHILD_SCOPE_FORBIDDEN, COMPANY_SCOPE_MISMATCH). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/runs/{runId}/cancel: post: operationId: v2-cancel-run summary: Request cancellation of a run description: 'Request cancellation of a run. Cancellation is asynchronous: the runner stops at the next checkpoint and the run then reports status "cancelled". Runs that already finished are unaffected. Requires the API key permission workflow:run.' tags: - Runs security: - apiKey: - workflow:run parameters: - name: runId in: path required: true schema: type: string minLength: 1 - $ref: '#/components/parameters/CompanyId' responses: '202': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/RunCancellation' meta: type: object description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.' required: - success - data '403': description: An Embedded end user's or installation's run cannot be used under X-Company-Id (CHILD_SCOPE_FORBIDDEN, COMPANY_SCOPE_MISMATCH). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/runs/{runId}/operations: get: operationId: v2-list-run-operations summary: List record-level operations (creates, updates, errors, warnings) for one run description: 'List record-level operations (creates, updates, errors, warnings) for one run. Filter by actionStatus or operation. Each filterable field is also a query parameter: `status=active` matches it exactly, and bracket operators (eq, ne, gt, gte, lt, lte, contains, starts, ends, in, nin) compare, e.g. `createdOn[gte]=2026-01-01` or `status[in]=failed,cancelled`. contains, starts, and ends apply to text fields only. Requires the API key permission log:view.' tags: - Runs security: - apiKey: - log:view parameters: - name: runId in: path required: true schema: type: string - name: fields in: query required: false schema: type: string description: 'Comma-separated fields to return; all of them when left out, and id always. Each item then carries only those keys, whatever its schema requires. Fields: id, workflowLogId, stepId, stepInstanceId, actionId, appId, model, operation, actionStatus, primaryKey, message, createdOn.' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - name: sort in: query required: false schema: type: string description: 'Comma-separated sort fields; prefix one with - for descending. Sortable fields: id, workflowLogId, stepId, stepInstanceId, actionId, appId, model, operation, actionStatus, primaryKey, message, createdOn. Default: -createdOn.' - name: where in: query required: false schema: type: string maxLength: 2048 description: 'RSQL filter expression. Filterable fields: id, workflowLogId, stepId, stepInstanceId, actionId, appId, model, operation, actionStatus, primaryKey, message, createdOn. Operators: ==, !=, >, >=, <, <=, =in=, =out=, =like=. Logical: ; (AND), , (OR); AND binds tighter than OR. Example: "status==active;name=like=Sales*"' - name: id in: query required: false schema: type: string description: 'Filter on id: `id=value` matches it exactly. Bracket operators: `id[ne]`, `id[gt]`, `id[gte]`, `id[lt]`, `id[lte]`, `id[contains]`, `id[starts]`, `id[ends]`, and `id[in]` / `id[nin]` with comma-separated values.' - name: workflowLogId in: query required: false schema: type: string description: 'Filter on workflowLogId: `workflowLogId=value` matches it exactly. Bracket operators: `workflowLogId[ne]`, `workflowLogId[gt]`, `workflowLogId[gte]`, `workflowLogId[lt]`, `workflowLogId[lte]`, `workflowLogId[contains]`, `workflowLogId[starts]`, `workflowLogId[ends]`, and `workflowLogId[in]` / `workflowLogId[nin]` with comma-separated values.' - name: stepId in: query required: false schema: type: string description: 'Filter on stepId: `stepId=value` matches it exactly. Bracket operators: `stepId[ne]`, `stepId[gt]`, `stepId[gte]`, `stepId[lt]`, `stepId[lte]`, `stepId[contains]`, `stepId[starts]`, `stepId[ends]`, and `stepId[in]` / `stepId[nin]` with comma-separated values.' - name: stepInstanceId in: query required: false schema: type: string description: 'Filter on stepInstanceId: `stepInstanceId=value` matches it exactly. Bracket operators: `stepInstanceId[ne]`, `stepInstanceId[gt]`, `stepInstanceId[gte]`, `stepInstanceId[lt]`, `stepInstanceId[lte]`, `stepInstanceId[contains]`, `stepInstanceId[starts]`, `stepInstanceId[ends]`, and `stepInstanceId[in]` / `stepInstanceId[nin]` with comma-separated values.' - name: actionId in: query required: false schema: type: string description: 'Filter on actionId: `actionId=value` matches it exactly. Bracket operators: `actionId[ne]`, `actionId[gt]`, `actionId[gte]`, `actionId[lt]`, `actionId[lte]`, `actionId[contains]`, `actionId[starts]`, `actionId[ends]`, and `actionId[in]` / `actionId[nin]` with comma-separated values.' - name: appId in: query required: false schema: type: string description: 'Filter on appId: `appId=value` matches it exactly. Bracket operators: `appId[ne]`, `appId[gt]`, `appId[gte]`, `appId[lt]`, `appId[lte]`, `appId[contains]`, `appId[starts]`, `appId[ends]`, and `appId[in]` / `appId[nin]` with comma-separated values.' - name: model in: query required: false schema: type: string description: 'Filter on model: `model=value` matches it exactly. Bracket operators: `model[ne]`, `model[gt]`, `model[gte]`, `model[lt]`, `model[lte]`, `model[contains]`, `model[starts]`, `model[ends]`, and `model[in]` / `model[nin]` with comma-separated values.' - name: operation in: query required: false schema: type: string description: 'Filter on operation: `operation=value` matches it exactly. Bracket operators: `operation[ne]`, `operation[gt]`, `operation[gte]`, `operation[lt]`, `operation[lte]`, `operation[contains]`, `operation[starts]`, `operation[ends]`, and `operation[in]` / `operation[nin]` with comma-separated values.' - name: actionStatus in: query required: false schema: type: string description: 'Filter on actionStatus: `actionStatus=value` matches it exactly. Bracket operators: `actionStatus[ne]`, `actionStatus[gt]`, `actionStatus[gte]`, `actionStatus[lt]`, `actionStatus[lte]`, `actionStatus[contains]`, `actionStatus[starts]`, `actionStatus[ends]`, and `actionStatus[in]` / `actionStatus[nin]` with comma-separated values.' - name: primaryKey in: query required: false schema: type: string description: 'Filter on primaryKey: `primaryKey=value` matches it exactly. Bracket operators: `primaryKey[ne]`, `primaryKey[gt]`, `primaryKey[gte]`, `primaryKey[lt]`, `primaryKey[lte]`, `primaryKey[contains]`, `primaryKey[starts]`, `primaryKey[ends]`, and `primaryKey[in]` / `primaryKey[nin]` with comma-separated values.' - name: message in: query required: false schema: type: string description: 'Filter on message: `message=value` matches it exactly. Bracket operators: `message[ne]`, `message[gt]`, `message[gte]`, `message[lt]`, `message[lte]`, `message[contains]`, `message[starts]`, `message[ends]`, and `message[in]` / `message[nin]` with comma-separated values.' - name: createdOn in: query required: false schema: type: string description: 'Filter on createdOn: `createdOn=value` matches it exactly. A date or timestamp, such as 2026-10-01 or 2026-10-01T12:00:00Z. Bracket operators: `createdOn[ne]`, `createdOn[gt]`, `createdOn[gte]`, `createdOn[lt]`, `createdOn[lte]`, and `createdOn[in]` / `createdOn[nin]` with comma-separated values.' - $ref: '#/components/parameters/CompanyId' responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true data: type: array items: $ref: '#/components/schemas/RunOperation' meta: $ref: '#/components/schemas/ListMeta' required: - success - data - meta default: description: Error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/runs/{runId}/steps: get: operationId: v2-list-run-steps summary: List the executed steps of one run as a flat index (no payloads) description: 'List the executed steps of one run as a flat index (no payloads). Fetch a single step for its full request and response. Requires the API key permission log:view.' tags: - Runs security: - apiKey: - log:view parameters: - name: runId in: path required: true schema: type: string minLength: 1 - $ref: '#/components/parameters/CompanyId' responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true data: type: array items: $ref: '#/components/schemas/RunStep' meta: type: object description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.' required: - success - data default: description: Error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /v2/runs/{runId}/steps/{stepInstanceId}: get: operationId: v2-get-run-step summary: Get one executed step of a run, including its full request and response payloads description: 'Get one executed step of a run, including its full request and response payloads. Requires the API key permission log:view.' tags: - Runs security: - apiKey: - log:view parameters: - name: runId in: path required: true schema: type: string minLength: 1 - name: stepInstanceId in: path required: true schema: type: string minLength: 1 - $ref: '#/components/parameters/CompanyId' responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/RunStepDetail' meta: type: object description: 'Response metadata, on endpoints that answer it: the usage window, a step count, or the provider paging of a Universal action run.' required: - success - data '403': description: An Embedded end user's or installation's run cannot be used under X-Company-Id (CHILD_SCOPE_FORBIDDEN, COMPANY_SCOPE_MISMATCH). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: RunDetail: type: object properties: id: type: - string - 'null' description: Unique id of the run. workflowId: type: - string - 'null' description: The workflow this run belongs to. status: type: - string - 'null' description: 'Where the run stands or how it ended: waiting, running, finished, failed, cancelled, interrupted, limitExceeded, or cancelling.' version: type: - string - 'null' description: The workflow version that ran, or "draft". environmentId: type: - string - 'null' description: The environment the run targeted. environmentName: type: - string - 'null' description: That environment's name. startedOn: type: - string - 'null' format: date-time description: When the run started. finishedOn: type: - string - 'null' format: date-time description: When the run finished. Empty while it is still going. durationMs: type: - number - 'null' description: How long the run took, in milliseconds. operations: type: - integer - 'null' description: How many tasks the run used. This is the number that counts against your limit. errorCount: type: - integer - 'null' description: How many errors the run logged. warningCount: type: - integer - 'null' description: How many warnings the run logged. infoCount: type: - integer - 'null' description: How many info entries the run logged. endUserId: type: - string - 'null' description: The embedded end user the run belongs to, if any. installationId: type: - string - 'null' description: The embedded installation the run belongs to, if any. triggerAppSlug: type: - string - 'null' description: The app that triggered the run. summary: type: - string - 'null' description: A short summary of what the run did. activeStepId: type: - string - 'null' description: The step the run is on right now, while running. activeMessage: type: - string - 'null' description: What the run is doing right now, while running. required: - id - workflowId - status - version - environmentId - environmentName - startedOn - finishedOn - durationMs - operations - errorCount - warningCount - infoCount - endUserId - installationId - triggerAppSlug - summary - activeStepId - activeMessage RunCancellation: type: object properties: id: type: string description: The run that was asked to stop. status: type: - string - 'null' description: The run status when the cancellation was requested. The run reports "cancelled" once it stops. required: - id - status ListMeta: type: object properties: pagination: type: object properties: totalCount: type: integer description: Matching records. A list read in SQL stops counting at 10000. totalCountExact: type: boolean description: False when totalCount stopped at that cap. hasNextPage: type: boolean description: True when another page follows. Page with this, not totalCount. hasPreviousPage: type: boolean required: - totalCount - totalCountExact - hasNextPage - hasPreviousPage required: - pagination ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string description: 'Fixed by the status: 400 VALIDATION_FAILED, 401 UNAUTHORIZED, 403 FORBIDDEN, 404 NOT_FOUND, 409 CONFLICT, 410 GONE, 413 PAYLOAD_TOO_LARGE, 421 and 503 UNAVAILABLE, 429 RATE_LIMITED, 500 INTERNAL_ERROR, 502 PROVIDER_ERROR.' examples: - VALIDATION_FAILED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - PAYLOAD_TOO_LARGE - RATE_LIMITED - INTERNAL_ERROR - PROVIDER_ERROR - UNAVAILABLE message: type: string details: type: object description: The specific cause (reason) and any evidence for it. Absent when the code says everything. properties: reason: type: string description: The specific cause, for example UNKNOWN_FILTER_FIELD or CONNECTION_IN_USE. field: type: string description: The parameter, filter, sort, or body field a 400 refused. accepted: type: array items: {} description: 'What a 400 would have accepted instead: parameter names, field names, or enum values.' provider: type: object description: 'On 502 PROVIDER_ERROR: the provider answer that failed.' properties: status: type: integer description: The provider's HTTP status. code: type: string description: The provider's own error code, when it sends one. required: - code - message required: - success - error RunStepDetail: type: object properties: stepInstanceId: type: - string - 'null' description: Unique id of this step execution. stepId: type: - string - 'null' description: The step in the workflow definition. actionId: type: - string - 'null' description: The action the step ran. success: type: - boolean - 'null' description: True if the step succeeded. ran: type: - boolean - 'null' description: True if the step actually executed. request: description: The exact data the step received. Its shape depends on the action. response: description: The exact data the step returned. Its shape depends on the action and the provider. required: - stepInstanceId - stepId - actionId - success - ran - request - response RunOperation: type: object properties: id: type: - string - 'null' description: Unique id of the operation. workflowLogId: type: - string - 'null' description: The run this operation happened in. stepId: type: - string - 'null' description: The workflow step that performed it. stepInstanceId: type: - string - 'null' description: The exact step execution that performed it. actionId: type: - string - 'null' description: The action that ran. appId: type: - string - 'null' description: The app that action belongs to. model: type: - string - 'null' description: The kind of record that was touched. operation: type: - string - 'null' description: 'What happened to the record: create, update, and so on.' actionStatus: type: - string - 'null' description: How it went, for example error. primaryKey: type: - string - 'null' description: The touched record's primary key in the target system. message: type: - string - 'null' description: What the platform logged about it. createdOn: type: - string - 'null' format: date-time description: When it happened. required: - id - workflowLogId - stepId - stepInstanceId - actionId - appId - model - operation - actionStatus - primaryKey - message - createdOn RunStep: type: object properties: stepInstanceId: type: - string - 'null' description: Unique id of this step execution. Use it to fetch the step's payloads with Get a Run Step. stepId: type: - string - 'null' description: The step in the workflow definition. actionId: type: - string - 'null' description: The action the step ran. success: type: - boolean - 'null' description: True if the step succeeded. ran: type: - boolean - 'null' description: True if the step actually executed. path: type: - string - 'null' description: Where the step sits inside loops and branches. required: - stepInstanceId - stepId - actionId - success - ran - path parameters: offset: name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of results to skip for pagination (default 0). limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum number of results to return (1-1000, default 100). CompanyId: name: X-Company-Id in: header required: false schema: type: string example: K3vX9qLm2RtA description: Optional. The id of a child organization of your API key's company to act on. Leave it out to act on the key's own company. See [Child organizations](https://mindcloud.co/docs/api/rest/introduction/child-organizations). securitySchemes: apiKey: type: http scheme: bearer description: 'Company-scoped MindCloud API key sent as `Authorization: Bearer `. Each key holds permissions from the MindCloud roles catalog (workflow:view, workflow:run, universal:read, api_key:manage, ...), chosen when it is created; each operation lists the ones it requires as this scheme''s roles. A request may use a permission only while the user who created the key still holds it in the company the request acts on; a missing one answers 403 with details.reason API_KEY_PERMISSION_DENIED and details.required, and a key whose creator left the organization answers API_KEY_CREATOR_INACTIVE. The key''s accessLevel (full_access, run_workflows, read_only, or none) summarizes its permissions. Create a key at https://app.mindcloud.co/user/api-keys.'