API ReferenceView as MarkdownOpenAPI

AI builder

View as Markdown

The AI builder makes and changes the site from plain-language requests in any language: one endpoint takes the request, and the answer says what to do next. The guide below walks through it; the endpoints after it are the steps it leads to. Each generation costs AI credits.

Endpoints that need a token: the site owner creates it in their admin (Developers > API reference). AI assistants: how to ask the user for one.

36 endpoints in 7 parts: Ai Orchestrator, Async Job, Chat History, Chat Message, Hero Animation, Planners, Site Wide Edit.

Building with AI

Tell Builderly what you want in plain words, in any language - "add a summer sale coupon for 20% off", "build me a site for my yoga studio" - and the AI builder decides what to make. One endpoint takes every request; you follow what it answers. Every step that generates something spends the account's AI credits.

1. Start a chat

POST /chat-history with an admin token starts a chat and returns { "chatHistory": { "_id": "..." } }. That _id is the chatId of every request below. A chat keeps its history and its language, so keep using the same one for one conversation.

2. Send a request

POST /ai-chat-orchestrator

{ "chatId": "<chatId>", "prompt": "Add a summer sale coupon, 20% off everything", "aiVersion": "fast" }
  • prompt and chatId are required (400 without them).
  • aiVersion is optional: fast, pro or ultra - better results, more credits.
  • One request per chat at a time: a second one while the first runs gets 429.
  • Out of credits: 403.

Every answer has an action, and user_tokens (credits left) and tokens (credits this step spent) where something was spent.

3. Follow the answer

  • RESPONSE - a reply in response: an answer, or a question back ("which product?"). Show it to the user and send their reply as the next prompt in the same chat. suggestions holds next steps the user can pick; send the chosen text as the prompt.
  • REDIRECT - call POST /<target_url> next, with chatId, aiVersion, prompt set to user_prompt, and every other field of the answer except action, target_url, user_prompt, response, chatId, tokens, user_tokens, collect_item_data, navigate_only and message. Its answer is one of these same actions - follow it the same way; one request may redirect twice (generate-blogpost, then create-new-blogpost). To change a particular item, the answer carries item_ids or item_id; pass it on. When navigate_only is true there is nothing to call: message points the user to a screen in their admin. target_url undefined means the request is not something the builder does yet.
  • JOB - the work runs in the background. Poll GET /async-jobs/<async_job._id> every few seconds until complete is true; status is then DONE or Failed. Meanwhile percent and status say how far it is. stalled: true means the build stopped - the chat will offer to resume it. out_of_credits: true means it paused for credits.
  • ERROR - message says why (with 400 or 429).

4. Read the result

A finished job does not carry its result: it is the newest message in the chat. Read GET /chat-message/<chatId>/0/5 (newest first) and take the latest message with role model:

  • OBJECT_RESPONSE - something was generated, in data.object (its kind in data.object_type, the edited item in data.item_id). What happens next depends on data.preview_state:
    • not set: a draft - nothing is saved yet. Show it to the user, then save it with the subject's own endpoint: create it (for example POST /products) or, with data.item_id, update that item (PATCH /products/<item_id>).
    • pending_commit: a change to a page, waiting. POST /commit-about-page-preview with { "chatId", "messageId": <the message _id> } applies it.
    • committed: already saved.
  • PROPOSED_ACTION - a plan waiting for a yes: building a page, or a site in several steps. data.proposed_action.summary lists what it will do. Show it to the user and only go on when they agree - see step 5.
  • RESPONSE - a reply or a question, as above.
  • ERROR - it failed; text says why.

5. Plans: ask first, then run

Pages and multi-step builds are proposed before anything is built:

  • A page (data.proposed_action.type CREATE_PAGE): POST /confirm-page-plan with { "messageId": <the message _id> } builds it. It answers JOB; the page arrives as an OBJECT_RESPONSE draft - save it with POST /about-pages.
  • A plan (RUN_PLAN): POST /confirm-ai-action with { "messageId": <the message _id>, "confirmed": true } runs it; "confirmed": false drops it. Replying "yes" as the next prompt in the chat does the same. A plan saves everything it builds - products, pages, the theme - as it goes; follow its job until complete, then read the chat for the summary.

