Content API - Hiveku Builder

List Content

/marketing/content

List all content items for the current organization.

Response

[
  {
    "id": "content_abc123",
    "title": "Getting Started with Hiveku",
    "status": "published",
    "author_id": "d4d4d4d4-...",
    "author": { "id": "d4d4d4d4-...", "name": "Jane Doe" },
    "avatar_id": "avatar_123",
    "journey_id": "journey_456",
    "journey_stage": "Problem Aware",
    "before_after_grid_id": null,
    "target_keyword": "getting started with hiveku",
    "customer_avatar": { "id": "avatar_123", "name": "Marketing Director" },
    "customer_journey": { "id": "journey_456", "name": "Agency buyer journey" },
    "before_after_grid": null,
    "faq": [{ "question": "How long does onboarding take?", "answer": "One working week from the kickoff call." }],
    "answer_block": "Onboarding takes one working week: ...",
    "search_intent": "commercial",
    "page_type": "guide",
    "review_disposition": null,
    "topic_cluster_id": "e5e5e5e5-...",
    "topic_cluster": { "id": "e5e5e5e5-...", "pillar_keyword": "agency onboarding" },
    "cluster_role": "spoke",
    "page_role": "support",
    "lead_magnet": { "kind": "checklist", "title": "The onboarding checklist", "form_id": "b8b8b8b8-..." },
    "offer_id": "o1o1o1o1-...",
    "serp_brief": null,
    "serp_brief_captured_at": "2026-09-12T10:00:00.000Z",
    "decay_status": null,
    "refresh_priority": null,
    "top_declining_keywords": [],
    "refreshed_at": null,
    "createdAt": "2025-03-15T10:00:00Z",
    "updatedAt": "2025-03-16T14:30:00Z"
  }
]

The grounding. Every row carries the five fields that say who the piece is for, avatar_id, journey_id, journey_stage, before_after_grid_id and target_keyword (each present, null when unset; target_keyword reads settings.target_keyword on rows written before 2026-09-12), plus customer_avatar, customer_journey and before_after_grid as { id, name } or null. The same keys come back from every create, get and update below. Filters (Olympus). GET /api/olympus/marketing/content under an API key also filters on avatar_id, journey_id and before_after_grid_id (exact; a value that is not a UUID is a 400) and journey_stage (case-insensitive exact match on the stage name), beside status, content_type, category_id, tags and search. The content_list MCP tool takes the same. See Who this is for. Newest published first (Olympus). published_since (an ISO 8601 instant; only items whose published_at is at or after it; a value that is not a date is a 400) and sort (updated, the default, by updated_at descending; published, by published_at descending with never-published rows last; or refresh_priority, by refresh_priority descending with items that never decayed last, then updated_at descending; any other value is a 400 sort must be one of: updated, published, refresh_priority.) join the filters, so status=published&published_since=<a week ago>&sort=published is everything that went live since the last digest, newest first. The content_list tool and the List Marketing Content workflow node take the same two (the node also takes published_within_days; the node’s sort stays updated or published). The refresh queue in one call (2026-09-12). decay_status filters on one of three states, never a raw status: decaying (the column is set and not one of resolved, refreshed, ignored, dismissed, recovered), recovered (one of those five) or none (the page never decayed). A raw status such as detected, or any other value, is a 400 decay_status must be one of: decaying, recovered, none. before any read; blank is no filter. So status=published&decay_status=decaying&sort=refresh_priority (content_list({ status: "published", decay_status: "decaying", sort: "refresh_priority" })) is the whole refresh queue, and the count and the pagination use the same predicate, so page 2 is the same queue. The dashboard list (GET /api/marketing/content) takes the same decay_status and sort values; all is its no-filter value. Before this date the queue was the published list filtered client-side. The elite fields (2026-09-12). Every row also carries author_id with author { id, name }, faq (always an array), answer_block, search_intent, page_type, review_disposition, topic_cluster_id with topic_cluster { id, pillar_keyword }, cluster_role, page_role, lead_magnet, offer_id, and the six columns other writers stamp: serp_brief and serp_brief_captured_at (the SERP brief), decay_status, refresh_priority and top_declining_keywords (the Sunday decay run, see Refresh Brief) and refreshed_at (the publish path). Every key is present and null when unset (faq and top_declining_keywords are []). The Olympus list adds six filters: author_id and topic_cluster_id (UUIDs; malformed is a 400), search_intent (informational, commercial, transactional, navigational), review_disposition (double_down, refresh, rewrite, consolidate, prune), cluster_role (pillar, spoke) and page_role (money, pillar, support, utility); a value outside a vocabulary is a 400. The dashboard list takes the same six and accepts all as the no-filter value. content_type now also accepts comparison, alternatives and research. The list returns serp_brief in full per row.

Create Content

/marketing/content

Create a new content item.

Request Body

{
  "title": "New Blog Post",
  "body": "Content body in rich text...",
  "status": "draft",
  "tags": ["blog", "tutorial"],
  "avatar_id": "avatar_123",
  "journey_id": "journey_456",
  "journey_stage": "Problem Aware",
  "before_after_grid_id": "grid_789",
  "target_keyword": "new blog post",
  "author_id": "d4d4d4d4-...",
  "search_intent": "commercial",
  "page_type": "comparison",
  "topic_cluster_id": "e5e5e5e5-...",
  "cluster_role": "spoke",
  "page_role": "support",
  "faq": [{ "question": "How long does concrete testing take?", "answer": "Two working days from delivery." }],
  "answer_block": "Concrete testing takes two working days from delivery: ...",
  "lead_magnet": { "kind": "checklist", "title": "The pre-pour checklist", "form_id": "b8b8b8b8-..." },
  "offer_id": "o1o1o1o1-..."
}

The grounding on create. avatar_id, journey_id and before_after_grid_id must name an avatar, a customer journey map and a before/after grid in this account (or be null); journey_stage is the stage name as the journey map spells it (up to 255 characters); target_keyword is up to 255 characters and lands on the target_keyword column, mirrored into settings.target_keyword. The Olympus POST /api/olympus/marketing/content and the content_create MCP tool take the same five.

Status	Meaning
`201`	Created; the response carries the five fields and the three `{ id, name }` objects
`400` `invalid_reference`	One of the three ids is malformed or belongs to another account. The error names the field and nothing is created
`400`	`journey_stage` or `target_keyword` is over 255 characters, or not a string. Nothing is created
`400` `read_only_field`	`serp_brief`, `serp_brief_captured_at`, `decay_status`, `refresh_priority`, `top_declining_keywords` or `refreshed_at` was sent with a value other than the column default; the error names the writer. Nothing is created

The eleven elite fields (2026-09-12). Accepted on create and update, on the Olympus routes, the dashboard routes and the content_create / content_update tools; null clears each.

Field	Accepts
`author_id`	A content author UUID in this account (see Content Authors); an item with none publishes under the account default
`faq`	`[{ question, answer }]`, both non-empty strings, at most 20; `null` or `[]` clears; any other shape is a `400` naming the entry
`answer_block`	The 40 to 60 word direct answer under the H1, trimmed; no length check on write
`search_intent`	`informational`, `commercial`, `transactional` or `navigational`
`page_type`	A string up to 100 characters (`guide`, `listicle`, `comparison`, `landing`, `tool`, `news`, `how_to` are what the brief writes)
`review_disposition`	`double_down`, `refresh`, `rewrite`, `consolidate` or `prune`: the decision the decision loop records
`topic_cluster_id`	A topic cluster UUID in this account
`cluster_role`	`pillar` or `spoke`
`page_role`	`money`, `pillar`, `support` or `utility`
`lead_magnet`	`{ kind, title, asset_id?, content_item_id?, form_id?, delivery_sequence_id? }`; `kind` is `guide`, `checklist`, `template`, `ebook`, `whitepaper`, `webinar`, `download` or `other` (one vocabulary since 2026-09-12, shared with the editor picker and the conversion plan, which keeps a stored `download` or `other` instead of calling it a guide; anything else is a `400` `lead_magnet.kind must be one of: guide, checklist, template, ebook, whitepaper, webinar, download, other.`), `title` up to 200 characters, and every id present is a UUID looked up in this account (a media asset, a content item, a website form, a marketing sequence); exactly those keys are stored
`offer_id`	The `id` of an entry in the active brand guide’s offers

An id outside the account, a malformed id or an unknown offer is 400 invalid_reference naming the field (and the tool that lists valid ids); a value outside a vocabulary is a 400 naming the list; nothing is written on either. When target_keyword is sent and another item in the account (status not archived or deleted) already targets the same keyword, case-insensitively, the 201 carries warnings[] with one keyword_already_targeted: ... line and keyword_conflicts[] with { code, content_item_id, title, slug, status, target_keyword }; the item is still created, and a writer relays the warning and offers to consolidate rather than retrying. On the Olympus route the Idempotency-Key header is honoured: a retry after a timed-out call replays the first answer (the 201, or the 4xx it got) for an hour instead of creating a second draft.

Get Content

/marketing/content/{id}

Get a specific content item by ID. The item carries the five grounding fields and the customer_avatar, customer_journey and before_after_grid objects described under List Content; the Olympus GET /api/olympus/marketing/content/:contentId and content_get add url, url_source and scheduled_publish.

Update Content

/marketing/content/{id}

Update a content item. The body is the whole item as the editor sends it.

