Content API

List Content

/marketing/content

List all content items for the current organization.

Response

[
  {
    "id": "content_abc123",
    "title": "Getting Started with Hiveku",
    "status": "published",
    "author": "user_xyz",
    "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,
    "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, or published, by published_at descending) 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).

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"
}

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

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. 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. 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, and POST /api/olympus/marketing/content/{id}/publish-to-site returns it as warnings and seo_check. 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. Every published post and page on one website project with its live URL, for internal linking. Query project_id (required, a website project UUID in the account) and limit (default and maximum 500).

Returns

{ data: [{ id, title, url, type, published_at, slug, source }], total, capped, project: { id, name, host }, posts: { listed, without_url }, pages: { listed }, notes }

. type is post or page; source is content_item, page_list or crawl; notes explains anything missing. 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 The Content Department.

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 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.

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.

Overview

Account API

Builder API

Marketing API

CRM API

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 Artifacts

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 Artifacts

​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 Artifacts

Content Comments

List Comments

Add Comment

Content Reviews

Version History

Image Upload