Autonnel v0.1.0
Get started

API overview

Autonnel is AI-native — every capability in the admin UI is also a tool an external agent can call.

Autonnel is built AI-native. Every capability you can reach from the admin UI — building funnels, generating pages, managing orders, issuing refunds, uploading media, configuring ad platforms — is also a first-class tool that an external AI agent can call. The API is not a side door bolted onto a human-only product; it is the same surface the product itself runs on, deliberately exposed so that agents can drive autonnel end-to-end.

This means you can hand an autonnel deploy to Claude, Cursor, Windsurf, or your own custom agent and let it run the shop. List orders, refund a stuck payment, draft a new landing page, A/B test a funnel, retune ad creative — all from natural-language instructions, with no human ever opening a tab.

Two transports, one capability surface

The same capabilities are exposed through two transports. Pick whichever fits the caller:

  • MCP server at /api/mcp — for AI agents. Tools are self-describing: an MCP client calls listTools on connect, gets typed schemas, and can immediately invoke them. No prompt engineering for endpoint paths, no hand-written wrappers. See the MCP server page.
  • REST API under /api/v1.1/* — for deterministic integrations (crons, webhooks, scripts, your own backend). Same operations, same auth, same permissions, stable shapes. See External endpoints.

Both transports share the same authentication, the same write-access gate, and the same permission model. They are not identical tool for tool: thirteen of the twenty MCP tools are bridged to REST and run the same schema and handler, while seven are MCP-only. See MCP server for which, and for the older REST endpoints that share a path but not a shape.

What’s exposed

Anything that the admin UI does, the API does. The current capability surface:

CapabilityWhat an agent can do
FunnelsList, fetch, create, update, delete; add, replace and remove steps, and rename a step slug.
PagesList, fetch, create, update, and publish (publishing is a flag on update, not a separate action).
Page templatesList them and read a template’s full Puck JSON, which is the authoritative reference for component shape.
ProductsRead products and variants from the connected ecommerce backend.
MediaUpload by URL, returning a CDN URL for component props. Binary upload is REST-only.
OrdersList orders, and mark one delivered. There is no refund tool.
StatsPer-step funnel conversion, counted by unique user.

Ad platform data is not exposed. Core ads support is token-mode conversion postback only, with no campaign or spend queries.

Tool signatures are introspectable via MCP and documented per-endpoint for REST. You do not need a separate “agent SDK” — the agent reads the schemas at connect time.

Prerequisites

  • An autonnel deploy reachable over HTTP.
  • At least one API key generated under Settings → API Keys. See API keys.

Authentication

Every request — REST or MCP — includes a Bearer token:

Authorization: Bearer <your-api-key>

The token is validated server-side. Only a hash is persisted; the raw token is never stored. Missing, malformed, expired, or unknown tokens return 401 Unauthorized:

{
  "error": {
    "message": "Invalid token",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Possible message values:

  • Missing Authorization header
  • Invalid Authorization header format. Expected: Bearer <token>
  • Empty token
  • API key has expired
  • Invalid token

Write access

Each API key has a writeAccess flag. A read-only key can call any tool that fetches data. A write-access key can additionally create, update, refund, publish, and delete. Calling a write tool with a read-only key returns 403 Forbidden.

This is the right knob for agent safety: give a research agent a read-only key and let it explore freely; give a fulfillment agent a write-access key scoped to the operations it actually needs. You can rotate or revoke any key from Settings → API Keys.

Permissions

API keys inherit the permission model used by the admin UI. The same feature IDs that gate human users (orders.refund, pages.publish, …) also gate API and MCP calls. An agent never has more authority than the human role it was issued under.

Rate limiting

The OSS core does not enforce rate limits. On autonnel SaaS, per-deployment rate limits apply — consult your plan documentation.

Caveats

  • API keys are scoped to a single deployment. A key issued on one deployment is rejected by any other, even within the same autonnel SaaS account.
  • Authorization: Bearer is the only supported auth mode. Query-string tokens are not accepted.
  • MCP tool definitions are stable within an autonnel release. If your agent caches the tool list, refresh after upgrades.
  • A failed MCP tool call still returns HTTP 200 with result.isError set. Only an unknown tool name produces a JSON-RPC error object. See MCP server for the full envelope.