The grounding on update. avatar_id, journey_id, journey_stage, before_after_grid_id and target_keyword are accepted with the same rules as on create; null clears a field, and a key that is absent leaves its column alone. The three ids are checked against the account before any field is written, so a 400 invalid_reference writes nothing. settings is merged into the stored object, never replaced, so keys another writer added (linked tasks, the published route) survive an autosave; a keyword typed into settings.target_keyword wins over the echoed top-level target_keyword, and both end up equal. The Olympus PATCH /api/olympus/marketing/content/:contentId and the content_update MCP tool take the same five, with the top-level target_keyword winning there. The distribution plan. settings.distribution_plan is the piece’s channel plan, written at brief time and updated as derivatives are made: { owned_first: true, channels: [{ channel, format, status, scheduled_for?, link?, note? }], written_at }, where channel is email_digest, social, community, partner, outreach or paid, status is planned, drafted, scheduled, done or skipped, and link names the derivative (social_post:<id>, campaign:<id>, task:<id> or a URL). At most 12 rows. Because settings merges, a writer sends settings: { distribution_plan } alone and every sibling key survives; a malformed plan is read as no plan. The same key is accepted on create, on the Olympus routes and by content_create and content_update. See The distribution plan on the row. The elite fields on update. The eleven fields above are accepted with the same rules; a key that is absent leaves its column alone. The six read-only columns (serp_brief, serp_brief_captured_at, decay_status, refresh_priority, top_declining_keywords, refreshed_at) are 400 read_only_field unless the value sent is exactly what the row holds: the editor echoes the whole row on every autosave and an agent that PATCHes a whole GET response back is echoing, and both are accepted (dates compare by instant, JSON by value with object keys in any order). The same echo rule skips the lookup for an unchanged author_id, topic_cluster_id, offer_id or lead_magnet. A keyword collision comes back as the same warnings[] and keyword_conflicts[] as on create, never a block; the dashboard PUT answers { contentItem, publishResult, publishError, warnings?, keyword_conflicts?, scheduled_publish? } and the Olympus PATCH { data, warnings?, keyword_conflicts?, scheduled_publish? }. Settings keys the round-B writers keep on the item, all merged: settings.serp_brief (the brief’s 30-day stamp), settings.title_candidates, settings.hook_pattern, settings.title_picked and settings.title_results (write hook_pattern yourself; never the other three), settings.json_ld and settings.json_ld_generated_at (the last publish), settings.comparison_table, settings.decision_cta, settings.methodology, settings.dataset (the bottom-funnel blocks), settings.cta_stage_table (the check’s stage table), settings.bofu (a seeded draft’s plan facts) and settings.decay_episode (the decay run’s claim; never clear it). Scheduling. A scheduled_publish_at (ISO 8601, in the future) whose instant differs from the stored value is a schedule request and puts the item’s site entry on the CMS scheduler; the value the row already holds is ignored as an autosave echo, and null never cancels. Send cancel_scheduled_publish: true to cancel. deploy_target is production (default), staging, dev, none or publish (Webflow).

Status	Meaning
`200`	Fields saved; `scheduled_publish` carries the scheduler row (`executes_via: "cms_scheduled_actions"`) and `contentItem.scheduled_publish_at` the time
`400`	The time is in the past, or `deploy_target` is unknown. Nothing is written
`409` `not_linked`	The item has no `website_project_id` and `cms_collection_id`, so there is no site entry to schedule. Nothing is written
other	The fields were saved but the schedule was not set; the body carries the helper’s error and `note: "Fields were saved; the schedule was NOT set."`

See Scheduling and the Content Calendar.

Pre-Publish SEO Check

/marketing/content/{id}/seo-check

Run the on-page SEO check on the stored item. Requires marketing.content read.

Response

{
  "data": {
    "content_id": "content_abc123",
    "checked_at": "2026-09-11T16:20:03.000Z",
    "result": {
      "ok": false,
      "score": 85,
      "checks": [
        { "id": "meta_description_missing", "level": "error", "field": "meta_description", "message": "Meta description is missing; search engines will pick a snippet themselves." }
      ],
      "stats": { "word_count": 812, "h1_count": 0, "heading_count": 6, "image_count": 2, "images_missing_alt": 0, "internal_link_count": 2, "external_link_count": 3, "format": "markdown" }
    },
    "context": { "target_keyword": "cnc uptime", "banned_phrases": [], "site_host": "www.example.com", "content_format": "markdown", "linked": true }
  }
}

level is error or warn; field names the column to fix (title, slug, meta_title, meta_description, content, featured_image_alt, target_keyword, author_id, answer_block or faq). ok is false only on errors; score is 100 minus 15 per error and 5 per warning. The same check is served under an Olympus API key at GET /api/olympus/marketing/content/{id}/seo-check (the content_seo_check MCP tool), and POST /api/olympus/marketing/content/{id}/publish-to-site returns it as warnings and seo_check. Since 2026-09-12 the rule ids also include author_missing (error), answer_block_missing (warn), faq_schema_mismatch (warn), title_generic (warn), money_link_missing (error at consideration and decision), pillar_link_missing (error), keyword_already_targeted (warn), comparison_table_missing (error), competitor_claim_unsourced (error), cta_missing (warn) and cta_stage_mismatch (warn); stats adds answer_block_words, faq_count, faq_in_body, title_generic, cta_count, money_link_count, pillar_linked, table_count and table_rows_unsourced; and context echoes journey_stage, content_type, author, answer_block, faq, money_page_urls, cluster, keyword_collision, comparison_table, offer and cta_stage_table for a local re-run. Every check is listed on Pre-Publish SEO Check.

Content Calendar

/marketing/content/calendar

Everything scheduled, published, failed or recorded in a window. Query from and to (ISO 8601 or YYYY-MM-DD), each defaulting to 45 days from now; a window wider than 190 days is a 400.

Response

{
  "range": { "from": "2026-08-30T00:00:00.000Z", "to": "2026-10-03T23:59:59.999Z" },
  "events": [
    { "id": "action:sched_123", "kind": "scheduled", "at": "2026-09-15T13:00:00.000Z", "title": "Why CNC uptime drops in year three", "content_id": "content_abc123", "content_type": "blog_post", "content_status": "approved", "href": "/dashboard/marketing/content/content_abc123", "project_id": "proj_xyz", "project_name": "Example site", "collection_id": "blog", "entry_slug": "cnc-uptime-year-three", "source": "cms_scheduled_actions", "deploy_target": "production", "error": null, "executes": true }
  ],
  "cadence": { "published_last_30_days": 12, "scheduled_pending": 3, "failed_pending": 0, "target": null, "target_source": null },
  "summary": "12 published in the last 30 days, 3 scheduled, target cadence from memory not set"
}

kind is scheduled, published, failed or recorded_only; executes is false only for recorded_only, a date stored on the item that nothing publishes. The cadence counts are account-wide. See Scheduling and the Content Calendar.

Site Links

/olympus/marketing/content/site-links

Olympus API key (the content_site_links MCP tool). Every published post and page on one website project with its live URL, for internal linking, ordered for the site’s architecture: money pages first, then the pillar of the item being written, then the other pillars, then the rest by recency. Query project_id (required, a website project UUID in the account), content_id (the item being written, a UUID in the account; 400 invalid_content_id when malformed, a note when unknown) and limit (default and maximum 500).

Returns

{ data: [{ id, title, url, type, published_at, slug, source, role, suggested_anchor, is_pillar_for_item }], total, capped, project: { id, name, host }, posts: { listed, without_url }, pages: { listed }, roles: { money, pillar }, item: { id, topic_cluster_id, cluster_role } | null, pillar: { id, title, url, cluster: { id, name } } | null, notes }

. id is the content item UUID, or page:<route>, crawl:<url> or pillar:<url> for a pillar URL nothing else lists; type is post or page; source is content_item, page_list or crawl; role is the stored page role or null; suggested_anchor is the target’s keyword, else its title without a brand suffix; is_pillar_for_item marks the item’s own pillar. The item named by content_id is never listed, and when it is itself its cluster’s pillar the response has pillar: null and a note. notes explains anything missing (no money page marked, no pillar found). 400 project_id_required and 404 project_not_found are the errors. The Olympus content list and get also carry url (and get carries url_source) per item. See Links that build the architecture.

Article Images

/marketing/content/{id}/images

Preview an article images run: no model call, no spend. Requires marketing.content read. The Olympus twin is GET /api/olympus/marketing/content/{id}/images under an API key.

Response

{
  "data": {
    "content_id": "content_abc123",
    "hero": { "has_featured_image": false, "featured_image_url": null },
    "sections": [
      { "heading": "Why uptime drops in year three", "anchor": "why-uptime-drops-in-year-three", "has_image": false },
      { "heading": "What the maintenance log shows", "anchor": "what-the-maintenance-log-shows", "has_image": true }
    ],
    "candidates": 1,
    "allowance": { "used": 12, "limit": 50, "remaining": 38 }
  }
}

sections is every H2 in the body with whether an image already sits directly below it; candidates counts the ones a run could illustrate. allowance.remaining is null on an unlimited plan.

/marketing/content/{id}/images

Run the pipeline: plan a hero and one image per H2 that adds information, render them (hero first, then the sections with the hero and the brand references as reference images), register each in the Media Library, place each under its heading, and set the featured image. Requires marketing.content update; the account must be in good billing standing. The Olympus twin is POST /api/olympus/marketing/content/{id}/images. Runs up to 300 seconds.

Request Body (every field optional; an empty body runs the default)

{
  "max_images": 4,
  "model": "gpt-image-2.5",
  "quality": "standard",
  "hero": true,
  "sections": true,
  "plan": {
    "hero": { "alt": "A CNC operator checking a spindle on a shop floor", "prompt": "..." },
    "sections": [
      { "heading": "Why uptime drops in year three", "alt": "A worn spindle bearing beside a new one on a workbench", "prompt": "..." }
    ]
  }
}

Field	Meaning
`max_images`	1 to 8, default 4, hero included. A longer post gets a second run, not a slideshow
`model`	`gpt-image-2.5` (default), `gpt-image-2.5-sunburst`, `gemini-3.1` or `gpt-5.4`
`quality`	`standard` (default) or `high`, or one of the GPT Image qualities `low`, `medium`, `high`, `xhigh`, `max`, `auto`
`hero`	Whether to make a hero. Default: yes when the item has no featured image
`sections`	Whether to make section images. Default `true`
`plan`	Skip the planner and supply the images yourself: `hero` as `{ alt, prompt }` or `null`, and `sections` as `[{ heading, alt, prompt }]` where every `heading` is an H2 that has no image yet

Response

{
  "data": {
    "content_id": "content_abc123",
    "plan": { "hero": { "alt": "...", "prompt": "..." }, "sections": [{ "heading": "...", "anchor": "...", "alt": "...", "prompt": "..." }] },
    "images": [
      { "url": "https://.../content-images/content_abc123/hero-hero-....png", "alt": "...", "heading": null, "anchor": null, "asset_id": "asset_123", "role": "hero" },
      { "url": "https://.../content-images/content_abc123/section-why-uptime-....png", "alt": "...", "heading": "Why uptime drops in year three", "anchor": "why-uptime-drops-in-year-three", "asset_id": "asset_124", "role": "section" }
    ],
    "warnings": [],
    "content": "...the body after insertion...",
    "content_changed": true,
    "featured_image_url": "https://.../hero-hero-....png",
    "featured_image_alt": "...",
    "featured_image_changed": true,
    "brand_applied": true,
    "brand_reference_ids": ["logo_primary", "asset_987"],
    "allowance": { "used": 14, "limit": 50, "remaining": 36 },
    "updated_at": "2026-09-12T15:04:11.000Z"
  }
}

