Skip to content

Create and manage over the API

Full CRUD for agents over REST: create the workflow as JSON, edit the draft, list, delete — all with the same API key.

Updated on Aug 10, 2026

Everything the builder does, the API does: a POST with the workflow JSON creates the agent, a PATCH edits the draft, and publish promotes the version that runs in production. Agents created over the API show up normally in the builder (and vice versa) — it is one cycle, with two interfaces.

Scope comes from your API key: agents belong to the organization and its project, and a key from another project gets a 404.

Nothing invalid gets in

Every workflow you send goes through the runtime validator (the same engine that executes it) before being saved. A workflow that would not work answers 422 with the error report — node by node. See Validate, sandbox, and publish.

The endpoints

MethodEndpointWhat it does
POST/v1/agentsCreates an agent (draft). The workflow is validated.
GET/v1/agentsLists the agents in the key's scope (limit/offset).
GET/v1/agents/{id}Detail, with the draft workflow.
PATCH/v1/agents/{id}Partial edit of the draft. The workflow is validated.
DELETE/v1/agents/{id}Deletes the agent (the published version goes offline).
POST/v1/agents/validateValidates a workflow without saving anything.
POST/v1/agents/{id}/publishPromotes the draft to the published version.

Create

POSThttps://agents.hinow.ai/v1/agentsBearer hi_YOUR_API_KEY

Creates an agent as a draft. Only name is required — you can create it empty and send the workflow later in a PATCH.

Parâmetros

  • namestring· bodyobrigatório

    Name of the agent (2–255 characters).

  • descriptionstring· body

    Free-form description.

  • workflowobject· body

    The `{nodes, edges}` graph — the same format as the builder. Validated before saving; invalid answers `422`.

  • modelstring· body

    Default model for the agent (fallback for agent nodes with no model of their own).

  • system_promptstring· body

    Default prompt (fallback, as in the builder).

  • configobject· body

    Extra settings (temperature and so on), as in the builder.

Respostas

201Agent created as a draft.
{
  "agent": {
    "id": "ddfe14bd-4bfb-4d6a-83a0-4e907278ad10",
    "name": "Pesquisador Web",
    "status": "draft",
    "published_version": 0,
    "has_unpublished_changes": false,
    "workflow": {"nodes": [/* ... */], "edges": [/* ... */]},
    "created_at": "2026-08-10T10:23:45Z"
  }
}
400`name` missing or too short, or a workflow that is not an object.
422The workflow did not pass the validator — nothing was saved.
{
  "error": {"message": "workflow failed validation", "type": "validation_error"},
  "validation": {
    "valid": false,
    "errors": [{"code": "missing_start", "message": "workflow needs exactly one 'start' node"}],
    "warnings": []
  }
}

The workflow JSON

It is the same format the builder saves: nodes (each with id, type, data, and position) and edges linking the ids. Three details account for nearly every beginner error:

  • One start node, and the flow follows the edges to an end node.
  • Tools do not join the flow: a tool node (search, webhook, MCP…) connects to the agent's slot — targetHandle: "slot-1" — and not through an ordinary edge.
  • Tools chain together with sourceHandle: "output": an edge from tool to tool forms a pipeline (for example search → summarize, where the search result is summarized before it goes back to the agent).

The full reference for each node type and its fields is the same as the builder's: Builder cards.

workflow mínimo com busca na webjson
{
  "name": "Pesquisador Web",
  "workflow": {
    "nodes": [
      { "id": "start",    "type": "start",      "data": { "label": "Início", "variables": [] } },
      { "id": "agent-1",  "type": "agent",      "data": { "name": "Pesquisador",
          "model": "hinow/himax",
          "system_prompt": "Você é um assistente de pesquisa. Use a busca na web para fatos atuais." } },
      { "id": "search-1", "type": "web_search", "data": { "config": { "num_results": 5 } } },
      { "id": "end-1",    "type": "end",        "data": { "label": "Fim", "status": "success" } }
    ],
    "edges": [
      { "id": "e1", "source": "start",    "target": "agent-1" },
      { "id": "e2", "source": "search-1", "target": "agent-1", "targetHandle": "slot-1" },
      { "id": "e3", "source": "agent-1",  "target": "end-1" }
    ]
  }
}

Search with summarization

For the agent to receive a summary instead of the raw list of results, chain summarization onto the search: add a summarize node and the edge {"source": "search-1", "sourceHandle": "output", "target": "summarize-1"}. The pipeline runs on every search, billed as part of the same run.

List, read, edit, delete

curl https://agents.hinow.ai/v1/agents?limit=20 \
  -H "Authorization: Bearer hi_SUA_API_KEY"
# → {"agents": [{"id": "...", "name": "...", "status": "draft"}], "total": 3}

The agent object

FieldMeaning
statusdraft (never published) or published (has a live version).
published_versionPublication counter — 0 while it is a draft.
has_unpublished_changestrue when the draft has diverged from the published version: time to [test in the sandbox and publish](/en/api/agents/publish).
workflowThe **draft** graph (the published one runs on /run).

Recommended flow

Create → validate → run the draft with version: "draft" → publish → run. Each step has its own endpoint; nothing goes live unless you say so.

Was this page helpful?