API reference · v1
Workflows
Trigger published journeys, pause execution, and inspect runs and paged step history.
List workflows
GET
/v1/workflowsQuery parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "wf_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"paused": false,
"isDirty": false,
"published": false
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of workflows.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Get a workflow
GET
/v1/workflows/{id}Error: workflow_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The workflow id.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "wf_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"paused": false,
"isDirty": false,
"published": false
},
"warnings": []
}Status codes
- 200The workflow.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Trigger a workflow
POST
/v1/workflows/{id}Starts a run at a published, unpaused incoming-webhook step. The path id is that step’s reference id, not the workflow id. Send the workflow’s configured JSON input as the body. HTTP 200 with data={} confirms run creation, not workflow completion. Errors use the standard JSON error envelope: workflow_step_not_found (404), invalid_request_body (400), or a server error for an invalid configured schema. Supports Idempotency-Key. Workflow authoring, run cancellation, and retry/redrive are not exposed by this public endpoint.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The incoming-webhook step's reference id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
Per-workflow-step payload, validated against the step's JSON schema.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{}'Response
{
"data": {},
"warnings": []
}Status codes
- 200The workflow run was started.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Pause a workflow
POST
/v1/workflows/{id}/pausePauses the workflow: new triggers and further execution of existing runs are blocked. An external effect already in flight may complete. Supports Idempotency-Key. Error: workflow_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The workflow id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I/pause' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "wf_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"paused": false,
"isDirty": false,
"published": false
},
"warnings": []
}Status codes
- 200The paused workflow.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Unpause a workflow
POST
/v1/workflows/{id}/unpauseUnpauses the workflow so eligible paused work can continue. This does not publish unpublished edits or redrive terminal failed runs. Supports Idempotency-Key. Error: workflow_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The workflow id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I/unpause' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "wf_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z",
"name": "string",
"description": "string",
"paused": false,
"isDirty": false,
"published": false
},
"warnings": []
}Status codes
- 200The unpaused workflow.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
List a workflow's runs
GET
/v1/workflows/{id}/runsLists runs newest first. Each run embeds at most its latest 100 history entries, ascending within that window. Use workflows.getRun with nextHistoryBeforeIndex to read earlier history. Error: workflow_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The workflow id.
Query parameters
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I/runs' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "wfr_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2026-09-14T10:30:00.000Z",
"updatedAt": "2026-09-14T10:30:01.000Z",
"versionId": "wfv_BcwDvBUeSaSDILA5tHgpmU7I",
"status": "running",
"failureReason": null,
"stepHistory": [
{
"index": 0,
"stepId": "wfs_BcwDvBUeSaSDILA5tHgpmU7I",
"stepLabel": "Incoming webhook",
"slotKey": "next",
"enteredAt": "2026-09-14T10:30:00.000Z",
"leftAt": "2026-09-14T10:30:01.000Z",
"failureReason": null
}
],
"stepCount": 1,
"parentRunId": null,
"parentExecutionOrdinal": null,
"nextHistoryBeforeIndex": null
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of workflow runs.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Get a workflow run
GET
/v1/workflows/{id}/runs/{runId}Returns public run status and a window of at most 100 step-history records, ordered by index ascending within the returned window. The initial window contains the latest records. To read older history, pass nextHistoryBeforeIndex as history_before until it is null. status is running while a current step exists; otherwise failed if the run has a failed step, or completed. failureReason comes from the returned window and can be null even for a failed run whose failure is older. No internal step graph, handling state, or input/output data is returned. Errors: workflow_not_found, workflow_run_not_found.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The workflow id.
- Name
runId- Type
- string
- Requirement
- Required
- Description
- The workflow run id.
Query parameters
- Name
history_before- Type
- integer
- Description
- Return step-history indices strictly below this non-negative safe integer. Use the previous nextHistoryBeforeIndex; omit for the latest 100 entries.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/workflows/wf_BcwDvBUeSaSDILA5tHgpmU7I/runs/wfr_BcwDvBUeSaSDILA5tHgpmU7I' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": {
"id": "wfr_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2026-09-14T10:30:00.000Z",
"updatedAt": "2026-09-14T10:30:01.000Z",
"versionId": "wfv_BcwDvBUeSaSDILA5tHgpmU7I",
"status": "running",
"failureReason": null,
"stepHistory": [
{
"index": 0,
"stepId": "wfs_BcwDvBUeSaSDILA5tHgpmU7I",
"stepLabel": "Incoming webhook",
"slotKey": "next",
"enteredAt": "2026-09-14T10:30:00.000Z",
"leftAt": "2026-09-14T10:30:01.000Z",
"failureReason": null
}
],
"stepCount": 1,
"parentRunId": null,
"parentExecutionOrdinal": null,
"nextHistoryBeforeIndex": null
},
"warnings": []
}Status codes
- 200The workflow run.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.