Build on Roman

List articles

Retrieve a paginated list of articles with optional filters.

Create an article

Create a draft article record. Use the generation endpoints to produce the outline or content.

{
  "id": "article-id",
  "target_keyword": "best crm for startups",
  "status": "draft"
}

Bulk update article status

{ "success": true, "updated": 5 }

Bulk delete articles

Permanently delete multiple articles and their associated assets.

Get an article

Retrieve article content, outline, product, and writing-style details, plus content_markdown: the article body as Markdown however it happens to be stored.

Bodies are saved as HTML or as Markdown depending on how the article was written, so content_markdown is the field to read when you need one predictable format.

{
  "id": "article-id",
  "target_keyword": "best crm for startups",
  "headline": "The 9 Best CRMs for Startups",
  "status": "complete",
  "content_markdown": "## Why startups outgrow spreadsheets\n\nA spreadsheet stops...",
  "outline": { "sections": [] },
  "product": { "id": "product-id", "name": "Acme" }
}

Update an article

Send only the fields you want to change.

Delete an article

{ "success": true }

Generate an outline

Starts outline generation and returns 202 Accepted.

Fire-and-forget. Poll the article status or consume generation-events until a terminal event.

{
  "accepted": true,
  "articleId": "...",
  "stream": { "runId": "...", "url": "/api/articles/.../generation-events?runId=..." }
}

Generate article content

Starts content generation from an existing outline and returns 202 Accepted.

Fire-and-forget. Poll the article status or consume generation-events until a terminal event.

Generate full article

Starts outline and content generation in one background run.

Fire-and-forget. Use generation-events for live progress.

Stream article generation progress

Server-Sent Events stream for an accepted outline, content, or full-article generation run.

SSE stream. The stream also emits heartbeat events while the job is running.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Generate link suggestions

Return internal and external link suggestions for an article.

Generate LinkedIn post draft

Publish to connected CMS

Publishes an article through the configured CMS integration. Every field is optional; anything you omit falls back to the saved article.

Returns an SSE progress stream.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Sync from the live page

Replaces the article's content, SEO title and meta description with what is published now, the same as the Sync button on the article page. The article is read from its connected CMS when Roman can read that CMS, otherwise from its published URL (or the URL it was imported from), leaving out sign-up boxes, share links and related posts. The current version is saved to the article's history first. Your CMS and site are only read, never changed.

No body. When the published version already matches, nothing is rewritten and sync.changed is false. Returns 400 when the article has no live URL, 409 while it is being written or refreshed, 422 when the page is missing, moved to a different article, or has no readable article text, and 502 when the site could not be reached. Every error leaves the article unchanged.

Publish to your webhook

Posts the article to the custom webhook URL saved in Settings. The payload carries the body both as saved (content_html) and as Markdown (content_markdown). See the Webhook Publishing section for the full payload and headers.

Returns 400 with code WEBHOOK_NOT_CONFIGURED when no URL is saved, and 502 with WEBHOOK_FAILED or WEBHOOK_ERROR when your receiver rejects the request or cannot be reached.

{
  "success": true,
  "message": "Article published via webhook successfully.",
  "webhook_status": 200
}

Export as DOCX

Returns a binary DOCX file.

A binary response body. Read it as a blob or a stream; do not parse it as JSON.

List article assets

Update asset status

Delete article assets

Bulk generate articles

Generate content for multiple articles.

Returns one SSE session_created acknowledgement with HTTP 202, then closes. Progress is stored against the session, so poll GET /api/articles/bulk-write/:sessionId. Only one bulk run can be active per account at a time; starting a second returns 409 with the active session.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

List bulk write sessions

Returns the 20 most recent sessions with their items.

Get bulk write session

Returns one session with its items. Session status is queued or preparing while the run is waiting to start, running once it is under way, then completed, stopped, or failed.

{
  "id": "session-id",
  "status": "running",
  "mode": "outline_ready_content",
  "total_articles": 5,
  "completed_articles": 2,
  "failed_articles": 0,
  "items": [
    { "id": "item-id", "article_id": "...", "target_keyword": "best crm", "status": "completed", "step": null }
  ]
}

Stop a bulk write session

Stops an active run and cancels the items that have not started. Articles already written are kept.

Returns 400 when the run has already finished.

{ "success": true }

Bulk publish to CMS

Returns an SSE stream with progress.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

List products

Returns an array of the products this key can reach, newest first.

Create a product

Get a product

Returns the product with its writing style.

Update a product

Send only the product fields you want to change.

Writing style edits are revision-checked: 428 with code REVISION_REQUIRED when expected_revision is missing, 409 with code WRITING_STYLE_CONFLICT when someone saved first. Both responses carry the current revision.

Delete a product

{ "success": true }

Analyze product URL

Extract product details from a website.

Extract writing style

Suggest positioning

Extract product data from document

Send as multipart/form-data.

Run keyword research

List keyword research history

Returns the 50 most recent research queries, newest first.

{
  "queries": [
    { "id": "query-id", "seed_keyword": "best crm", "total_results": 412, "created_at": "2026-09-01T10:00:00.000Z" }
  ]
}

Get keyword research results

Returns the saved query and its keyword rows, highest search volume first.

