# Deepvue Workflows

## Documentation

- [Deepvue Workflows API Docs - Verification Journeys, Runs & Reports](https://docs.deepvue.link/introduction.md): Trigger multi-step verification journeys with one API call. Start runs, poll to completion, resolve human reviews, and pull signed verification reports.
- [Quickstart - Your First Verification Run in 5 Minutes](https://docs.deepvue.link/quickstart.md): Get started with the Deepvue Workflows API in minutes. Find a workflow, start a run, send your customer to the journey, and read the result with cURL, Python, or Node.js.
- [Docs Search MCP - Connect AI Tools to the Workflows Docs](https://docs.deepvue.link/mcp-server.md): Connect Claude, Cursor, or any MCP client to the Deepvue Workflows documentation. Search the API reference from your AI coding tools without leaving your editor.
- [Conventions & Object Schemas - Deepvue Workflows API](https://docs.deepvue.link/concepts.md): Reference for Workflows API conventions and object shapes. Timestamps, the list envelope, absent versus null, and the Workflow, Run, Check, and ReviewFlag schemas.
- [Run Status Lifecycle - Six Statuses & Terminal States](https://docs.deepvue.link/run-lifecycle.md): Understand the six Deepvue Workflows run statuses, which are terminal, and how abandoned differs from expired. Includes filtering rules and read-time computation.
- [Reviews & Decisions - The Human Verdict Queue](https://docs.deepvue.link/reviews.md): Work the Deepvue Workflows review queue. Learn how the decision axis differs from status, what flags a run for review, and how to record a verdict that settles it.
- [Verification Reports - JSON Content Model & PDF](https://docs.deepvue.link/reports.md): Read a Deepvue Workflows verification report as JSON for your own UI, or as a rendered PDF for archiving. Includes the full content model and presence rules.
- [Webhooks - Run Lifecycle Events](https://docs.deepvue.link/webhooks.md): Configure a Deepvue Workflows lifecycle webhook to be notified when a run reaches a terminal status, instead of polling. Includes setup and what does not fire.

## API Reference

- [Authentication - Client ID & API Key](https://docs.deepvue.link/authentication.md): Learn how to authenticate with the Deepvue Workflows API using your client ID and API key headers. Includes code examples and failure handling.
- [Error Codes & Troubleshooting Guide](https://docs.deepvue.link/errors.md): Complete reference for Deepvue Workflows API errors. Learn the transport error envelope, the five run error codes, and which failures are worth retrying.
- [List workflows](https://docs.deepvue.link/get-v1-workflows.md): Returns the workflows available to your account.
- [Get one workflow](https://docs.deepvue.link/get-v1-workflows-id.md): Returns the workflow plus `steps` - every check key that can appear in a run's `checks[]`, so you can build your result mapping before running anything.

`steps` is a superset: workflows branch, so a single run produces a subset of these keys. A key that never arrives means that branch was not taken, not that something failed. Order is indicative, not guaranteed.

- [Set the run-completion webhook](https://docs.deepvue.link/post-v1-workflows-id-webhook.md): Add-only: sets the URL when none is configured, `409` otherwise.

- [Start a run](https://docs.deepvue.link/post-v1-workflows-id-runs.md): Starts a run of the workflow.

For interactive workflows the response blocks briefly and already carries `action_required.url`, so no poll is needed to obtain the link. If the wait times out you receive a non-terminal status with `action_required: null` - poll `GET /v1/runs/{id}` for the link.

- [List runs](https://docs.deepvue.link/get-v1-runs.md): Returned newest first (`started_at` DESC). List shape - `checks`, `reviews`, and the decision fields are deliberately absent; list to find runs, then `GET /v1/runs/{id}` to read results.

`status` and `decision` are independent axes and are AND-ed together. Every pairing is legal; `?status=completed&decision=review` - runs that look finished but are not - is the most useful one.

`?status=failed` does not return expired runs. Query both if you mean "everything that halted badly".

- [Get one run](https://docs.deepvue.link/get-v1-runs-id.md): Detail shape - includes `checks`, `reviews`, and the decision fields.

Pass `?view=report` to replace the response body with the report's content model: the same document `GET /v1/runs/{id}/report.pdf` is printed from, before rendering. Use it to display results in your own UI without parsing a PDF.

- [Get the verification report as PDF](https://docs.deepvue.link/get-v1-runs-id-report-pdf.md): Returns the rendered verification report for a terminal run as a PDF document, suitable for archiving or sharing with the subject.

Operator notes recorded during review are deliberately excluded from this document.

- [Cancel a run](https://docs.deepvue.link/post-v1-runs-id-cancel.md): Cancels a non-terminal run. A cancelled run leaves `?decision=review` and is never reported there again. No request body.

- [Deliver a signal to a run](https://docs.deepvue.link/post-v1-signals-run_id-signal_name.md): Delivers a signal to a run. The signal name comes from `action_required.signal_name` on a non-terminal run; the review signal is `human_review_decision`.

One route, two behaviours, and the response says which. If the run is parked on a review step, this delivers the signal and the workflow advances - `"result": "signal_delivered"`. If the run has already finished, it records an annotation and nothing advances - `"result": "review_recorded"`. Never infer which happened from the run's state; read `result`.

The verdict is the run's - there is no `node_id`, and sending one is a `400`, not an ignored field. Re-deciding is allowed and overwrites the previous verdict. Recording a verdict does not change `status` or `completed_at`, does not re-run anything, and fires no webhook.

Both credential types work on this route: `client-id` + `x-api-key`, or a dashboard Bearer token.