Workspace and keys
An API key belongs to one workspace and sees all of it. Keys are created and revoked by workspace admins in Paramètres → API (Settings → API), with 10 active keys at most; every admin is notified when one is created. A key is revoked automatically when the admin who created it leaves the workspace or stops being an admin. Keys are stored only as a fingerprint: Agentova can’t show a key again after creation. See Security for storing and rotating them. A workspace on the free plan has API access. Access is closed (403 workspace_access_denied) only while the workspace’s subscription is unpaid, paused or incomplete.
There’s no separate test environment: to experiment without touching your real automations, use a workspace dedicated to testing.
Automations
An automation is what makes one of your agents act on a channel. The API lists them all under one shape, whatever the underlying channel:
Not covered in v1: phone agents, the website chatbot itself (it’s an agent, not an automation), scheduled social posts, and builder workflows. An automation that was deleted or turned off in the Agentova app, or whose account is disconnected, doesn’t appear at all.
status is one of active, paused, draft, error. Any internal state the API doesn’t know is exposed as error.
The API builds each automation’s name in English: what the automation does, then the agent’s name, served as it was typed in Agentova — “Comment replies — Support Agent”, “Story replies — …”, “Message replies — …”, “Email replies — …”, “Lead Ads — …”. A CRM source is named after its tool and what it follows — “HubSpot contacts — …”, “Typeform responses — …”. A name is for display: two automations can share one (the same agent on two channels), so to target an automation, always use its id.
Pausing and reactivating
Pausing and reactivating are safe to repeat: pausing an automation that’s already paused, or activating one that’s already active, returns it unchanged — no error, and no new status event. The API answers within 8 seconds. When reactivating takes longer — reconnecting a mailbox, for example — the response shows the status at that moment, and the final status arrives as an Automation status changed event:active, or error if the channel couldn’t be reconnected.
Nothing that arrives during a pause is caught up afterwards, except for Customer.io after a short pause:
Only
active and paused automations can be switched. A draft or error automation is refused (422 automation_not_controllable): fix it in the Agentova app first.
A mailbox can only be used by one active agent, as in the Agentova app: reactivating an email automation whose mailbox another active agent already uses is refused too (422 automation_not_controllable, with details.reason: account_in_use). Detach the mailbox from the other agent in the Agentova app first.
Leads
A lead is created — and Lead created fires — from five places:
A
social or crm lead is created only when the prospect gave an email or a phone number, and only once per person and automation. Its name is what Agentova knows: the Instagram or Facebook username for social, the first and last name from the CRM for crm.
These don’t create leads: the private messages and emails your agents reply to, and comments that don’t lead to contact details. For CRM sources other than Customer.io, the partner service that relays their events doesn’t yet tell Agentova which automation handled a contact: their leads are recorded only when the workspace has a single such CRM automation.
phone is the number as it was typed or captured — it isn’t normalized. custom_fields holds the extra answers of the form; keys starting with _ are internal to Agentova and are never exposed.
GET /leads can filter on source and agent_id. The agent_id of a phone lead is the phone agent, exposed under the same agt_… prefix as the others.
Events
When a failure takes an automation away — revoked access to the account, a mailbox that refuses the sign-in, a channel that can’t be reconnected — the automation leaves the API and a last Automation status changed with the
error status is sent: by the time it arrives, looking the automation up by its ID answers automation_not_found. Deleting an automation or turning it off in the Agentova app sends nothing.
When a disconnected account is reconnected in Agentova, an Automation status changed event with the active status is sent for each automation that comes back.
Webhook subscriptions filter by event type only: a subscriber receives every event of that type in the workspace. Filter on source, agent_id, status… on your side. Events are delivered at least once and in no guaranteed order — see Webhooks & signatures.
Runs
A run is one execution of an automation, with the list of actions it took and their result. Each action’sstatus is success or failed. The run’s own status is success when no action failed (a run without any action is success too), failed when every action failed, and partial otherwise — for example an email reply that couldn’t be sent and was kept as a draft.
Good to know:
- No run when nothing happened. A message your agent finally didn’t answer produces no run.
- Several messages in a row, one run. Messages that arrive together and are answered together make a single run.
- A Lead Ads automation with no action configured still records a run, with the
successstatus and an empty list of actions. While it’s paused, its leads are created but no action runs. - No runs for the website chatbot.
- CRM sources: Customer.io records a run for each contact it acts on. The other CRM sources (HubSpot, Typeform, Close, Monday, ClickUp, Tally, Odoo…) are relayed by a partner service that doesn’t yet tell Agentova which automation handled an event: their runs are recorded only when the workspace has a single such CRM automation. A CRM workflow records one run per action.
- On comments, an action you didn’t configure can show as
success. This is a known limitation. - Runs are kept for 90 days, then deleted.
What v1 doesn’t cover
- Creating, editing or deleting automations; triggering one manually.
- Conversations, contacts, phone calls, meetings, publications, documents.
- Per-key permissions: every key sees the whole workspace.
- Calls from a web browser: the API is server-to-server only (no CORS).