Every image is registered in the Media Library with its alt text, prompt and model under the tags content_image and content:<item id>; an asset_id of null means the image is hosted and placed but the library row could not be written. warnings names a heading that already had an image (left alone), a render that failed (its generation refunded) and, when the allowance ran out part-way, the images that were not made.

Status	Meaning
`200`	The run completed; read `warnings` for anything partial
`400` `invalid_request`	A field is out of range, or the body is not JSON. Nothing is spent
`400` `invalid_plan`	`plan.sections` names a heading that is not an H2 without an image; the offenders are listed. Nothing is spent
`402` `quota_exhausted`	The monthly image allowance is used up before anything was planned; the body carries `remaining: 0`, `used` and `limit`
`404`	The item is not in this account
`503` `brand_unavailable`	The brand guide could not be read; nothing is spent. Retry
`503` `planner_unavailable` / `planner_bad_response`	The image planner did not answer, or did not return a plan; nothing is spent. Retry, or send a `plan`

See Images for the piece.

Brand Image Profile

/olympus/marketing/brand/image-profile

Olympus API key. The account’s brand image profile exactly as every branded image generation sends it. Read-only. Query project_id (optional website project UUID; that project’s own guide wins over the account-level guide). The brand_image_profile_get MCP tool is the same read.

Response

{
  "data": {
    "prompt_block": "Brand image profile (apply when this is brand or marketing material; ignore for a clearly non-brand request).\nBrand: Acme Corp, a Construction brand.\nPalette: primary #1E40AF, secondary #F59E0B, accent #10B981, background #FFFFFF, text #111827.\nTypography for any text in the image: headings in Inter, body text in Inter.\nPhotography style: warm lighting, real people on job sites.\nLogo: the primary logo is supplied as the first reference image; reproduce it exactly, never redraw, restyle or recolour it, and use it only where a logo naturally belongs.\nAvoid: stock-photo handshakes.",
    "avoid_list": ["stock-photo handshakes"],
    "reference_images": [
      { "id": "logo_primary", "url": "https://.../logo.png", "role": "logo" },
      { "id": "asset_987", "url": "https://.../site-photo.jpg", "role": "brand" }
    ],
    "reference_tag": "brand_reference"
  }
}

prompt_block is plain sentences rendered from the imagery side of the brand guide; avoid_list is the forbidden phrases plus the imagery don’ts; reference_images is the primary logo first (role logo, id logo_primary), then up to three Media Library images tagged brand_reference (role brand, id = the media asset id), newest first. To mark an approved brand image, add brand_reference to its tags with PATCH /api/olympus/marketing/media/{assetId}.

Status	Meaning
`200`	The profile
`404` `no_active_brand_guide`	The account (or the project) has no active brand guide
`503` `brand_unavailable`	The guide could not be read. Retry

See The brand image profile.

Performance and Leads

/marketing/content/views

Batch page and lead stats for up to 200 content items, the read behind the list’s Leads column. Requires marketing.content read. The Olympus twin is POST /api/olympus/marketing/content/views.

Request Body

{ "items": [{ "projectId": "f7a0ec1d-...", "path": "/blog/why-dentists-need-local-seo" }] }

Response

{
  "stats": {
    "f7a0ec1d-...:/blog/why-dentists-need-local-seo": {
      "views": 1840, "views30d": 410, "visitors": 1290,
      "form_submits": 31, "form_submits30d": 9,
      "leads": 27, "leads30d": 8, "contacts": 24
    }
  }
}

path is site-absolute; the query string and fragment are stripped and the trailing slash removed, and the key in stats carries that normalised path. form_submits is what the tracking embed saw in the browser; leads is what reached the forms ledger, with spam, duplicates and deleted rows excluded; contacts is the CRM contacts those rows resolved to. A pair with no page views and no ledger rows is absent from stats, not zero-filled, and a project the account does not own is omitted without an error. When the analytics collector is unreachable the response is a 200 with stats: {} and degraded: true: read degraded before reading an absent key as zero. More than 200 items, or no items, is a 400. Nothing is written.

/marketing/content/{id}/scorecard

The per-piece scorecard the editor’s Performance section shows, computed now for ?window (7d, 30d, 90d or all; default 30d), plus last_stored, the date and computed_at of the newest nightly row, or null before the first nightly run. Requires marketing.content read.

/olympus/marketing/content/{id}/analytics

Olympus API key (the content_analytics_get MCP tool). The same scorecard and last_stored, plus data, the stored daily rows the nightly writer keeps (one per closed UTC day; views and unique_views are that day’s own counts, external_analytics carries the rolling 30-day scorecard as of that night), newest first, paged with page and limit (default 30, max 100) and filtered with from_date and to_date, with pagination and a content_summary sourced from the live scorecard.

Response (the scorecard, the same on both)

{
  "scorecard": {
    "content_id": "content_abc123",
    "project_id": "f7a0ec1d-...",
    "path": "/blog/why-dentists-need-local-seo",
    "window": { "key": "30d", "from": "2026-08-13T15:04:05.000Z", "to": "2026-09-12T15:04:05.000Z" },
    "views": 410,
    "visitors": 322,
    "form_submits": 9,
    "leads": 8,
    "contacts": 7,
    "attributed_contacts": 5,
    "deals": { "created": 2, "won": 1, "pipeline_value_cents": 480000, "won_value_cents": 180000 },
    "rank": { "best_position": 4, "keywords": [{ "keyword": "dentist local seo", "current_rank": 4, "best_rank": 3, "last_checked_at": "2026-09-12T06:00:00.000Z" }] },
    "social": { "posts": 3, "published": 3, "engagement": 88, "impressions": 4120, "likes": 61, "comments": 9, "shares": 18, "clicks": 74 },
    "lead_rate": 0.0195,
    "degraded": { "clickhouse": false },
    "computed_at": "2026-09-12T15:04:05.000Z"
  },
  "last_stored": { "date": "2026-09-11", "computed_at": "2026-09-12T02:10:44.000Z" }
}

views, visitors and form_submits are null when the piece has no site page (path is null) or the collector could not answer (degraded.clickhouse is true); they are never 0 in either case. leads, contacts and attributed_contacts come from Postgres and always answer. deals is null when there were no contacts to roll up; lead_rate is leads / views to four decimals, null when views is null or zero. rank.keywords are the rank-tracking rows publish-to-site seeded for the item; social sums the latest snapshot of every post carrying linked_content_id. See The scorecard.

Campaign ROI

/marketing/reports/campaign-roi

Attributed contacts, deals and revenue per marketing asset, content items included, from the credit table through the shared revenue engine: the same builder as the Reports hub. Requires marketing.reports read. The Olympus twin is GET /api/olympus/marketing/reports/campaign-roi (the marketing_campaign_roi MCP tool). Read-only.

Query Parameters

Parameter	Meaning
`from`, `to`	ISO 8601 or `YYYY-MM-DD`; a date-only `to` is inclusive of that day
`attribution`	`first`, `last` (default) or `any`: participation counting, where per-asset rows overlap and the summary is computed once over the union of contacts
`confidence`	`all` (default) or `solid` (exact-id and alias credits only)
`asset_types`	Comma-separated: `email_campaign`, `ppc_campaign`, `social_post`, `content_item`, `email_sequence`, `cold_email_campaign`, `site_page`, `media_asset`; default all. A `400` when nothing named is a known type

Response

{
  "window": { "from": "2026-08-13T00:00:00.000Z", "to": "2026-09-12T23:59:59.999Z" },
  "attribution": "last",
  "confidence": "all",
  "asset_types": ["content_item"],
  "truncated": false,
  "spend_data_through": "2026-09-11",
  "assets": [
    { "asset_type": "content_item", "asset_id": "content_abc123", "name": "Why dentists need local SEO", "status": "published", "platform": null, "spend_cents": 0, "sends": null, "impressions": null, "clicks": null, "contacts": 5, "deals_created": 2, "deals_won": 1, "pipeline_value_cents": 480000, "won_value_cents": 180000, "payments_applied_cents": 180000, "shopify_revenue_cents": 0, "revenue_cents": 180000, "roas": null }
  ],
  "summary": { "mode": "attributed", "spend_cents": 0, "contacts": 5, "deals_created": 2, "deals_won": 1, "pipeline_value_cents": 480000, "won_value_cents": 180000, "payments_applied_cents": 180000, "shopify_revenue_cents": 0, "revenue_cents": 180000, "roas": null },
  "mixed_currency": false
}

Money is integer cents in each source’s own currency, not FX-normalised; mixed_currency is true when the sums span more than one currency. truncated is true when more than 200 assets were cut, the biggest contact sets kept. A content item is credited when a visitor arrived on a link carrying utm_medium=content and utm_content=<its slug>, the keys the repurpose source package and the weekly digest stamp. See UTM crediting.

Proof Pack

/marketing/content/proof-pack

The account’s proof in one read: public consented testimonials, review text, the first inbound message of support tickets in the segment, call summaries, completed-survey free text, measured results from the active before/after grids and the objection library with its best response. Requires marketing.content read. The Olympus twin is GET /api/olympus/marketing/content/proof-pack (the content_proof_pack MCP tool). Read-only.

Query Parameters

Parameter	Meaning
`avatar_id`	Customer avatar UUID in this account; tickets are segmented by its tags and grids by target avatar. `404 avatar_not_found` outside the account, `400` when malformed
`journey_stage`	Stage name, free text; classified into awareness, consideration, decision or retention, which orders the mix
`keyword`	Case-insensitive substring every entry must contain (up to 120 characters)
`since`	ISO date or datetime; only records on or after it
`limit`	Entries in the pack, 1 to 100, default 40

Response

