Create or update by slug

PUT

api

pages

by-slug

{slug}

curl -X PUT "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report" \
  -H "Authorization: Bearer $MAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales report",
    "visibility": "private",
    "content": "<!doctype html><html><head><title>Sales</title></head><body><h1>Sales</h1></body></html>",
    "change_note": "hourly"
  }'

const res = await fetch(
  'https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report',
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.MAC_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Sales report',
      visibility: 'private',
      content: html,
      change_note: 'hourly'
    })
  }
)

const { created, version, url, deduplicated } = await res.json()

import os, requests

res = requests.put(
    "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report",
    headers={"Authorization": f"Bearer {os.environ['MAC_KEY']}"},
    json={
        "title": "Sales report",
        "visibility": "private",
        "content": html,
        "change_note": "hourly",
    },
)

body = res.json()

{
  "ok": true,
  "created": true,
  "page": {
    "id": "9b3f11c2-…",
    "slug": "sales-report",
    "title": "Sales report",
    "description": null,
    "visibility": "private",
    "chatbot_id": "c1a2…",
    "conversation_id": null,
    "current_version": 1,
    "version_count": 1,
    "total_bytes": 2048,
    "disabled_reason": null,
    "created_at": "2026-09-21T03:00:00.000Z",
    "updated_at": "2026-09-21T03:00:00.000Z",
    "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report"
  },
  "version": 1,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/1",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": false
}

{
  "ok": true,
  "created": false,
  "page": { "id": "9b3f11c2-…", "slug": "sales-report", "current_version": 4 },
  "version": 4,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/4",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": true
}

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN_CHATBOT",
    "message": "This key's chatbot does not own that page (writes are scoped to the key's chatbot)."
  }
}

The automation-friendly write. If a Page in your workspace holds this slug (or held it before a rename), the call adds a version to it. Otherwise it creates the Page under this slug. You never have to store a page id. Needs a key with Pages write turned on. See Scheduled and automated Pages for the full recipe.

Authorization

string

required

Bearer mac_live_…

Path parameters

string

required

1 to 63 lowercase letters, digits and dashes. Anything else is 422 VALIDATION_FAILED.

Body

string

required

The full HTML document. Up to your plan’s per-version cap (512 KB on Free).

string

Up to 150 characters. On create, without it we use the HTML <title>, then “Untitled page”. On update it renames the Page.

string | null

Plain text, up to 300 characters. null clears it.

string

private or public. Defaults to private on create. On update it changes the Page’s visibility.

string

Up to 500 characters, shown next to the version in the app.

string

Link the Page to a conversation. Only used on create.

Every run applies the fields it sends and leaves the rest alone, so leave out title or visibility if someone manages them in the app. Otherwise the next run overwrites their change.

Response

201 Created when this call created the Page, 200 OK when it updated one.

boolean

true on success.

boolean

true when this call created the Page.

object

The Page. Same fields as Get a page.

integer

The version this call produced, or the current one when deduplicated.

string

The Page’s link: the members-only door for private, the Page itself for public.

string

The permanent /v/{n} address of this version. For a private Page it sends members through the sign-in door first.

string

SHA-256 of the stored content.

boolean

true when the content was byte-for-byte identical to the current version, so nothing new was stored.

curl -X PUT "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report" \
  -H "Authorization: Bearer $MAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales report",
    "visibility": "private",
    "content": "<!doctype html><html><head><title>Sales</title></head><body><h1>Sales</h1></body></html>",
    "change_note": "hourly"
  }'

const res = await fetch(
  'https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report',
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.MAC_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Sales report',
      visibility: 'private',
      content: html,
      change_note: 'hourly'
    })
  }
)

const { created, version, url, deduplicated } = await res.json()

import os, requests

res = requests.put(
    "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report",
    headers={"Authorization": f"Bearer {os.environ['MAC_KEY']}"},
    json={
        "title": "Sales report",
        "visibility": "private",
        "content": html,
        "change_note": "hourly",
    },
)

body = res.json()

