How we document 162 API endpoints from one source

Behavly can be used in three ways besides clicking through the app. You can ask Behavly Agent in plain words. An AI app such as Claude, ChatGPT or Cursor can connect to Behavly's MCP server and work in your workspace. And your own code can call the REST API. Behind all three is the same list of actions: look up campaigns, create a Pattern Campaign, send an event, draft a reply, and about 160 others.

Three ways in usually means three sets of docs that slowly stop agreeing. This is how we keep one.

One action, one definition

Every action is written once, in one place. Its definition holds its name, a plain description, the exact shape of its input as JSON Schema, what it does to your workspace, and which roles may run it. The chat, the MCP server and the API all read that same definition.

• The name becomes the endpoint: send_event is POST /api/v1/send_event.
• The input schema is what the API checks, what an AI app is told to send, and what the docs list under Body.
• What it does sets the key it needs: a lookup works with a Read only key, a change needs Read & write, and deleting something or sending email to real people waits for your approval.

So a new action shows up in all three places at once, with the same rules, and a field cannot be renamed in one place and forgotten in the others.

Docs that are generated, not written

The API reference is an OpenAPI 3.1 file built from those definitions, at /api/v1/openapi.json, and shown at /api/v1/docs. Nothing in it is typed out by hand per endpoint, so it cannot list an action that does not exist or miss one that does. Each endpoint also says, in one line, what kind of key it needs.

behavly

162

Two readers, two texts

An action's description is written first for an AI model. It tells Behavly Agent when to reach for the action, like “use it when the person asks how a campaign did”, and how to show the result. That is the right text for a model and the wrong one for a developer reading the docs.

So an action can carry a second text, written for developers: the same facts, without the instructions to an AI. The docs show that one, and the AI keeps its own. Today 99 actions have one. Because the two sit side by side in the same definition, whoever changes one sees the other.

An example answer for every endpoint

A list of inputs is only half of an API. You also need to know what comes back. Every endpoint in the reference now shows an example answer traced from the code that builds it: the same keys, the same nesting, and the exact words the API uses for statuses and link labels. Only the values are made up.

Each example was then checked a second time, key by key, against that code. The second pass caught the kind of mistake a reader trusts and a program breaks on: a count that could not add up, a list that showed fewer rows than its total said, a timeline that could not happen.

The same rules everywhere

Because every way in runs the same action, the rules come with it:

• Approvals. Deleting something or sending email to real people answers 202 approval_required with a link, and the key's owner approves or declines it in Behavly within 30 minutes.
• Plan limits. Everything a call does counts toward your plan exactly as if you did it in the app. Over a limit, the answer is 402 with what ran out and where to upgrade.
• Rate limits. 120 requests a minute per key, with a Retry-After header when you go over.
• Your role. A key acts as the person who made it, with that person's role as it is when the call is made.
• The audit log. Every change made through the API or MCP shows in the audit log as via API or via MCP.

Retired, but not broken

When guided one-time campaigns were replaced by Pattern Campaigns, three of their actions were retired: create_campaign, launch_campaign and duplicate_campaign. They are no longer listed in the reference, but they still answer. A call gets 400 invalid_input with the way forward, so an older script or AI app learns what to use instead of hitting an unknown action.

Try it

Every plan can use the API and the MCP server, Free included. Create a key under Settings → API, then start from the API reference, or connect an AI app with the MCP steps.