/v1/agents/…, with the same keys, errors and conventions as the
rest of the API.
- They exist when the account’s plan includes AI agents and they are switched on for
it; otherwise every one answers
404 module_off. - What a key does is recorded as
API · <key name>— in an agent’s activity when its setup changes, and as the reason when it pauses an agent or stops a plan. - Agents, plans and workflow versions have numbers for ids. Contacts and deals are named by the ids they have everywhere else in the API.
Scopes
A key that only approves plans from your own approval tool, say, needs
agents:read and
agents.plans:write. See Keys and scopes.
What stays on the panel
- AI provider keys. The keys your agents use are added, tested and chosen only on the
panel, under AI agents → AI providers and in each agent’s Model & key step. They
are never sent or set over the API: a
PATCHwithcredentialis refused. An agent’sprovidersays which key it uses, never the key itself. - Engaging pipelines. An agent needs at least one pipeline before it can go live; choose them in its Engage step.
- The workflow designer’s helpers — laying out the canvas, Design with AI, the ready-made workflows, test runs, export and import. The API reads, saves and publishes the graph itself.
Setting an agent up
The path to live is the panel’s: create the agent, choose its key and model and engage a
pipeline on the panel, verify, set it up with
PATCH, then activate. PATCH takes
the agent’s instructions, channels, knowledge collections, actions and approvals, when to
plan again, working hours, limits and how it shares conversations with your team.
Changing an agent’s model sends it back to be verified: a live agent becomes a draft
until it passes. When it can’t go live, activate answers 409 invalid_state and lists
what is missing.
Workflows
Saving and publishing need the
revision you read. Someone may be editing the same
workflow on the panel: if they saved since you read it, your save is refused with
409 revision_conflict instead of overwriting their work. Read it again, apply your change
to theirs, and save with the new revision.
issues list them. Publishing needs nothing
broken — anything left is refused with 409 invalid_state.
Knowledge
A good fit for keeping FAQs in step with your own help centre or product catalogue: when
an answer changes there,
PATCH the FAQ. A source is processing until it has been read,
then ready — usually a few seconds later.
Putting agents on contacts
A contact has at most one agent in each role — one sales agent and one support agent, say.
Putting an agent on starts it at once.
run is how your systems tell an agent something
happened — “order A-1042 was delivered today” — and let it decide what to do.
Deciding plans
What you approve is exactly what runs. Before approving you may change a step in the
fields its
editable lists — a message’s wording, a note, an amount — and the edit is
checked again as if the agent had planned it. A rejection’s note is read by the agent the
next time it plans for that contact. A plan nobody decides is dropped after the account’s
approval time, 24 hours by default, rather than run late.
Activity and usage
The tokens are used on your own AI keys and billed by your AI provider; OMNI doesn’t
charge for AI.
Webhook events
Rather than asking, subscribe a webhook endpoint to:
They are sent however it happened — on the panel, through the API, or by the agent
itself.
contact is { "id", "name", "phone" }, with the contact’s id; agent is
{ "id", "name" }.
agent.plan_proposed and the plans endpoints you can put approvals where your team
already works — a chat tool or your own back office — and approve or reject from there.