For AI assistants

  • Use this when the user wants something made or changed and is happy for Builderly's AI to write it. For exact edits you already know - a price, a date, a field - call the subject's endpoints directly: it is faster and costs no AI credits.
  • Always show a PROPOSED_ACTION to the user and wait for their yes before confirming it. Before saving a draft, show what it will create or change.
  • Questions in a RESPONSE are meant for the user: ask them, do not answer them yourself.
  • Keep one chat per conversation. A new chat loses the history the builder relies on ("make it blue" needs the page it just made).

Create an AI chat orchestrator

AI: the chat's entry point: saves the owner's message and runs the agent for it, one turn per chat at a time. Send chatId and prompt. Answers one of the chat actions: RESPONSE (a reply), JOB (work started: poll GET /async-jobs/:id), a proposal to confirm, or ERROR. 429 while the chat already has a turn running; 400 without chatId or prompt. Language, credits and the plan state come from the chat, not the request.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the AI chat orchestrator, in plain words - any language.

originalPromptstring

The AI chat orchestrator's original prompt.

current_page_urlstring

The AI chat orchestrator's current page url.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

attachmentsstring

The AI chat orchestrator's attachments.

Status codes

200 400 401 429 500

POST/ai-chat-orchestrator
curl -X POST 'http://smartman.max-media.io/ai-chat-orchestrator?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "originalPrompt": "...", "current_page_url": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Duplicate a AI

AI: reads a site the owner wants to clone and drafts a brief of it (pages, products, look). Send chatId and the site's url. Starts reading the site as a job; the brief is kept as a pending plan that /ai-clone/brief, /ai-clone/refine and /ai-clone/products work on. A second call while one runs gets the running one.

Admin token

Needs a site admin token.

Parameters
chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

urlstring

The AI's URL slug, as in its address on the site.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 400 401 429 500

POST/ai-clone/analyze
curl -X POST 'http://smartman.max-media.io/ai-clone/analyze?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "chatId": "...", "url": "...", "aiVersion": "..." }'

Duplicate a AI

AI: saves the owner's edits to the pending clone brief. 404 when there is no pending clone analysis for the chat. Answers the updated brief.

Admin token

Needs a site admin token.

Parameters
chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

Status codes

200 400 401 404 500

POST/ai-clone/brief
curl -X POST 'http://smartman.max-media.io/ai-clone/brief?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "chatId": "..." }'

Duplicate a AI

AI: the clone brief's products with their credit cost. Send chatId and count (how many products to copy, capped at what the site has). Answers { action: 'PRODUCTS', productCount, estimate }: the clone's credit estimate for pages and products.

Admin token

Needs a site admin token.

Parameters
aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

countstring

The AI's count.

Status codes

200 400 401 404 500

POST/ai-clone/products
curl -X POST 'http://smartman.max-media.io/ai-clone/products?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "aiVersion": "...", "chatId": "...", "count": "..." }'

Duplicate a AI

AI: changes the pending clone brief as the owner asked in words. Send chatId and text. 429 while another request runs for the chat; 404 without a pending clone analysis. Answers the updated brief.

Admin token

Needs a site admin token.

Parameters
chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

textstring

The AI's text.

Status codes

200 400 401 404 429 500

POST/ai-clone/refine
curl -X POST 'http://smartman.max-media.io/ai-clone/refine?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "chatId": "...", "text": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Retrieve an async job

A background job's progress and result, polled by the admin while AI work runs. Answers the job: percent, status, complete, and result when done. A plan job whose process died is retired here and comes back complete, with a resume offer in its chat. 404 when there is no such job.

Admin token

Needs a site admin token.

Path parameters
idstringRequired

The ID of the async job.

Status codes

200 401 404 500

GET/async-jobs/:id
curl -X GET 'http://smartman.max-media.io/async-jobs/{id}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'

Retrieve the chat history

Every AI chat, each with its newest message, the most recently used first. Answers an array, newest first.

Admin token

Needs a site admin token.

Returns

Returns the ChatHistory object.

Status codes

200 401 500

GET/all-chat-history
curl -X GET 'http://smartman.max-media.io/all-chat-history?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Retrieve the chat history

The latest AI chat with its messages. Answers { chatHistory, messages }: the newest 20 messages.

Admin token

Needs a site admin token.

Returns

Returns the ChatHistory object.

Status codes

200 401 500

GET/chat-history
curl -X GET 'http://smartman.max-media.io/chat-history?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Create a chat history

Starts a new AI chat. Answers { chatHistory }.

Admin token

Needs a site admin token.

Returns

Returns the ChatHistory object.

Status codes