{
  "data": {
    "generated_at": "2026-09-12T15:04:05.000Z",
    "filters": { "avatar_id": "a1a1a1a1-...", "journey_stage": "Decision", "journey_stage_kind": "decision", "keyword": null, "since": null, "limit": 40 },
    "avatar": { "id": "a1a1a1a1-...", "name": "Practice owner", "tags": ["dental"] },
    "entries": [
      { "source_type": "testimonial", "source_id": "t1", "date": "2026-08-02", "text": "We booked eleven new patients in the first month.", "attribution": "Dr Lena Ortiz, Ortiz Dental", "consent": true, "citation": "[source: testimonial:t1]", "rating": 5 },
      { "source_type": "grid_result", "source_id": "g1", "date": "2026-07-15", "text": "Map-pack impressions from 1,200 to 4,800 a month", "attribution": null, "consent": true, "citation": "[source: before_after_grid:g1]" },
      { "source_type": "ticket", "source_id": "k7", "date": "2026-06-30", "text": "We are on page three and the phone has stopped ringing.", "attribution": null, "consent": false, "citation": "[source: ticket:k7]" },
      { "source_type": "objection", "source_id": "o2", "date": null, "text": "We tried SEO before and nothing happened.", "attribution": null, "consent": false, "citation": "[source: objection:o2]", "response": "Ask what was measured; most practices were sold rankings, not calls." }
    ],
    "counts": { "testimonial": 4, "review": 12, "ticket": 9, "call": 3, "survey": 2, "grid_result": 5, "objection": 6 },
    "phrases": [{ "phrase": "new patients", "count": 7 }],
    "sources": [{ "source_type": "call", "count": 3, "ok": true }, { "source_type": "survey", "count": 0, "ok": false, "note": "No survey responses in the window" }],
    "notes": []
  }
}

consent is read from the rows, never assumed: true (testimonial, review, grid result) may be quoted verbatim with its attribution; false (ticket, call, survey, objection) is internal voice of customer to paraphrase without a name. citation is the marker the pre-publish check accepts as a source beside a figure. Entries are interleaved in the order the stage calls for; text is at most 600 characters. A source that cannot be read is reported with ok: false in sources and a line in notes, and the other sources still return.

Status	Meaning
`200`	The pack
`400`	A malformed query (a non-UUID `avatar_id`, a `limit` out of range, a `since` that is not a date)
`404` `avatar_not_found`	The avatar is not in this account

Case Study

/marketing/content/case-study

Draft a case study from a won CRM deal and save it as a content item of type case_study in draft, at the Decision stage. Requires marketing.content create; the row is attributed to the user. The Olympus twin is POST /api/olympus/marketing/content/case-study (the content_case_study_draft MCP tool). The draft holds the request open for up to three minutes and honours Idempotency-Key, so a retry replays the first answer instead of saving a second row.

Request Body

{
  "deal_id": "d1d1d1d1-...",
  "testimonial_id": "t1t1t1t1-...",
  "grid_item_id": "g1g1g1g1-...",
  "avatar_id": "a1a1a1a1-..."
}

Field	Meaning
`deal_id`	Required. A won deal in this account: its status is one the account marks `is_won` in its CRM statuses, or the literal `won` or `closed_won`
`testimonial_id`	Optional. Must be public with consent granted and not revoked. Omitted: the newest consented testimonial from the deal’s contacts, when there is one
`grid_item_id`	Optional. A before/after grid id, or the `item_id` of one transformation inside a grid
`avatar_id`	Optional. A customer avatar in this account; omitted: the grid’s target avatar

Response

{
  "data": {
    "id": "content_abc124",
    "slug": "ortiz-dental-map-pack",
    "title": "How Ortiz Dental went from page three to the map pack",
    "status": "draft",
    "content_type": "case_study",
    "avatar_id": "a1a1a1a1-...",
    "before_after_grid_id": "g1g1g1g1-...",
    "journey_stage": "Decision",
    "case_study": {
      "client": { "company": "Ortiz Dental", "industry": "Dental", "contact_name": "Lena Ortiz", "contact_role": "Owner" },
      "problem": "The practice sat on page three and the phone had stopped ringing.",
      "solution": "A Business Profile rebuild, review capture and three service pages.",
      "results": [{ "metric": "Map-pack impressions a month", "before": "1,200", "after": "4,800", "source": "before_after_grid:g1g1g1g1-..." }],
      "quote": { "text": "We booked eleven new patients in the first month.", "author": "Dr Lena Ortiz", "consent": true, "source": "reputation_testimonial:t1t1t1t1-..." },
      "sources": ["crm_deal:d1d1d1d1-...", "reputation_testimonial:t1t1t1t1-...", "before_after_grid:g1g1g1g1-..."],
      "deal_id": "d1d1d1d1-...",
      "drafted_at": "2026-09-12T15:04:05.000Z"
    },
    "sources": ["crm_deal:d1d1d1d1-...", "reputation_testimonial:t1t1t1t1-...", "before_after_grid:g1g1g1g1-..."],
    "notes": []
  }
}

The body has five sections (The problem, What we did, Results, In their words, What this means for you); every result line carries [source: before_after_grid:<id>] and the quote [source: reputation_testimonial:<id>]. Numbers never come from the model: the results are parsed from the grid’s measurable results, and the quote is copied from the testimonial row and never rewritten. The editor shows the record in its five case-study sections, with the sources read-only.

Status	Meaning
`201`	The draft was saved
`400` `invalid_request` / `invalid_reference`	A malformed body, or an avatar outside the account. Nothing is written
`404` `deal_not_found` / `testimonial_not_found` / `grid_not_found`	The record is not in this account
`409` `deal_not_won`	The deal’s status is not a won status. Nothing is written
`409` `no_consent`	The testimonial is not public with consent granted and not revoked. Nothing is written
`502` `draft_unavailable` / `draft_bad_response`	The content department did not answer, or did not answer with the JSON asked for. Nothing is written

See Proof and case studies.

Research

/marketing/content/{id}/research

The stored research for the item: settings.research and the knowledge artifact it points at, each null before the first run. Requires marketing.content read. The Olympus twin is GET /api/olympus/marketing/content/{id}/research (the content_research_get MCP tool).

/marketing/content/{id}/research

Run the research for the item: every knowledge base in the account first, then the SERP for the target keyword, then up to max_sources web pages, extraction with a verbatim quote per claim, indexing of every page used into the account’s Content research knowledge base, the artifact, and settings.research stamped last. Requires marketing.content update. The Olympus twin is POST /api/olympus/marketing/content/{id}/research (content_research_run). Synchronous, up to 300 seconds: use a client timeout of 240 seconds or more and send an Idempotency-Key.

Request Body (every field optional)

Field	Meaning
`queries`	Up to five, each up to 200 characters; default the target keyword, else the title
`keyword`	The SERP keyword when it differs from the target keyword
`include_web`, `include_serp`	Default `true`
`max_sources`	Web pages to fetch and index, 1 to 10, default 5
`location_code` / `location_name`	SERP market; `2840`, `2826`, `2124`, `2036`, `2372` and `2554` map to a name, any other code falls back to the account market with a warning; `location_name` wins when given
`index_sources`	Default `true`
`serp_brief_from_item`	Default `true`: reuse `settings.serp_brief` when it was captured in the last 30 days instead of paying for the SERP

Response (201)

{
  "data": {
    "artifact_id": "art_123",
    "knowledge_base_id": "kb_research",
    "artifact_created": false,
    "content_id": "content_abc123",
    "topic": "Why dentists need local SEO",
    "queries": ["dentist local seo"],
    "ran_at": "2026-09-12T15:04:05.000Z",
    "research": { "version": 1, "artifact_id": "art_123", "knowledge_base_id": "kb_research", "ran_at": "2026-09-12T15:04:05.000Z", "queries": ["dentist local seo"], "claims_count": 7, "stats_count": 3, "sources": [{ "url": "https://example.org/local-seo-study", "title": "Local SEO study 2026", "document_id": "doc_1", "page_id": "page_1" }], "serp_keyword": "dentist local seo", "gaps": [] },
    "claims": [
      { "claim": "Most map-pack clicks go to the top three results.", "quote": "the top three listings receive 64% of clicks", "source_url": "https://example.org/local-seo-study", "page_id": "page_1", "document_id": "doc_1", "upload_id": "up_1", "knowledge_base_id": "kb_research", "kind": "web", "score": null },
      { "claim": "The practice offers same-week emergency appointments.", "quote": "Same-week emergency appointments for new patients", "source_url": null, "page_id": null, "document_id": "doc_9", "upload_id": "up_9", "knowledge_base_id": "kb_services", "kind": "kb", "score": 0.61 }
    ],
    "stats": [{ "statement": "Share of clicks to the top three", "value": "64%", "source_url": "https://example.org/local-seo-study", "quote": "the top three listings receive 64% of clicks", "page_id": "page_1", "document_id": "doc_1", "kind": "web" }],
    "competitor_notes": [{ "url": "https://competitor.example/local-seo", "domain": "competitor.example", "position": 1, "title": "Local SEO for dentists", "notes": "Covers review velocity; no pricing." }],
    "gaps": [{ "question": "Average cost per new patient from local search", "why": "no source found" }],
    "sources": [{ "url": "https://example.org/local-seo-study", "title": "Local SEO study 2026", "document_id": "doc_1", "upload_id": "up_1", "page_id": "page_1", "indexed": true, "already_indexed": false, "chars": 12800, "query": "dentist local seo" }],
    "serp": { "keyword": "dentist local seo", "location_code": 2840, "captured_at": "2026-09-12T15:04:05.000Z", "top_10": [{ "position": 1, "url": "https://competitor.example/local-seo", "title": "Local SEO for dentists", "domain": "competitor.example" }], "people_also_ask": [], "features": [] },
    "kb_hits": 4,
    "web_hits": 5,
    "extraction": "llm",
    "confidence_score": 0.86,
    "spent": { "serp_requests": 1, "search_requests": 1, "scrape_requests": 5, "documents_indexed": 5, "kb_searches": 1 },
    "warnings": []
  },
  "result_info": { "queries": ["dentist local seo"], "spent": { "serp_requests": 1, "search_requests": 1, "scrape_requests": 5, "documents_indexed": 5, "kb_searches": 1 }, "warnings": [], "extraction": "llm", "artifact_created": false }
}

