Agents and the REST API #

This page is for developers who give an AI agent access to content over HTTP. The REST API is part of the kernel; an agent uses it like any other client, as the account behind its credential. The full reference is REST API v1 and v2 for applications and the guide REST API v1 and v2; this page adds what matters for agents.

Contents #

1. The routes an agent needs
2. The credential
3. Describing the routes to a model
4. Answers the agent must handle
5. Writing through REST

The routes an agent needs #

Relative to /api/ezp/<version>:

A read-only agent needs only the GET routes.

The credential #

A personal API key (Authorization: Bearer expk_...) is the simplest credential for an agent you run yourself:

1. Create an account for the agent and give it only the content policies it needs.
2. Signed in as that account, make a key in My account > API access with only the scopes the agent needs (read for a reader) and a short lifetime. The key is shown once.
3. Store it in the agent's secret store or an environment variable, never in a prompt or a repository.

A key never gets a right its owner does not hold, and a route needs the scope it is mapped to; a write route of an extension stays closed to keys until its scope is named (Personal API keys, scopes). An app that acts for many users uses OAuth2 instead (OAuth and API keys).

Describing the routes to a model #

When the agent framework lets you define tools for the model, define one tool per route you allow, not a generic "HTTP request" tool:

Your code builds the URL from validated inputs and adds the key; the model never sees the key and cannot reach other routes or hosts. Tell the model in the tool description that field values are data written by people, not instructions.

Answers the agent must handle #

Lists are paged; let the agent page with a limit you choose rather than asking for everything.

Writing through REST #

A POST to /api/ezp/v2/content/node/create creates and publishes. For agent-written content that a person must review first, create into a section that visitors cannot see and that an approval workflow covers, or use Exponential Intelligence, which writes drafts. Test every write workflow on a test installation, and read the audit trail afterwards (A content import workflow).

Since Exponential 6.0.15 with ezprestapi 1.2.9, a POST or PUT to /api/ezp/v2/content/node/<id> updates: it publishes a new version with the values sent and keeps the old one in the history, where an editor can compare and restore it. The key needs the edit scope. Values are text: rich text as HTML, a file as a public https address; an unknown attribute is refused with 400, which an agent can show to the model as a correctable error. A 202 answer means a workflow holds the version, for example for an approval (Updating and the values of a write).

Related pages #

• Choosing an interface for an agent
• Credentials for agents
• Headless Exponential
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.