{
  "ok": true,
  "created": true,
  "page": {
    "id": "9b3f11c2-…",
    "slug": "sales-report",
    "title": "Sales report",
    "description": null,
    "visibility": "private",
    "chatbot_id": "c1a2…",
    "conversation_id": null,
    "current_version": 1,
    "version_count": 1,
    "total_bytes": 2048,
    "disabled_reason": null,
    "created_at": "2026-09-21T03:00:00.000Z",
    "updated_at": "2026-09-21T03:00:00.000Z",
    "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report"
  },
  "version": 1,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/1",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": false
}

{
  "ok": true,
  "created": false,
  "page": { "id": "9b3f11c2-…", "slug": "sales-report", "current_version": 4 },
  "version": 4,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/4",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": true
}

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN_CHATBOT",
    "message": "This key's chatbot does not own that page (writes are scoped to the key's chatbot)."
  }
}

Errors

Status	Code	Meaning
`401`	`INVALID_API_KEY`	Missing, broken, or revoked.
`402`	`PAGE_LIMIT_REACHED`	Creating would exceed your plan’s Page count. Reuse a slug or delete a Page.
`402`	`STORAGE_QUOTA_EXCEEDED`	Workspace storage is full.
`403`	`PAGES_WRITE_DISABLED`	Turn on Pages write for this key.
`403`	`FORBIDDEN_CHATBOT`	Another bot’s Page holds this slug.
`403`	`PAGE_DISABLED`	The Page was disabled by an admin. Writes are rejected.
`409`	`SLUG_TAKEN`	The slug belonged to a deleted Page and is retired. Pick another.
`413`	`CONTENT_TOO_LARGE`	Over your plan’s per-version cap. `limit_bytes` says how much.
`422`	`VALIDATION_FAILED`	Bad slug or body.
`429`	`RATE_LIMITED`	Over 120 writes per minute for this key. Wait for `retry_after_seconds`.
`500`	`PERSIST_FAILED`	We could not store the Page. Safe to retry.

curl -X PUT "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report" \
  -H "Authorization: Bearer $MAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales report",
    "visibility": "private",
    "content": "<!doctype html><html><head><title>Sales</title></head><body><h1>Sales</h1></body></html>",
    "change_note": "hourly"
  }'

const res = await fetch(
  'https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report',
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.MAC_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Sales report',
      visibility: 'private',
      content: html,
      change_note: 'hourly'
    })
  }
)

const { created, version, url, deduplicated } = await res.json()

import os, requests

res = requests.put(
    "https://app.my-aichatbot.com/api/v1/pages/by-slug/sales-report",
    headers={"Authorization": f"Bearer {os.environ['MAC_KEY']}"},
    json={
        "title": "Sales report",
        "visibility": "private",
        "content": html,
        "change_note": "hourly",
    },
)

body = res.json()

{
  "ok": true,
  "created": true,
  "page": {
    "id": "9b3f11c2-…",
    "slug": "sales-report",
    "title": "Sales report",
    "description": null,
    "visibility": "private",
    "chatbot_id": "c1a2…",
    "conversation_id": null,
    "current_version": 1,
    "version_count": 1,
    "total_bytes": 2048,
    "disabled_reason": null,
    "created_at": "2026-09-21T03:00:00.000Z",
    "updated_at": "2026-09-21T03:00:00.000Z",
    "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report"
  },
  "version": 1,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/1",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": false
}

{
  "ok": true,
  "created": false,
  "page": { "id": "9b3f11c2-…", "slug": "sales-report", "current_version": 4 },
  "version": 4,
  "url": "https://app.my-aichatbot.com/pages/view/acme/sales-report",
  "version_url": "https://acme.my-aichatbot-space.com/sales-report/v/4",
  "content_sha256": "3a7bd3e2…",
  "deduplicated": true
}

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN_CHATBOT",
    "message": "This key's chatbot does not own that page (writes are scoped to the key's chatbot)."
  }
}

Overview

Messages

Files

Pages

Create or update by slug

Authorization

Path parameters

Body

Response

Errors

​Authorization

​Path parameters

​Body

​Response

​Errors

Authorization

Path parameters

Body

Response

Errors