API overview and request format

agaro exposes an authenticated action API under /api/v1. It dispatches the same registered server actions used by the application, so validation, module gates, model permissions, record scope, workspace mutation checks, and activity attribution remain in force.

The Open API and MCP are included in Scale and Enterprise at no extra cost, with no seat to buy or assign. Essentials does not include them, and a trial, the Free plan, or a read only workspace is refused until the workspace has a paid subscription.

Keys are for your own code and systems that call the REST API. AI assistants such as Claude, ChatGPT, and Cursor do not use a key: they connect through MCP by adding a connector URL and signing in with Agaro. See Connect an AI assistant (MCP).

#Create an actor bound key

A workspace Super Admin opens Settings, then the API and MCP tab. The API keys block is the second block on the tab, under Connect an AI assistant (MCP). Old links to /settings/mcp land on it.

1. Confirm the workspace has a paid Scale or Enterprise subscription. No seat is needed: pick an active Super Admin or Manager as the actor.
2. In Create an API key, enter a specific Key name, such as Revenue reporting integration.
3. Under Acts as, choose an active Super Admin or Manager. Every call made with the key has exactly that person's permissions.
4. Under Expires, choose 30 days, 90 days, 1 year, or Never expires.
5. Select Create API key.
6. Copy the plaintext immediately. The reveal reads Your new API key and says it is the only time the full key is shown.

Only the SHA 256 hash is stored. The full key cannot be retrieved after you close the reveal. Prefer an expiring key and rotate it on a schedule.

#Authentication

Current keys encode their workspace route and are bound to one actor. Send the key as a bearer token:

Authorization: Bearer <your-key>

For a JSON body, also send:

Content-Type: application/json

Do not add an actor header to change identity. The actor stored on the key is authoritative, and request headers cannot rebind it.

#Direct action route

Registered actions use this pattern:

POST https://erp.agaro.ai/api/v1/{module}/{action}

Examples of route shape include:

POST /api/v1/clients/list
POST /api/v1/leads/create
POST /api/v1/invoices/recordPayment
POST /api/v1/tasks/complete

Action names and schemas evolve with the product. Use the current registered action surface rather than copying an old list into an integration.

#Request bodies

The canonical body wraps positional action arguments in args:

{
  "args": [
    {
      "companyName": "Example Company"
    }
  ]
}

For a one argument action, the raw input object is also accepted:

{
  "companyName": "Example Company"
}

An action with no arguments can receive an empty body or:

{ "args": [] }

Use args for generated clients because it remains unambiguous when an action takes more than one argument.

#Example request

curl -X POST \
  "https://erp.agaro.ai/api/v1/clients/list" \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  --data '{"args":[]}'

Never place the key in a URL, source repository, browser bundle, analytics event, or shared command history.

#GET and mutation methods

Read actions can be called with GET where the route resolves them as nonmutating. GET accepts an encoded args query parameter or maps query parameters to a single object for supported actions.

Mutating actions cannot be called with GET. Use POST, PATCH, PUT, or DELETE as supported by the route. Sending a body through POST, PATCH, or PUT requires application/json; otherwise the API returns 415 Unsupported Media Type.

Inventory additionally supports namespaced routes such as:

/api/v1/inventory/{entity}/{action}

Some inventory entities also support collection and item conventions for list, create, get, update, and archive or remove.

#Response shape

Actions generally return the same structured result used by the application. A successful action can look like:

{
  "ok": true,
  "data": {}
}

Validation or business failures that return ok: false use HTTP 400 and can include fieldErrors and formError. Dates use their normal JSON representation. Big integer money values are serialized as exact decimal strings rather than losing precision.

#Status codes

Use the returned status and error body. Do not retry a validation or permission failure as if it were a transient network error.

#Rate limits and idempotency

The API limits requests per actor and per workspace. A 429 response includes a 60 second retry hint. Apply bounded exponential backoff and avoid parallel retry storms.

Not every action is idempotent. Retrying a create action can create another business record unless that action has its own deduplication key. For payments, billing, sends, imports, and other high impact writes, keep the provider or action idempotency identifier and check the result before retrying.

#Rotate and revoke

Rotate a key from the key table to issue a new plaintext for the same key record. Rotation invalidates the previous secret immediately. Update the client before its next call.

Revoke a key when the integration is retired or the secret may have been exposed. Revocation is immediate and cannot be undone. Create a new key instead of trying to recover a revoked one.

The Keys in this workspace table shows each key's name, actor, prefix, last used time, call count, expiry, and status, with Rotate and Revoke on each active key.

The Call the API block on the same tab shows the API base URL, the Authorization header, and the Workspace ID, each with a copy button. Keys made now already carry the workspace. An older key also needs it in an x-agaro-workspace-id header, or you can rotate the key.

#Troubleshooting

#A new key returns 402

The workspace must be on a paid, active Scale or Enterprise subscription. On Essentials the response names the plan that includes API and MCP access. A trial, the Free plan, or a lapsed subscription answers with a Subscribe message and a link to Settings → Subscription. Existing keys are kept and work again as soon as the workspace pays.

#A request returns 403 after a role change

Keys use live actor and creator authority. A suspended, removed, deleted, or demoted actor can lose access immediately. A key also cannot act above its creator's current privilege ceiling.

#POST returns 415

Send Content-Type: application/json whenever the request contains a body.

#An action is not found

Internal jobs and provider callback actions are deliberately excluded. Confirm the current registered module and action names and use the supported public integration path.