> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentova.ai/llms.txt > Use this file to discover all available pages before exploring further. # Concepts > What the API covers — automations, lead sources, events and runs — and what it doesn't ## 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](https://docs.agentova.ai/en/security.md) 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: | Type | What it does | Channels (`provider`) | | - | - | - | | `social_comments` | Replies to comments on your posts | Facebook, Instagram | | `social_story` | Replies to story replies | Instagram | | `social_messages` | Replies to private messages | Facebook, Instagram, WhatsApp | | `lead_ads` | Handles Lead Ads forms (message to the prospect, add to your CRM) | Facebook, Instagram | | `email_messages` | Replies to emails | Gmail, Outlook, IMAP | | `crm_source` | Acts when a contact or a response arrives in a CRM or a form tool | HubSpot, Close, Monday, ClickUp, Typeform, Tally, Odoo, Customer.io… | **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: | Channel | While paused | When reactivated | | - | - | - | | Emails (Gmail, Outlook, IMAP) | Agentova stops listening to the mailbox — unless another active agent uses the same mailbox. Emails received during the pause **get no reply**. | The mailbox is reconnected. Only the emails that arrive from then on are handled. | | Private messages (Facebook, Instagram, WhatsApp), comments, stories | Whatever arrives is ignored | New messages, comments and story replies are handled again | | Lead Ads | Leads are still saved in Agentova and announced by **Lead created**; only the automation's actions (message, email, call…) are skipped | Actions run again for new leads; the skipped ones are not run afterwards | | CRM sources | Agentova stops reacting to the CRM | Events that happened during the pause are not replayed | | Customer.io | Agentova stops reading the segment (it normally reads it every 15 minutes) | After a pause of more than 6 hours, the segment changes made during the pause are never handled; after a shorter pause, they may be handled when the automation resumes | 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: | Source | Where the lead comes from | | - | - | | `widget` | The contact form of your website chatbot, when a visitor fills it in. Leads created by hand in Agentova, where that option is available, also use `widget`. | | `lead_ads` | A Facebook or Instagram Lead Ads form, handled by a Lead Ads automation — even while that automation is paused | | `telephony` | A phone call qualified by your phone agent | | `social` | A prospect who commented one of your Instagram or Facebook posts, then sent their contact details (email or phone) in a private message to your comment automation | | `crm` | An incoming contact of a connected CRM (HubSpot, Monday, Customer.io…) for which one of your CRM automations ran | 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 | Event | Fires when | What you receive | | - | - | - | | **Lead created** (`lead.created`) | A new lead is captured in your workspace: your website chatbot's contact form, a Lead Ads form, your phone agent, a prospect who sent their contact details after commenting a post, or an incoming CRM contact. Only on creation: a lead that is updated later (for example a chat form submitted twice in the same conversation) doesn't fire again. | The lead: name, email, phone, source, agent, custom fields | | **Run completed** (`run.completed`) | One of your automations has just done something: replied to a message, a comment or an email, handled a Lead Ads form, processed a CRM contact. | The run: which automation, what triggered it, each action with its result (`success` or `failed`), and the overall result of the run (`success`, `partial` or `failed`) | | **Automation status changed** (`automation.status_changed`) | An automation's status really changes, whether the change comes from the Agentova app or from the API: it's paused or reactivated, a CRM source is activated, a failure puts it in `error`, or it comes back `active` once its account is reconnected. | The automation, with its new status | 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](https://docs.agentova.ai/en/guides/webhooks-and-signatures.md#the-delivery). ## Runs A run is one execution of an automation, with the list of actions it took and their result. Each action's `status` 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. | Automation | A run is recorded when… | Trigger (`trigger_type`) | Actions listed | | - | - | - | - | | Private messages (Facebook, Instagram, WhatsApp) | your agent actually sent a reply | `message` | the reply | | Emails (Gmail, Outlook, IMAP) | an incoming email was handled | `email` | the reply sent, or the draft saved | | Comments (Facebook, Instagram) | a comment was handled | `comment` | the public reply, the private message | | Comments (Facebook, Instagram), after the prospect's reply | a prospect sent their contact details in a private message, and the automation's follow-up actions ran | `message` | add to CRM, message to the prospect | | Stories (Instagram) | a story reply was handled | `story_reply` | the reply | | Lead Ads | a form was received and the lead created | `lead_ads` | message to the prospect, add to CRM — the run also carries the lead's ID | | CRM sources | an action ran for an incoming contact | `crm_event` | message (email, WhatsApp), add to CRM — the run also carries the lead's ID when a lead was created | 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 `success` status 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). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.