The Non-Agent API vs the Agent API: which one you need

You found two VICIdial APIs and you are not sure which one to call. Both take a web address with a function parameter, both reply in plain text, and both want a username and password. The difference is what they touch: one drives a live agent on screen, the other does not.

Two files, two jobs

VICIdial ships the two APIs as two separate PHP files. They share a calling style on purpose, but they were built for different audiences: one for back-office automation, one for live agent control. Knowing which file to point at saves you from chasing errors that are really just the wrong endpoint.

The Non-agent API lives at /vicidial/non_agent_api.php and handles everything not tied to the agent screen: adding a Lead, listing campaigns, reading the Hopper, or pulling a list of audio files. It is the back-office API.

The Agent API lives at /agc/api.php and acts on a specific logged-in agent. It dials a number for them, pauses them, hangs up a call, or changes their disposition — the same things the buttons on the agent screen do. If the named agent is not logged in, those calls fail with a clear message saying so.

The naming is the giveaway. A Non-Agent API call never identifies a live agent to act on; it works on stored data and settings. An Agent API call almost always carries an agent_user parameter, because the whole point is to drive that one person's screen and their active Session ID.

How to decide

flowchart TD
    A[What is your task?] --> B{Acts on a logged in agent?}
    B -->|Yes| C[Agent API at /agc/api.php]
    B -->|No| D{Touches leads, lists or settings?}
    D -->|Yes| E[Non-Agent API]
    D -->|No| F[Non-Agent API for reports and lookups]

Say you want to import a fresh batch of contacts each morning. No agent is on a call yet, so that is the Non-Agent API and its add_lead function. Now say a customer clicks call-me on your website and you want a specific agent to dial them right away. That agent is logged in, so that is the Agent API. Some jobs even use both in sequence: the Non-Agent API drops the contact into an Ingroup, then the Agent API tells a logged-in agent to take it.

What they share

Both APIs need an API-enabled VICIdial user, both can run over HTTPS when your web server is configured for it, and both answer with a line that starts with SUCCESS or ERROR plus an explanation. Both also live behind the same permission model, so the user level and checkboxes on your account decide what each one will let you do. So once you can read one, you can read the other. If you mostly drive agents, start with the Agent API guide; if you are wiring up a CRM feed, the Non-Agent API is your home base.

For how both fit alongside the Asterisk Gateway Interface and the wider integration story, read the VICIdial API and AGI overview. Both APIs come ready on every managed VICIfast server, so you can pick the right one and start building — check the pricing page for the details.