200 401 500

POST/chat-history
curl -X POST 'http://smartman.max-media.io/chat-history?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Retrieve a chat history

One AI chat. 404 when there is no such record.

Admin token

Needs a site admin token.

Path parameters
idstringRequired

The ID of the chat history.

Returns

Returns the ChatHistory object.

Status codes

200 401 404 500

GET/chat-history/:id
curl -X GET 'http://smartman.max-media.io/chat-history/{id}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Update a chat history

Renames an AI chat (title). 404 when there is no such chat.

Admin token

Needs a site admin token.

Path parameters
idstringRequired

The ID of the chat history.

Parameters
titlestring

Name of the chat, shown in the chat list.

Returns

Returns the ChatHistory object.

Status codes

200 400 401 404 500

PATCH/chat-history/:id
curl -X PATCH 'http://smartman.max-media.io/chat-history/{id}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "..." }'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Delete a chat history

Deletes an AI chat with its messages. Answers the deleted record, or 404. Records that point to it are not changed.

Admin token

Needs a site admin token.

Path parameters
idstringRequired

The ID of the chat history.

Returns

Returns an empty answer on success.

Status codes

200 401 404 500

DELETE/chat-history/:id
curl -X DELETE 'http://smartman.max-media.io/chat-history/{id}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'

Create a chat message

Adds a message to an AI chat. Answers { message }.

Admin token

Needs a site admin token.

Path parameters
chatIdstringRequired

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

Returns

Returns the ChatMessage object.

Status codes

200 401 500

POST/chat-message/:chatId
curl -X POST 'http://smartman.max-media.io/chat-message/{chatId}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Update a chat message

Updates a chat message's text, data or options. Answers { message }. 404 when it is not in that chat.

Admin token

Needs a site admin token.

Path parameters
chatIdstringRequired

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

messageIdstringRequired

The chat message's message id.

Parameters
textstring

The message's text.

datastring

The chat message's data.

optionsstring[]

Quick replies offered under the message.

Returns

Returns the ChatMessage object.

Status codes

200 401 404 500

PATCH/chat-message/:chatId/:messageId
curl -X PATCH 'http://smartman.max-media.io/chat-message/{chatId}/{messageId}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "...", "data": "...", "options": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Retrieve a chat message

A chat's messages, a page at a time; offers to resume a build that stopped. Answers { messages }, newest first.

Admin token

Needs a site admin token.

Path parameters
chatIdstringRequired

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

skipstringRequired

How many results to skip - for paging.

limitstringRequired

How many results to return.

Returns

Returns the ChatMessage object.

Status codes

200 401 500

GET/chat-message/:chatId/:skip/:limit
curl -X GET 'http://smartman.max-media.io/chat-message/{chatId}/{skip}/{limit}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Delete a chat message

Deletes a chat's last error message and the message that caused it, to retry. Answers { deleted }: how many messages were removed.

Admin token

Needs a site admin token.

Path parameters
chatIdstringRequired

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

Returns

Returns an empty answer on success.

Status codes

200 401 500

DELETE/chat-message/:chatId/last-error
curl -X DELETE 'http://smartman.max-media.io/chat-message/{chatId}/last-error?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'

Retrieve an AI builder

Returns one AI builder, found by its ID.

Admin token

Needs a site admin token.

Path parameters
pageIdstringRequired

The AI builder's page id.

Status codes

200 400 401 404 500

