Every API here is available over the APIs.io API and to AI agents over MCP.
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 <key>`. 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.'