Shape your requests

The standard list endpoints share one query grammar: workflows, workflow runs, run operations, connections, members, roles, companies, environments, and API keys. Learn it once and it applies to all of them.

Some lists work differently, and their pages say so:

• Universal API app and action discovery take q, fields, limit (1 to 100, default 20), and offset.
• Embedded end-user connections take limit (1 to 100, default 20) and offset.
• Workflow versions, run steps, and the usage endpoints return their full result without pagination.

Pagination

Use limit and offset. limit defaults to 100 and accepts 1 to 1000; a value outside that range falls back to 100. The response meta.pagination describes where you are:

{
  "meta": {
    "pagination": { "totalCount": 312, "totalCountExact": true, "hasNextPage": true, "hasPreviousPage": true }
  }
}

Page with hasNextPage. totalCount is for display: counting stops at 10,000 rows, and past that totalCount reads 10000 with totalCountExact set to false.

curl "https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/runs?limit=50&offset=100" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Lists have a stable default order, so pages stay consistent without passing sort. Members are the exception: pass sort when you page through them.

Sorting

Pass sort with one or more comma-separated fields. Prefix a field with - for descending:

curl "https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/runs?sort=-startedOn" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Field selection

Pass fields to receive only the columns you need. id is always included:

curl "https://connect.mindcloud.co/v2/workflows?fields=id,name,isActive" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Filtering

Any exposed field filters with plain equality or a bracket operator:

# Equality
curl "https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/runs?status=failed" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

# Operators
curl "https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/runs?startedOn[gte]=2026-07-01&status[in]=failed,interrupted" \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Use only the field names listed on each endpoint's page. A filter, sort, or field selection on a name the endpoint does not expose is currently ignored rather than rejected, so a misspelled filter returns unfiltered results.

Advanced filters

For OR conditions and grouping, pass an RSQL expression in where:

curl "https://connect.mindcloud.co/v2/workflows/Wq3kZ8pLx2Nb/runs" \
  --data-urlencode "where=(status==failed,status==interrupted);startedOn>=2026-07-01" -G \
  -H "Authorization: Bearer $MINDCLOUD_API_KEY"

Always group mixed AND and OR conditions with parentheses. where expressions are limited to 2,048 characters and combine with bracket filters using AND.

Rate limits

Each API key gets 240 read requests (GET) and 60 write requests (POST, PUT, PATCH, DELETE) per minute, in separate budgets. Every response reports where you stand:

Past the limit, requests return 429 with code RATE_LIMITED and a Retry-After header with the seconds to wait. Back off until then; the budget refills at the reset time.

Errors

Invalid parameters return 400 with code INVALID_QUERY. Missing resources return 404 with code NOT_FOUND. A key without the access level an endpoint needs returns 403 with code API_KEY_ACCESS_DENIED. A write that conflicts with the resource's state returns 409 with a specific code, like WORKFLOW_NOT_PUBLISHED when you run a workflow that was never published, or CONNECTION_IN_USE when active workflows still use a connection you asked to delete. Errors use this envelope:

{
  "success": false,
  "error": { "code": "INVALID_QUERY", "message": "Invalid filter \"startedOn[foo]\"" }
}

Run step reads can also return 409 RUN_OUTPUT_UNAVAILABLE when the final log upload is still pending or failed. A finished execution does not guarantee that its final step output is available.

An invalid, missing, or revoked API key returns 401 with { "success": false, "message": "..." } and no error object.