GET/ai-builder/hero-animation/:pageId
curl -X GET 'http://smartman.max-media.io/ai-builder/hero-animation/{pageId}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "requiresLogin": false,
  "requiresSubscription": false,
  "price_plan_ids": [
    "example"
  ],
  "title": "Example",
  "url": "example-item",
  "redirectUrl": "example",
  "legal_kind": "example",
  "isPartial": false,
  "showTo": "0",
  "showHeader": true,
  "showFooter": true,
  "ai_context_v2": {},
  "ai_surfaces_v2": {},
  "ai_overview": "example",
  "ai_generation_metadata": {},
  "containers": [
    {
      "isFluid": false,
      "parallaxEnabled": false,
      "parallaxAmount": 49.9,
      "parallaxZoom": 1,
      "continuousEnabled": false,
      "continuousEffect": "none",
      "continuousDuration": 2400,
      "continuousIntensity": 4,
      "backgroundImage": "example",
      "backgroundSize": "example",
      "backgroundPosition": "example",
      "backgroundRepeat": "example",
      "backgroundVideo": "example",
      "backgroundColor": "#3557c4",
      "backgroundParallax": false,
      "minHeight": 1,
      "minHeightMobile": 1,
      "allowOffset": false,
      "offsetX": 0,
      "offsetY": 0,
      "offsetMobileX": 0,
      "offsetMobileY": 0,
      "zIndex": 0,
      "wrap_reverse": false,
      "backgroundGradient": {
        "enabled": false,
        "type": "example",
        "degrees": 0,
        "radialShape": "example",
        "radialPosition": "example",
        "colors": "#3557c4",
        "css": "example"
      },
      "padding_top": {
        "value": "example",
        "unit": "example",
        "mobile_value": "example",
        "mobile_unit": "example"
      },
      "padding_right": {
        "value": "example"
      }
    }
  ],
  "suitability_price_plans": [
    "6543210fedcba98765432101"
  ],
  "isSuitable": false,
  "archived": false,
  "archivedAt": "2026-11-04T12:00:00.000Z",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Apply the AI builder

Apply the AI builder.

Admin token

Needs a site admin token.

Path parameters
pageIdstringRequired

The AI builder's page id.

Parameters
mediastring

The AI builder's media.

Status codes

200 400 401 404 409 500

POST/ai-builder/hero-animation/:pageId/apply
curl -X POST 'http://smartman.max-media.io/ai-builder/hero-animation/{pageId}/apply?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "media": "..." }'
Response
{
  "file": "example",
  "file_path": "example",
  "alt": "example",
  "filename": "Example",
  "filetype": "example",
  "vimeo_uri": "example",
  "vimeo_picture": "example",
  "duration": 1,
  "vimeo_url": "example-item",
  "youtube_url": "example-item",
  "youtube_picture": "example",
  "thumbnail": "example",
  "gcs_url": "example-item",
  "gcs_480_30_url": "example-item",
  "gcs_720_30_url": "example-item",
  "gcs_1080_30_url": "example-item",
  "picture_gcs_url": "example-item",
  "transcode_status": "not_started",
  "owner_id": "6543210fedcba98765432100",
  "source_url": "example-item",
  "source_framing": "example",
  "origin": "example",
  "width": 1,
  "height": 1,
  "sequence": {
    "status": "example",
    "started_at": "example",
    "updated_at": "example",
    "step": "example",
    "done": 0,
    "total": 0,
    "ext": "example",
    "trim_start": 0,
    "trim_end": 0,
    "build_id": "example",
    "previous_base": "example",
    "frame_count": 0
  }
}

Dismiss the AI builder

Dismiss the AI builder.

Admin token

Needs a site admin token.

Path parameters
pageIdstringRequired

The AI builder's page id.

Status codes

200 400 401 404 500

POST/ai-builder/hero-animation/:pageId/dismiss
curl -X POST 'http://smartman.max-media.io/ai-builder/hero-animation/{pageId}/dismiss?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "requiresLogin": false,
  "requiresSubscription": false,
  "price_plan_ids": [
    "example"
  ],
  "title": "Example",
  "url": "example-item",
  "redirectUrl": "example",
  "legal_kind": "example",
  "isPartial": false,
  "showTo": "0",
  "showHeader": true,
  "showFooter": true,
  "ai_context_v2": {},
  "ai_surfaces_v2": {},
  "ai_overview": "example",
  "ai_generation_metadata": {},
  "containers": [
    {
      "isFluid": false,
      "parallaxEnabled": false,
      "parallaxAmount": 49.9,
      "parallaxZoom": 1,
      "continuousEnabled": false,
      "continuousEffect": "none",
      "continuousDuration": 2400,
      "continuousIntensity": 4,
      "backgroundImage": "example",
      "backgroundSize": "example",
      "backgroundPosition": "example",
      "backgroundRepeat": "example",
      "backgroundVideo": "example",
      "backgroundColor": "#3557c4",
      "backgroundParallax": false,
      "minHeight": 1,
      "minHeightMobile": 1,
      "allowOffset": false,
      "offsetX": 0,
      "offsetY": 0,
      "offsetMobileX": 0,
      "offsetMobileY": 0,
      "zIndex": 0,
      "wrap_reverse": false,
      "backgroundGradient": {
        "enabled": false,
        "type": "example",
        "degrees": 0,
        "radialShape": "example",
        "radialPosition": "example",
        "colors": "#3557c4",
        "css": "example"
      },
      "padding_top": {
        "value": "example",
        "unit": "example",
        "mobile_value": "example",
        "mobile_unit": "example"
      },
      "padding_right": {
        "value": "example"
      }
    }
  ],
  "suitability_price_plans": [
    "6543210fedcba98765432101"
  ],
  "isSuitable": false,
  "archived": false,
  "archivedAt": "2026-11-04T12:00:00.000Z",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Revert the AI builder