Every claim’s quote is copied verbatim from the passage it cites; a quote the run cannot find in the passage is dropped and counted in warnings. kind is web for a fetched page (with source_url) and kb for a knowledge-base passage (source_url is null; cite the knowledge base). extraction is fallback and confidence_score is 0 when no model key is configured: the passages themselves are the claims. A monthly SEO research cap hit returns serp: null and a gap, not an error; a page over 60,000 characters is skipped and reported as a gap; one source failing to index is reported (indexed: false) and the run continues. A re-run refreshes the same artifact (artifact_created: false) and never re-indexes a URL the knowledge base already holds (already_indexed: true). The stamp is at most 8,000 characters (sources and gaps trimmed to 10) and is merged into settings, so sibling keys survive.

Status	Meaning
`201`	The run completed; read `warnings` and `gaps` for anything partial
`400`	A field is out of range (too many queries, `max_sources` outside 1 to 10)
`404`	The item is not in this account. Nothing is written
`500`	The artifact could not be written; nothing is stamped

/olympus/marketing/content/research

Olympus API key (content_research_topic). The same run for a topic that has no content item yet: topic (required), keyword, avatar_id, project_id and the same knobs. Nothing is stamped; the artifact is the deliverable and its id can be attached to an item later. GET on the same path lists the artifacts in the account’s Content research knowledge base (every type), newest first, with artifact_type, content_id, is_verified, page and limit as filters; knowledge_base_id is null and data empty before the first run created the KB.

See Research with the knowledge base.

Knowledge Documents

/olympus/marketing/knowledge-bases/{kbId}/documents

Olympus API key (kb_documents_index_text). Stores a raw text document in the knowledge base and indexes it for kb_search: the server chunks and embeds the full text and keeps a 1000-character preview on the row. Body content (required; 400 content is required), title (default Untitled document, stored as metadata.filename), source_url, tags, metadata (an object merged into the row) and embed (false skips the vector index). Idempotency-Key honoured. 404 when the knowledge base is not in the account.

source_url and tags (2026-09-12). These are the two keys the kb_documents_index_text tool has always sent; until this date the route dropped both, so an indexed passage had no URL to cite and a research run could not tell the page was already in the knowledge base. source_url is stored as metadata.url in the normalised form the research run compares against (fragment dropped; utm_*, fbclid, gclid, mc_cid, mc_eid and ref parameters stripped; lower-case host; no trailing slash), so a later run finds the page already indexed instead of indexing it twice and a search hit cites it. Absent, null or blank writes no URL; a value that is not an http(s) URL is a 400 source_url must be an http(s) URL, a non-string a 400 source_url must be a URL string, both before anything is written. tags is stored as metadata.tags, trimmed, blank entries dropped, de-duplicated, each cut to 100 characters and at most 50 kept; anything but an array of strings is a 400 tags must be an array of strings. Both win over a url or tags key inside metadata, and the same provenance goes on every vector. Response

{
  "data": {
    "id": "doc_123",
    "knowledge_base_id": "kb_research",
    "content": "Plans start at 49 a month...",
    "metadata": { "filename": "Pricing page", "source": "olympus_api", "text_length": 1840, "url": "https://www.example.com/pricing", "tags": ["pricing", "website"], "upload_id": "up_9f2", "chunks_created": 3 },
    "created_at": "2026-09-12T15:04:05.000Z"
  },
  "upload_id": "up_9f2",
  "chunks_created": 3
}

The example was sent with source_url https://www.Example.com/pricing/?utm_source=newsletter#plans; the stored metadata.url is the normalised form. GET on the same path pages the documents (page, limit up to 100) as { data, pagination: { page, limit, total, total_pages } }.

Knowledge Artifacts

/olympus/knowledge-bases/artifacts

Olympus API key (kb_artifacts_list). Every knowledge artifact in the account, by type, without knowing the knowledge base id first, newest first. Query artifact_type (content_research, serp_brief, positioning, proof_pack, case_study, data_study, or any type a writer stored), kb_id, content_id (artifacts whose content_json.content_id matches), is_verified (true or false), page (default 1) and limit (default 20, max 100); a page or limit that is not a positive number is read as the default.

Response

