API Documentation — Content.One Agent

Content.One Agent API

The Content.One Agent API provides programmatic access to an AI-powered assistant for Zesty.io CMS instances. It can create content, edit templates, manage schemas, generate images, install integrations, add comments, and more — all via a single conversational endpoint.

All endpoints are JSON-based. Requests use Content-Type: application/json and responses return JSON objects with an ok boolean field.

Authentication

Most endpoints require a Zesty.io Instance ZUID and Developer Token. These can be provided in two ways:

Request body — pass instance_zuid and instance_token in the JSON body (POST/PUT endpoints).

Query + Header — pass ?instance_zuid=... as a query parameter and Authorization: Bearer <token> as a header (GET endpoints).

If omitted, the server falls back to the ZESTY_INSTANCE_ZUID environment variable (where configured).

Base URL

https://agent.content.one

All endpoint paths below are relative to this base URL.

Messaging

Send messages to the AI agent and manage in-flight requests.

POST /client/message Send a message to the AI agent

The primary conversational endpoint. Sends a user message (with optional attachments) to the agent, which parses intent, routes to the appropriate sub-agent, and returns a structured response.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Zesty instance ZUID (e.g. `8-xyz...`)
`instance_token`	string	Yes	Zesty developer token
`message`	string	Yes*	The user's message. *Required unless attachments are provided.
`requestId`	string	No	Client-generated request ID for log streaming. Auto-generated if omitted.
`lang`	string	No	Language code (`en`, `es`, `nl`). Affects AI response language.
`attachments`	array	No	Up to 10 file attachments. Each: `{ name, type, data }` where `data` is base64. Max 20MB each.
`zpw`	string	No	Preview lock password for gated WebEngine previews.

Example Request

curl -X POST https://agent.content.one/client/message \
  -H "Content-Type: application/json" \
  -d '{
    "instance_zuid": "8-abcdef1234",
    "instance_token": "your-developer-token",
    "message": "Write a blog post about sustainable farming"
  }'

Response

Returns an ok boolean, a message (markdown), and action-specific fields depending on the agent that handled the request:

{
  "ok": true,
  "message": "I've created a new article about sustainable farming...",
  "previewUrl": "https://xyz.preview.zesty.io/blog/sustainable-farming/",
  "approveUrl": "/client/approve?modelZuid=6-...&itemZuid=7-...&version=1",
  "durationMs": 4523
}

Additional response fields may include: viewZuid, modelZuid, pendingSchema, pendingScript, discoveryResults, mediaResults, codeSearchResults, blockResults, headTagResults, settingsResults, commentResults, mediaUrl, showHelp, and more.

POST /client/cancel Cancel an in-flight request

Aborts a running agent request by its request ID.

Request Body

Parameter	Type	Required	Description
`requestId`	string	Yes	The request ID to cancel (from the original `/client/message` call).

// Response
{ "ok": true }

History & Logs

Retrieve conversation history, streaming logs, and token usage data.

GET /client/history/:instanceZuid Get message history

Returns the full conversation history for a given instance, including messages, responses, preview URLs, and all agent-specific result data.

Path Parameters

Parameter	Type	Description
`instanceZuid`	string	The Zesty instance ZUID.

{
  "ok": true,
  "messages": [
    {
      "message": "Write a blog post about tomatoes",
      "response": "I've created a new article...",
      "previewUrl": "https://...",
      "approveUrl": "/client/approve?...",
      "durationMs": 3200,
      "timestamp": 1709834400000
    }
  ]
}

GET /client/logs/:requestId Stream logs (SSE)

Server-Sent Events (SSE) endpoint that streams real-time console logs for a running request. Connect before sending /client/message to capture all logs.

Path Parameters

Parameter	Type	Description
`requestId`	string	Client-generated request ID matching the upcoming `/client/message` call.

Example

const evtSource = new EventSource(
  'https://agent.content.one/client/logs/my-request-123'
);
evtSource.onmessage = (e) => {
  const log = JSON.parse(e.data);
  // { level: 'info', message: '...', timestamp: ... }
  // Final event: { level: 'done', message: 'Request complete' }
};

