Getting started¶
This page walks you through your first Validance workflow. By the end you will have registered a workflow, uploaded an input file, triggered a run, retrieved the run record, and verified the audit chain.
About fifteen minutes. Uses Validance's hosted evaluation environment at api.validance.io, so there is nothing to install. The endpoint requires credentials; see the note below.
Pre-GA evaluation, credentials required
Validance is pre-GA. The hosted endpoint at api.validance.io requires credentials: every request needs HTTP basic authentication, and unauthenticated requests are refused with 401. Request evaluation access from wiktor.lisowski@validance.io, which is also the address for discussing production access.
What you need¶
curland a terminal, or any HTTP client- Evaluation credentials for
api.validance.io(see the note above) - About fifteen minutes
- A small text file to use as workflow input
Setup¶
export VALIDANCE_API_URL="https://api.validance.io"
export VALIDANCE_API_USER="<your username>"
export VALIDANCE_API_PASSWORD="<your password>"
Check the endpoint is reachable and your credentials work:
You should get a JSON response with "status":"healthy". A 401 means the credentials were
not accepted; a response with no body usually means the header never arrived, so check the
shell quoting. Every command from here on carries the same -u flag.
Step 1: Define a workflow¶
Validance workflows are JSON. Here is a minimal one with a single task that hashes an input file:
{
"name": "hello.hashing",
"version": "1.0",
"tasks": [
{
"name": "hash_file",
"docker_image": "alpine:3.19",
"command": "sha256sum inputs/sample/sample.txt > hash.txt",
"inputs": {},
"output_files": {
"hashed": "hash.txt"
},
"output_vars": {},
"depends_on": [],
"timeout": 60,
"gate": "auto-approve"
}
]
}
Save this as hello.json.
What this workflow does:
- Takes one file at trigger time. Validance stages it into the container at
inputs/<role>/<name>(relative to the task's working directory). The role and name come from the trigger request you'll make in Step 4. - Runs
sha256sumon it and writes the result tohash.txtin the working directory. - Declares
hash.txtas a recorded output (theoutput_filesfield): the engine collects it after the task completes and records its content hash.
It is small on purpose; the goal is to see the full evidence chain end to end, not to do real work yet.
Step 2: Register the workflow¶
curl -X POST \
-u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
-H "Content-Type: application/json" \
-d @hello.json \
"$VALIDANCE_API_URL/api/workflows"
The response includes a definition_hash: the SHA-256 of the canonical JSON of your workflow. The same JSON always produces the same hash; any change produces a different one. This hash is the workflow's identity, and it appears on every run record produced from this definition.
It also includes an action, which is created the first time. Registering the identical JSON again reports unchanged and changes nothing; registering modified JSON under the same name reports versioned and creates a new revision. Workflows has the full vocabulary.
Step 3: Upload an input file¶
echo "hello world" > sample.txt
curl -X POST \
-u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
-F "file=@sample.txt" \
"$VALIDANCE_API_URL/api/files/upload"
The response includes a uri (typically azure://...). Note this URI; you will pass it at trigger time. It also includes two identifiers that will reappear on the run record:
file_hashis the SHA-256 of the bytes: proof of which exact content was processed;upload_hashis the identity of this upload act. The upload itself is an audited event, and any run that later stages this file carries it as provenance.
Step 4: Trigger a run¶
Substitute the uri from Step 3:
curl -X POST \
-u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
-H "Content-Type: application/json" \
-d '{
"input_files": [
{
"role": "sample",
"name": "sample.txt",
"uri": "azure://...replace-with-uri-from-step-3..."
}
]
}' \
"$VALIDANCE_API_URL/api/workflows/hello.hashing/trigger"
The response includes a workflow_hash (16-char hex), a session_hash, and status: "triggered" confirming the run was accepted. The workflow_hash is the run identifier you will use for status and audit queries.
The run itself progresses through pending → running → success (or failed) at the workflow level. The trigger response reports only that the run was accepted; the states appear on the run record you poll in Step 5, where the workflow status is lower case and the per-task states are upper case (PENDING, RUNNING, SUCCESS, FAILED). Compare status case-insensitively rather than against a literal.
Step 5: Wait for completion¶
Poll the run record, addressed by the workflow_hash from Step 4:
curl -s -u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
"$VALIDANCE_API_URL/api/runs/<workflow_hash>"
(The run hash addresses everything in Validance: this record, the files, the logs, and the audit trail you will query next. If you only know the workflow's name, GET /api/workflows/hello.hashing/status returns its latest run.) Once the workflow status reaches success, you have a completed run record including:
workflow_hash, the run identifierworkflow_namestatus: "success"(and per-taskstatus: "SUCCESS")start_time/end_time(UTC, microsecond precision)definition_hash, bound to this run; identifies the exact workflow definition that produced it- For each task:
task_name,task_hash,status,docker_image,start_time,end_time,duration_seconds
The definition_hash you saw at registration is bound to this run. Container image, command, and the per-task hash are recorded automatically.
Step 6: Retrieve the complete run record¶
One call returns every audit event of the run, merged in chronological order. Substitute your workflow_hash:
curl -s -u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
"$VALIDANCE_API_URL/api/audit/<workflow_hash>"
The response contains entity_id, entity_type: "workflow", aggregate: true, total_events, and an events array: the run's story, compiled automatically at run time as each event happened. For this run the sequence reads:
file.uploaded: your upload from Step 3, with its content hash indetails.file_hashworkflow.startedfile.created: the run log is openedtask.started:hash_filetask.status_changed:RUNNINGfile.created: the task's stdout logfile.created: your input staged into the containertask.status_changed:SUCCESStask.completed: the full provenance record (shown below)file.created: the outputhash.txtvariable.set: the output registered as a workflow variableworkflow.status_changed:SUCCESSfile.created: the final run log
Each event is a complete record. Here is a real task.completed (because the walkthrough input is the exact bytes hello world\n, the two content hashes below are the same ones you will see):
{
"id": 273150,
"event_type": "task.completed",
"entity_type": "task",
"entity_id": "cf8ab65b6086452a",
"actor": "system",
"timestamp": "2026-10-21T21:10:38.901553",
"details": {
"command": "sha256sum inputs/sample/sample.txt > hash.txt",
"docker_image": "alpine:3.19",
"docker_image_digest": "sha256:6baf43584bcb78f2e5847d1de515f23499913ac9f12bdf834811a3145eb11ca1",
"duration_seconds": 0.289,
"exit_code": 0,
"input_file_hashes": {
"inputs/sample/sample.txt": "a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447"
},
"output_file_hashes": {
"hash.txt": "4c24f90c0471d30dab8c2a66d677a6b32f094f84388eb3e289c31a2a07ff3d75"
},
"status": "success",
"task_name": "hash_file",
"workflow_hash": "<your workflow_hash>"
},
"event_hash": "a6eef49a58180c84566dded3f7de33a1...",
"previous_event_hash": "884e5e63b53a9dcfcaab062f975a5b85...",
"previous_entity_hash": "884e5e63b53a9dcfcaab062f975a5b85..."
}
Every event carries its actor, a UTC microsecond-precision timestamp, its own hash, and pointers to its predecessors. Every event is recorded against the specific thing it happened to (the run, the task, one particular use of a file, your upload), so the trail contains exactly this run's history. The event count varies slightly with log-file handling; what matters is that the upload, every state transition, every file, and the full task provenance are all present, in order, from one call.
Anchoring the same endpoint on a task hash returns just that task's slice. Anchoring it on a file's content hash (the 64-character SHA-256) answers a different question: every upload and every use of those exact bytes, across all runs. That is the lineage view.
Step 7: Verify the chains¶
Every event is hash-chained to its predecessors, in a global chain (system-wide) and a per-entity chain (this run, this task, this file use). Verification recomputes the hashes and walks the chains:
curl -s -u "$VALIDANCE_API_USER:$VALIDANCE_API_PASSWORD" \
"$VALIDANCE_API_URL/api/audit/<workflow_hash>/verify"
Response (abridged; one record per entity in the run, including each file use):
{
"entity_id": "<workflow_hash>",
"entity_type": "workflow",
"aggregate": true,
"all_intact": true,
"entities": [
{"entity_type": "workflow", "entity_id": "<workflow_hash>", "valid": true, "total_events": 2, "break_at": null, "details": "All hashes verified"},
{"entity_type": "task", "entity_id": "<task_hash>", "valid": true, "total_events": 4, "break_at": null, "details": "All hashes verified"},
{"entity_type": "file", "entity_id": "...", "valid": true, "total_events": 1, "break_at": null, "details": "All hashes verified"}
]
}
all_intact: true is the one-line answer to "has anything in this run's record been altered since it was written?" Each entity's chain is verified independently; if a record had been modified, that entity would report valid: false with break_at pointing at the broken link. Only that entity turns invalid, so you'd know exactly what was touched.
For the system-wide check (every event the engine has ever recorded, one chain), use the anchor-less form:
What you have just demonstrated¶
In the records above, all captured automatically:
| Captured | Where you saw it |
|---|---|
| Exact workflow definition | definition_hash: registration response (Step 2), status (Step 5) |
| Exact run instance | workflow_hash: trigger response (Step 4), status (Step 5), audit (Step 6) |
| Container image used | docker_image: status (Step 5), task.completed details (Step 6) |
| Exact image that ran, by content | docker_image_digest: task.completed details (Step 6). A mutable tag such as alpine:3.19 still resolves to exact bytes afterwards |
| Exact input file by content | file_hash: upload response (Step 3), file.uploaded / file.created / task.completed details (Step 6) |
| Where the input came from | upload_hash: upload response (Step 3); the upload event appears in the run record (Step 6) |
| Exact output file by content | output file_hash: file.created / task.completed details (Step 6), file list (GET /api/files/<workflow_hash>) |
| Exit code per task | exit_code: task.completed details (Step 6) |
| Time of every state change | start_time / end_time per task and per run; event timestamps in the trail |
| Complete run trail, one call | GET /api/audit/<workflow_hash> (Step 6): merged, chronological, no client-side assembly |
| Tamper-evident record | verify endpoints (Step 7): per-run all_intact and global chain verification |
You produced this in seven authenticated HTTP calls without any QA-side instrumentation. It is the substrate the Regulatory mapping page describes in clause-by-clause terms.
Where to go next¶
- Workflows for more on workflow definition and registration
- Tasks for task structure including dependencies, approvals, secrets, and resource constraints
- Audit and evidence for full audit and lineage retrieval
- Regulatory mapping for how the artefacts you just produced map to specific regulatory clauses
- The Python SDK if you would rather construct workflows in Python than write JSON directly