Revert the AI builder.

Admin token

Needs a site admin token.

Path parameters
pageIdstringRequired

The AI builder's page id.

Status codes

200 400 401 404 500

POST/ai-builder/hero-animation/:pageId/revert
curl -X POST 'http://smartman.max-media.io/ai-builder/hero-animation/{pageId}/revert?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "requiresLogin": false,
  "requiresSubscription": false,
  "price_plan_ids": [
    "example"
  ],
  "title": "Example",
  "url": "example-item",
  "redirectUrl": "example",
  "legal_kind": "example",
  "isPartial": false,
  "showTo": "0",
  "showHeader": true,
  "showFooter": true,
  "ai_context_v2": {},
  "ai_surfaces_v2": {},
  "ai_overview": "example",
  "ai_generation_metadata": {},
  "containers": [
    {
      "isFluid": false,
      "parallaxEnabled": false,
      "parallaxAmount": 49.9,
      "parallaxZoom": 1,
      "continuousEnabled": false,
      "continuousEffect": "none",
      "continuousDuration": 2400,
      "continuousIntensity": 4,
      "backgroundImage": "example",
      "backgroundSize": "example",
      "backgroundPosition": "example",
      "backgroundRepeat": "example",
      "backgroundVideo": "example",
      "backgroundColor": "#3557c4",
      "backgroundParallax": false,
      "minHeight": 1,
      "minHeightMobile": 1,
      "allowOffset": false,
      "offsetX": 0,
      "offsetY": 0,
      "offsetMobileX": 0,
      "offsetMobileY": 0,
      "zIndex": 0,
      "wrap_reverse": false,
      "backgroundGradient": {
        "enabled": false,
        "type": "example",
        "degrees": 0,
        "radialShape": "example",
        "radialPosition": "example",
        "colors": "#3557c4",
        "css": "example"
      },
      "padding_top": {
        "value": "example",
        "unit": "example",
        "mobile_value": "example",
        "mobile_unit": "example"
      },
      "padding_right": {
        "value": "example"
      }
    }
  ],
  "suitability_price_plans": [
    "6543210fedcba98765432101"
  ],
  "isSuitable": false,
  "archived": false,
  "archivedAt": "2026-11-04T12:00:00.000Z",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Start the AI builder

Start the AI builder.

Admin token

Needs a site admin token.

Path parameters
pageIdstringRequired

The AI builder's page id.

Parameters
ideastring

The AI builder's idea.

mediaIdsstring

The AI builder's media ids.

Status codes

200 401 403 404 409 500