{
  "data": [
    { "id": "art_123", "knowledge_base_id": "kb_research", "artifact_type": "content_research", "name": "Research: Why dentists need local SEO", "content_json": { "version": 1, "content_id": "content_abc123" }, "content_markdown": "# Research: Why dentists need local SEO\n\n## Claims\n...", "source_chunk_ids": [], "source_page_ids": ["page_1"], "generated_from_kb_ids": ["kb_services", "kb_research"], "confidence_score": 0.86, "is_verified": false, "created_at": "2026-09-05T09:12:00.000Z", "updated_at": "2026-09-12T15:04:05.000Z" }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

/olympus/knowledge-bases/artifacts/{artifactId}

Olympus API key (kb_artifact_get). One artifact by id, the id a settings.research, settings.serp_brief or settings.proof_pack stamp carries. 404 when the artifact’s knowledge base is not in the account, 400 for a malformed id. Returns { data: artifact }.

The per-knowledge-base list at GET /api/olympus/marketing/knowledge-bases/{kbId}/artifacts is unchanged; these two are the account-wide view. An artifact’s markdown is also indexed as a document in its knowledge base, so kb_search finds it semantically and the hit carries metadata.artifact_id and metadata.artifact_type. See Artifacts, and how to find them.

Publish to Site

/olympus/marketing/content/{id}/publish-to-site

Olympus API key (the content_publish_to_site MCP tool). Publish a CMS-linked content item to its website collection through the same path the editor uses (mapping, validation, the versioned entry write, route resolution, rank-tracking enrolment for the target keyword), or take it down with { unpublish: true } (content_unpublish_from_site). A native entry lands in the project working tree and needs a deploy; a Webflow item is staged until an item publish. The on-page check runs first and its findings come back as warnings[] plus seo_check, never a block.

Since 2026-09-12 a publish also maps the item’s author (author_id, else the account default) onto the collection’s author reference, creating the entry in the scaffold’s authors collection when it is missing (a slug already typed into settings.cms_fields for that field wins); builds the page’s JSON-LD graph (WebSite, Organization, WebPage, an Article with the author as a Person, a BreadcrumbList, and a FAQPage when faq has questions), stores it as settings.json_ld and writes it into the collection’s JSON-LD field when one is mapped (a jsonLd, schemaMarkup, structuredData or customCode field; a value already typed into settings.cms_fields for it is published unchanged and the graph stays on the row); stamps refreshed_at when a live piece republishes on the same entry slug and marks the decay rows linked to the item refreshed; and regenerates the project’s llms.txt on every native write. An unpublish builds no graph. The ::cta and ::upgrade shortcodes publish verbatim on a markdown body for the site’s PostBody renderer; on an html-typed body they are removed at publish today, because this path hands the mapper no conversion plan yet. Response (200)

{
  "data": {
    "filePath": "content/blog/cnc-uptime-year-three.json", "slug": "cnc-uptime-year-three", "collectionId": "blog", "versionNumber": 3,
    "unmapped": [], "route": "/blog/cnc-uptime-year-three", "trackingStarted": true,
    "visibility": { "kind": "deploy_required" }, "mode": "native", "published": true, "note": "...",
    "warnings": ["Warning (content): Only 1 internal link; link at least 2 existing pages on the site."],
    "seo_check": { "ok": true, "score": 95, "checks": [], "stats": {} },
    "author": { "id": "d4d4d4d4-...", "name": "Jane Doe", "entry_slug": "jane-doe", "entry_created": false },
    "json_ld_target": "field",
    "refreshed": true,
    "llms_txt_regenerated": true,
    "publish_warnings": []
  }
}

json_ld_target is field, row (the graph is on the item only; a Webflow collection without a custom code field also gets a publish_warnings line) or null on an unpublish. Relay every publish_warnings[] line the way warnings[] are relayed.

Status	Meaning
`400`	The item is not linked to a project or a collection
`404`	The item, the manifest or the collection is not there
`422` `author_missing`	The collection requires an author and the item has none and the account has no default; `details: { field, code }`
`422` `author_entry_failed`	The author exists but its entry in the authors collection could not be written; `details: { field, code, author_id, warnings[] }` names the cause. Relay the warnings rather than asking for another author
`422`	Any other required field with no source; `details.field` names it
provider errors	Keep their own status and code (a Webflow `429` carries `retry_after_seconds`)

The scheduled-publish cron flips an entry live without this path, so a scheduled go-live regenerates no llms.txt and stamps no refreshed_at. See The markup a publish emits.

Content Authors

/olympus/marketing/content-authors

Olympus API key (content_authors_list). The account’s content authors, the named practitioners its posts publish under, default first then by name. No parameters. Returns

{ data: [{ id, account_id, name, role, bio, headshot_url, credentials, same_as[], voice_notes, is_default, content_count, created_at, updated_at }], total }

. Dashboard twin: GET /api/marketing/content-authors (marketing.content read).

/olympus/marketing/content-authors

Olympus API key (content_authors_create). Body name (required, up to 200 characters, unique per account), role, bio, headshot_url (http(s)), credentials, same_as (up to 20 http(s) URLs), voice_notes, is_default. The first author of an account becomes the default; is_default: true on another author makes it the default and clears the previous one in the same transaction. 201 { data }; 400 invalid_request; 409 duplicate_name. Idempotency-Key honoured. Dashboard twin: POST /api/marketing/content-authors (marketing.content create).

/olympus/marketing/content-authors/{authorId}

Olympus API key (content_authors_get). One author: { data }, or 404 not_found (also for a malformed id).

/olympus/marketing/content-authors/{authorId}

Olympus API key (content_authors_update). Any of the create fields; null clears a text field. is_default: false on the current default is 409 default_required (make another author the default instead); a taken name is 409 duplicate_name. 200 { data }.

/olympus/marketing/content-authors/{authorId}

Olympus API key (content_authors_delete). Unlinks the author’s items (author_id null) and removes the row: 200 { data: { id, deleted: true, items_unlinked } }. The default cannot be deleted while other authors exist (409 default_in_use); the last author can. Dashboard twins: GET, PATCH and DELETE /api/marketing/content-authors/{authorId}.

content_items.author_id points at an author; a publish maps the item’s author, else the default, onto the collection’s author reference, and the author_missing check rule fires when an item has no author and the account has no default. See A named author on every post.

SERP Brief

/olympus/marketing/content/{id}/brief

Olympus API key (content_brief_build). Read the live Google SERP for the item’s target keyword (or the keyword sent; neither is 400 keyword_required), parse the top parse_top organic pages (default 3, at most 5), decide the search intent and the page type, derive the word-count band and what the top three all say, store the brief as a serp_brief knowledge artifact and the SERP into seo_serp_analysis, and stamp search_intent, page_type, serp_brief and serp_brief_captured_at on the row last, with settings.serp_brief in the shape the research run reuses for 30 days. Body (all optional): keyword, avatar_id, project_id, location_code or location_name, parse_top. Runs up to 300 seconds; Idempotency-Key honoured. Dashboard twin: POST /api/marketing/content/{id}/brief (marketing.content update).

Response (201)

{
  "data": {
    "content_id": "content_abc123",
    "topic": "materials testing lab",
    "brief": {
      "version": 1, "keyword": "materials testing lab", "location_name": "United States", "location_code": 2840, "captured_at": "2026-09-12T15:04:05.000Z",
      "intent": "commercial", "intent_signals": ["keyword modifier: lab (+3 commercial)"], "intent_decided_by": "rules",
      "page_type": "comparison", "page_type_signals": ["3 of the top 10 titles read as a comparison"], "page_type_decided_by": "rules",
      "result_types": { "organic": 10, "people_also_ask": 1 }, "features": ["people_also_ask"],
      "paa": ["How much does materials testing cost?"], "related_searches": ["materials testing near me"], "featured_snippet": null,
      "top_10": [{ "position": 1, "url": "https://rival.example/testing", "title": "Materials testing services", "domain": "rival.example" }],
      "top_results": [{ "position": 1, "url": "https://rival.example/testing", "title": "Materials testing services", "domain": "rival.example", "word_count": 1420, "h1": "Materials testing services", "outline": ["What we test", "Turnaround", "Pricing"] }],
      "word_count_band": { "min": 900, "max": 2100, "median": 1420, "target": 1400, "label": "long-form", "sample_size": 3 },
      "what_the_top_3_all_say": ["Turnaround", "Pricing"],
      "artifact_id": "art_456", "knowledge_base_id": "kb_research"
    },
    "artifact_id": "art_456", "knowledge_base_id": "kb_research", "artifact_created": true, "stamped": true,
    "serp_analysis": { "project_id": "seo_789", "written": true, "note": null },
    "spent": { "serp_requests": 1, "page_parses": 3, "model_calls": 0 },
    "warnings": []
  },
  "result_info": { "intent": "commercial", "page_type": "comparison", "spent": { "serp_requests": 1, "page_parses": 3, "model_calls": 0 }, "warnings": [], "artifact_created": true }
}

intent is informational, commercial, transactional or navigational; page_type is guide, listicle, comparison, landing, tool, news or how_to; *_decided_by is rules, model (the tie-break, at most one completion) or default. location_name wins over location_code; the codes 2840, 2826, 2124, 2036, 2372 and 2554 map to a market and any other falls back to the account market with a warning. Each build spends one SERP read plus parse_top page parses against the monthly SEO research cap.

Status	Meaning
`400`	A bad body, or `keyword_required` when the item has no target keyword and none was sent
`402` `seo_research_limit`	The monthly research cap is spent. Nothing is written
`404`	The item is not in this account. Nothing is written
`502` `serp_read_failed`	The SERP vendor did not answer

/olympus/marketing/content/{id}/brief

Olympus API key (content_brief_get). What is stored: { data: { content_id, search_intent, page_type, serp_brief, serp_brief_captured_at, artifact | null } }, or 404. Dashboard twin: GET /api/marketing/content/{id}/brief (marketing.content read).

/olympus/marketing/content/brief

Olympus API key (content_brief_topic). The same build for a topic that has no content item yet: topic or keyword is required (keyword defaults to topic), plus avatar_id, project_id, location_code or location_name and parse_top. Nothing is stamped; the artifact is the deliverable and content_id is null. 201 { data: ContentBriefResult, result_info }; 402 seo_research_limit; 502 serp_read_failed. Dashboard twin: POST /api/marketing/content/brief (marketing.content create).

The four brief columns are read-only on the content routes (400 read_only_field): this route is their writer. See The SERP brief.

Brand Positioning

/olympus/marketing/brand/positioning

Olympus API key (brand_positioning_get). The positioning on the active brand guide: the project’s own guide when project_id is given, else the account-level guide, else any active one; guide_id names a specific guide instead. Returns

{ data: { guide_id, guide_name, positioning: { thesis, beliefs[], we_are_against[], category_name, proof_points: [{ claim, source }] }, is_empty, updated_at } }

; 404 no_active_brand_guide. Dashboard twin: GET /api/marketing/brand/positioning (marketing.branding read).

/olympus/marketing/brand/positioning

Olympus API key (brand_positioning_set). Replaces the whole object: send every key each time, a key left out is cleared. The body is the positioning object itself or { positioning: {...} }; guide_id and project_id may ride in the body or the query. Strings are trimmed and capped (thesis 500, category 120, each belief or against 300, twelve entries per list, twelve proof points), a proof point needs both claim and source, and a 400 names the field. The saved object is mirrored as a verified positioning knowledge artifact in the Content research KB; a failed mirror is a warning. Returns 200 { data, artifact: { id, knowledge_base_id } | null, warnings: string[] }; 404 no_active_brand_guide. Dashboard twin: PUT /api/marketing/brand/positioning (marketing.branding update).

See Positioning.

Title Candidates

/olympus/marketing/content/{id}/titles

Olympus API key (content_titles_generate). Ask the content department for count (default 5, at most 10) claim-shaped titles, each tagged with one of the sixteen hook patterns (specific-number, contrarian, mistake, before-after, unanswerable-question, persona-callout, curiosity-gap, objection-first, in-medias-res, hot-take, list-promise, myth-truth, customer-quote, timely, proof-teaser, definition-reframe) filtered to the item’s journey stage and argued from the positioning. Stored as settings.title_candidates, replacing the previous set; nothing else on the item changes. A line is dropped and named in dropped[] when its pattern is not open at the stage, it carries an exclamation mark, it duplicates another or it equals the current title. Idempotency-Key honoured; the department call is capped at 120 seconds. Dashboard twin: POST /api/marketing/content/{id}/titles (marketing.content update).

Response (201)

{
  "data": {
    "content_id": "content_abc123",
    "title": "A guide to CNC uptime",
    "meta_title": "A guide to CNC uptime",
    "journey_stage": "Problem Aware",
    "hook_pattern": null,
    "candidates": [
      { "title": "Your machines are not slow, your calendar is", "pattern": "contrarian", "rationale": "Names the belief the positioning states." },
      { "title": "The 3 hours a week most shops lose to unplanned stops", "pattern": "specific-number", "rationale": "Quantifies the pain from the research figures." }
    ],
    "current_index": null,
    "picked": null,
    "results": null,
    "patterns_for_stage": ["contrarian", "mistake", "specific-number", "curiosity-gap", "unanswerable-question", "persona-callout"],
    "generated_at": "2026-09-12T15:04:05.000Z",
    "patterns_offered": ["contrarian", "mistake", "specific-number", "curiosity-gap", "unanswerable-question", "persona-callout"],
    "dropped": ["\"Everything you need to know about uptime\": pattern list-promise is not open at Problem Aware"],
    "positioning_used": true
  }
}

current_index is the 0-based index of the candidate whose text is live as meta_title, else title, or null; picked is settings.title_picked; results is settings.title_results once the weekly test has run. 404 outside the account (no writes); 502 titles_unavailable when the department does not answer, 502 titles_bad_response when it answers with nothing usable.

/olympus/marketing/content/{id}/titles

Olympus API key (content_titles_get). The same shape without patterns_offered, dropped and positioning_used. Dashboard twin: GET /api/marketing/content/{id}/titles (marketing.content read).

/olympus/marketing/content/{id}/titles/pick

Olympus API key (content_titles_pick). Body index (the 0-based position in settings.title_candidates), apply_to (both, the default, title or meta_title), change_summary. Writes the title and meta title, sets settings.hook_pattern to the candidate’s pattern when the H1 changes, stamps settings.title_picked { index, picked_at, picked_by, applied_to } and records a content_versions row. Returns

200 { data: { content_id, index, candidate: { title, pattern, rationale }, title, meta_title, hook_pattern, applied_to, version_number } }

; 400 invalid_index; 404. Idempotency-Key honoured. The new title reaches the live page only on the next publish of a published piece. Dashboard twin: POST /api/marketing/content/{id}/titles/pick (marketing.content update).

The weekly title test (Monday 06:10 UTC) pools the live title’s Search Console CTR with the click rates of the social posts tagged title:<index> and the email links carrying utm_term=title-<index>, writes settings.title_results and, when a candidate beats the live title by the thresholds, the winner to meta_title with a version row. See Titles that make a claim.

Refresh Brief

/olympus/marketing/content/{id}/refresh-brief

Olympus API key (content_refresh_brief_get). The pre-filled refresh brief for one item, assembled from rows that already exist; nothing is spent. 400 on a non-UUID, 404 content_not_found outside the account. Dashboard twin: GET /api/marketing/content/{id}/refresh-brief (marketing.content read).

Response (200)

{
  "data": {
    "version": 1, "generated_at": "2026-09-13T06:20:11.000Z",
    "content_id": "content_abc123", "title": "Why CNC uptime drops in year three", "url": "https://www.example.com/blog/cnc-uptime-year-three",
    "content_type": "article", "page_role": "support", "target_keyword": "cnc uptime", "search_intent": "informational", "page_type": "guide",
    "published_at": "2025-06-10T09:00:00.000Z", "last_published_at": "2025-06-10T09:00:00.000Z", "refreshed_at": null, "word_count": 1180, "website_project_id": "f7a0ec1d-...",
    "decay": { "decay_id": "dc1...", "status": "detected", "severity": "moderate", "decay_type": "traffic", "traffic_decline_pct": 41.2, "peak_traffic": 340, "current_traffic": 200, "peak_keywords": 18, "current_keywords": 11, "keywords_lost": 7, "peak_avg_position": 6.1, "current_avg_position": 9.8, "position_decline": 3.7, "content_age_days": 460, "detected_at": "2026-09-13T05:40:00.000Z", "last_analyzed_at": "2026-09-13T05:40:00.000Z", "refreshed_at": null, "recommended_actions": ["Update the year-three figures", "Add the maintenance log section"] },
    "declining_keywords": [{ "query": "cnc uptime", "prior_clicks": 210, "current_clicks": 120, "prior_position": 5.2, "current_position": 8.9, "clicks_lost": 90 }],
    "serp_brief": { "captured_at": "2026-09-12T10:00:00.000Z", "brief": { "version": 1 } },
    "scorecard": { "source": "content_analytics", "as_of": "2026-09-12", "window": "30d", "views": 410, "visitors": 322, "form_submits": 9, "leads": 8, "contacts": 7, "lead_rate": 0.0195, "best_position": 9, "deals_won": 1, "won_value_cents": 180000 },
    "keyword_siblings": [], "cannibalization": null,
    "link_donors": [{ "content_id": "n1...", "title": "The 2026 spindle maintenance log", "url": "https://www.example.com/blog/spindle-log-2026", "published_at": "2026-08-30T14:02:11.000Z", "same_cluster": true }],
    "refresh_priority": 2090, "decay_status": "detected", "review_disposition": null, "suggested_disposition": "refresh",
    "checklist": ["Re-read the SERP brief before changing the outline", "Cover the declining keywords", "Link the newer donors", "Publish on the same URL"]
  },
  "markdown": "# Refresh: Why CNC uptime drops in year three\n\n## What declined\n..."
}

decay_status mirrors the decay row and becomes recovered when the row converges away; refresh_priority is higher sooner (severe 3000, moderate 2000, mild 1000, plus the clicks lost); suggested_disposition is refresh, rewrite, consolidate, prune or double_down and the route only suggests: record the decision with review_disposition on the content update. The same brief is filed as the Refresh: title PM task by the Sunday run when no workflow handles the decay trigger. See The decision loop.

Prune Candidates

/olympus/marketing/content/prune-candidates

Olympus API key (content_prune_candidates). Published items at least min_age_days old (30 to 1095, default 365) with zero views and zero leads across the last twelve months, oldest first, up to limit (1 to 200, default 50), optionally on one project_id. Read-only. Dashboard twin: GET /api/marketing/content/prune-candidates (marketing.content read).

Response (200)

{
  "data": {
    "generated_at": "2026-09-13T06:22:00.000Z",
    "window": { "from": "2025-09-13T06:22:00.000Z", "to": "2026-09-13T06:22:00.000Z", "min_age_days": 365 },
    "candidates": [
      { "content_id": "old1...", "title": "Trade show recap, spring 2024", "url": "https://www.example.com/blog/trade-show-2024", "content_type": "blog_post", "page_role": "support", "published_at": "2024-05-01T09:00:00.000Z", "age_days": 865, "target_keyword": null, "views_12m": 0, "leads_12m": 0, "measured_by": "content_analytics", "suggested_disposition": "prune", "consolidate_into": null, "review_disposition": null, "decay_status": null, "default_action": { "tool": "content_unpublish_from_site", "route": "POST /api/olympus/marketing/content/:contentId/publish-to-site", "content_id": "old1...", "body": { "unpublish": true } } }
    ],
    "unmeasured": [{ "content_id": "np1...", "title": "Internal memo", "reason": "no_page" }],
    "counts": { "published_eligible": 40, "candidates": 1, "measured_by_analytics": 36, "measured_by_views_lookup": 2, "unmeasured": 1, "excluded_money_pages": 3, "truncated": 0 },
    "warnings": ["content_analytics has no rows covering the last 365 days for 2 item(s) (0 with rows that start inside the window); they were measured through the live views lookup"]
  }
}

measured_by is content_analytics (the nightly rows cover the window) or views_lookup (the live analytics query over the whole window, with a warning); an item that cannot be measured (no_page, clickhouse_unavailable) is under unmeasured, never a candidate. Money pages are excluded and counted. suggested_disposition is consolidate with consolidate_into when another published item holds the keyword or an open cannibalisation row (status detected, in_progress, open or monitoring, the one vocabulary the prune list, the refresh brief and the keyword map read since 2026-09-12) names it, else prune. default_action names the unpublish, which drafts the entry; nothing leaves the internet until the project deploys. 400 on a bad query. See Prune candidates.

Page Roles

/olympus/marketing/site-architecture/page-roles

Olympus API key (site_page_roles_get). Every page and post of one website project (project_id, required) with its page_role (money, pillar, support, utility or null), plus a suggestion for each unset row and the counts. Dashboard twin: GET /api/marketing/site-architecture/page-roles (marketing.content read).

Response (200)

{
  "data": {
    "project": { "id": "f7a0ec1d-...", "name": "Example site", "host": "https://www.example.com" },
    "pages": [
      { "page_id": "wp1...", "content_id": null, "title": "Pricing", "route": "/pricing", "url": "https://www.example.com/pricing", "page_role": "money", "kind": "website_page", "cluster_role": null, "topic_cluster_id": null, "status": "published" },
      { "page_id": null, "content_id": "a1b2c3d4-...", "title": "The CNC maintenance guide", "route": "/guides/cnc-maintenance", "url": "https://www.example.com/guides/cnc-maintenance", "page_role": null, "kind": "content_item", "cluster_role": "pillar", "topic_cluster_id": "c1c1c1c1-...", "status": "published" }
    ],
    "suggestions": [
      { "page_id": null, "content_id": "a1b2c3d4-...", "title": "The CNC maintenance guide", "route": "/guides/cnc-maintenance", "url": "https://www.example.com/guides/cnc-maintenance", "page_role": "pillar", "current_role": null, "reason": "cluster_role_pillar", "source": "content_items.cluster_role" }
    ],
    "counts": { "money": 1, "pillar": 0, "support": 6, "utility": 2 },
    "notes": []
  }
}

reason is conversion_goal (a url-kind conversion definition; a goal on a confirmation route such as /thank-you is skipped), seo_memory (the SEO department’s Money pages list), route_pattern, cluster_pillar_url or cluster_role_pillar. 400 project_id_required, 404 project_not_found.

/olympus/marketing/site-architecture/page-roles

Olympus API key (site_page_roles_set). Two bodies. { pages: [{ page_id | content_id, page_role }] } sets roles in bulk (up to 500; each entry its own write; null clears; a row outside the account is not_found, never updated):

200 { data: { results: [{ ok, page_id, content_id, page_role } | { ok: false, page_id, content_id, error, code: invalid_target | invalid_role | not_found | write_failed }], updated, failed } }

. { project_id, seed: true, apply?: boolean } proposes roles for the unset rows and, with apply: true, writes them, never over a role a person set: 200 { data: { suggestions, applied, failed, errors } }. 400 invalid_body names the bad entry (pages[2]: ...). Idempotency-Key honoured. Dashboard twin: POST /api/marketing/site-architecture/page-roles (marketing.content update).

Roles are stored, never inferred: the site-links order and the money_link_missing and pillar_link_missing check rules read them. See Page roles.

Keyword Map

/olympus/marketing/content/keyword-map

Olympus API key (content_keyword_map). Keyword to item to live URL to best rank position to decay status, grouped by topic cluster with the pillar row first, plus the collisions. Query project_id (optional website project UUID; 400 when malformed). Read-only. Dashboard twin: GET /api/marketing/content/keyword-map (marketing.content read).

Returns

{ data: { generated_at, project_id, groups: [{ cluster: { id, name, domain, pillar_keyword, pillar_url, coverage_score, internal_link_score, missing_subtopics } | null, rows: [{ keyword, normalized_keyword, content_id, title, status, content_type, url, project_id, cluster_id, cluster_role, page_role, search_intent, best_position, tracked_keywords, decay_status, refresh_priority, review_disposition, published_at }] }], collisions: [{ keyword, kind: duplicate_target | cannibalization, items: [{ content_id, title, url, status }], cannibalization: { id, domain, severity, status, recommended_primary_url, competing_pages } | null }], without_keyword: [{ content_id, title, status, url }], totals: { items, with_keyword, without_keyword, clusters, collisions, ranked, decaying } } }

. Every cluster is a group (an empty one lists its missing subtopics); items with no cluster are the last group with cluster: null; best_position is the lowest current rank among the rank-tracking rows seeded for the item. Read it before choosing a keyword for a new piece. See The keyword map.

Bottom-Funnel Plan

/olympus/marketing/content/bofu-plan

Olympus API key (content_bofu_plan). Plan the brand vs rival, rival alternatives and best category for segment pages for one website project from the tracked competitors, the active avatars and the brand guide, with DataForSEO volume and difficulty (one keyword_overview call for the exact phrases and, with include_ideas, one keyword_ideas call, both against the monthly SEO research cap), and optionally seed the drafts. Idempotency-Key honoured; a retried POST does not seed twice. Dashboard twin: POST /api/marketing/content/bofu-plan (marketing.content create).

Request Body

Field	Meaning
`project_id`	Required. A website project UUID in this account
`max_candidates`	1 to 40, default 12
`seed_drafts`	Default `false`. `true` writes one draft content item per candidate
`min_volume`	Monthly searches floor, default 10
`max_difficulty`	0 to 100, default 70
`rivals`	Hosts to add to (or supply instead of) the tracked competitor set
`include_ideas`	Default `true`: the discovery call

Response (201)

{
  "data": {
    "plan": {
      "project_id": "f7a0ec1d-...", "project_name": "Example site", "brand": "Acme", "category": "same-day materials testing",
      "rivals": [{ "host": "rival.example", "name": "Rival", "shared_keywords": 84, "organic_traffic": 12000, "source": "seo_competitor_analysis" }],
      "segments": [{ "avatar_id": "a1a1a1a1-...", "name": "Site engineer" }],
      "candidates": [
        { "type": "vs", "title": "Acme vs Rival", "target_keyword": "acme vs rival", "keyword_variants": ["acme versus rival"], "volume": 90, "keyword_difficulty": 22, "rival": "rival.example", "rival_name": "Rival", "segment": null, "search_intent": "commercial", "avatar_id": null, "template_slug": "brand-vs-rival", "content_type": "comparison", "evidence": { "rival_facts_sources": ["https://rival.example/pricing", "https://rival.example/"], "own_proof": { "testimonial": 4, "review": 12, "ticket": 9, "call": 3, "survey": 2, "grid_result": 5, "objection": 6 } } }
      ],
      "dropped": [{ "type": "alternatives", "title": "Rival alternatives", "target_keyword": "rival alternatives", "reason": "keyword_collision", "detail": "already targeted by \"Rival alternatives for site engineers\" (published, c2c2...)", "volume": 40 }],
      "filters": { "min_volume": 10, "max_difficulty": 70, "max_candidates": 12, "include_ideas": true },
      "spent": { "keyword_overview_requests": 1, "keyword_ideas_requests": 1 },
      "warnings": [], "notes": [], "generated_at": "2026-09-12T15:04:05.000Z"
    },
    "seeded": { "created": [{ "content_id": "n3...", "slug": "acme-vs-rival", "title": "Acme vs Rival", "type": "vs", "content_type": "comparison", "target_keyword": "acme vs rival", "template_slug": "brand-vs-rival" }], "skipped": [], "template_ids": { "brand-vs-rival": "t1...", "rival-alternatives": "t2...", "best-category-for-segment": "t3..." } },
    "artifact_id": "art_bofu", "artifact_created": true, "artifact_error": null
  },
  "result_info": { "candidates": 1, "dropped": 1, "seeded": 1, "skipped": 0, "spent": { "keyword_overview_requests": 1, "keyword_ideas_requests": 1 }, "warnings": [], "artifact_id": "art_bofu" }
}

dropped[].reason is volume_below_floor, difficulty_above_cap, keyword_collision, keyword_too_long or not_serviceable. A seeded draft carries content_type comparison or alternatives, page_role: money, journey_stage: Decision, search_intent: commercial, the avatar, the keyword, the project, settings.bofu and an empty settings.comparison_table and settings.decision_cta. The three templates appear in the templates list as account rows after the first plan. Two plans for one project at the same moment seed each page once. An empty competitor set, no category or no avatars returns 201 with no candidates, a note per gap, and spends nothing.

Status	Meaning
`400` `invalid_request`	A malformed body
`402` `seo_research_limit`	The monthly research cap is spent
`404` `project_not_found`	The project is not in this account
`502` `keyword_metrics_unavailable`	The overview read failed; nothing was counted
`500` `plan_failed`	The plan could not be built

/olympus/marketing/content/bofu-plan

Olympus API key (content_bofu_plan_get). The newest stored plan for project_id: { data: { artifact_id, knowledge_base_id, updated_at, plan, seeded } | null }; 400 without a UUID. Dashboard twin: GET /api/marketing/content/bofu-plan (marketing.content read).

See Bottom-funnel pages.

Brand Offers

/olympus/marketing/brand/offers

Olympus API key (brand_offers_get). The offers on the active brand guide (project_id resolves that project’s own guide first):

{ data: { guide_id, guide_name, cta_primary, lock_version, offers: [{ id, name, promise, guarantee, bonuses[], cta_label, cta_url, stages[] }] } }

. Dashboard twin: GET /api/marketing/brand/offers (marketing.content read).

/olympus/marketing/brand/offers

Olympus API key (brand_offers_set). Body { offers, project_id?, expected_lock_version? }. A full replacement: read first, send the whole list back. Ids are minted by the server, and an incoming id survives only when it names an existing entry, so content items stay pointed at it. Limits: 20 offers; name unique and up to 120 characters; promise and guarantee 400; eight bonuses of 200; cta_label 60; cta_url an http(s) URL or a site path starting with /, at most 500 characters; ten stages of 80. Idempotency-Key honoured. Dashboard twin: PUT /api/marketing/brand/offers (marketing.content update).

Status	Meaning
`200`	The list as stored, with the new `lock_version`
`400` `invalid_offers`	Names the entry and field (`offers[2].cta_url is required`); `invalid_request` for a malformed body
`404` `no_active_brand_guide`	The account (or the project) has no active brand guide
`409` `offers_conflict`	`expected_lock_version` is behind; the body carries the current `lock_version`. Reload and resend
`503` `brand_unavailable`	`{ error: "The brand guide could not be read; try again", code: "brand_unavailable" }`

stages are matched to a content item’s journey_stage case-insensitively; an offer with no stages fits every stage. content_items.offer_id is checked against this list at write time (an unknown id is 400 invalid_reference). See Offers on the brand guide.

Conversion Plan

/olympus/marketing/content/{id}/conversion

Olympus API key. The conversion plan of a content item (MCP tool content_conversion_plan_get): the journey-stage row it converts on, the offer it asks with, the lead magnet with everything it references, and the inline, end and upgrade blocks the ::cta and ::upgrade shortcodes render to. Read-only. Dashboard twin: GET /api/marketing/content/{id}/conversion (marketing.content read).

/olympus/marketing/content/{id}/conversion

Olympus API key (content_conversion_plan). The same plan, and it ensures the journey checkpoint: when the piece has a lead magnet with a form and sits on a journey stage, that stage gets a form_submit checkpoint for the form, once. Body { ensure_checkpoint: true } (the default). Idempotency-Key honoured. Dashboard twin: POST /api/marketing/content/{id}/conversion (marketing.content update).

Response (200)

{
  "data": {
    "content_id": "content_abc123",
    "generated_at": "2026-09-12T15:04:05.000Z",
    "plan": {
      "stage": { "stage_name": "Comparing options", "stage_id": "st3...", "rung": "solution_aware", "source": "keyword", "job": "Compare the ways to solve it", "allowed_hooks": ["contrarian", "myth-truth", "objection-first"], "proof_type": "case_study", "cta_verb": "compare", "destination": "comparison", "fallbacks": ["lead_magnet", "newsletter"] },
      "table": [{ "stage_name": "Problem Aware", "stage_id": "st2...", "rung": "problem_aware", "source": "keyword", "job": "Show the cost of the problem", "allowed_hooks": ["mistake", "specific-number"], "proof_type": "story", "cta_verb": "download", "destination": "lead_magnet", "fallbacks": ["newsletter"] }],
      "offer": { "id": "o1o1o1o1-...", "name": "Maintenance audit", "promise": "Know your year-three risk in a week", "guarantee": "No report, no invoice", "bonuses": [], "cta_label": "Book the audit", "cta_url": "/contact", "stages": ["Comparing options", "Ready to buy"] },
      "offer_source": "item",
      "cta_primary": "Book the audit",
      "lead_magnet": { "kind": "checklist", "title": "The pre-pour checklist", "description": null, "benefits": [], "asset_id": null, "content_item_id": null, "form_id": "b8b8b8b8-...", "delivery_sequence_id": null, "url": null, "asset": null, "content_item": null, "form": { "id": "b8b8b8b8-...", "form_key": "pre-pour-checklist" }, "sequence": null, "download_url": null, "missing": [] },
      "blocks": {
        "inline": { "variant": "inline", "verb": "compare", "destination": "comparison", "headline": "...", "supporting_line": "...", "label": "Compare the options", "url": "https://www.example.com/compare/acme-vs-rival", "form": null, "proof_type": "case_study", "proof_line": "..." },
        "end": { "variant": "end", "verb": "compare", "destination": "comparison", "headline": "...", "supporting_line": "...", "label": "Compare the options", "url": "https://www.example.com/compare/acme-vs-rival", "form": null, "proof_type": "case_study", "proof_line": "..." },
        "upgrade": { "kind": "checklist", "title": "The pre-pour checklist", "description": null, "benefits": [], "download_url": null, "form": { "form_key": "pre-pour-checklist", "form_id": "b8b8b8b8-...", "fields": ["email"], "submit_label": "Send me the checklist", "success_message": "It is on its way." } }
      },
      "warnings": [{ "code": "delivery_sequence_missing", "message": "No sequence delivers the checklist after the form submits." }]
    },
    "shortcodes": { "inline": 1, "end": 1, "upgrade": 1 },
    "journey": { "id": "j1...", "name": "Trade contractor journey" },
    "guide": { "id": "g1...", "name": "Acme brand" },
    "checkpoint": { "status": "created", "journey_id": "j1...", "stage_id": "st3...", "checkpoint_id": "cp1...", "is_exit": false },
    "delivery": { "status": "sequence_missing", "sequence_id": null, "note": "The form's submissions land in the ledger and the CRM; no sequence sends the file yet." }
  }
}

warnings[].code is one of lead_magnet_missing, lead_magnet_reference_missing, offer_missing, offer_stage_mismatch, comparison_page_missing, form_missing, delivery_sequence_missing, journey_stage_missing. offer_source is item, stage, first or null; checkpoint.status is created (this call made it), exists, missing or skipped with a reason; delivery.status is sequence_linked, sequence_inactive, sequence_missing, no_form or no_lead_magnet. The lead magnet is read as stored (kind download, checklist, template, guide or other); a kind the plan has no copy for renders as a guide. The publish path does not call this route yet. 400 on a malformed id, 404 content_not_found, 503 brand_unavailable. See Conversion inside the piece.

Content Comments

List Comments

/marketing/content/{id}/comments

Get all comments on a content item.

Add Comment

/marketing/content/{id}/comments

Add a comment to a content item.

Content Reviews

/marketing/content/{id}/reviews

Get review status and history for a content item.

/marketing/content/{id}/reviews

Submit a review (approve or request changes).

Version History

/marketing/content/{id}/versions

List all versions of a content item.

Image Upload

/marketing/content/{id}/upload-image

Upload an image to attach to a content item.

/marketing/content/{id}/delete-image

Remove an image from a content item.

​List Content

​Create Content

​Get Content

​Update Content

​Pre-Publish SEO Check

​Content Calendar

​Site Links

​Article Images

​Brand Image Profile

​Performance and Leads

​Campaign ROI

​Proof Pack

​Case Study

​Research

​Knowledge Documents

​Knowledge Artifacts

​Publish to Site

​Content Authors

​SERP Brief

​Brand Positioning

​Title Candidates

​Refresh Brief

​Prune Candidates

​Page Roles

​Keyword Map

​Bottom-Funnel Plan

​Brand Offers

​Conversion Plan

​Content Comments

​List Comments

​Add Comment

​Content Reviews

​Version History

​Image Upload

List Content

Create Content

Get Content

Update Content

Pre-Publish SEO Check

Content Calendar

Site Links

Article Images

Brand Image Profile

Performance and Leads

Campaign ROI

Proof Pack

Case Study

Research

Knowledge Documents

Knowledge Artifacts

Publish to Site

Content Authors

SERP Brief

Brand Positioning

Title Candidates

Refresh Brief

Prune Candidates

Page Roles

Keyword Map

Bottom-Funnel Plan

Brand Offers

Conversion Plan

Content Comments

List Comments

Add Comment

Content Reviews

Version History

Image Upload