{"openapi":"3.1.0","info":{"title":"Manifestly API v2","version":"v2","description":"Manifestly API v2 for workflow management. Manage workflows, runs, and steps programmatically. See the [API v2 changelog](/api/v2/changelog) for recent changes. Optional client header: X-Client (e.g., chatgpt) for observability.","contact":{"url":"https://www.manifest.ly/contact","name":"Manifestly Support"},"license":{"name":"Terms of Service","url":"https://www.manifest.ly/tos"}},"paths":{"/assignments":{"get":{"summary":"List assignments for current user","tags":["Assignments"],"operationId":"listAssignments","description":"Returns the actionable run-steps assigned to the access-token user.","parameters":[{"name":"user_id","in":"query","schema":{"type":"integer"},"description":"ID of user whose assignments to retrieve (admins only; defaults to current user)"},{"name":"state","in":"query","schema":{"type":"string","enum":["overdue","upcoming","with_due_date","without_due_date"]},"description":"Status filter"},{"name":"sort","in":"query","schema":{"type":"string","enum":["due_asc","due_desc"],"default":"due_asc"},"description":"Sort assignments by due date. Null due dates are always last. Default: due_asc."},{"name":"workflow_id","in":"query","schema":{"type":"integer"},"description":"Filter by workflow"},{"name":"department_id","in":"query","schema":{"type":"integer"},"description":"Filter by department"},{"name":"run_id","in":"query","schema":{"type":"integer"},"description":"Filter by run"},{"name":"due_before","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO8601 upper bound for due date"},{"name":"due_after","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO8601 lower bound for due date"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search step or run title"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page index"},{"name":"per_page","in":"query","schema":{"type":"integer"},"description":"Items per page (1-100)"},{"name":"include_completed","in":"query","schema":{"type":"boolean"},"description":"Include completed assignments (default: false)"}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"assignments":[{"id":10,"title":"Collect ID badge","header_step":false,"due_at":"2024-07-12T09:00:00Z","run":{"id":101,"title":"Jane Doe","workflow_title":"Onboard New Employee","workflow_id":42},"assignees":[{"user_id":12,"email":"user@example.com"}],"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/101/run_steps/10","method":"GET"},{"rel":"complete","href":"https://api.example.com/api/v2/runs/101/run_steps/10","method":"POST","body":{"action":"complete"}}]}],"meta":{"current_page":1,"per_page":20,"total_count":1,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}}}}},"400":{"description":"invalid date filter"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/data_tables":{"get":{"summary":"List data tables","tags":["Data Tables"],"operationId":"listDataTables","description":"Returns Data Tables visible to the current user within the current master account. Requires the `data_tables` feature.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"403":{"description":"feature not available"}}},"post":{"summary":"Create a data table","tags":["Data Tables"],"operationId":"createDataTable","description":"Create a new Data Table. `account_id` must be a department the caller admins (master admins may also pass the master account ID to create a table shared across departments).","parameters":[],"responses":{"201":{"description":"created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data_table":{"type":"object","properties":{"name":{"type":"string","description":"Display name (max 100 chars)"},"account_id":{"type":"integer","description":"Owning department (account) ID"}},"required":["name","account_id"]}},"required":["data_table"]}}},"required":true},"x-required-scopes":["write"]}},"/data_tables/{id}":{"get":{"tags":["Data Tables"],"summary":"Get a data table","operationId":"getDataTable","parameters":[{"name":"id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"404":{"description":"not found"}}},"patch":{"tags":["Data Tables"],"summary":"Update a data table","description":"Rename a Data Table. Note: changing column structure happens via the columns endpoints.","operationId":"updateDataTable","parameters":[{"name":"id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data_table":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}},"required":["data_table"]}}},"required":true},"x-required-scopes":["write"]},"delete":{"tags":["Data Tables"],"summary":"Delete a data table","description":"Soft-deletes the Data Table. Returns 409 if the table is referenced by a step data setting (see `in_use` on the table response).","operationId":"deleteDataTable","parameters":[{"name":"id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"deleted"},"409":{"description":"in use"}},"x-required-scopes":["write"]}},"/data_tables/{data_table_id}/columns":{"get":{"tags":["Data Tables"],"summary":"List columns","operationId":"listDataTableColumns","parameters":[{"name":"data_table_id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}}},"post":{"tags":["Data Tables"],"summary":"Create a column","description":"Adds a column to the data table. Deleting a column cascades to all of its cells (`dependent: :destroy` on the underlying association).","operationId":"createDataTableColumn","parameters":[{"name":"data_table_id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"column":{"type":"object","properties":{"name":{"type":"string"},"column_type":{"type":"string","enum":["text","number","date","boolean","email","url"]},"internal_key":{"type":"string","description":"Optional — auto-derived from the name if omitted.","nullable":true},"position":{"type":"integer","description":"Optional — defaults to the next available slot.","nullable":true}},"required":["name","column_type"]}},"required":["column"]}}},"required":true},"x-required-scopes":["write"]}},"/data_tables/{data_table_id}/columns/reorder":{"patch":{"tags":["Data Tables"],"summary":"Reorder columns","description":"Reorders columns by accepting an ordered list of column IDs. Column position values are updated to match the supplied order.","operationId":"reorderDataTableColumns","parameters":[{"name":"data_table_id","in":"path","description":"Data table ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"column_ids":{"type":"array","items":{"type":"integer"}}},"required":["column_ids"]}}},"required":true},"x-required-scopes":["write"]}},"/data_tables/{data_table_id}/columns/{id}":{"patch":{"tags":["Data Tables"],"summary":"Update a column","operationId":"updateDataTableColumn","parameters":[{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"column":{"type":"object","properties":{"name":{"type":"string"},"column_type":{"type":"string","enum":["text","number","date","boolean","email","url"]},"position":{"type":"integer"}}}},"required":["column"]}}},"required":true},"x-required-scopes":["write"]},"delete":{"tags":["Data Tables"],"summary":"Delete a column","description":"Soft-deletes the column. All cells belonging to this column are removed via `dependent: :destroy`.","operationId":"deleteDataTableColumn","parameters":[{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"deleted"}},"x-required-scopes":["write"]}},"/data_tables/{data_table_id}/rows":{"get":{"tags":["Data Tables"],"summary":"List rows","operationId":"listDataTableRows","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}}},"post":{"tags":["Data Tables"],"summary":"Create a row","description":"Creates a row and its cells in a single transaction. Cells are keyed by the column `internal_key`. Unknown keys are silently ignored (whitelisted against the table's actual columns).","operationId":"createDataTableRow","parameters":[{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cells":{"type":"object","description":"Cell values keyed by the column `internal_key`.","additionalProperties":{"type":"string","nullable":true}}}}}},"required":true},"x-required-scopes":["write"]}},"/data_tables/{data_table_id}/rows/{id}":{"patch":{"tags":["Data Tables"],"summary":"Update a row","description":"Patches cell values on an existing row. Unspecified cells are left unchanged. Unknown keys are silently ignored.","operationId":"updateDataTableRow","parameters":[{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cells":{"type":"object","additionalProperties":{"type":"string","nullable":true}}},"required":["cells"]}}},"required":true},"x-required-scopes":["write"]},"delete":{"tags":["Data Tables"],"summary":"Delete a row","operationId":"deleteDataTableRow","parameters":[{"name":"data_table_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"deleted"}},"x-required-scopes":["write"]}},"/departments":{"get":{"summary":"list departments","tags":["Departments"],"description":"List departments accessible to the authenticated token. Supports search \u0026 pagination.","operationId":"listDepartments","parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","schema":{"type":"integer"}},{"name":"search","in":"query","description":"Search term (case-insensitive)","schema":{"type":"string"}}],"responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/departments/{id}":{"get":{"tags":["Departments"],"summary":"show department","description":"Retrieve a single department by ID, including its members.","operationId":"getDepartment","parameters":[{"name":"id","in":"path","description":"Department ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"department":{"id":3,"name":"Engineering","members":[{"id":42,"email":"alice@example.com","name":"Alice","role":"admin"},{"id":57,"email":"bob@example.com","name":"Bob","role":"user"}]}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/logout":{"post":{"summary":"logout","tags":["Authentication"],"description":"Logout and revoke the current OAuth access token","operationId":"logout","responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"message":"Successfully logged out"}}},"schema":{"$ref":"#/components/schemas/LogoutResponse"}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/run_steps/{run_step_id}/comments":{"get":{"tags":["Run Step Comments"],"summary":"list run step comments","description":"Retrieve all comments for a given run step.","operationId":"listRunStepComments","parameters":[{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"schema":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}},"required":["comments"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Run Step Comments"],"summary":"create run step comment","description":"Create a new comment on the specified run step.","operationId":"createRunStepComment","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"created":{"value":{"comment":{"id":1,"comment_with_links":"Great work","created_at":"2024-07-10T12:00:00Z","user":{"id":12,"name":"Alex"}},"message":"Comment created successfully"}}}}}},"422":{"description":"validation error","content":{"application/json":{"examples":{"invalid":{"value":{"error":"Validation failed","errors":{"comment":["can't be blank"]}}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"comment":{"type":"object","properties":{"comment":{"type":"string"}},"required":["comment"]}},"required":["comment"]},"examples":{"basic":{"summary":"Add a comment","value":{"comment":{"comment":"Verified with the vendor — all good."}}}}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/run_steps/{run_step_id}/fields":{"get":{"tags":["Fields"],"summary":"list data fields for a run step","description":"Returns data collection field definitions and current values for a run step. For header steps, returns fields across all substeps. For non-header steps, returns all fields on that step. Use PUT /fields/{id} to update a specific field.","operationId":"listRunStepFields","parameters":[{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID (header or individual step)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful — non-header step with data setting","content":{"application/json":{"examples":{"header_with_fields":{"value":{"run_step":{"id":501,"title":"Employee Details","header_step":true},"fields":[{"field_id":101,"label":"Employee Name","value_format":"text","required":true,"config":null,"value":null,"run_step_id":502},{"field_id":102,"label":"Role","value_format":"list","required":true,"config":{"values":["Engineer","Designer","PM"],"value_selection_type":"single"},"value":null,"run_step_id":503}],"summary":{"total":2,"filled":0,"empty":2}}},"single_step_with_data":{"value":{"run_step":{"id":502,"title":"Serial Number","header_step":false},"fields":[{"field_id":101,"label":"Serial Number","value_format":"text","required":false,"config":null,"value":"SN-001","run_step_id":502}],"summary":{"total":1,"filled":1,"empty":0}}},"multi_field_step":{"value":{"run_step":{"id":503,"title":"Employee Info","header_step":false},"fields":[{"field_id":201,"label":"Full Name","value_format":"text","required":true,"config":null,"value":"Jane Doe","run_step_id":503},{"field_id":202,"label":"Email","value_format":"email","required":true,"config":null,"value":"jane@example.com","run_step_id":503},{"field_id":203,"label":"Department","value_format":"list","required":false,"config":{"values":["Engineering","Design","PM"],"value_selection_type":"single"},"value":null,"run_step_id":503}],"summary":{"total":3,"filled":2,"empty":1}}}},"schema":{"type":"object","properties":{"run_step":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"header_step":{"type":"boolean"}},"required":["id","title","header_step"]},"fields":{"type":"array","items":{"type":"object","properties":{"field_id":{"type":"integer","description":"Canonical v2 identifier for this data field"},"label":{"type":"string","description":"Human-readable label for the field"},"value_format":{"type":"string","enum":["text","paragraph","date","datetime","email","phone","list","number","file","image","signature","url"]},"required":{"type":"boolean"},"config":{"type":"object","nullable":true,"description":"Format-specific config (e.g. list values, selection type)"},"value":{"type":"string","nullable":true,"description":"Current data value"},"run_step_id":{"type":"integer","description":"Run step ID (contextual reference)"}},"required":["field_id","label","value_format","required","config","value","run_step_id"]}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"filled":{"type":"integer"},"empty":{"type":"integer"}},"required":["total","filled","empty"]}},"required":["run_step","fields","summary"]}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Fields"],"summary":"batch set field data","description":"Batch-set data on run step fields by field_id. For header steps, field_ids may span substeps. Fields are auto-completed after data is saved. Returns per-field results with run progress. Use PUT /fields/{id} to update a single field instead.","operationId":"batchSetRunStepFields","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID (header or individual step)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"batch_success":{"value":{"results":[{"field_id":101,"label":"Employee Name","value":"Jane Doe","status":"ok"},{"field_id":102,"label":"Role","value":"Engineer","status":"ok"}],"summary":{"total":2,"filled":2,"empty":0},"progress":{"total":7,"completed":4,"percentage":57}}},"partial_failure":{"value":{"results":[{"field_id":101,"label":"Employee Name","value":"Jane Doe","status":"ok"},{"field_id":102,"label":"Role","value":"InvalidRole","status":"error","error":"Data is not included in the list"}],"summary":{"total":2,"filled":1,"empty":1},"progress":{"total":7,"completed":3,"percentage":43}}}},"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"field_id":{"type":"integer"},"label":{"type":"string","nullable":true},"value":{"type":"string"},"status":{"type":"string","enum":["ok","error"]},"error":{"type":"string","description":"Error message (only when status=error)"}},"required":["field_id","value","status"]}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"filled":{"type":"integer"},"empty":{"type":"integer"}},"required":["total","filled","empty"]},"progress":{"type":"object","properties":{"total":{"type":"integer","description":"Total completable steps in the run"},"completed":{"type":"integer","description":"Completed steps in the run"},"percentage":{"type":"integer","description":"Completion percentage (0-100)"}},"required":["total","completed","percentage"]}},"required":["results","summary","progress"]}}}},"400":{"description":"bad request — missing or invalid data parameter","content":{"application/json":{"examples":{"bad_request":{"value":{"error":"Invalid request","message":"Parameter fields must be a non-empty array of { field_id, value } objects"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"field_id":{"type":"integer","description":"Target data field ID"},"value":{"type":"string","description":"Data value to set"}},"required":["field_id","value"]}}},"required":["fields"]},"examples":{"batch_fields":{"summary":"Set data on multiple fields","value":{"fields":[{"field_id":101,"value":"Jane Doe"},{"field_id":102,"value":"Engineer"}]}}}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/run_steps/{run_step_id}/fields/{id}":{"get":{"tags":["Fields"],"summary":"get a single field","description":"Returns a single data collection field definition and its current value. The field ID is the run_step_data_setting ID, obtainable from GET /fields.","operationId":"getRunStepField","parameters":[{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Field ID (run_step_data_setting ID)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"single_field":{"value":{"field":{"field_id":101,"label":"Full Name","value_format":"text","required":true,"config":null,"value":null,"run_step_id":502}}}},"schema":{"type":"object","properties":{"field":{"type":"object","properties":{"field_id":{"type":"integer"},"label":{"type":"string"},"value_format":{"type":"string"},"required":{"type":"boolean"},"config":{"type":"object","nullable":true},"value":{"type":"string","nullable":true},"run_step_id":{"type":"integer"}},"required":["field_id","label","value_format","required","value","run_step_id"]}},"required":["field"]}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Fields"],"summary":"update a single field value","description":"Set the value for a specific data collection field on a run step. When all required fields have values, the step is auto-completed. Clearing a required value auto-uncompletes the step.","operationId":"updateRunStepField","parameters":[{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"run_step_id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Field ID (run_step_data_setting ID)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"update_single_field":{"value":{"field":{"field_id":101,"label":"Full Name","value_format":"text","required":true,"config":null,"value":"Jane Doe","run_step_id":502},"run_step":{"id":502,"title":"Employee Name","header_step":false,"completed_at":null},"message":"Field updated successfully"}},"update_triggers_auto_complete":{"value":{"field":{"field_id":202,"label":"Email","value_format":"email","required":true,"config":null,"value":"jane@example.com","run_step_id":503},"run_step":{"id":503,"title":"Employee Info","header_step":false,"completed_at":"2026-04-14T12:00:00Z","data":"Jane Doe"},"message":"Field updated successfully"}}},"schema":{"type":"object","properties":{"field":{"type":"object","properties":{"field_id":{"type":"integer"},"label":{"type":"string"},"value_format":{"type":"string"},"required":{"type":"boolean"},"config":{"type":"object","nullable":true},"value":{"type":"string","nullable":true},"run_step_id":{"type":"integer"}},"required":["field_id","label","value_format","required","value","run_step_id"]},"run_step":{"type":"object"},"message":{"type":"string"}},"required":["field","run_step","message"]}}}},"400":{"description":"missing value parameter","content":{"application/json":{"examples":{"missing_value":{"value":{"error":"Missing required parameter","message":"Parameter value is required"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","description":"Data value to set"}},"required":["value"]}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/steps/{step_id}":{"get":{"tags":["Run Steps"],"summary":"show run step (by step_id)","description":"Retrieve a run step by the original workflow step_id.","operationId":"getRunStepByStepId","parameters":[{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"step_id","in":"path","description":"Workflow step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[]}}}},"schema":{"type":"object","properties":{"run_step":{"$ref":"#/components/schemas/RunStep"}},"required":["run_step"]}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"not visible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/runs/{run_id}/run_steps":{"get":{"tags":["Run Steps"],"summary":"list run steps","description":"List live run steps as a standalone resource with filtering, pagination, and optional hierarchy mode.","operationId":"listRunSteps","parameters":[{"name":"mode","in":"query","enum":["flat","hierarchy"],"description":"Response mode: flat (default) or hierarchy:\n * `flat` \n * `hierarchy` \n ","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","enum":["completed","not_completed"],"description":"Filter by completion status","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","enum":["all","sections"],"description":"Filter: all (default) or sections only","required":false,"schema":{"type":"string"}},{"name":"parent_run_step_id","in":"query","description":"Scope to steps under a specific section header","required":false,"schema":{"type":"integer"}},{"name":"step_id","in":"query","description":"Find run step(s) for a specific workflow step definition","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","required":false,"schema":{"type":"integer"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"run_steps":[{"id":1,"title":"Step 1","header_step":false,"completed_at":null},{"id":2,"title":"Step 2","header_step":false,"completed_at":"2024-07-10T12:00:00Z"}],"meta":{"current_page":1,"per_page":25,"total_count":2,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}},"schema":{"type":"object","properties":{"run_steps":{"type":"array","items":{"$ref":"#/components/schemas/RunStep"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["run_steps","meta"]}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Run Steps"],"summary":"create run step","description":"Add a new run step to an *ad-hoc* run.","operationId":"createRunStep","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}}],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"created":{"value":{"run_step":{"id":99,"title":"New Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/123/run_steps/99","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/123","method":"GET"}]}}}}}}},"400":{"description":"bad request","content":{"application/json":{"examples":{"bad_request":{"value":{"error":"Missing required parameter","message":"Parameter title is required"}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"examples":{"unprocessable":{"value":{"error":"Failed to create run step","message":"Parent can't have a parent"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"Whether this is a section header"},"after_step_id":{"type":"integer","description":"Insert after this step ID"},"parent_run_step_id":{"type":"integer","description":"Parent header step ID for sub-steps"},"position":{"type":"integer","description":"Explicit position (overrides automatic calculation)"},"assigned_to_membership_id":{"type":"integer","description":"Membership assignment"},"due_at":{"type":"string","format":"date_time","description":"Due-at ISO8601 datetime. Preferred over late_at."},"late_at":{"type":"string","format":"date_time","description":"Due-at ISO8601 datetime (deprecated, use due_at)","deprecated":true}},"required":["title"]},"examples":{"basic":{"summary":"Add a simple step","value":{"title":"Verify serial number","header_step":false}},"header":{"summary":"Add a section header","value":{"title":"Pre-departure checks","header_step":true}},"substep":{"summary":"Insert a substep after a specific step","value":{"title":"Order equipment","parent_run_step_id":501,"after_step_id":502}}}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/run_steps/{id}":{"post":{"tags":["Run Steps"],"summary":"change run step state","description":"Change a run-step state using the `action` request body parameter.","operationId":"changeRunStepState","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"data updated","content":{"application/json":{"examples":{"successful":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":"2024-07-10T12:00:00Z","content":[{"type":"text","value":"Review the client's submitted documents..."},{"type":"image","url":"https://example.s3.amazonaws.com/image.png"},{"type":"file","url":"https://example.s3.amazonaws.com/file.pdf","filename":"checklist.pdf"},{"type":"video","url":"https://vimeo.com/123456789"}],"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step completed successfully"}},"uncomplete_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step uncompleted successfully"}},"reset_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step reset successfully"}},"skip_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step skipped successfully"}},"unskip_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step unskipped successfully"}},"data_updated":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"data_collection":{"enabled":true,"label":"Serial Number","value_format":"text","required":false},"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step data updated successfully"}},"start_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step started successfully"}},"stop_success":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step stopped successfully"}},"data_updated_real":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null,"data_collection":{"enabled":true,"label":"Serial Number","value_format":"text","required":false},"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/45/run_steps/1","method":"GET"},{"rel":"run","href":"https://api.example.com/api/v2/runs/45","method":"GET"}]},"message":"Run step data updated successfully"}}}}}},"400":{"description":"bad request — clear_data with non-uncomplete action","content":{"application/json":{"examples":{"bad_request":{"value":{"error":"Invalid action","message":"Action must be one of complete, uncomplete, skip, unskip, start, stop, or data"}},"clear_data_invalid":{"value":{"error":"Invalid parameter","message":"clear_data is only valid with action uncomplete"}}}}}},"403":{"description":"forbidden","content":{"application/json":{"examples":{"forbidden":{"value":{"error":"Access denied","message":"You are not authorized to perform this action"}}}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}}}}},"422":{"description":"data on multi-field step","content":{"application/json":{"examples":{"data_no_setting":{"value":{"error":"Failed to update run step data","message":"Run step is not configured to collect data"}},"data_multi_field_rejected":{"value":{"error":"Failed to update run step data","message":"This step has multiple data fields. Use PUT /api/v2/runs/:run_id/run_steps/:run_step_id/fields/:id to update individual fields."}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["complete","uncomplete","skip","unskip","start","stop","data"],"example":"complete","description":"Action to perform on the run step"},"data":{"type":"string","description":"Data value when action = data"},"private_data_upload":{"type":"string","format":"binary","description":"File upload when action = data and step expects an upload"},"private_data_upload_original_filename":{"type":"string"},"private_data_upload_content_type":{"type":"string"},"private_data_upload_file_size":{"type":"integer"},"clear_data":{"type":"boolean","example":false,"description":"When true and action = uncomplete, clears the step's stored data and upload metadata in addition to uncompleting. Invalid with any other action."}},"required":["action"]},"examples":{"complete":{"summary":"Complete a step","value":{"action":"complete"}},"uncomplete":{"summary":"Uncomplete a step","value":{"action":"uncomplete"}},"uncomplete_clear":{"summary":"Uncomplete and clear collected data","value":{"action":"uncomplete","clear_data":true}},"skip":{"summary":"Skip a step","value":{"action":"skip"}},"unskip":{"summary":"Unskip a step","value":{"action":"unskip"}},"start":{"summary":"Start a step","value":{"action":"start"}},"stop":{"summary":"Stop a step","value":{"action":"stop"}},"set_data":{"summary":"Set collected data (text/number/email)","value":{"action":"data","data":"SN-2024-0042"}}}}}},"x-required-scopes":["write"]},"get":{"tags":["Run Steps"],"summary":"show run step","description":"Retrieve a single run step. Header steps will include paginated substeps when `page` is provided (default 10 per page, max 50). Without `page`, substeps is empty but `_links` has pagination URLs.","operationId":"getRunStep","parameters":[{"name":"page","in":"query","description":"Page number for substeps (header steps only). **Required** to load substeps — omitting this returns an empty substeps array.","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Substeps per page (default: 10, max: 50)","required":false,"schema":{"type":"integer"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"header_step_without_page_param":{"value":{"run_step":{"id":501,"title":"Pre-arrival Setup","header_step":true,"completed_at":null,"content":[],"substeps":[],"_links":{"self":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"first":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"last":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"}},"data_collection":{"enabled":false}}}},"header_step_with_page_param":{"value":{"run_step":{"id":501,"title":"Pre-arrival Setup","header_step":true,"completed_at":null,"substeps":[{"id":502,"title":"Order laptop and peripherals","header_step":false,"completed_at":null,"subtasks":[{"id":1001,"title":"Select hardware configuration","position":1,"completed_at":null,"completed_by_id":null},{"id":1002,"title":"Submit purchase order","position":2,"completed_at":null,"completed_by_id":null}],"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/runs/101/run_steps/502","method":"GET"},{"rel":"run","href":"https://api.manifest.ly/api/v2/runs/101","method":"GET"},{"rel":"complete","href":"https://api.manifest.ly/api/v2/runs/101/run_steps/502","method":"POST"}]},{"id":503,"title":"Set up email and Slack accounts","header_step":false,"completed_at":"2024-03-27T14:30:00Z","_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/runs/101/run_steps/503","method":"GET"},{"rel":"run","href":"https://api.manifest.ly/api/v2/runs/101","method":"GET"},{"rel":"complete","href":"https://api.manifest.ly/api/v2/runs/101/run_steps/503","method":"POST"}]}],"_links":{"self":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"first":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"last":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"}},"data_collection":{"enabled":false}}}},"regular_step":{"value":{"run_step":{"id":502,"title":"Order laptop and peripherals","header_step":false,"completed_at":null,"content":[{"type":"text","value":"Order the hardware listed below."}],"data_collection":{"enabled":false},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/runs/101/run_steps/502","method":"GET"},{"rel":"run","href":"https://api.manifest.ly/api/v2/runs/101","method":"GET"}]}}}},"schema":{"type":"object","properties":{"run_step":{"$ref":"#/components/schemas/RunStep"}},"required":["run_step"]}}}},"404":{"description":"wrong-scoped ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"wrong_id":{"value":{"error":"Resource not found","message":"This endpoint expects a run-scoped step ID (unique within its run). Did you pass a workflow step ID by mistake?"}}}}}}}},"patch":{"tags":["Run Steps"],"summary":"update run step due date","description":"Update (or clear) the due date of the run step. Use blank string to clear.","operationId":"updateRunStep","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"400":{"description":"bad request"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"due_at":{"type":"string","description":"ISO8601 date-time or blank to clear. Preferred over late_at."},"late_at":{"type":"string","description":"ISO8601 date-time or blank to clear (deprecated, use due_at)","deprecated":true}}},"examples":{"set_due":{"summary":"Set a due date (preferred)","value":{"due_at":"2024-12-31T17:00:00Z"}},"set_due_legacy":{"summary":"Set a due date (deprecated)","value":{"late_at":"2024-12-31T17:00:00Z"}},"clear_due":{"summary":"Clear the due date","value":{"due_at":""}}}}}},"x-required-scopes":["write"]}},"/runs/{run_id}/run_steps/{id}/assign":{"post":{"tags":["Run Steps"],"summary":"assign run step","description":"Assign the run step to a membership or unassign when body is empty.","operationId":"assignRunStep","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}},{"name":"run_id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Run step ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"assigned","content":{"application/json":{"examples":{"assigned":{"value":{"run_step":{"id":1,"title":"Sample Step","header_step":false,"completed_at":null},"message":"Run step assigned successfully"}}}}}},"404":{"description":"assignee not found"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignee_membership_id":{"type":"integer","description":"Membership ID to assign to"}}},"examples":{"assign":{"summary":"Assign to a membership","value":{"assignee_membership_id":42}},"unassign":{"summary":"Unassign (empty body)","value":{}}}}}},"x-required-scopes":["write"]}},"/runs/{id}/summary":{"get":{"tags":["Runs"],"summary":"run summary","description":"Get a lightweight section-level completion overview of a run. Returns section headers with completion counts and overall progress without step detail.","operationId":"getRunSummary","parameters":[{"name":"id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"sections":[{"id":100,"title":"Section 1","total":5,"completed":3,"skipped":0,"incomplete":2},{"id":200,"title":"Section 2","total":3,"completed":3,"skipped":0,"incomplete":0}],"progress":{"total":8,"completed":6,"skipped":0,"incomplete":2,"percentage":75}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}}}}},"/runs":{"get":{"summary":"list runs","tags":["Runs"],"description":"List runs with filtering, sorting, and pagination","operationId":"listRuns","parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","schema":{"type":"integer"}},{"name":"search","in":"query","description":"Search term","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order (started_asc, started_desc, title_asc, title_desc, due_at_asc, due_at_desc, late_at_asc, late_at_desc)","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status (closed, late, in-progress, upcoming)","schema":{"type":"string"}},{"name":"tag","in":"query","description":"Filter by tag","schema":{"type":"string"}},{"name":"workflow_id","in":"query","description":"Filter by workflow ID","schema":{"type":"integer"}},{"name":"department_id","in":"query","description":"Filter by department id","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"runs":[{"id":1,"title":"Sample Run","workflow_id":123,"state":"started","started_at":"2024-03-20T10:00:00Z","completed_at":null,"due_at":"2024-03-21T10:00:00Z","assignee_count":2,"progress":{"completed_steps":3,"total_steps":10,"percentage":30}}],"meta":{"current_page":1,"per_page":20,"total_count":1,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}}}},"post":{"summary":"create run","tags":["Runs"],"operationId":"createRun","description":"Create a new run from a workflow (requires write scope)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}}],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"created":{"value":{"run":{"id":101,"title":"New Run","workflow_id":42,"state":"started","participants":[{"user_id":12,"email":"user@example.com","role":"member"}],"_links":[{"rel":"self","href":"https://api.example.com/api/v2/runs/101","method":"GET"},{"rel":"run_steps","href":"https://api.example.com/api/v2/runs/101/run_steps","method":"GET"}]}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"examples":{"invalid":{"value":{"error":"Unprocessable Entity","message":"Validation failed: Run checklist must exist"}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"workflow_id":{"type":"integer","description":"ID of the workflow to create run from"},"checklist_id":{"type":"integer","description":"Alias for workflow_id","deprecated":true},"title":{"type":"string","description":"Title of the run"},"external_id":{"type":"string","description":"External identifier for the run"},"channel":{"type":"string","description":"Slack channel for the run"},"origin":{"type":"string","description":"Source of the run creation (defaults to User-Agent)"},"notes":{"type":"string","description":"Notes for the run"},"due_at":{"type":"string","format":"date_time","description":"Due date for the run (ISO8601 datetime or yyyy-mm-dd). Preferred over late_at."},"late_at":{"type":"string","format":"date","description":"Due date for the run (format: yyyy-mm-dd)","deprecated":true},"started_at":{"type":"string","format":"date","description":"Start date for the run (format: yyyy-mm-dd)"},"tag_list":{"type":"array","items":{"type":"string"},"description":"List of tags for the run"},"roles_to_users":{"type":"array","description":"Optional array of role assignments for the run","items":{"type":"object","required":["role_id","email"],"properties":{"role_id":{"type":"integer","description":"ID of the role to assign"},"email":{"type":"string","format":"email","description":"Email of the user to attach to the role"}}}},"data_choices":{"type":"object","description":"Optional hash of data choices for the run (keyed by index)","additionalProperties":{"type":"object","required":["data_setting_id","data"],"properties":{"data_setting_id":{"type":"integer","description":"ID of the workflow data setting"},"data":{"type":"string","description":"Value of the data to populate"}}}},"participants":{"type":"array","description":"Optional list of participants to add","items":{"type":"object","oneOf":[{"required":["user_id"],"properties":{"user_id":{"type":"integer"}}},{"required":["email"],"properties":{"email":{"type":"string","format":"email"}}}]}}},"required":["checklist_id"]}}},"examples":{"minimal":{"summary":"Minimal — workflow ID only","value":{"run":{"checklist_id":42,"title":"Q1 Onboarding"}}},"with_participants":{"summary":"With participants, tags, and due date","value":{"run":{"checklist_id":42,"title":"Q1 Onboarding","participants":[{"email":"alice@example.com"},{"user_id":7}],"tag_list":["onboarding","q1"],"late_at":"2024-12-31","notes":"New hire starting Jan 2"}}},"with_roles_and_data":{"summary":"With role assignments and pre-filled data","value":{"run":{"checklist_id":42,"roles_to_users":[{"role_id":1,"email":"manager@example.com"}],"data_choices":{"0":{"data_setting_id":5,"data":"Acme Corp"}}}}}}}}},"x-required-scopes":["write"]}},"/runs/{id}":{"get":{"tags":["Runs"],"summary":"show run","description":"Get a run with its main steps. Header steps (`header_step: true`) always return `substeps: []` here. Fetch substeps via `GET /runs/{run_id}/run_steps/{step_id}?page=1`. See `_links` on each header step.","operationId":"getRun","parameters":[{"name":"id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}},{"name":"steps_page","in":"query","description":"Page number for main (top-level) steps","required":false,"schema":{"type":"integer"}},{"name":"steps_per_page","in":"query","description":"Number of main steps per page (default: 10, max: 50)","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"with_header_steps":{"value":{"run":{"id":101,"title":"Employee Onboarding — Mar 27","workflow_id":42,"state":"started","started_at":"2024-03-27T10:00:00Z","completed_at":null,"progress":{"completed_steps":2,"total_steps":12,"percentage":17},"run_steps":[{"id":501,"title":"Pre-arrival Setup","header_step":true,"completed_at":null,"substeps":[],"_links":{"self":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"first":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"},"last":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/501?page=1\u0026per_page=10","method":"GET"}},"data_collection":{"enabled":false}},{"id":510,"title":"First Day Orientation","header_step":true,"completed_at":null,"substeps":[],"_links":{"self":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/510?page=1\u0026per_page=10","method":"GET"},"first":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/510?page=1\u0026per_page=10","method":"GET"},"last":{"href":"https://api.manifest.ly/api/v2/runs/101/run_steps/510?page=1\u0026per_page=10","method":"GET"}},"data_collection":{"enabled":false}}]},"step_meta":{"current_page":1,"per_page":10,"total_count":4,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"}}},"put":{"tags":["Runs"],"summary":"update run","description":"Update properties of an existing run (requires write scope)","operationId":"updateRun","parameters":[{"name":"id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"run":{"id":101,"title":"Updated Run Title","workflow_id":42,"department_id":3,"department_name":"Engineering","state":"started","started_at":"2024-03-20T10:00:00Z","completed_at":null,"due_at":null,"assignee_count":2,"progress":{"completed_steps":3,"total_steps":10,"percentage":30},"participants":[{"user_id":12,"email":"user@example.com","role":"member"}],"created_at":"2024-03-20T09:00:00Z","updated_at":"2024-03-20T10:30:00Z"}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"title":{"type":"string","description":"New title for the run"},"participants":{"type":"array","description":"Authoritative list of participants","items":{"type":"object","oneOf":[{"required":["user_id"],"properties":{"user_id":{"type":"integer"}}},{"required":["email"],"properties":{"email":{"type":"string","format":"email"}}}]}}}}}},"examples":{"rename":{"summary":"Rename the run","value":{"run":{"title":"Updated Run Title"}}},"with_participants":{"summary":"Update title and replace participant list","value":{"run":{"title":"Sprint Review","participants":[{"email":"alice@example.com"},{"user_id":7}]}}}}}}},"x-required-scopes":["write"]},"delete":{"tags":["Runs"],"summary":"close run","description":"Close a run (soft delete) (requires write scope)","operationId":"closeRun","parameters":[{"name":"id","in":"path","description":"Run ID","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"no content"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"}},"x-required-scopes":["write"]}},"/workflows/{workflow_id}/steps/{step_id}/data_settings":{"get":{"summary":"show step data setting","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"step_id","in":"path","description":"Step ID","required":true,"schema":{"type":"integer"}}],"tags":["Data Settings"],"operationId":"getStepDataSetting","description":"Return the data setting for a workflow step. Data settings define how data is collected on a step (e.g., text, number, list, date). Returns 404 if the step has no data setting configured.","responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"list_format":{"value":{"data_setting":{"id":1,"label":"Priority","value_format":"list","value_format_config":{"values":["Low","Medium","High"],"value_selection_type":"single"},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}},"text_format":{"value":{"data_setting":{"id":2,"label":"Customer Name","value_format":"text","value_format_config":{},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/6/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/6","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}}},"schema":{"type":"object","properties":{"data_setting":{"$ref":"#/components/schemas/StepDataSetting"}},"required":["data_setting"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"Invalid or expired token"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"step_not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"create step data setting","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"step_id","in":"path","description":"Step ID","required":true,"schema":{"type":"integer"}}],"tags":["Data Settings"],"operationId":"createStepDataSetting","description":"Create a data setting for a step. Only one data setting per step. Config keys (values, value_selection_type) are only valid for list format; other formats should omit config or use {}.","responses":{"201":{"description":"created file upload (no config)","content":{"application/json":{"examples":{"list_input":{"value":{"data_setting":{"id":1,"label":"Priority Level","value_format":"list","value_format_config":{"values":["Low","Medium","High","Critical"],"value_selection_type":"single"},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}},"email_input":{"value":{"data_setting":{"id":2,"label":"Customer Email","value_format":"email","value_format_config":{},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/6/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/6","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}},"number_input":{"value":{"data_setting":{"id":3,"label":"Amount","value_format":"number","value_format_config":{},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/7/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/7","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}},"file_upload":{"value":{"data_setting":{"id":4,"label":"Upload Document","value_format":"file","value_format_config":{},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/8/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/8","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}}},"schema":{"type":"object","properties":{"data_setting":{"$ref":"#/components/schemas/StepDataSetting"}},"required":["data_setting"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"Invalid or expired token"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"step_not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation errors","content":{"application/json":{"examples":{"validation_error":{"value":{"errors":["Label is too long (maximum is 75 characters)","Value format is not included in the list"]}}},"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data_setting":{"$ref":"#/components/schemas/StepDataSettingCreate"}},"required":["data_setting"]},"examples":{"text":{"summary":"Text input","value":{"data_setting":{"label":"Customer Name","value_format":"text","required":true}}},"email":{"summary":"Email input","value":{"data_setting":{"label":"Contact Email","value_format":"email","required":true}}},"number":{"summary":"Number input","value":{"data_setting":{"label":"Amount","value_format":"number","required":false}}},"file":{"summary":"File upload","value":{"data_setting":{"label":"Upload Document","value_format":"file","required":true}}},"list":{"summary":"Dropdown list (single select)","value":{"data_setting":{"label":"Priority","value_format":"list","required":true,"value_format_config":{"values":["Low","Medium","High","Critical"],"value_selection_type":"single"}}}}}}},"required":true},"x-required-scopes":["write"]},"patch":{"summary":"update step data setting","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"step_id","in":"path","description":"Step ID","required":true,"schema":{"type":"integer"}}],"tags":["Data Settings"],"operationId":"updateStepDataSetting","description":"Update an existing data setting for a step. Config keys (values, value_selection_type) are only valid for list format; other formats should omit config or use {}.","responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"updated_list":{"value":{"data_setting":{"id":1,"label":"Status","value_format":"list","value_format_config":{"values":["Not Started","In Progress","Completed","Blocked"],"value_selection_type":"single"},"_links":[{"rel":"self","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5/data_settings","method":"GET"},{"rel":"step","href":"https://api.manifest.ly/api/v2/workflows/10/steps/5","method":"GET"},{"rel":"workflow","href":"https://api.manifest.ly/api/v2/workflows/10","method":"GET"}]}}}},"schema":{"type":"object","properties":{"data_setting":{"$ref":"#/components/schemas/StepDataSetting"}},"required":["data_setting"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"Invalid or expired token"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"step_not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"validation errors","content":{"application/json":{"examples":{"validation_error":{"value":{"errors":["Label is too long (maximum is 75 characters)"]}}},"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data_setting":{"$ref":"#/components/schemas/StepDataSettingCreate"}},"required":["data_setting"]},"examples":{"rename":{"summary":"Rename the label","value":{"data_setting":{"label":"Updated Label"}}},"change_to_list":{"summary":"Change format to dropdown list","value":{"data_setting":{"label":"Status","value_format":"list","value_format_config":{"values":["Not Started","In Progress","Completed","Blocked"],"value_selection_type":"single"}}}}}}},"required":true},"x-required-scopes":["write"]},"delete":{"summary":"delete step data setting","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"step_id","in":"path","description":"Step ID","required":true,"schema":{"type":"integer"}}],"tags":["Data Settings"],"operationId":"deleteStepDataSetting","description":"Delete the data setting for a workflow step. This will remove all data collection configuration from the step.","responses":{"204":{"description":"no content"},"401":{"description":"unauthorized","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"Invalid or expired token"}}}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"step_not_found":{"value":{"error":"Resource not found"}}}}}}},"x-required-scopes":["write"]}},"/workflows/{workflow_id}/steps":{"get":{"tags":["Steps"],"summary":"list workflow steps","description":"List workflow template steps as a standalone resource with pagination and optional hierarchy mode.","operationId":"listWorkflowSteps","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"mode","in":"query","enum":["flat","hierarchy"],"description":"Response mode: flat (default) or hierarchy","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","enum":["all","sections"],"description":"Filter: all (default) or sections only","required":false,"schema":{"type":"string"}},{"name":"parent_step_id","in":"query","description":"Scope to steps under a specific section header","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"steps":[{"id":1,"title":"Section 1","header_step":true},{"id":2,"title":"Step 1a","header_step":false}],"meta":{"current_page":1,"per_page":25,"total_count":2,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}},"schema":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/Step"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["steps","meta"]}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workflows/{workflow_id}/steps/{id}":{"get":{"tags":["Steps"],"summary":"show step","description":"Return a single workflow step. Header steps can paginate substeps via page/per_page.","operationId":"getStep","parameters":[{"name":"workflow_id","in":"path","description":"Workflow (checklist) ID","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"Step ID","required":true,"schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number for substeps pagination","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Substeps per page","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"step":{"id":1,"title":"Section Header","header_step":true,"created_at":"2024-07-10T12:00:00Z","updated_at":"2024-07-10T12:00:00Z","step_data_setting":null,"content":[{"type":"text","value":"Review the client's submitted documents..."},{"type":"image","url":"https://example.s3.amazonaws.com/image.png"},{"type":"file","url":"https://example.s3.amazonaws.com/file.pdf","filename":"checklist.pdf"},{"type":"video","url":"https://vimeo.com/123456789"}],"substeps":[{"id":2,"title":"Sub 1","header_step":false},{"id":3,"title":"Sub 2","header_step":false}],"_links":{"self":{"href":"https://api.manifest.ly/api/v2/workflows/10/steps/1?page=1\u0026per_page=2","method":"GET"},"first":{"href":"https://api.manifest.ly/api/v2/workflows/10/steps/1?page=1\u0026per_page=2","method":"GET"},"next":{"href":"https://api.manifest.ly/api/v2/workflows/10/steps/1?page=2\u0026per_page=2","method":"GET"}}}}}},"schema":{"type":"object","properties":{"step":{"$ref":"#/components/schemas/Step"}},"required":["step"]}}}},"404":{"description":"not found","content":{"application/json":{"examples":{"not_found":{"value":{"error":"Resource not found"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users":{"get":{"summary":"list users","tags":["Users"],"description":"List users within the master account. Only accessible to admins. Master admins see all users; department admins see only users in their admin departments. Supports search by name/username, email filter, department filter, and pagination.","operationId":"listUsers","parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","schema":{"type":"integer"}},{"name":"search","in":"query","description":"Search term (name or username, case-insensitive)","schema":{"type":"string"}},{"name":"email","in":"query","description":"Filter by exact email address (case-insensitive)","schema":{"type":"string"}},{"name":"department_id","in":"query","description":"Filter by department ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/users/{id}":{"get":{"tags":["Users"],"summary":"show user","description":"Retrieve a single user by their user ID. Only accessible to admins with access to that user.","operationId":"getUser","parameters":[{"name":"id","in":"path","description":"User ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/verify":{"get":{"summary":"verify","tags":["Verify"],"description":"Verify that OAuth authentication is working and return user information","operationId":"verifyOAuth","responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"message":"OAuth is working!"}}},"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List webhooks","tags":["Webhooks"],"operationId":"listWebhooks","description":"Returns active webhooks for the current master account.","responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}}}},"post":{"summary":"Create webhook","tags":["Webhooks"],"operationId":"createWebhook","description":"Create a new webhook subscription.","parameters":[],"responses":{"201":{"description":"created step_tagged"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"422":{"description":"validation errors"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/WebhookCreate"},"hookable":{"type":"string","enum":["checklist","step","run","run_step"]},"hookable_id":{"type":"integer"}},"required":["webhook","hookable","hookable_id"]},"examples":{"workflow_completed":{"summary":"Notify when a run completes (workflow-level)","value":{"webhook":{"url":"https://example.com/hook","event":"completed","signature_version":2},"hookable":"checklist","hookable_id":42}},"step_completed":{"summary":"Notify when a step completes (run-level)","value":{"webhook":{"url":"https://example.com/hook","event":"step_completed","signature_version":2},"hookable":"run","hookable_id":101}},"step_started":{"summary":"Notify when a specific run step starts","value":{"webhook":{"url":"https://example.com/hook","event":"step_started","signature_version":2},"hookable":"run_step","hookable_id":555}},"step_assigned":{"summary":"Notify when a run step gets a new assignee","value":{"webhook":{"url":"https://example.com/hook","event":"step_assigned","signature_version":2},"hookable":"run","hookable_id":101}},"step_tagged":{"summary":"Notify when a run step gains/loses one of the tracked tags","value":{"webhook":{"url":"https://example.com/hook","event":"step_tagged","signature_version":2,"tag_list":["urgent","blocked"]},"hookable":"run_step","hookable_id":555}},"tag_changed":{"summary":"Notify on tag changes (filtered to specific tags)","value":{"webhook":{"url":"https://example.com/hook","event":"tag_changed","signature_version":2,"tag_list":["urgent","blocked"]},"hookable":"checklist","hookable_id":42}}}}},"required":true},"x-required-scopes":["write"]}},"/webhooks/{id}":{"patch":{"tags":["Webhooks"],"summary":"Update webhook","description":"Partially update an existing webhook. Send only the fields you want to change. `hookable` and `hookable_id` are optional — supply both together to repoint the webhook at a different target; omit them to leave the existing target unchanged.","operationId":"updateWebhook","parameters":[{"name":"id","in":"path","description":"Webhook ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"webhook":{"id":7,"target_url":"https://example.com/updated","event":"completed","signature_version":2,"tag_list":null,"created_at":"2024-03-01T00:00:00Z","updated_at":"2024-03-20T10:00:00Z","deactivated_at":null}}}}}}},"404":{"description":"not found"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/WebhookCreate"},"hookable":{"type":"string","enum":["checklist","step","run","run_step"]},"hookable_id":{"type":"integer"}},"required":["webhook"]},"examples":{"change_url":{"summary":"Change the webhook URL and event","value":{"webhook":{"url":"https://example.com/new-url","event":"completed"},"hookable":"run","hookable_id":101}}}}},"required":true},"x-required-scopes":["write"]},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","description":"Webhook ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"404":{"description":"not found"}},"x-required-scopes":["write"]}},"/workflows/{id}/template":{"get":{"tags":["Workflows"],"summary":"export workflow template","description":"Export a workflow as a JSON template suitable for import","operationId":"exportWorkflowTemplate","parameters":[{"name":"id","in":"path","description":"Workflow ID","required":true,"schema":{"type":"integer"}},{"name":"obfuscate","in":"query","required":false,"description":"If true, replaces sensitive fields with placeholders (default: false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}}}}},"/workflows/{id}/export_csv":{"post":{"tags":["Workflows"],"summary":"export workflow as CSV","description":"Export a workflow template as CSV format including all steps and configuration. Returns an export ID that can be used to check status and download the file. Requires admin access.","operationId":"exportWorkflowCSV","parameters":[{"name":"id","in":"path","description":"Workflow ID","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"export initiated","content":{"application/json":{"examples":{"initiated":{"value":{"export_id":55,"status":"created","message":"Export initiated. Use the export_id to check status and download."}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"}},"x-required-scopes":["write"]}},"/workflows/{id}/export_status":{"get":{"tags":["Workflows"],"summary":"check CSV export status","description":"Check the status of a CSV export. When finished, provides download URL.","operationId":"checkExportStatus","parameters":[{"name":"id","in":"path","description":"Workflow ID","required":true,"schema":{"type":"integer"}},{"name":"export_id","in":"query","description":"Export ID returned from export_csv","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"export not found"}}}},"/workflows/import":{"post":{"summary":"import workflow template","tags":["Workflows"],"operationId":"importWorkflowTemplate","description":"Create a workflow in a department from a JSON template","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"UUID to ensure safe retries; server will replay original 2xx for duplicates","schema":{"type":"string"}}],"responses":{"201":{"description":"created","content":{"application/json":{"examples":{"created":{"value":{"workflow":{"id":99,"title":"Imported via API","department_id":3},"_links":{"self":{"href":"https://api.manifest.ly/api/v2/workflows/99"},"runs":{"href":"https://api.manifest.ly/api/v2/runs?workflow_id=99"}}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"department_id":{"type":"integer","description":"Target department ID (must be admin)"},"template":{"type":"string","description":"Workflow template JSON string (conforming to /api/v2/schemas/checklist.json)"}},"required":["department_id","template"]},"examples":{"basic":{"summary":"Import a simple workflow template","value":{"department_id":3,"template":"{\"checklist\":{\"title\":\"Onboarding\",\"description\":\"New hire onboarding\",\"tag_list\":[\"hr\"]},\"main_steps\":[{\"title\":\"Send welcome email\",\"header_step\":false}],\"conditionals\":[]}"}}}}}},"x-required-scopes":["write"]}},"/workflows/import/validate":{"post":{"summary":"validate workflow template","tags":["Workflows"],"operationId":"validateWorkflowTemplate","description":"Validate a workflow JSON template without creating records","parameters":[],"responses":{"200":{"description":"valid"},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"422":{"description":"invalid"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"department_id":{"type":"integer","description":"Target department ID (must be accessible to caller)"},"template":{"type":"string","description":"Workflow template JSON string (conforming to /api/v2/schemas/checklist.json)"}},"required":["department_id","template"]},"examples":{"validate":{"summary":"Validate a template before importing","value":{"department_id":3,"template":"{\"checklist\":{\"title\":\"Onboarding\",\"description\":null,\"tag_list\":[]},\"main_steps\":[],\"conditionals\":[]}"}}}}}},"x-required-scopes":["write"]}},"/workflows":{"get":{"summary":"list workflows","tags":["Workflows"],"description":"List workflows with filtering, sorting, and pagination","operationId":"listWorkflows","parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}},{"name":"per_page","in":"query","description":"Items per page (max 100)","schema":{"type":"integer"}},{"name":"search","in":"query","description":"Search term","schema":{"type":"string"}},{"name":"tag","in":"query","description":"Filter by tag","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order","schema":{"type":"string"}},{"name":"department_id","in":"query","description":"Filter by department id","schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"workflows":[{"id":1,"title":"Sample Workflow","description":"A sample workflow for testing","slug":"sample-workflow","department_id":123,"department_name":"Test Account","step_count":5,"tags":["sample"],"roles":[{"role_id":1,"name":"Manager","user_emails":["manager@example.com"]},{"role_id":2,"name":"Reviewer","user_emails":["reviewer1@example.com","reviewer2@example.com"]}],"shared_publicly":true,"shared_publicly_at":"2024-03-20T10:00:00Z","business_days":["Monday","Tuesday","Wednesday","Thursday","Friday"],"expected_duration":60,"expected_duration_units":"minutes","hide_numbers":false,"hide_steps_from_external":false,"only_assigned_can_complete":false,"created_at":"2024-03-20T10:00:00Z","updated_at":"2024-03-20T10:00:00Z","app_url":"https://app.manifestly.com/checklists/1","last_run_at":"2024-03-21T14:30:00Z"}],"meta":{"current_page":1,"per_page":20,"total_count":1,"total_pages":1,"has_previous_page":false,"has_next_page":false}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}},"/workflows/{id}":{"get":{"tags":["Workflows"],"summary":"show workflow","description":"Get workflow details including steps","operationId":"getWorkflow","parameters":[{"name":"id","in":"path","description":"Workflow ID","required":true,"schema":{"type":"integer"}},{"name":"steps_page","in":"query","description":"Page number for steps","required":false,"schema":{"type":"integer"}},{"name":"steps_per_page","in":"query","description":"Number of steps per page","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"successful","content":{"application/json":{"examples":{"successful":{"value":{"workflow":{"id":42,"title":"Employee Onboarding","description":"Standard onboarding process for new hires","slug":"employee-onboarding","department_id":3,"department_name":"Engineering","step_count":12,"tags":["onboarding","hr"],"roles":[{"role_id":1,"name":"Manager","user_emails":["manager@example.com"]}],"shared_publicly":false,"shared_publicly_at":null,"business_days":["Monday","Tuesday","Wednesday","Thursday","Friday"],"expected_duration":5,"expected_duration_units":"days","hide_numbers":false,"hide_steps_from_external":false,"only_assigned_can_complete":false,"created_at":"2024-01-15T08:00:00Z","updated_at":"2024-03-20T10:00:00Z","app_url":"https://app.manifestly.com/checklists/42","last_run_at":"2024-03-27T10:00:00Z","steps":[{"id":201,"title":"Pre-arrival Setup","header_step":true,"substeps":[],"data_collection":{"enabled":false}},{"id":202,"title":"Send welcome email","header_step":false,"substeps":[],"data_collection":{"enabled":false}}]},"step_meta":{"current_page":1,"per_page":10,"total_count":12,"total_pages":2,"has_previous_page":false,"has_next_page":true}}}}}}},"401":{"description":"token_revoked","content":{"application/json":{"examples":{"unauthorized":{"value":{"error":"invalid_token","message":"The access token is invalid"}},"token_revoked":{"value":{"error":"invalid_token","message":"The access token was revoked"}}}}}},"404":{"description":"not found"},"429":{"description":"too many requests","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}}}}}}},"servers":[{"url":"https://api.manifest.ly/api/v2","description":"Production server"}],"externalDocs":{"description":"API v2 Changelog","url":"/api/v2/changelog"},"components":{"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer","description":"OAuth2 Bearer token obtained from /oauth/token endpoint"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"errors":{"type":"object","description":"Validation errors by field","additionalProperties":{"type":"array","items":{"type":"string"}}}},"oneOf":[{"required":["error"]},{"required":["errors"]}]},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"per_page":{"type":"integer","description":"Items per page"},"total_count":{"type":"integer","description":"Total number of items"},"total_pages":{"type":"integer","description":"Total number of pages"},"has_previous_page":{"type":"boolean","description":"Whether there is a previous page"},"has_next_page":{"type":"boolean","description":"Whether there is a next page"}},"required":["current_page","per_page","total_count","total_pages","has_previous_page","has_next_page"]},"LinkObject":{"type":"object","properties":{"href":{"type":"string","description":"Absolute or relative URL"},"rel":{"type":"string","description":"Relation type (e.g. next, prev, self)","nullable":true}},"required":["href"]},"Workflow":{"type":"object","properties":{"id":{"type":"integer","description":"Workflow ID"},"title":{"type":"string","description":"Workflow title"},"description":{"type":"string","description":"Workflow description","nullable":true},"slug":{"type":"string","description":"Workflow slug or public identifier","nullable":true},"department_id":{"type":"integer","description":"Department ID"},"department_name":{"type":"string","description":"Department name"},"step_count":{"type":"integer","description":"Number of active steps"},"locked":{"type":"boolean","description":"Whether this workflow is locked (read-only shared copy)"},"source_share_id":{"type":["integer","null"],"description":"ID of the WorkflowShare that produced this copy (null for originals)"},"shared_departments":{"type":"array","description":"Department IDs the workflow is shared with (present only for admins)","items":{"type":"integer"}},"tags":{"type":"array","items":{"type":"string"},"description":"Array of tag names"},"roles":{"type":"array","description":"Array of roles assigned to workflow steps","items":{"type":"object","properties":{"role_id":{"type":"integer","description":"Role ID"},"name":{"type":"string","description":"Role name"},"user_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Array of user email addresses assigned to this role"}},"required":["role_id","name","user_emails"]}},"shared_publicly":{"type":"boolean","description":"Whether the workflow is shared publicly"},"shared_publicly_at":{"type":"string","format":"date-time","description":"Timestamp when workflow was shared publicly","nullable":true},"business_days":{"type":"array","description":"Days of the week the business operates","items":{"type":"string","enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"]}},"expected_duration":{"type":"integer","description":"Expected duration in specified units","nullable":true},"expected_duration_units":{"type":"string","description":"Units for expected duration","nullable":true},"open_duration":{"type":"integer","description":"How long the run stays open after starting","nullable":true},"open_duration_units":{"type":"string","description":"Units for open_duration","nullable":true},"hide_numbers":{"type":"boolean","description":"Whether to hide step numbers"},"hide_steps_from_external":{"type":"boolean","description":"Whether to hide steps from external users"},"only_assigned_can_complete":{"type":"boolean","description":"Whether only assigned users can complete steps"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"app_url":{"type":"string","format":"uri","description":"Fully-qualified link to view/edit the object in the Manifestly web app."},"_links":{"type":"array","description":"HATEOAS links related to this workflow","items":{"$ref":"#/components/schemas/LinkObject"}},"last_run_at":{"type":"string","format":"date-time","description":"Last run timestamp","nullable":true}},"required":["id","title","slug","department_id","department_name","step_count","tags","roles","shared_publicly"]},"WorkflowWithSteps":{"allOf":[{"$ref":"#/components/schemas/Workflow"},{"type":"object","properties":{"steps":{"type":"array","description":"Paginated top-level workflow steps (same shape as `GET /workflows/{id}/steps/{step_id}` — see `Step`)","items":{"$ref":"#/components/schemas/Step"}}},"required":["steps"]}]},"VerifyResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"},"user_id":{"type":"integer","description":"Authenticated user ID"},"email":{"type":"string","description":"Authenticated user email"},"account_id":{"type":"integer","description":"Master account ID"},"account_name":{"type":"string","description":"Master account name"}},"required":["message","user_id","email","account_id","account_name"]},"LogoutResponse":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}},"required":["message"]},"Webhook":{"type":"object","properties":{"id":{"type":"integer"},"target_url":{"type":"string","format":"uri"},"event":{"type":"string","description":"Event type that triggers the webhook","enum":["completed","late","started","step_assigned","step_completed","step_late","step_skipped","step_started","step_tagged","tag_changed"]},"signature_version":{"type":"integer"},"tag_list":{"type":"array","description":"Optional list of tags to watch (present only when event = tag_changed or step_tagged)","items":{"type":"string"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deactivated_at":{"type":"string","format":"date-time","nullable":true},"_links":{"type":"array","description":"HATEOAS links describing possible actions","items":{"$ref":"#/components/schemas/LinkObject"}}},"required":["id","target_url","event","created_at","updated_at"]},"WebhookCreate":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Webhook endpoint URL"},"event":{"type":"string","description":"Event type to trigger the webhook. Valid events depend on the hookable type:\n- `checklist` and `run` hookables support: `completed`, `late`, `started`, `tag_changed`.\n- `step` and `run_step` hookables support: `step_assigned`, `step_completed`, `step_late`, `step_skipped`, `step_started`, `step_tagged`.","enum":["completed","late","started","step_assigned","step_completed","step_late","step_skipped","step_started","step_tagged","tag_changed"]},"signature_version":{"type":"integer","enum":[2],"description":"Signature algorithm version: 2 for SHA256"},"tag_list":{"type":"array","items":{"type":"string"},"description":"List of tags that trigger the webhook. Required when `event` is `tag_changed` (run/checklist) or `step_tagged` (step/run_step); ignored otherwise.","nullable":true}},"required":["url","event"]},"Run":{"type":"object","properties":{"id":{"type":"integer","description":"Run ID"},"title":{"type":"string","description":"Run title","nullable":true},"workflow_id":{"type":"integer","description":"ID of the workflow this run is based on"},"workflow_title":{"type":"string","description":"Title of the workflow this run is based on"},"department_id":{"type":"integer","description":"Department ID"},"department_name":{"type":"string","description":"Department name"},"state":{"type":"string","description":"Current state of the run","enum":["scheduled","started","completed","closed"]},"started_at":{"type":"string","format":"date-time","description":"When the run was started","nullable":true},"completed_at":{"type":"string","format":"date-time","description":"When the run was completed","nullable":true},"due_at":{"type":"string","format":"date-time","description":"When the run is due","nullable":true},"late_at":{"type":"string","format":"date-time","description":"When the run is due (same value as due_at)","nullable":true},"auto_close_at":{"type":"string","format":"date-time","description":"When the run will auto-close","nullable":true},"auto_closed_at":{"type":"string","format":"date-time","description":"When the run was auto-closed","nullable":true},"channel":{"type":"string","description":"Slack channel associated with the run","nullable":true},"external_id":{"type":"string","description":"External identifier for the run (set by API consumers)","nullable":true},"notes":{"type":"string","description":"Notes for the run","nullable":true},"origin":{"type":"string","description":"Source of the run creation","nullable":true},"tag_list":{"type":"array","description":"List of tags associated with the run","items":{"type":"string"},"nullable":true},"roles_to_users":{"type":"array","description":"Role assignments for the run","items":{"type":"object","properties":{"role_id":{"type":"integer","description":"Role ID"},"email":{"type":"string","format":"email","description":"Email of the user assigned to the role"}},"required":["role_id","email"]},"nullable":true},"assignee_count":{"type":"integer","description":"Number of participants to this run"},"progress":{"type":"object","properties":{"completed_steps":{"type":"integer","description":"Number of completed steps"},"total_steps":{"type":"integer","description":"Total number of steps"},"percentage":{"type":"integer","description":"Completion percentage"}},"required":["completed_steps","total_steps","percentage"]},"participants":{"type":"array","description":"List of participants on the run","items":{"type":"object","properties":{"user_id":{"type":"integer","description":"User ID"},"email":{"type":"string","format":"email","description":"Participant email"},"role":{"type":"string","description":"Role of the user within the account","enum":["admin","user","member","limited"]}},"required":["user_id","email"]}},"app_url":{"type":"string","format":"uri","description":"Fully-qualified link to view/edit the object in the Manifestly web app."},"_links":{"type":"array","description":"HATEOAS links related to this run","items":{"$ref":"#/components/schemas/LinkObject"}}},"required":["id","title","workflow_id","department_id","department_name"]},"RunStep":{"type":"object","properties":{"id":{"type":"integer","description":"Run-scoped step ID (unique only within this run)"},"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"Whether this is a header step"},"kind":{"type":"string","enum":["standard","stop_task","approval"],"description":"The kind of step. `stop_task` blocks downstream steps in its scope until completed. `approval` requires a reviewer-recorded decision via the approval flow before completion. Read-only — derived from the underlying workflow step at run materialization."},"blocked_by_stop_task":{"type":"boolean","description":"True when an upstream `stop_task` in the same run is still incomplete and is gating this step. Blocked steps appear in responses but reject `complete`/`skip` actions until the gate is released."},"blocking_run_step_id":{"type":"integer","nullable":true,"description":"When `blocked_by_stop_task` is true, the run step ID of the stop task that must be completed to unlock this step. Null when not blocked."},"completed_at":{"type":"string","format":"date-time","description":"When the step was completed","nullable":true},"data":{"type":"string","description":"Data entered for this step (only present if step has data setting)","nullable":true},"substeps":{"type":"array","description":"Substeps within a header step (section). **Important:** This array is empty unless you explicitly pass `?page=1` (or another page number) when fetching the step via `GET /runs/{run_id}/run_steps/{id}?page=1`. In the `GET /runs/{id}` response, substeps are always empty — use the `_links` on each header step to fetch its substeps.","items":{"$ref":"#/components/schemas/RunSubStep"}},"subtasks":{"type":"array","description":"Array of subtasks (only present when step has subtasks)","items":{"$ref":"#/components/schemas/Subtask"}},"_links":{"type":"array","description":"HATEOAS pagination links for substeps (only present for header steps). Follow the `self` or `first` link to load substeps.","items":{"$ref":"#/components/schemas/LinkObject"}},"data_collection":{"type":"object","description":"Describes whether and how this step collects data","oneOf":[{"$ref":"#/components/schemas/DataCollectionDisabled"},{"$ref":"#/components/schemas/DataCollectionList"},{"$ref":"#/components/schemas/DataCollectionOther"}]},"content":{"type":"array","description":"Structured content objects attached to this step (text, images, files, videos). Text values have tokens replaced with runtime values.","items":{"$ref":"#/components/schemas/ContentObject"}}},"required":["id","title","header_step","data_collection"]},"Assignment":{"type":"object","properties":{"id":{"type":"integer","description":"Run-step ID (assignment key)"},"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"True if header step"},"due_at":{"type":"string","format":"date-time","description":"Step due date","nullable":true},"run":{"type":"object","description":"Summary of the run this step belongs to","properties":{"id":{"type":"integer"},"title":{"type":"string","nullable":true},"workflow_title":{"type":"string"},"workflow_id":{"type":"integer"}},"required":["id","title","workflow_title","workflow_id"]},"assignees":{"type":"array","description":"Assigned users or roles","items":{"type":"object","properties":{"user_id":{"type":"integer","nullable":true},"email":{"type":"string","format":"email","nullable":true},"role_id":{"type":"integer","nullable":true},"name":{"type":"string","nullable":true}}}},"subtasks":{"type":"array","description":"Array of subtasks (only present when step has subtasks)","items":{"$ref":"#/components/schemas/Subtask"}},"_links":{"type":"array","description":"HATEOAS links describing possible actions","items":{"$ref":"#/components/schemas/LinkObject"}}},"required":["id","title","header_step","run"]},"RunSubStep":{"type":"object","properties":{"id":{"type":"integer","description":"Step ID"},"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"Whether this is a header step"},"kind":{"type":"string","enum":["standard","stop_task","approval"],"description":"The kind of step. `stop_task` blocks downstream steps in its scope until completed. `approval` requires a reviewer-recorded decision via the approval flow before completion."},"blocked_by_stop_task":{"type":"boolean","description":"True when an upstream `stop_task` in the same run is still incomplete and is gating this substep."},"blocking_run_step_id":{"type":"integer","nullable":true,"description":"When `blocked_by_stop_task` is true, the run step ID of the stop task that must be completed to unlock this substep. Null when not blocked."},"completed_at":{"type":"string","format":"date-time","description":"When the step was completed","nullable":true},"_links":{"type":"array","description":"HATEOAS links related to this run step","items":{"type":"object","properties":{"rel":{"type":"string","description":"Link relation"},"href":{"type":"string","description":"Link URL"},"method":{"type":"string","description":"HTTP method"}},"required":["rel","href","method"]}}},"required":["id","title","header_step"]},"StepSubStep":{"type":"object","properties":{"id":{"type":"integer","description":"Step ID"},"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"Whether this is a header step"}},"required":["id","title","header_step"]},"Subtask":{"type":"object","description":"Subtask in run context (includes completion fields)","properties":{"id":{"type":"integer","description":"Subtask ID"},"title":{"type":"string","description":"Subtask title"},"position":{"type":"integer","description":"Position within the step"},"completed_at":{"type":"string","format":"date-time","description":"When the subtask was completed (only present in run context)","nullable":true},"completed_by_id":{"type":"integer","description":"User ID who completed the subtask (only present in run context)","nullable":true}},"required":["id","title","position"]},"WorkflowSubtask":{"type":"object","description":"Subtask in workflow context (no completion fields)","properties":{"id":{"type":"integer","description":"Subtask ID"},"title":{"type":"string","description":"Subtask title"},"position":{"type":"integer","description":"Position within the step"}},"required":["id","title","position"]},"Step":{"type":"object","properties":{"id":{"type":"integer","description":"Step ID"},"title":{"type":"string","description":"Step title"},"header_step":{"type":"boolean","description":"Whether this is a header step"},"kind":{"type":"string","enum":["standard","stop_task","approval"],"description":"The kind of step. `stop_task` blocks downstream steps in its scope until completed. `approval` requires a reviewer-recorded decision via the approval flow before completion."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"step_data_setting":{"type":"object","nullable":true,"description":"Data collection settings for this step","properties":{"id":{"type":"integer","description":"Data setting ID"},"label":{"type":"string","nullable":true,"description":"Data setting label"},"value_format":{"type":"string","enum":["text","list","date","number","file","image","signature","url","email","paragraph","phone"],"description":"Type of data to collect"},"value_format_config":{"type":"object","description":"Additional configuration for the data format","additionalProperties":true},"required":{"type":"boolean","description":"Whether this data setting is required"}},"required":["id","value_format","value_format_config","required"]},"substeps":{"type":"array","description":"Array of substeps (only present for header steps when page parameter is provided)","items":{"$ref":"#/components/schemas/StepSubStep"}},"subtasks":{"type":"array","description":"Array of subtasks (only present when step has subtasks)","items":{"$ref":"#/components/schemas/WorkflowSubtask"}},"_links":{"type":"object","description":"Pagination links for substeps (only present for header steps)","additionalProperties":{"$ref":"#/components/schemas/LinkObject"}},"content":{"type":"array","description":"Structured content objects attached to this step (text, images, files, videos).","items":{"$ref":"#/components/schemas/ContentObject"}}},"required":["id","title","header_step"]},"RunWithSteps":{"allOf":[{"$ref":"#/components/schemas/Run"},{"type":"object","properties":{"run_steps":{"type":"array","description":"Paginated array of run steps","items":{"$ref":"#/components/schemas/RunStep"}}},"required":["run_steps"]}]},"Department":{"type":"object","properties":{"id":{"type":"integer","description":"Department ID"},"name":{"type":"string","description":"Department name"}},"required":["id","name"]},"DepartmentMember":{"type":"object","properties":{"id":{"type":"integer","description":"User ID"},"email":{"type":"string","description":"User email address"},"name":{"type":"string","nullable":true,"description":"User display name"},"role":{"type":"string","enum":["admin","user","member","limited"],"description":"Role within the department"}},"required":["id","email","role"]},"DepartmentDetail":{"type":"object","properties":{"id":{"type":"integer","description":"Department ID"},"name":{"type":"string","description":"Department name"},"members":{"type":"array","description":"Members of the department","items":{"$ref":"#/components/schemas/DepartmentMember"}}},"required":["id","name","members"]},"DepartmentCollection":{"type":"object","properties":{"departments":{"type":"array","items":{"$ref":"#/components/schemas/Department"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["departments","meta"]},"User":{"type":"object","properties":{"id":{"type":"integer","description":"User ID"},"email":{"type":"string","description":"User email address"},"name":{"type":"string","nullable":true,"description":"Display name"},"username":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true,"description":"Avatar image URL"},"simple_display_name":{"type":"string","description":"Name if present, otherwise email"},"memberships":{"type":"array","description":"Memberships within the master account","items":{"type":"object","properties":{"id":{"type":"integer","description":"Membership ID"},"department_id":{"type":"integer","description":"Department (account) ID"},"department_name":{"type":"string","description":"Department name"},"role":{"type":"string","enum":["admin","user","member","limited"],"description":"Role within the department"}},"required":["id","department_id","department_name","role"]}}},"required":["id","email","simple_display_name","memberships"]},"UserCollection":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["users","meta"]},"Comment":{"type":"object","properties":{"id":{"type":"integer"},"comment_with_links":{"type":"string","description":"Comment body rendered with HATEOAS links"},"created_at":{"type":"string","format":"date-time"},"user":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"]}},"required":["id","comment_with_links","created_at"]},"ContentObject":{"type":"object","description":"A content object attached to a step","properties":{"type":{"type":"string","enum":["text","image","file","video"],"description":"Content type"},"value":{"type":"string","description":"Text value (only present when type is \"text\")","nullable":true},"url":{"type":"string","description":"URL of the asset (present for image, file, video types)","nullable":true},"filename":{"type":"string","description":"Original filename (only present for file type when available)","nullable":true}},"required":["type"]},"DataCollectionDisabled":{"type":"object","description":"Data collection is disabled for this step","properties":{"enabled":{"type":"boolean","enum":[false]}},"required":["enabled"],"additionalProperties":false},"DataCollectionList":{"type":"object","description":"Data collection settings for list-type steps","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean","nullable":true},"value_format":{"type":"string","const":"list"},"config":{"type":"object","properties":{"values":{"type":"array","description":"Allowed list values","items":{"type":"string"}},"value_selection_type":{"type":"string","enum":["single","multi"]},"input_format_hint":{"type":"string","description":"Client hint for multi-select list format","nullable":true}},"required":["values"],"additionalProperties":false}},"required":["enabled","config"]},"DataCollectionOther":{"type":"object","description":"Data collection settings for non-list steps","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean","nullable":true},"value_format":{"type":"string","enum":["text","date","number","file","image","signature","url","email","paragraph","phone"],"nullable":true},"config":{"type":"object","nullable":true,"additionalProperties":false,"description":"No config for non-list formats"}},"required":["enabled","value_format"]},"StepDataSetting":{"type":"object","properties":{"id":{"type":"integer","description":"Data setting ID"},"label":{"type":"string","nullable":true,"description":"Data setting label"},"value_format":{"type":"string","enum":["text","list","date","number","file","image","signature","url","email","paragraph","phone","datetime","choose_from_data_table"],"description":"Type of data to collect"},"value_format_config":{"type":"object","description":"Additional configuration for the data format","additionalProperties":true,"nullable":true},"data_table_options":{"type":"array","description":"Available display values for choose_from_data_table fields. Submit one of these strings as the field value; the server resolves the matching data table row automatically. Only present when value_format is choose_from_data_table.","items":{"type":"string"}}},"required":["id","value_format"]},"StepDataSettingCreate":{"type":"object","properties":{"label":{"type":"string","nullable":true,"description":"Data setting label (max 75 characters)"},"value_format":{"type":"string","enum":["text","list","date","number","file","image","signature","url","email","paragraph","phone","datetime","choose_from_data_table"],"description":"Type of data to collect"},"required":{"type":"boolean","description":"Whether this data field is required","nullable":true},"value_format_config":{"type":"object","description":"Configuration for the data format.\n\nFormat 'list' supports:\n- values (array of strings): List of allowed values\n- value_selection_type ('single' or 'multi'): Selection mode\n\nFormat 'choose_from_data_table' supports:\n- data_table_id (integer): ID of the data table whose rows back this field\n- display_column_id (integer): ID of the column whose value is shown to users\n\nFormat 'number' supports:\n- min (number): minimum allowed value (inclusive)\n- max (number): maximum allowed value (inclusive)\n- max_decimal_places (integer, \u003e= 0): maximum number of digits after the decimal point\n- allow_negative (boolean, default true): when false, negative values are rejected\n\nAll other formats (text, date, file, image, etc.) do not support any config keys and should be omitted or set to {}.\nInvalid keys are silently filtered out.","additionalProperties":true,"nullable":true}},"required":["value_format"],"example":{"label":"Priority","value_format":"list","required":true,"value_format_config":{"values":["Low","Medium","High","Critical"],"value_selection_type":"single"}}},"StepDataSettingConfigList":{"type":"object","description":"Configuration for list format data settings. Only list format supports value_format_config keys.","properties":{"values":{"type":"array","items":{"type":"string"},"description":"Array of allowed list values","example":["Low","Medium","High"]},"value_selection_type":{"type":"string","enum":["single","multi"],"description":"Whether user can select single or multiple values","example":"single"}}},"DataTable":{"type":"object","description":"Account-level reference table backing the choose_from_data_table step field format.","properties":{"id":{"type":"integer"},"name":{"type":"string","description":"Display name of the data table"},"account_id":{"type":"integer","description":"Owning department (account) ID. May be the master account ID when shared across departments."},"master_account_id":{"type":"integer","description":"Master account that owns this table"},"in_use":{"type":"boolean","description":"True when the table is referenced by at least one step data setting (blocks deletion)."},"columns_count":{"type":"integer","description":"Number of columns on the table"},"rows_count":{"type":"integer","description":"Number of rows on the table"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"_links":{"type":"array","items":{"$ref":"#/components/schemas/LinkObject"}}},"required":["id","name","account_id","master_account_id"]},"DataTableCollection":{"type":"object","properties":{"data_tables":{"type":"array","items":{"$ref":"#/components/schemas/DataTable"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data_tables","meta"]},"DataTableColumn":{"type":"object","properties":{"id":{"type":"integer"},"data_table_id":{"type":"integer"},"name":{"type":"string","description":"Display name of the column"},"internal_key":{"type":"string","description":"Stable machine-readable key for the column (lowercase letters, numbers, underscores). Used as the cell key in row payloads."},"column_type":{"type":"string","enum":["text","number","date","boolean","email","url"],"description":"Column data type. The API stores cell values as strings regardless of column_type; per-type validation is not enforced."},"position":{"type":"integer","description":"Zero-indexed display order"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","data_table_id","name","internal_key","column_type","position"]},"DataTableRow":{"type":"object","properties":{"id":{"type":"integer"},"data_table_id":{"type":"integer"},"cells":{"type":"object","description":"Cell values keyed by column internal_key.","additionalProperties":{"type":"string","nullable":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","data_table_id","cells"]}}},"security":[{"bearer_auth":[]}]}