{
  "query": { "id": "query-id", "seed_keyword": "best crm" },
  "results": [{ "id": "result-id", "keyword": "best crm for startups", "search_volume": 1900 }]
}

Add keyword results to import

Fetch the live Google results page (results in order; competitors = organic domains)

List keyword import batches

Create keyword import batch

Get import batch

Returns the batch with its keyword_imports rows.

Rename an import batch

Delete an import batch

Deletes the batch and the keyword rows in it.

{ "success": true }

Update a keyword import row

Returns 400 when the body contains none of these fields.

Delete a keyword import row

{ "success": true }

Generate from batch

Returns an SSE stream with progress.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

List content import batches

{
  "batches": [{ "id": "batch-id", "source_type": "sitemap", "status": "completed" }],
  "total": 12,
  "page": 1,
  "page_size": 50,
  "has_more": false
}

Create content import batch

Get content import batch

Delete content import batch

{ "success": true }

Stream content import progress

SSE stream.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Fetch source content

Reads the sitemap or connected CMS and records what it finds against the batch.

Returns an SSE stream.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Import fetched content as articles

Returns an SSE stream.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Get AI Visibility overview

Returns aggregate metrics, trend points, provider breakdowns, top prompts to fix, alerts, and suggestions.

Get AI Visibility settings

Read the configured brand, competitors, aliases, providers, cadence, and setup state.

List tracked prompts

Get prompt detail

Returns prompt metrics, provider responses, citations, fan-out queries, competitor rows, and timeline data.

List AI Visibility citations

List competitor profiles

Returns lightweight competitor profile summaries with AI visibility, share of voice, citation rate, citation URL count, and stable identifiers.

Get competitor profile

Returns one competitor profile and a paginated list of citation URLs. Each URL carries its content category and a per-prompt breakdown of where it was cited. The competitor path value is the stable identifier returned by the list endpoint; legacy encoded names are also accepted.

List AI Visibility alerts

List AI Visibility suggestions

List AI Visibility runs

List audits

Create an audit

Creates an audit job and auto-starts background processing when possible.

Background job. Read GET /api/seo-audit/:id for status and page counts.

Get audit details

Delete an audit

Deletes the audit and its crawled pages.

{ "success": true }

Start or continue audit processing

Safe to call repeatedly. Each call continues the audit where it left off and returns the saved progress, hasMore, and time estimates.

Returns 409 with { paused: true } while paused. Poll the audit details endpoint for completion.

{
  "progress": { "total": 160, "crawled": 42, "analyzed": 37 },
  "hasMore": true,
  "pages": [],
  "crawlRuntime": {
    "phase": "crawling",
    "currentUrl": "https://example.com/docs",
    "processedUrls": 42,
    "analyzedUrls": 37,
    "totalUrls": 160,
    "failedUrls": 1,
    "discardedUrls": 0,
    "crawlTargetSeconds": 1080,
    "crawlEtaSeconds": 708,
    "analysisEtaSeconds": 738,
    "summaryEtaSeconds": 60,
    "overallEtaSeconds": 798
  }
}

Get or queue the audit summary

Completed audits return the saved summary immediately. Audits still in progress continue where they left off and return the saved progress instead.

Clients must handle 200, 202, and 409 responses; an active request does not synchronously generate a summary.

// 200 — completed
{ "summary": { "overallScore": 82 }, "linkGraph": { "stats": { "totalPages": 160 } } }

// 202 — active
{ "queued": true, "progress": { "total": 160, "crawled": 42, "analyzed": 37 }, "hasMore": true }

// 409 — paused
{ "paused": true }

// 409 — failed
{ "error": "Resume, restart, or run a Deep Scan before requesting the summary." }

Run link analysis

Returns an SSE stream with progress.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Get audit insights

Returns the grouped issues found across the audited pages and how page scores are distributed.

copy_status is pending or generating while the written explanations are still being prepared, then ready. The rest of the response is already usable in all three states.

{
  "insights": {
    "diagnosis": "Thin metadata is the biggest drag on this site.",
    "stats": { "analyzedPages": 160, "averageScore": 74, "criticalPages": 12, "quickWins": 23 },
    "priorityActions": [
      { "id": "meta-descriptions", "title": "Write missing meta descriptions", "impact": "high", "effort": "low", "scope": 12, "pages": [] }
    ],
    "pageOpportunities": [],
    "metadataQueue": [],
    "performancePriorities": []
  },
  "score_distribution": { "good": 84, "fair": 52, "poor": 24, "total": 160 },
  "copy_status": "ready"
}

Get audited page details

Returns one crawled page with its checks and scores, plus a summary of the audit it belongs to.

Run deep page analysis

Returns an SSE stream with progress.

event: progress
data: {"status":"running","processed":12,"total":50}

event: done
data: {"status":"completed","id":"..."}

Preview sitemap URLs

List backlink sessions

Create backlink session

Get backlink session

Returns the session with its opportunities.

Delete backlink session

{ "success": true }

Enrich backlink opportunities

Returns an NDJSON stream with progress updates.

{"type":"progress","processed":12,"total":50}
{"type":"result","id":"...","status":"updated"}
{"type":"done","processed":50}

Run backlink research