Validate, sandbox, and publish
The runtime validator refuses what will not run; the sandbox actually executes the draft; publish promotes the version that goes live.
Updated on Aug 10, 2026
Between creating and going to production there are three steps — all over the API:
- Validate: the workflow is checked by the runtime itself (graph, fields of each node, models in the catalogue).
- Sandbox: the draft actually runs, with
"version": "draft"on/run— without touching the published version. - Publish: the valid draft becomes the version that
/run, the widget, and A2A serve.
https://agents.hinow.ai/v1/agents/validateBearer hi_YOUR_API_KEYValidates a standalone workflow (dry run). Nothing is created or changed — ideal for CI, or for validating while the user edits.
Parâmetros
workflowobject· bodyobrigatórioThe `{nodes, edges}` graph to validate.
Respostas
{
"valid": false,
"errors": [
{"code": "missing_start", "message": "workflow needs exactly one 'start' node"},
{"code": "unknown_model", "message": "model 'gpt-4-fake' not found in the catalog (see GET https://api.hinow.ai/v1/models)"}
],
"warnings": [
{"code": "missing_end", "message": "no 'end' node: the run finishes at the first node without outgoing edges"}
]
}Errors prevent saving and publishing; warnings do not block — they point at behaviour that is probably unintended (an unreachable node, a tool with no slot, an if with no false branch). Each item carries a stable code, the message and, where it makes sense, the node_id.
| Some error codes | Cause |
|---|---|
missing_start / multiple_start | The flow needs exactly one start node. |
unknown_node_type | A node type the runtime does not know — the full list is in Builder cards. |
edge_source_missing / edge_target_missing | An edge pointing at an id that does not exist in nodes. |
tool_needs_slot / flow_into_tool | A tool wired as if it were flow — it connects to the agent's targetHandle: "slot-N". |
if_no_condition / while_no_condition | A control node without the condition that drives it. |
participants_missing | Debate/voting/sequential with no participants (static, dynamic, or connected). |
unknown_model | A model slug outside the catalogue — check it at GET https://api.hinow.ai/v1/models. |
The same /run as always, with one extra field. The draft runs for real — same tools, same events, normal billing per inference — but the published version stays untouched, serving production.
curl -X POST https://agents.hinow.ai/v1/agents/SEU_AGENT_ID/run \
-H "Authorization: Bearer hi_SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "teste do rascunho", "version": "draft", "stream": false}'The sandbox validates the draft on the spot: if it was broken afterwards (by editing in the builder, for instance), /run with version: "draft" answers 422 with the report — instead of executing something that would fail halfway.
https://agents.hinow.ai/v1/agents/{agent_id}/publishBearer hi_YOUR_API_KEYRevalidates the draft and promotes it to the published version. The switch is atomic: runs in progress finish on the old version; the next ones pick up the new one.
Parâmetros
agent_iduuid· pathobrigatórioThe agent to publish.
Respostas
{
"agent": {
"id": "ddfe14bd-4bfb-4d6a-83a0-4e907278ad10",
"name": "Pesquisador Web",
"status": "published",
"published_version": 2,
"published_at": "2026-08-10T10:24:13Z",
"has_unpublished_changes": false
}
}Once published, the draft stays free: edit at will (has_unpublished_changes turns true), test in the sandbox, and publish again when it is ready. Production only changes on publish.