GET /client/stored-logs/:instanceZuid Get stored logs

Returns all persisted logs for a given instance, grouped by request ID.

{ "ok": true, "logs": [ { "requestId": "...", "logs": [...] } ] }

GET /client/stored-tokens/:instanceZuid Get token usage

Returns stored token usage data for a given instance, including per-request breakdowns of input/output tokens across Claude and DALL-E calls.

{
  "ok": true,
  "tokens": [
    {
      "requestId": "abc-123",
      "calls": [
        { "function": "parseIntent", "input_tokens": 450, "output_tokens": 80 },
        { "function": "generateContent", "input_tokens": 2100, "output_tokens": 1500 }
      ],
      "prompt": "Write a blog post about tomatoes",
      "durationMs": 4200
    }
  ]
}

Publishing

Approve and publish content items and code views.

GET /client/approve Publish a content item

One-click publish endpoint for content items. Publishes a specific version of a content item.

Query Parameters

Parameter	Type	Required	Description
`modelZuid`	string	Yes	Content model ZUID
`itemZuid`	string	Yes	Content item ZUID
`version`	string	No	Version number (default: `1`)
`instance_zuid`	string	No	Instance ZUID override

Headers

Authorization: Bearer <developer-token>

{ "ok": true, "message": "Item 7-abc123 published successfully." }

GET /client/approve-view Publish a code view

Publishes a code view/template by fetching its latest version and posting to the versions endpoint.

Query Parameters

Parameter	Type	Required	Description
`viewZuid`	string	Yes	View/template ZUID
`instance_zuid`	string	No	Instance ZUID override

Headers

Authorization: Bearer <developer-token>

{ "ok": true, "message": "View 11-abc123 published successfully.", "data": { ... } }

POST /client/mark-approved Record approval in history

Records that a message was approved (published) so the UI shows a disabled "Approved" state on reload.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`timestamp`	number	Yes	Message timestamp to mark
`approvedAt`	number	No	Approval timestamp (defaults to now)

{ "ok": true }

Schema & Integration

Confirm pending schemas and install scripts/stylesheets.

POST /client/schema/confirm Confirm and create a schema

Creates a content model and its fields from a previously proposed pendingSchema object (returned by the schema agent via /client/message).

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`instance_token`	string	Yes	Developer token
`pendingSchema`	object	Yes	The schema proposal object from the agent response

{
  "ok": true,
  "message": "Created model 'Articles' with 8 fields and template code.",
  "modelZuid": "6-abc123",
  "viewZuid": "11-def456"
}

POST /client/integration/confirm Install a script/stylesheet

Installs a script or stylesheet snippet into a Zesty view template. Supports head or body position, global or model-specific scope.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`instance_token`	string	Yes	Developer token
`snippet`	string	Yes	The HTML snippet to install (script/link tags)
`position`	string	No	`head` or `body`
`scope`	string	No	`global` or `model`
`modelZuid`	string	No	Target model ZUID (when scope is `model`)
`modelName`	string	No	Target model name for display

{ "ok": true, "viewFileName": "loader", "viewZuid": "11-..." }

DELETE /client/headtag Delete a head tag

Removes a head tag (script, link, meta) from the instance.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`instance_token`	string	Yes	Developer token
`headtag_zuid`	string	Yes	ZUID of the head tag to delete

{ "ok": true, "message": "Head tag 21-abc123 deleted." }

Instance Data

Fetch instance configuration, models, views, and domain info.

GET /client/instance-data Get instance settings and metadata

Fetches instance settings indexed by category, the preview lock password, and the instance name. Called by the frontend at load time.

Query Parameters

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID

Headers

Authorization: Bearer <developer-token>

{
  "ok": true,
  "settings": { "general": { ... }, "seo": { ... } },
  "zpw": "preview-password-or-null",
  "instanceName": "My Zesty Instance"
}

GET /client/models List content models

Returns all non-block content models for the instance. Used by pickers like "Add Block to Model".

Query & Headers

?instance_zuid=... + Authorization: Bearer ...