POST/ai-builder/hero-animation/:pageId/start
curl -X POST 'http://smartman.max-media.io/ai-builder/hero-animation/{pageId}/start?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "idea": "...", "mediaIds": "..." }'
Response
{
  "requiresLogin": false,
  "requiresSubscription": false,
  "price_plan_ids": [
    "example"
  ],
  "title": "Example",
  "url": "example-item",
  "redirectUrl": "example",
  "legal_kind": "example",
  "isPartial": false,
  "showTo": "0",
  "showHeader": true,
  "showFooter": true,
  "ai_context_v2": {},
  "ai_surfaces_v2": {},
  "ai_overview": "example",
  "ai_generation_metadata": {},
  "containers": [
    {
      "isFluid": false,
      "parallaxEnabled": false,
      "parallaxAmount": 49.9,
      "parallaxZoom": 1,
      "continuousEnabled": false,
      "continuousEffect": "none",
      "continuousDuration": 2400,
      "continuousIntensity": 4,
      "backgroundImage": "example",
      "backgroundSize": "example",
      "backgroundPosition": "example",
      "backgroundRepeat": "example",
      "backgroundVideo": "example",
      "backgroundColor": "#3557c4",
      "backgroundParallax": false,
      "minHeight": 1,
      "minHeightMobile": 1,
      "allowOffset": false,
      "offsetX": 0,
      "offsetY": 0,
      "offsetMobileX": 0,
      "offsetMobileY": 0,
      "zIndex": 0,
      "wrap_reverse": false,
      "backgroundGradient": {
        "enabled": false,
        "type": "example",
        "degrees": 0,
        "radialShape": "example",
        "radialPosition": "example",
        "colors": "#3557c4",
        "css": "example"
      },
      "padding_top": {
        "value": "example",
        "unit": "example",
        "mobile_value": "example",
        "mobile_unit": "example"
      },
      "padding_right": {
        "value": "example"
      }
    }
  ],
  "suitability_price_plans": [
    "6543210fedcba98765432101"
  ],
  "isSuitable": false,
  "archived": false,
  "archivedAt": "2026-11-04T12:00:00.000Z",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Create an AI

AI: stops the agent turn and plan running in a chat (chatId) before their next step. Answers { stopped: true, plans } with how many plans were told to stop. A plan finishes the step it is on, then stops and is marked partially completed. Jobs that are not a plan (a single page, a picture) run to the end.

Admin token

Needs a site admin token.

Parameters
chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

Status codes

200 400 401 500

POST/ai-stop
curl -X POST 'http://smartman.max-media.io/ai-stop?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "chatId": "..." }'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Create a dynamic features plan with AI

AI: builds the custom models and pages of an accepted features plan. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the dynamic features plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/create-dynamic-features-plan
curl -X POST 'http://smartman.max-media.io/create-dynamic-features-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'

Create a dynamic modification plan with AI

AI: applies an accepted custom model modification plan. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the dynamic modification plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/create-dynamic-modification-plan
curl -X POST 'http://smartman.max-media.io/create-dynamic-modification-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'

Create a plan with AI

AI: runs the agent for a /create-plan message: plans the work and runs it as a background job. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

noticestring

The plan's notice.

reference_requeststring

The plan's reference request.

selection_requeststring

The plan's selection request.

Status codes

200 401 500

POST/create-plan
curl -X POST 'http://smartman.max-media.io/create-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "...", "notice": "...", "reference_request": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Generate a companion app plan with AI

AI: talks through the companion app settings with the owner and proposes the changes. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the companion app plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/generate-companion-app-plan
curl -X POST 'http://smartman.max-media.io/generate-companion-app-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'

Generate a dynamic features plan with AI

AI: drafts a plan of custom models and pages for a feature the owner described. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the dynamic features plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/generate-dynamic-features-plan
curl -X POST 'http://smartman.max-media.io/generate-dynamic-features-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Generate a dynamic modification plan with AI

AI: drafts changes to existing custom models and pages. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the dynamic modification plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/generate-dynamic-modification-plan
curl -X POST 'http://smartman.max-media.io/generate-dynamic-modification-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Generate a page link plan with AI

AI: works out which record a new page is about and where to link it, then builds it. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the page link plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

item_idsstring

The page link plan's item ids.

Status codes

200 401 500

POST/generate-page-link-plan
curl -X POST 'http://smartman.max-media.io/generate-page-link-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "...", "item_ids": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Generate a project plan with AI

AI: drafts a business project plan for the site from the chat. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the project plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/generate-project-plan
curl -X POST 'http://smartman.max-media.io/generate-project-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Generate a social mode plan with AI

AI: talks through the social mode settings with the owner and proposes the changes. Answers { action: 'JOB', async_job } at once; the admin polls GET /async-jobs/:id, and the result arrives in the chat as a message when the job ends. The AI work is charged to the account's credits.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the social mode plan, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/generate-social-mode-plan
curl -X POST 'http://smartman.max-media.io/generate-social-mode-plan?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

List all unfinished plans

AI: the owner's plans that stopped before finishing, each with its chat, offering to resume stalled ones. Answers { unfinished }: up to 20, the most recently touched first, each with its planId, chat and title. A plan whose process died is offered for resuming.

Admin token

Needs a site admin token.

Status codes

200 401 500

GET/unfinished-plans
curl -X GET 'http://smartman.max-media.io/unfinished-plans?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'
Response
{
  "user": "6543210fedcba98765432100",
  "title": "Example",
  "stop_requested_at": "2026-11-04T12:00:00.000Z",
  "language": "en",
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z"
}

Delete an unfinished plan

AI: deletes an unfinished plan and closes its job and chat cards. Answers { deleted: true }, or { deleted: false } when there is no such plan. 409 while the build is still running: stop it first.

Admin token

Needs a site admin token.

Path parameters
idstringRequired

The ID of the unfinished plan.

Returns

Returns an empty answer on success.

Status codes

200 401 409 500

DELETE/unfinished-plans/:id
curl -X DELETE 'http://smartman.max-media.io/unfinished-plans/{id}?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>'

Create a site wide edit

Finds every place a requested text change applies to and proposes it,. as a chat card, for confirmation. Background job; the card is the result.

Admin token

Needs a site admin token.

Parameters
promptstring

What the AI should do with the site wide edit, in plain words - any language.

chatIdstring

The AI chat this request belongs to; its history and language carry over. Leave it out to start a new chat.

aiVersionstring

Which version of the AI builder to use; leave it out for the current one.

Status codes

200 401 500

POST/site-wide-edit
curl -X POST 'http://smartman.max-media.io/site-wide-edit?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "prompt": "...", "chatId": "...", "aiVersion": "..." }'
Response
{
  "zip_code": "example",
  "city": "example",
  "address": "example",
  "contact": "example",
  "email": "jane@example.com",
  "google_app": "example",
  "workhours": "example",
  "logo": "6543210fedcba98765432100",
  "site_name": "Example",
  "domain": "example",
  "stock_domain": "example",
  "isMarket": false,
  "forbidden_collections": [
    {
      "collection_id": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "isInit": false,
  "template": "0000",
  "lang": "en",
  "favicon": "6543210fedcba98765432100",
  "cacheEnabled": false,
  "has_completed_startup_prompt": true,
  "gmb_location": "example",
  "ga_property": "example",
  "site_generated_at": "2026-11-04T12:00:00.000Z",
  "admin_first_opened_at": "2026-11-04T12:00:00.000Z",
  "admin_last_opened_at": "2026-11-04T12:00:00.000Z",
  "allowedComponents": {
    "services": false,
    "products": false,
    "blogposts": false,
    "programs": false
  }
}

Apply the site wide edit

Writes the ticked changes of a proposal; keeps each field's previous value for undo. Answers { applied, skipped, reloads_index }; reloads_index tells the admin to reload the page it shows. 400 "Nothing to apply".

Admin token

Needs a site admin token.

Parameters
messageIdstring

The site wide edit's message id.

Status codes

200 400 401 500

POST/site-wide-edit/apply
curl -X POST 'http://smartman.max-media.io/site-wide-edit/apply?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "messageId": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}

Undo the site wide edit

Puts back what an applied change replaced - where nothing has changed it since. Answers { restored, changedSince }: fields edited again since are left as they are. 400 "Nothing to undo".

Admin token

Needs a site admin token.

Parameters
messageIdstring

The site wide edit's message id.

Status codes

200 400 401 500

POST/site-wide-edit/undo
curl -X POST 'http://smartman.max-media.io/site-wide-edit/undo?ionic=true' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "messageId": "..." }'
Response
{
  "chat_id": "6543210fedcba98765432100",
  "role": "user",
  "text": "Text shown on the site.",
  "target_url": "example-item",
  "action": "RESPONSE",
  "options": [
    "example"
  ],
  "medias": [
    {
      "media": "6543210fedcba98765432100",
      "gcs_url": "example-item",
      "gemini_uri": "example",
      "gemini_interaction_id": "example",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "products": [
    "6543210fedcba98765432101"
  ],
  "services": [
    "6543210fedcba98765432101"
  ],
  "blogposts": [
    "6543210fedcba98765432101"
  ],
  "programs": [
    "6543210fedcba98765432101"
  ],
  "suggestions": [
    {
      "text": "Text shown on the site.",
      "route": "example",
      "item_id": "6543210fedcba98765432100",
      "medias": [],
      "picture": "6543210fedcba98765432100",
      "_id": "6543210fedcba98765432100"
    }
  ],
  "is_system": false,
  "_id": "6543210fedcba98765432100",
  "updatedAt": "2026-11-04T12:00:00.000Z",
  "createdAt": "2026-11-04T12:00:00.000Z",
  "data": {
    "object": "example",
    "object_type": "example",
    "edit_summary": "example",
    "edit_diff": "example",
    "undo_record": "example",
    "hero_animation_offer": "example",
    "preview_state": "example",
    "pending_credit_cost": 0,
    "target_restore": "example",
    "media_request": "example",
    "item_request": "example",
    "reference_request": "example"
  }
}
↑↓ Navigate↵ GoEsc Close