List workflows
GET
/v1/workflow-builder/data-workflows
GET / needs workflowBuilder.What this endpoint does
Quick start
page=1, limit=20, no status filter).Authentication and permission
Authorization: Bearer <API_KEY> with workflowBuilder. The community comes from the key, so the list never spans communities and there is no community parameter to get wrong.| Failure | Meaning | Recovery |
|---|---|---|
401 AUTHENTICATION_REQUIRED | No key, or an unknown key | Send a valid key. |
401 API_KEY_REQUIRED | A valid admin session was used | Use a community API key. |
403 API_KEY_PERMISSION_DENIED | The key authenticated without workflowBuilder | Grant the permission. |
Complete examples
{
"data": [
{
"_id": "65f1a2b3c4d5e6f708192a3b",
"communityId": "65f1a2b3c4d5e6f708192a50",
"name": "VIP bonus",
"status": "deployed",
"outgoingWebhookUrl": null,
"createdAt": "2026-10-24T09:15:00.000Z",
"updatedAt": "2026-10-24T09:20:11.000Z",
"trigger": { "_id": "65f1a2b3c4d5e6f708192a41", "name": "Trade bonus trigger", "type": "webhook", "status": "idle", "options": { "tokenExchangeEnabled": false, "apiKey": { "enabled": true, "value": ["__REDACTED__"] } } },
"nodes": [],
"revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
"redactedPaths": ["trigger.options.apiKey.value"]
}
],
"meta": { "page": 2, "limit": 10, "total": 11, "totalPages": 2 }
}{
"data": [],
"meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}Success and readback
200 with data (an array) and meta (page, limit, total, totalPages). Each item carries the same fields as GET /{workflowId}, including its revision, so a list read can be the read half of a later write. The list is the readback that proves a rename, a copy or a delete: re-read it after the mutation and match by _id.totalPages is 0 when nothing matches. Rows are ordered newest first by creation time, with the identifier as a tie-break, so a page can only repeat or skip a row if a workflow is created between two calls.Errors and recovery
| Status and code | When | Recovery |
|---|---|---|
400 VALIDATION_FAILED | limit above 100, a non-numeric page, or an unknown status value. errors[].path names the query field | Fix the query value. |
401 AUTHENTICATION_REQUIRED | No key, or an unknown key | Send a valid key. |
403 API_KEY_PERMISSION_DENIED | No workflowBuilder | Grant the permission. |
429 RATE_LIMITED | The community's API rate limit was reached | Wait for the window to reset, then retry. |
500 INTERNAL_ERROR | Unexpected failure | Retry with bounded backoff. |
Retry safety
page from 1 and stop when page > meta.totalPages; a page beyond the last one returns data: [].Gotchas
limit, then GET /{workflowId} for the one workflow you need.status filters exactly one state. To see both drafts and deployed workflows, call twice or omit the filter.trigger: null. That is not a broken row.meta.total is the number of workflows matching the filter, not the number in this page.apiKey.value of ["__REDACTED__"] means a key is stored, not that the key is unset.Next steps
GET /{workflowId} for one workflow with the revision to write against.POST /{workflowId}/duplicate to copy a workflow before editing it.POST /{workflowId}/validate for the advisory check before deploying.Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/workflow-builder/data-workflows?page=1&limit=20&status=deployed' \
--header 'Authorization: Bearer <API_KEY>'Response Response Example
200 - 200 Success
{
"data": [
{
"_id": "65f1a2b3c4d5e6f708192a3b",
"communityId": "65f1a2b3c4d5e6f708192a50",
"name": "VIP bonus",
"status": "draft",
"outgoingWebhookUrl": null,
"createdAt": "2026-10-24T09:15:00.000Z",
"updatedAt": "2026-10-24T09:20:11.000Z",
"trigger": {
"_id": "65f1a2b3c4d5e6f708192a41",
"name": "Trade bonus trigger",
"type": "webhook",
"status": "idle",
"options": {
"tokenExchangeEnabled": false,
"apiKey": {
"enabled": false
},
"aesKey": {
"enabled": false
}
}
},
"nodes": [
{
"_id": "65f1a2b3c4d5e6f708192a3c",
"name": "Read member XP",
"type": "platform-action",
"order": 1,
"continueOnFailure": false,
"retryOnFailure": false,
"options": {
"action": "get-user-fields",
"selectUser": {
"type": "email",
"value": [
"{{65f1a2b3c4d5e6f708192a41.email}}"
]
},
"fields": [
{
"label": "Total XP",
"field": "total_xp"
}
]
}
}
],
"revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
"redactedPaths": []
},
{
"_id": "65f1a2b3c4d5e6f708192a42",
"communityId": "65f1a2b3c4d5e6f708192a50",
"name": "Trade bonus",
"status": "deployed",
"outgoingWebhookUrl": null,
"createdAt": "2026-10-24T09:15:00.000Z",
"updatedAt": "2026-10-24T09:20:11.000Z",
"trigger": null,
"nodes": [],
"revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
"redactedPaths": []
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 2,
"totalPages": 1
}
}Modified at 2026-10-28 04:45:11