{
  "ok": true,
  "models": [
    { "ZUID": "6-abc", "name": "articles", "label": "Articles", "type": "templateset" }
  ]
}

GET /client/views List template views

Returns all editable template views for the instance.

Query Parameters

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`all`	string	No	Set to `true` to include views without a content model association

Headers

Authorization: Bearer <developer-token>

{
  "ok": true,
  "views": [
    { "fileName": "articles", "ZUID": "11-abc123" }
  ]
}

GET /client/webengine-domain Get WebEngine preview domain

Returns the WebEngine preview domain for building preview URLs.

Query & Headers

?instance_zuid=... + Authorization: Bearer ...

{ "ok": true, "domain": "abc123.preview.zesty.io" }

Blocks

Manage block components and model associations.

POST /client/block/add-to-model Add a block selector field to a model

Creates a block_selector field on a target content model, allowing editors to attach blocks to content items.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`instance_token`	string	Yes	Developer token
`block_name`	string	Yes	Block model name (e.g. `hero_banner`)
`target_model_zuid`	string	Yes	ZUID of the model to add the field to

{
  "ok": true,
  "fieldName": "hero_banner_block",
  "fieldLabel": "Hero Banner Block",
  "fieldZuid": "12-abc123",
  "message": "Added \"Hero Banner Block\" field"
}

Context Files

Manage AI context files that guide brand voice, writing style, image direction, and coding standards.

GET /client/context Get AI context files

Fetches all four AI context files (brand, writing, images, coding) from Zesty views. Creates any missing files with empty content.

Query & Headers

?instance_zuid=... + Authorization: Bearer ...

{
  "ok": true,
  "context": {
    "brand":   { "ZUID": "11-...", "fileName": "/-/ai/context/brand.md",   "code": "...", "lastEdited": "..." },
    "writing": { "ZUID": "11-...", "fileName": "/-/ai/context/writing.md", "code": "...", "lastEdited": "..." },
    "images":  { "ZUID": "11-...", "fileName": "/-/ai/context/images.md",  "code": "...", "lastEdited": "..." },
    "coding":  { "ZUID": "11-...", "fileName": "/-/ai/context/coding.md",  "code": "...", "lastEdited": "..." }
  }
}

PUT /client/context Update an AI context file

Saves an AI context file back to Zesty. The content is stored as a view file and used by agents to guide content generation.

Request Body

Parameter	Type	Required	Description
`instance_zuid`	string	Yes	Instance ZUID
`viewZuid`	string	Yes	ZUID of the context view to update
`code`	string	No	The new context content (markdown). Defaults to empty.

Headers

Authorization: Bearer <developer-token>

{ "ok": true }

Utility

Health check and system status.

GET /health Health check

Simple health check endpoint to verify the server is running.

{ "status": "ok" }

Agent Actions Reference

When you send a message to /client/message, the agent classifies your intent and routes to a specialized sub-agent. Here are all supported actions:

Create Content

Generate full content items with AI-written text, images, and SEO metadata.

"Write a blog post about sustainable farming"

Edit Content

Search for and edit fields on existing content items.

"Change the homepage title to Hello World"

Edit Template

Modify existing Zesty view/template code with natural language.

"Add a sidebar to the articles template"

Create Template

Generate brand-new view files from scratch.

"Create /components/nav.html with a responsive navbar"

Manage Schema

Create models, add fields, or inspect existing schemas.

"Create an articles model with tags"

Create Block

Build complete block components — schema, fields, template, and seed content.

"Make a hero banner block"

Generate Image

Search media library first, then generate with DALL-E 3 if needed.

"Generate a landscape image of a mountain sunset"

Upload Media

Upload pasted or attached images to the media library.

"Upload this image"

Discover Content

Search for content items, media files, code files, blocks, head tags, or settings.

"Find me an article named Rosie the Riveter"

Install Script

Install Tailwind, Bootstrap, Font Awesome, Google Fonts, or custom tags.

"Install Tailwind CSS"

Create Endpoint

Build JSON API endpoints backed by content models.

"Make a search endpoint for articles"

Comments

Add or view comments on views, models, or content items.

"Add comment to loader: script is installed twice"