Building agents — Finn docs

Beta. Building agents by API is switched on per organization. Ask Finn support to turn it on.

Overview

An agent is a Finn Operator workflow: the steps it takes on a case, who it talks to and what it may do. These endpoints list agents, draft and edit them, check a draft and try it in a sandbox. To start real cases on a live agent, see cases.

The API never makes an agent live. A person reviews and publishes it in Finn.

Base URL: https://api.hirefinn.ai/api/v1. Auth: Authorization: Bearer finn_live_..., or a member's token. See authentication.

Scopes: reads need operator:read (or operator:build). Everything else needs operator:build. See scopes.

Endpoints

Method	Path	Scope	What it does
`GET`	`/agents`	`operator:read`	Your agents, most recently updated first. Filter by `status`. Cursor pages.
`GET`	`/agents/{id}`	`operator:read`	One agent with its draft and `draft_rev`.
`POST`	`/agents/draft`	`operator:build`	Turn a plain `description` into a draft graph. Nothing is saved. 10 per minute per key.
`POST`	`/agents`	`operator:build`	Create a draft agent. Pass a drafted `graph` as `draft` to keep it.
`PUT`	`/agents/{id}/draft`	`operator:build`	Replace the draft. The live version keeps running until a person publishes.
`POST`	`/agents/{id}/validate`	`operator:build`	Check the draft. An empty `problems` list means a person could publish it.
`POST`	`/agents/{id}/test`	`operator:build`	Open a sandbox test case on the draft.
`POST`	`/cases/{id}/test/{action}`	`operator:build`	Move a sandbox test case. `action` is `run`, `step`, `reply`, `skip-wait` or `restart`.
`POST`	`/agents/{id}/publish`	none	Always refused for API keys and tokens. Only a signed-in person publishes, in Finn.
`POST`	`/agents/{id}/archive`	`operator:build`	Rolling out. Archive an agent. See below.

Reads share 300 requests per minute per key. Writes share 120 per minute per key.

Safe edits

Send If-Match: "<draft_rev>" with PUT /agents/{id}/draft. If someone changed the draft since you read it, the save is refused with 409. Read the agent again and redo your change.

Send an Idempotency-Key with POST /agents to make a retry safe. See idempotency.

Testing

A test case runs on the draft. Every side effect is faked. No call, message or email leaves Finn, and nothing is written to records. It moves only when you drive it:

run: run until it waits.
step: run one block.
reply: answer as a participant. Send the reply as the JSON body.
skip-wait: skip past a timer.
restart: start again from the top, as a new case.

Live cases are refused.

Archiving (rolling out)

POST /agents/{id}/archive is rolling out and may answer 404 for your organization for now. It archives the agent. Nothing is deleted.

An archived agent takes no new cases: live, test or triggered. It can't be published or paused.
Archiving twice is fine. The second call returns 200 with the same body.
An agent that has a published version needs a person with the publisher or admin role. Others get 403 forbidden.
It takes no body.

Example: draft, save and check an agent

Draft it from a description:

curl -X POST https://api.hirefinn.ai/api/v1/agents/draft \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "When a renewal is 30 days out, email the client, then call if they have not replied in 3 days." }'

{
  "name": "Renewal reminder",
  "graph": { "nodes": [], "edges": [] },
  "notes": ["Asks for the renewal date from the record."],
  "problems": []
}

Save it as a draft agent by passing graph as draft:

curl -X POST https://api.hirefinn.ai/api/v1/agents \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: renewal-reminder-v1" \
  -d '{ "name": "Renewal reminder", "draft": { "nodes": [], "edges": [] } }'

{
  "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "name": "Renewal reminder",
  "status": "draft",
  "draft": { "nodes": [], "edges": [] },
  "draft_rev": 1
}

The graphs are shortened here. A real draft has its steps in nodes and edges. Then call POST /agents/{id}/validate, run a test case, and ask a person to publish it in Finn.