News Factory API

The News Factory public REST API: find news in your niche, turn it into stories with AI, check them for quality and SEO, and publish them to your site. Everything the app does with stories, content sources, RSS feeds and workflows, scoped to one organization and one Topic Workspace.

Authentication. Send Authorization: Bearer <API key> with every request. An organization admin creates keys in the app under Organization settings, API keys (Pro, Business and Enterprise plans), choosing the scopes each integration needs and, optionally, one Topic Workspace and an expiry. Keys start with nfk_ and are shown once.

Start with GET /me. It returns the organization, the key's scopes, the Topic Workspaces the key can act on and anything that would block a request.

Errors are always { "error": { "code", "message", "details", "requestId", "docs" } }; docs links to what the code means and what to do.

Limits. 100 requests per minute per organization (429 RATE_LIMIT_EXCEEDED with Retry-After). AI endpoints spend the organization's AI credits (429 LLM_QUOTA_EXCEEDED when they run out).

Locale codes are always full codes such as en-US, pt-BR or es-CO, never bare en.

Quickstart

The News Factory API lets software, and AI agents, do what the News Factory app does: find news in a niche, turn articles into stories with AI, check them for quality and SEO, translate them, and publish them.

1. Get a key. An organization admin opens the app, goes to Organization settings, API keys, and creates a key. Pick the access it needs (read only, read and write, or full access including AI), optionally one Topic Workspace and an expiry. The key starts with nfk_ and is shown once: store it as a secret.
2. Check it. Call GET /v1/me. It answers who the key is, its scopes, the Topic Workspaces it can act on and anything that would block a request.

curl https://client-api.news-factory.app/v1/me \
  -H "Authorization: Bearer $NEWS_FACTORY_API_KEY"

3. List stories.

curl "https://client-api.news-factory.app/v1/stories?status=published&language=en-US&order=publishedAt%20DESC&limit=10" \
  -H "Authorization: Bearer $NEWS_FACTORY_API_KEY"

Every response is JSON. Lists answer { "data": [...], "meta": { "page", "limit", "hasMore" } }; single records answer { "data": {...} }; writes answer { "success": true, "data": {...}, "message" }; errors answer { "error": { "code", "message", "details", "requestId", "docs" } }.

Machine-readable versions of this reference: OpenAPI 3.1, llms.txt and the whole reference as Markdown. The OpenAPI operationIds (listStories, createContentSource, ...) make good tool names for an agent.

Authentication and scopes

Send the key on every request:

Authorization: Bearer nfk_...

Keys belong to the organization, not to a person: they keep working when their creator leaves, until an admin revokes them or they expire. Work done with a key is attributed to the admin who created it. An organization can hold up to 25 active keys, so give every integration its own key with only the scopes it needs, and revoke it on its own when it is no longer used.

Scopes

A key carries one or more scopes. An endpoint lists the scopes it needs; a key must have all of them, otherwise the answer is 403 INSUFFICIENT_SCOPE with details.missing.

AI endpoints need ai:generate together with the scope of what they read or change: suggesting titles needs ai:generate and stories:read; translating a story, which creates one, needs ai:generate and stories:write.

The app offers three presets: Read only (every :read scope), Read and write (adds every :write scope and workflows:run, no AI) and Full access (everything).

Keeping keys safe

• Keys are shown once. News Factory stores only a hash, so a lost key cannot be recovered: create a new one and revoke the old one.
• Never put a key in a browser, a mobile app or a public repository. Call the API from a server.
• Revoking or expiring a key takes effect everywhere within one minute.
• Keys start with nfk_ so secret scanners can recognise them.

Legacy keys

Keys created before scoped keys (they start with ak_) keep working with full access, but they are deprecated. GET /v1/me reports them with deprecated: true and the problem LEGACY_API_KEY. Replace them with scoped keys in the app.

Plans

The API is included in the Pro, Business and Enterprise plans (and their trials). On other plans every endpoint except GET /v1/me answers 403 PLAN_REQUIRED.

Topic Workspaces

Everything in News Factory belongs to a Topic Workspace: a niche with its own feeds, stories, settings and keywords. Every request acts on exactly one.

• A key bound to a Topic Workspace always acts on it. Leave out X-Topic-Key; sending a different one is refused with 403 INVALID_TOPIC.
• A key for all Topic Workspaces picks one with the X-Topic-Key header. Without the header, the organization's first Topic Workspace is used. An unknown key answers 400 INVALID_TOPIC with details.validTopics.

GET /v1/me lists the Topic Workspaces a key can use (data.topic.available, each { key, name }) and which one the request resolved to.

curl https://client-api.news-factory.app/v1/stories \
  -H "Authorization: Bearer $NEWS_FACTORY_API_KEY" \
  -H "X-Topic-Key: health"

Records never move between Topic Workspaces through the API: the request's Topic Workspace decides where a story or content source is created.

Errors

Every error has the same shape and a matching HTTP status:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key lacks the scope stories:write needed for this endpoint. Edit the key's access in the app or use another key.",
    "details": { "required": ["stories:write"], "missing": ["stories:write"], "granted": ["stories:read"] },
    "requestId": "6f1c2a9e-3b7d-4c41-9f0e-2d8a5b7c9e10",
    "docs": "https://client-api.news-factory.app/docs#error-insufficient-scope"
  }
}

message is written for people and may change; branch on code. requestId is also in the X-Request-Id response header: quote it to support. You may send your own X-Request-Id (8 to 64 letters, digits, ., _ or -) to correlate logs.

UNAUTHORIZED (401). No key, a malformed key, or a revoked or expired key. Do not retry with the same key. Check the Authorization: Bearer nfk_... header; if the key was revoked, ask an admin for a new one. Many failed attempts from one address pause that address for a few minutes (429).

FORBIDDEN (403). The request is not allowed for this organization, for example a record of another organization. Do not retry.

INSUFFICIENT_SCOPE (403). The key lacks a scope the endpoint needs. details.missing names them. An admin can add scopes to the key in the app, or use a key that has them.

PLAN_REQUIRED (403). The organization's plan does not include the API. It needs Pro, Business or Enterprise.

INVALID_TOPIC (400 or 403). X-Topic-Key names a Topic Workspace that does not exist (400, details.validTopics lists the valid keys), or the key is bound to another Topic Workspace (403), or the key's Topic Workspace was deleted (403, create a new key).

NO_TOPIC_WORKSPACE (409). The organization has no Topic Workspace yet. Create one in the app.

NOT_FOUND (404). The record does not exist in this Topic Workspace, or the path is not an endpoint (see this reference).

METHOD_NOT_ALLOWED (405). The path exists but not with this HTTP method. The Allow header lists the methods it supports.

VALIDATION_ERROR (400, 413 or 422). A parameter or body field is missing or wrong; message says which. 413 means the body is too large (10 MB for image uploads, 1 MB otherwise). 422 from an apply-fix endpoint means the text changed since the check; retry with mode: "rewrite". Fix the request before retrying.

CONFLICT (409). The request clashes with the current state: a content source with this link already exists (details.existingContentSourceId), a workflow run is already active (details.runId), a run already finished. Use the existing record or wait.

PLAN_LIMIT_REACHED (403). A plan limit stops the action (feeds, languages, storage, ...). details.limitKey, details.limit and details.current say which. An admin can upgrade or buy an add-on.

RATE_LIMIT_EXCEEDED (429). More than 100 requests in a minute for the organization, too many failed authentications from one address, or a job queue that is busy. Wait the number of seconds in Retry-After, then retry.

DAILY_QUOTA_EXCEEDED (429). The plan's daily request quota is used up. details.resetsAt is the next midnight UTC.

LLM_QUOTA_EXCEEDED (429). The organization has no AI credits left for today. details.resetsAt says when the daily allowance comes back. Non-AI endpoints keep working.

UPSTREAM_ERROR (502). A News Factory service failed. Retry with exponential backoff (for example 2, 4, 8 seconds); if it keeps failing, contact support with the requestId.

GATEWAY_MISCONFIGURED (503). API keys cannot be verified right now. Retry in a minute.

INTERNAL_ERROR (500). Something unexpected failed. Retry once; then contact support with the requestId.

Retrying safely

Retry 429, 502, 503 and 500 with backoff. Never blindly retry a POST that creates something (a story, a content source, a translation, a run) after a timeout: list the records first, or you may create a duplicate. Do not retry other 4xx answers without changing the request.

Pagination and filtering

List endpoints take limit (default 20, at most 100) and page (zero based) and answer meta: { page, limit, hasMore }. hasMore is true when the page was full, so request the next page until it is false. page * limit can be at most 10000; narrow the query with filters to reach older records.

Most lists sort with order=<field> ASC|DESC on the fields each endpoint documents.

Stories

GET /v1/stories and GET /v1/stories/by-language/{language} take flat filters (status, language, tag, search, dateFrom, dateTo, include) or one advanced filter JSON in LoopBack's shape:

{
  "where": { "status": "published", "publishedAt": { "gte": "2026-08-01T00:00:00Z" } },
  "include": ["images"],
  "order": ["publishedAt DESC"],
  "limit": 50
}

Rules for filter (a filter that breaks one answers 400 VALIDATION_ERROR naming it):

• where fields: id, title, slug, summary, content, language, status, tags, thumbnail, thumbnailImageId, mainImageId, mainImageUrl, translationStatus, publishedAt, firstReported, createdAt, updatedAt. Other fields are ignored.
• Operators: eq, neq, gt, gte, lt, lte, between, inq, nin, like, nlike, ilike, nilike, exists. regexp and near are not supported.
• like patterns are regular expressions of at most 100 characters, without groups, repetition counts or back references.
• and / or / nor nest at most 3 levels with at most 20 conditions each; inq / nin take at most 100 values; strings at most 500 characters; offset / skip at most 10000.

Story dates: publishedAt is when the story was first published (null until then; kept if it is unpublished later), firstReported when its earliest source was published, createdAt when News Factory wrote it, updatedAt its last change. dateFrom / dateTo filter on createdAt; filter on publication with where.publishedAt. A page of the latest published stories is status=published&order=publishedAt DESC.

include adds relations to each story: images, authors, categories, qualityChecks, seoAudits, translations, contentSources. Relations you do not request are never returned.

Locale codes

Languages are always full locale codes: en-US, en-GB, pt-BR, es-CO, de-DE. Bare codes such as en are not used anywhere in the API.

Limits

Responses carry RateLimit and RateLimit-Policy headers (IETF draft 7) so a client can slow down before it is limited. When a daily quota applies, X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset are set too.

AI endpoints (marked with the ai:generate scope) can take up to a few minutes. Use a client timeout of at least 5 minutes for them and do not retry them on a timeout without checking whether the result already exists.

Recipes for agents

Short, tested sequences for common goals. Each step names the operationId from the OpenAPI document.

Before anything: know your key

getMe (GET /v1/me): check data.problems is empty, note data.credential.scopes and data.topic.available. If a step below needs a scope the key lacks, stop and tell the user which scope to add.

Write a story from a web article

Scopes: content-sources:write, content-sources:read, stories:write, ai:generate.

1. createContentSource (POST /v1/content-sources) with { "title": "<headline>", "link": "<article URL>", "sourceType": "website" }. A 409 CONFLICT means it exists: use details.existingContentSourceId.
2. scrapeContentSource (POST /v1/content-sources/{id}/scrape) to fetch and parse the page.
3. repurposeContentSource (POST /v1/content-sources/{id}/repurpose) with { "languageCode": "en-US" }. It answers data.storyId of the new draft.
4. getStoryById (GET /v1/stories/{id}) to read the result.

Check and improve a story before publishing

Scopes: stories:read, stories:write, ai:generate.

1. qualityCheck (POST /v1/stories/{storyId}/content/quality-check) and seoAudit (POST /v1/stories/{storyId}/content/seo-audit).
2. For each finding or fix worth applying: applyQualityFix or applySeoFix with the finding or fix object from the report. On 422 retry with "mode": "rewrite".
3. updateStory (PATCH /v1/stories/{id}) with { "status": "published" } when the story is ready. News Factory records the moment in publishedAt.

Show the latest published stories

Scope: stories:read. listStories (GET /v1/stories?status=published&order=publishedAt DESC) answers the newest publications first; show each story's publishedAt as its date and rewrite the links between stories (/{slug}) to your own route, as Rendering stories on your site explains. For one language use listStoriesByLanguage with the same params; for a date window use filter with where.publishedAt (gte / lte).

Suggest what to read next

Scope: stories:read. getStoryById (GET /v1/stories/{id}) or getStoryBySlug answers data.relatedStories: up to 5 published stories in the same language, closest first, each with slug, title, summary and a score from 0 to 1. Use them for a Read next block, for internal links when you write or edit a story, or to spot that a topic was already covered. They are found within about a minute of publication: right after updateStory publishes a story, read it again a minute later for its list.

Publish in another language

Scopes: stories:write, ai:generate. translateStory (POST /v1/stories/{storyId}/content/translate) with { "languageCode": "de-DE" } creates the translated story. Read every language version with include=translations, or list one language with listStoriesByLanguage.

Pick relevant news from followed feeds

Scopes: feeds:read (and the scopes of the recipe above to write from it).

1. listFeeds (GET /v1/feeds) for the feeds the Topic Workspace follows; searchFeedCatalog and subscribeFeed to follow more (feeds:write).
2. listFeedArticles (GET /v1/feeds/articles?minConfidence=70) for articles already judged relevant to the Topic Workspace, highest confidence first with order=matchConfidence DESC.
3. Write a story from an article's url with the first recipe.

Run a workflow and wait for it

Scopes: workflows:read, workflows:run.

1. listWorkflows (GET /v1/workflows) and pick one (isActive=true).
2. runWorkflow (POST /v1/workflows/{id}/run) answers 202 with data.runId. A 409 means a run is already active: use details.runId.
3. Poll getWorkflowRun (GET /v1/workflow-runs/{runId}) every 10 to 30 seconds until status is completed, failed or cancelled. listNodeRuns shows per-step progress. pauseWorkflowRun, resumeWorkflowRun and cancelWorkflowRun (Stop) control it.

Good manners

• Read before you write; never create duplicates by retrying a POST after a timeout.
• Keep to 100 requests a minute and honour Retry-After.
• AI endpoints spend the organization's credits: run them only when the user asked for the result.

Images and provenance

Every image the client API returns (in images[] on stories, and from the /stories/{storyId}/media endpoints) is a public Image object. Storage internals are stripped and three provenance fields are added so a consumer can decide which picture to show without knowing how News Factory stores files.

Public Image object

{
  "id": "6a99370b892980259c5de946",
  "url": "https://news-factory.s3.us-east-1.amazonaws.com/.../generated_openai_1788425993651_0.png",
  "width": 1024,
  "height": 576,
  "format": "PNG",
  "contentType": "image/png",
  "fileSize": 1583022,
  "imageType": "main",
  "origin": "generated",
  "aiGenerated": true,
  "generation": {
    "provider": "openai",
    "model": "gpt-image-1",
    "prompt": "Topic tags: Amazon, AI, Cloud Computing ... Image Requirements: Editorial illustration ..."
  },
  "sourceType": "generated",
  "parentId": null,
  "title": "AI Generated Image - openai",
  "description": "...",
  "altText": null,
  "caption": null,
  "author": "openai AI",
  "source": "openai",
  "license": null,
  "creditLine": null,
  "originalUrl": null,
  "tags": ["ai-generated", "openai", "ai"],
  "createdAt": "2026-09-03T08:59:55.424Z",
  "updatedAt": "2026-09-03T08:59:55.424Z"
}

origin values

Derived images (a parentId pointing at another image in the same response, e.g. a resized thumbnail) take the origin of their parent when their own record does not carry the AI flag, so a thumbnail of the publisher's photo reports origin: "source" even though it is stored as sourceType: "generated".

Getting images with stories

Images are an opt-in include on every story read:

GET /v1/stories?include=images&language=en-US&limit=20
GET /v1/stories/by-language/es-CO?include=images
GET /v1/stories/{id}?include=images
GET /v1/stories/slug/{slug}?include=images
GET /v1/stories/{id}/media

The story itself also carries quick-access fields:

Choosing which image to show

Prefer the flag, never sourceType:

function pickHeroImage(story) {
  const images = story.images ?? [];
  const generated = images.filter((img) => img.aiGenerated && img.url);
  return (
    generated.find((img) => img.imageType === "main") ??
    generated.find((img) => img.imageType === "thumbnail") ??
    generated[0] ??
    null // fall back to your own placeholder
  );
}

To show any image but avoid republishing the publisher's photo:

images.filter((img) => img.origin !== "source" && img.url)

Media endpoints

GET /stories/{storyId}/media returns { success, data: PublicImage[], meta: { count } }. POST /stories/{storyId}/media, POST .../media/from-url and POST .../media/{imageId} return the created/attached image in the same public shape. POST .../media/generate returns the raw generation result (provider, model, images[] with imageId and url); re-read the story with include=images to get the public objects with provenance.

Connect an AI agent (MCP)

The API is also a Model Context Protocol server at https://client-api.news-factory.app/mcp (Streamable HTTP, stateless). Every endpoint is a tool named after its operationId (getMe, listStories, translateStory, ...) with its parameters and body as the input, and a key only sees the tools its scopes allow. A tool call runs the same REST request with the same key, so scopes, the Topic Workspace, limits and errors are exactly the API's.

Claude Code:

claude mcp add --transport http news-factory https://client-api.news-factory.app/mcp \
  --header "Authorization: Bearer $NEWS_FACTORY_API_KEY"

Any MCP client that can send a header works the same way: the URL above and Authorization: Bearer <API key>. Give the agent a key with only the scopes it needs, for example a Read only key for research, and add ai:generate only when it should spend AI credits.

Tool results are the API's JSON answers, prefixed with the HTTP status (HTTP 200). A failed call is a tool error carrying the API's error body.

Rendering stories on your site

A story's content is HTML, ready to place in your page. Three things need handling before you publish it: links to other stories, dates, and stories still being written. Every story also tells you which of your other stories to show next.

Links to other stories

News Factory links one story to another (for example the SEO step's internal links) with the linked story's slug at the site root:

<a href="/the-hidden-cost-of-ai-generated-workslop">AI-generated</a>

News Factory stores the slug, never a URL: your site decides where a story lives. Rewrite these links to your own story route before rendering, or they lead to a 404 on any site that does not serve stories at /{slug}.

• Recognise them. A story link's href is exactly / followed by a slug (lowercase letters, digits and hyphens), optionally followed by ?query or #fragment. Leave every other link alone: other sites, your own pages, anchors.
• Rewrite them to your route, for example /{slug} to /news/{slug}, /es/news/{slug} or https://example.com/blog/{slug}. Keep the query or fragment.
• Translations. In a translated story, a link points at the linked story's version in the same language when that version existed at translation time, otherwise at the original. GET /v1/stories/slug/{slug} finds a story in any language; its language and translations tell you which of your pages to link.
• Check the target. A linked story can be unpublished, deleted, hollow (no body yet) or outside what your site shows. Link only to stories you have a page for (your own list of slugs, or GET /v1/stories/slug/{slug} not answering 404), and otherwise keep the text without the link.

// Point story links at your route; drop the ones you have no page for.
const STORY_LINK = /<a\b([^>]*?\bhref\s*=\s*)(["'])\/([a-z0-9][a-z0-9-]*)\/?([?#][^"']*)?\2([^>]*)>([\s\S]*?)<\/a>/gi;

function rewriteStoryLinks(html, { route = (slug) => `/news/${slug}`, hasPage = () => true } = {}) {
  return html.replace(STORY_LINK, (link, before, quote, slug, suffix = "", after, text) =>
    hasPage(slug) ? `<a${before}${quote}${route(slug)}${suffix}${quote}${after}>${text}</a>` : text,
  );
}

// rewriteStoryLinks(story.content, { hasPage: (slug) => publishedSlugs.has(slug) })

If a body can link to one of your own top-level pages (for example /pricing), skip those paths before rewriting: they are pages, not stories.

Related stories (Read next)

Every story read one at a time (GET /v1/stories/{id}, GET /v1/stories/slug/{slug}) and every story of GET /v1/stories/by-language/{language} carries relatedStories: up to 5 published stories of the same Topic Workspace and the same language that are closest to it in meaning, closest first. No include is needed. The plain list (GET /v1/stories) leaves them out to stay light.

"relatedStories": [
  {
    "id": "68b9b7c2f1a2b3c4d5e6f740",
    "title": "Hospitals Cut Waiting Times with AI Triage",
    "slug": "hospitals-cut-waiting-times-with-ai-triage",
    "summary": "Emergency departments using AI triage report shorter waits and fewer missed cases.",
    "language": "en-US",
    "publishedAt": "2026-08-12T09:10:00.000Z",
    "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/generated_openai_1788125993651_0.png",
    "thumbnail": null,
    "score": 0.8412
  }
]

• When they appear. News Factory finds them when a story is published, within about a minute, and again when a published story gets a new title or summary. Until then the list is empty, and it stays empty when no published story is close enough (score below 0.7). A story published later joins the lists of the older stories it is close to, so lists keep up without anyone republishing.
• Always current. Only stories that are published right now are listed, with their current title and slug: one you unpublish or delete drops out at once and the next closest takes its place.
• Per language. A story's related stories are in its own language and never include another language version of the same story. A translation gets its own list, from the stories published in that language.
• Render them like any link to a story: point slug at your own route (/news/{slug}), and skip the ones you have no page for, as above.

// Read next: up to 3 related stories your site has a page for.
const readNext = story.relatedStories.filter((r) => publishedSlugs.has(r.slug)).slice(0, 3);
// <a href={`/news/${r.slug}`}>{r.title}</a>

A static site built from GET /v1/stories/by-language/{language} gets every story's list in the same response, without a call per story; rebuild it now and then so new publications show up in older stories' Read next blocks.

Dates

• publishedAt: when the story was first published (null until then; kept if it is unpublished later). Show it as the publication date and order lists with status=published&order=publishedAt DESC.
• updatedAt: the last change, for "Updated on".
• firstReported: when the earliest source article was published, not your story.
• createdAt: when News Factory wrote the story.

Stories still being written

A workflow creates a story with its title first and writes the body a moment later, and a story can stay without one. Skip stories whose content has no real text (for example fewer than 80 words once the HTML is stripped) so a list never links to an empty page.

Account

Who the credential is and what it may do. Start here.

Who Am I

GET /v1/me · operationId getMe · scopes: any valid key

Describe the credential: the organization, the plan, the key's scopes, the Topic Workspaces it can act on, the rate limit and where the documentation lives. It answers even when the plan or the Topic Workspace would block every other endpoint, and lists the problem in problems, so call it first.

Responses

• 200 The credential and what it may do

{
  "data": {
    "credential": {
      "type": "api-key",
      "keyId": "68f0c1a2b3c4d5e6f7a8b9c0",
      "name": "Website sync",
      "scopes": [
        {
          "scope": "stories:read",
          "description": "Read stories, their media, quality-check and SEO audit history"
        },
        {
          "scope": "feeds:read",
          "description": "Read followed feeds, the feed catalogue, feed articles and the scheduler status"
        }
      ],
      "expiresAt": null,
      "deprecated": false
    },
    "organization": {
      "id": "org_2abc123",
      "plan": "pro",
      "apiIncluded": true
    },
    "topic": {
      "current": "tech",
      "boundTo": "tech",
      "available": [
        {
          "key": "tech",
          "name": "Technology"
        }
      ],
      "howToChoose": "This key always acts on its Topic Workspace; X-Topic-Key is not needed."
    },
    "limits": {
      "requestsPerMinute": 100,
      "dailyRequests": null
    },
    "problems": [],
    "docs": {
      "reference": "https://client-api.news-factory.app/docs",
      "openapi": "https://client-api.news-factory.app/openapi.json",
      "llms": "https://client-api.news-factory.app/llms.txt",
      "llmsFull": "https://client-api.news-factory.app/llms-full.txt"
    }
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 429 Rate limited: more than 100 requests in one minute per organization. Wait for the Retry-After seconds.

Example

curl -X GET "https://client-api.news-factory.app/v1/me" \
  -H "Authorization: Bearer nfk_xxx..."

Stories

Read, create and publish the stories News Factory writes, with their images, translations, quality checks and SEO audits

List Stories

GET /v1/stories · operationId listStories · scopes: stories:read

Page through the Topic Workspace's original stories (translations are reached through include=translations or GET /stories/by-language/{language}). Filter with the flat params or the advanced filter JSON. The list is lightweight: content, bulletPoints, sentiment and metadata are only returned by the detail endpoints.

Query parameters

Responses

• 200 A page of stories

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f700",
      "title": "AI Revolution in Healthcare",
      "summary": "How artificial intelligence is transforming medical diagnostics.",
      "slug": "ai-revolution-in-healthcare",
      "status": "published",
      "language": "en-US",
      "tags": [
        "ai",
        "healthcare",
        "technology"
      ],
      "topicKey": "tech",
      "parentId": null,
      "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
      "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
      "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
      "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
      "publishedAt": "2026-08-15T11:45:00.000Z",
      "firstReported": "2026-08-15T08:00:00.000Z",
      "createdAt": "2026-08-15T10:30:00.000Z",
      "updatedAt": "2026-08-15T12:00:00.000Z",
      "images": [
        {
          "id": "68b9b7c2f1a2b3c4d5e6f701",
          "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
          "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
          "originalUrl": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
          "width": 1024,
          "height": 683,
          "format": "JPEG",
          "contentType": "image/jpeg",
          "fileSize": 214532,
          "imageType": "main",
          "origin": "source",
          "aiGenerated": false,
          "generation": null,
          "sourceType": "story",
          "parentId": null,
          "title": "AI Revolution in Healthcare",
          "description": null,
          "altText": null,
          "caption": null,
          "author": null,
          "source": "https://techcrunch.com/2026/07/30/ai-healthcare/",
          "license": null,
          "creditLine": null,
          "tags": [],
          "createdAt": "2026-08-15T10:30:00.000Z",
          "updatedAt": "2026-08-15T10:30:00.000Z"
        },
        {
          "id": "68b9b7c2f1a2b3c4d5e6f702",
          "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
          "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
          "originalUrl": null,
          "width": 1024,
          "height": 576,
          "format": "PNG",
          "contentType": "image/png",
          "fileSize": 1583022,
          "imageType": "main",
          "origin": "generated",
          "aiGenerated": true,
          "generation": {
            "provider": "openai",
            "model": "gpt-image-1",
            "prompt": "Editorial illustration of AI-assisted medical diagnostics in a modern hospital"
          },
          "sourceType": "generated",
          "parentId": null,
          "title": "AI Generated Image - openai",
          "description": null,
          "altText": null,
          "caption": null,
          "author": "openai AI",
          "source": "openai",
          "license": null,
          "creditLine": null,
          "tags": [
            "ai-generated",
            "openai",
            "healthcare"
          ],
          "createdAt": "2026-08-15T11:02:00.000Z",
          "updatedAt": "2026-08-15T11:02:00.000Z"
        }
      ],
      "translations": [
        {
          "code": "en-US",
          "storyId": "68b9b7c2f1a2b3c4d5e6f700",
          "default": true,
          "slug": "ai-revolution-in-healthcare",
          "title": "AI Revolution in Healthcare"
        },
        {
          "code": "de-DE",
          "storyId": "68b9b7c2f1a2b3c4d5e6f710",
          "default": false,
          "slug": "ki-revolution-im-gesundheitswesen",
          "title": "KI-Revolution im Gesundheitswesen"
        },
        {
          "code": "pt-BR",
          "storyId": "68b9b7c2f1a2b3c4d5e6f711",
          "default": false,
          "slug": "revolucao-da-ia-na-saude",
          "title": "Revolução da IA na saúde"
        }
      ]
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "hasMore": true
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 429 Rate limited: more than 100 requests in one minute per organization. Wait for the Retry-After seconds.

Example

curl -X GET "https://client-api.news-factory.app/v1/stories?status=published&language=en-US&include=images%2Ctranslations&limit=20" \
  -H "Authorization: Bearer nfk_xxx..."

Create Story

POST /v1/stories · operationId createStory · scopes: stories:write

Create a story in the Topic Workspace. Only title is required; everything else defaults (draft status, the Topic Workspace's default language). Fields outside the documented list are ignored.

Request body (JSON): Story data

{
  "title": "AI Revolution in Healthcare",
  "summary": "How AI is transforming medical diagnostics",
  "content": "<p>Full story content here...</p>",
  "language": "en-US",
  "status": "draft",
  "tags": [
    "ai",
    "healthcare"
  ]
}

Responses

• 201 Story created

{
  "success": true,
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f700",
    "title": "AI Revolution in Healthcare",
    "summary": "How artificial intelligence is transforming medical diagnostics.",
    "slug": "ai-revolution-in-healthcare",
    "status": "draft",
    "language": "en-US",
    "tags": [
      "ai",
      "healthcare",
      "technology"
    ],
    "topicKey": "tech",
    "parentId": null,
    "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
    "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
    "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
    "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
    "publishedAt": null,
    "firstReported": "2026-08-15T08:00:00.000Z",
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T12:00:00.000Z",
    "content": "<h3>Overview</h3><p>A comprehensive look at how AI is being deployed across diagnostics, triage and treatment planning.</p>",
    "bulletPoints": [
      "AI diagnostics accuracy reaches 95%",
      "Cost reduction of 40% in pilot hospitals"
    ],
    "sentiment": 0.8,
    "metadata": {
      "title": "AI Revolution in Healthcare: What Changes in 2026",
      "description": "AI is transforming diagnostics, triage and treatment planning. Here is what hospitals report.",
      "keywords": "ai, healthcare, diagnostics"
    }
  },
  "message": "Story created successfully"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/stories" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"title":"AI Revolution in Healthcare","summary":"How AI is transforming medical diagnostics","content":"<p>Full story content here...</p>","language":"en-US","status":"draft","tags":["ai","healthcare"]}'

List Stories by Language

GET /v1/stories/by-language/{language} · operationId listStoriesByLanguage · scopes: stories:read

Page through every story written in one language, originals and translations alike, with a stable order. Ideal for building a per-language site: pair it with include=translations to render language switchers. Every story carries its relatedStories in that language, so a static site can render Read next blocks without a call per story.

Path parameters

Query parameters

Responses

• 200 A page of stories in that language

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f700",
      "title": "AI Revolution in Healthcare",
      "summary": "How artificial intelligence is transforming medical diagnostics.",
      "slug": "ai-revolution-in-healthcare",
      "status": "published",
      "language": "en-US",
      "tags": [
        "ai",
        "healthcare",
        "technology"
      ],
      "topicKey": "tech",
      "parentId": null,
      "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
      "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
      "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
      "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
      "publishedAt": "2026-08-15T11:45:00.000Z",
      "firstReported": "2026-08-15T08:00:00.000Z",
      "createdAt": "2026-08-15T10:30:00.000Z",
      "updatedAt": "2026-08-15T12:00:00.000Z",
      "translations": [
        {
          "code": "en-US",
          "storyId": "68b9b7c2f1a2b3c4d5e6f700",
          "default": true,
          "slug": "ai-revolution-in-healthcare",
          "title": "AI Revolution in Healthcare"
        },
        {
          "code": "de-DE",
          "storyId": "68b9b7c2f1a2b3c4d5e6f710",
          "default": false,
          "slug": "ki-revolution-im-gesundheitswesen",
          "title": "KI-Revolution im Gesundheitswesen"
        },
        {
          "code": "pt-BR",
          "storyId": "68b9b7c2f1a2b3c4d5e6f711",
          "default": false,
          "slug": "revolucao-da-ia-na-saude",
          "title": "Revolução da IA na saúde"
        }
      ],
      "relatedStories": [
        {
          "id": "68b9b7c2f1a2b3c4d5e6f740",
          "title": "Hospitals Cut Waiting Times with AI Triage",
          "slug": "hospitals-cut-waiting-times-with-ai-triage",
          "summary": "Emergency departments using AI triage report shorter waits and fewer missed cases.",
          "language": "en-US",
          "publishedAt": "2026-08-12T09:10:00.000Z",
          "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/generated_openai_1788125993651_0.png",
          "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/thumb_400x225.jpg",
          "score": 0.8412
        },
        {
          "id": "68b9b7c2f1a2b3c4d5e6f741",
          "title": "Regulators Draft Rules for Diagnostic AI",
          "slug": "regulators-draft-rules-for-diagnostic-ai",
          "summary": "A draft framework would require clinical trials before diagnostic models reach patients.",
          "language": "en-US",
          "publishedAt": "2026-08-09T15:30:00.000Z",
          "mainImageUrl": null,
          "thumbnail": null,
          "score": 0.7761
        }
      ]
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "hasMore": false,
    "language": "en-US"
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/by-language/en-US?include=translations&limit=20" \
  -H "Authorization: Bearer nfk_xxx..."

Translation Map

GET /v1/stories/translation-map · operationId translationMap · scopes: stories:read

A compact map from each story to all of its language versions, without loading the stories themselves. Use it to generate hreflang tags or language switchers. With lang, entries are anchored on the stories in that language so the map lines up with GET /stories/by-language/{language}.

Query parameters

Responses

• 200 The map

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f700",
      "translations": [
        {
          "id": "68b9b7c2f1a2b3c4d5e6f700",
          "code": "en-US",
          "slug": "ai-revolution-in-healthcare"
        },
        {
          "id": "68b9b7c2f1a2b3c4d5e6f710",
          "code": "de-DE",
          "slug": "ki-revolution-im-gesundheitswesen"
        },
        {
          "id": "68b9b7c2f1a2b3c4d5e6f711",
          "code": "pt-BR",
          "slug": "revolucao-da-ia-na-saude"
        }
      ]
    }
  ],
  "meta": {
    "count": 1,
    "lang": "en-US",
    "limit": 500
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/translation-map?lang=en-US&limit=200" \
  -H "Authorization: Bearer nfk_xxx..."

Get Story

GET /v1/stories/{id} · operationId getStoryById · scopes: stories:read

One story with its full HTML content, key points, sentiment, SEO metadata and relatedStories: up to 5 published stories in the same language that are closest to it, for a Read next block. Add relations with include.

Path parameters

Query parameters

Responses

• 200 The story

{
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f700",
    "title": "AI Revolution in Healthcare",
    "summary": "How artificial intelligence is transforming medical diagnostics.",
    "slug": "ai-revolution-in-healthcare",
    "status": "published",
    "language": "en-US",
    "tags": [
      "ai",
      "healthcare",
      "technology"
    ],
    "topicKey": "tech",
    "parentId": null,
    "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
    "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
    "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
    "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
    "publishedAt": "2026-08-15T11:45:00.000Z",
    "firstReported": "2026-08-15T08:00:00.000Z",
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T12:00:00.000Z",
    "content": "<h3>Overview</h3><p>A comprehensive look at how AI is being deployed across diagnostics, triage and treatment planning.</p>",
    "bulletPoints": [
      "AI diagnostics accuracy reaches 95%",
      "Cost reduction of 40% in pilot hospitals"
    ],
    "sentiment": 0.8,
    "metadata": {
      "title": "AI Revolution in Healthcare: What Changes in 2026",
      "description": "AI is transforming diagnostics, triage and treatment planning. Here is what hospitals report.",
      "keywords": "ai, healthcare, diagnostics"
    },
    "relatedStories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f740",
        "title": "Hospitals Cut Waiting Times with AI Triage",
        "slug": "hospitals-cut-waiting-times-with-ai-triage",
        "summary": "Emergency departments using AI triage report shorter waits and fewer missed cases.",
        "language": "en-US",
        "publishedAt": "2026-08-12T09:10:00.000Z",
        "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/generated_openai_1788125993651_0.png",
        "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/thumb_400x225.jpg",
        "score": 0.8412
      },
      {
        "id": "68b9b7c2f1a2b3c4d5e6f741",
        "title": "Regulators Draft Rules for Diagnostic AI",
        "slug": "regulators-draft-rules-for-diagnostic-ai",
        "summary": "A draft framework would require clinical trials before diagnostic models reach patients.",
        "language": "en-US",
        "publishedAt": "2026-08-09T15:30:00.000Z",
        "mainImageUrl": null,
        "thumbnail": null,
        "score": 0.7761
      }
    ],
    "images": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f701",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "originalUrl": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
        "width": 1024,
        "height": 683,
        "format": "JPEG",
        "contentType": "image/jpeg",
        "fileSize": 214532,
        "imageType": "main",
        "origin": "source",
        "aiGenerated": false,
        "generation": null,
        "sourceType": "story",
        "parentId": null,
        "title": "AI Revolution in Healthcare",
        "description": null,
        "altText": null,
        "caption": null,
        "author": null,
        "source": "https://techcrunch.com/2026/07/30/ai-healthcare/",
        "license": null,
        "creditLine": null,
        "tags": [],
        "createdAt": "2026-08-15T10:30:00.000Z",
        "updatedAt": "2026-08-15T10:30:00.000Z"
      },
      {
        "id": "68b9b7c2f1a2b3c4d5e6f702",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
        "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
        "originalUrl": null,
        "width": 1024,
        "height": 576,
        "format": "PNG",
        "contentType": "image/png",
        "fileSize": 1583022,
        "imageType": "main",
        "origin": "generated",
        "aiGenerated": true,
        "generation": {
          "provider": "openai",
          "model": "gpt-image-1",
          "prompt": "Editorial illustration of AI-assisted medical diagnostics in a modern hospital"
        },
        "sourceType": "generated",
        "parentId": null,
        "title": "AI Generated Image - openai",
        "description": null,
        "altText": null,
        "caption": null,
        "author": "openai AI",
        "source": "openai",
        "license": null,
        "creditLine": null,
        "tags": [
          "ai-generated",
          "openai",
          "healthcare"
        ],
        "createdAt": "2026-08-15T11:02:00.000Z",
        "updatedAt": "2026-08-15T11:02:00.000Z"
      }
    ],
    "authors": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f720",
        "name": "Jane Doe",
        "status": "active",
        "avatarUrl": "https://cdn.news-factory.app/authors/jane.jpg",
        "topicKey": "tech"
      }
    ],
    "categories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f730",
        "name": "Health Tech",
        "slug": "health-tech",
        "parentId": null
      }
    ],
    "translations": [
      {
        "code": "en-US",
        "storyId": "68b9b7c2f1a2b3c4d5e6f700",
        "default": true,
        "slug": "ai-revolution-in-healthcare",
        "title": "AI Revolution in Healthcare"
      },
      {
        "code": "de-DE",
        "storyId": "68b9b7c2f1a2b3c4d5e6f710",
        "default": false,
        "slug": "ki-revolution-im-gesundheitswesen",
        "title": "KI-Revolution im Gesundheitswesen"
      },
      {
        "code": "pt-BR",
        "storyId": "68b9b7c2f1a2b3c4d5e6f711",
        "default": false,
        "slug": "revolucao-da-ia-na-saude",
        "title": "Revolução da IA na saúde"
      }
    ]
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700?include=images%2Cauthors%2Ccategories%2Ctranslations" \
  -H "Authorization: Bearer nfk_xxx..."

Update Story

PATCH /v1/stories/{id} · operationId updateStory · scopes: stories:write

Update the provided fields and return the fresh story. Arrays such as tags replace the existing value. Publishing is a status change: set status to published. The related stories of a story you publish (or retitle) are found within about a minute, so the response still shows the previous relatedStories: read the story again later for the new ones.

Path parameters

Request body (JSON): Fields to update (at least one)

{
  "title": "AI Revolution in Healthcare: 2026 Update",
  "status": "published",
  "tags": [
    "ai",
    "healthcare",
    "2026"
  ]
}

Responses

• 200 Story updated

{
  "success": true,
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f700",
    "title": "AI Revolution in Healthcare: 2026 Update",
    "summary": "How artificial intelligence is transforming medical diagnostics.",
    "slug": "ai-revolution-in-healthcare",
    "status": "published",
    "language": "en-US",
    "tags": [
      "ai",
      "healthcare",
      "technology"
    ],
    "topicKey": "tech",
    "parentId": null,
    "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
    "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
    "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
    "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
    "publishedAt": "2026-08-15T11:45:00.000Z",
    "firstReported": "2026-08-15T08:00:00.000Z",
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T12:00:00.000Z",
    "content": "<h3>Overview</h3><p>A comprehensive look at how AI is being deployed across diagnostics, triage and treatment planning.</p>",
    "bulletPoints": [
      "AI diagnostics accuracy reaches 95%",
      "Cost reduction of 40% in pilot hospitals"
    ],
    "sentiment": 0.8,
    "metadata": {
      "title": "AI Revolution in Healthcare: What Changes in 2026",
      "description": "AI is transforming diagnostics, triage and treatment planning. Here is what hospitals report.",
      "keywords": "ai, healthcare, diagnostics"
    },
    "relatedStories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f740",
        "title": "Hospitals Cut Waiting Times with AI Triage",
        "slug": "hospitals-cut-waiting-times-with-ai-triage",
        "summary": "Emergency departments using AI triage report shorter waits and fewer missed cases.",
        "language": "en-US",
        "publishedAt": "2026-08-12T09:10:00.000Z",
        "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/generated_openai_1788125993651_0.png",
        "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/thumb_400x225.jpg",
        "score": 0.8412
      },
      {
        "id": "68b9b7c2f1a2b3c4d5e6f741",
        "title": "Regulators Draft Rules for Diagnostic AI",
        "slug": "regulators-draft-rules-for-diagnostic-ai",
        "summary": "A draft framework would require clinical trials before diagnostic models reach patients.",
        "language": "en-US",
        "publishedAt": "2026-08-09T15:30:00.000Z",
        "mainImageUrl": null,
        "thumbnail": null,
        "score": 0.7761
      }
    ]
  },
  "message": "Story updated successfully"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X PATCH "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"title":"AI Revolution in Healthcare: 2026 Update","status":"published","tags":["ai","healthcare","2026"]}'

Delete Story

DELETE /v1/stories/{id} · operationId deleteStory · scopes: stories:write

Delete a story permanently. Images that no other story or source uses are removed from storage as well. Translations of the story are not deleted.

Path parameters

Responses

• 200 Story deleted

{
  "success": true,
  "message": "Story deleted successfully"
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X DELETE "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700" \
  -H "Authorization: Bearer nfk_xxx..."

Get Story by Slug

GET /v1/stories/slug/{slug} · operationId getStoryBySlug · scopes: stories:read

The same detail as GET /stories/{id}, related stories included, looked up by the story's URL slug. Slugs are unique per Topic Workspace and language, so send the X-Topic-Key header when your key spans Topic Workspaces.

Path parameters

Query parameters

Responses

• 200 The story

{
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f700",
    "title": "AI Revolution in Healthcare",
    "summary": "How artificial intelligence is transforming medical diagnostics.",
    "slug": "ai-revolution-in-healthcare",
    "status": "published",
    "language": "en-US",
    "tags": [
      "ai",
      "healthcare",
      "technology"
    ],
    "topicKey": "tech",
    "parentId": null,
    "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_400x225.jpg",
    "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
    "mainImageId": "68b9b7c2f1a2b3c4d5e6f702",
    "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
    "publishedAt": "2026-08-15T11:45:00.000Z",
    "firstReported": "2026-08-15T08:00:00.000Z",
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T12:00:00.000Z",
    "content": "<h3>Overview</h3><p>A comprehensive look at how AI is being deployed across diagnostics, triage and treatment planning.</p>",
    "bulletPoints": [
      "AI diagnostics accuracy reaches 95%",
      "Cost reduction of 40% in pilot hospitals"
    ],
    "sentiment": 0.8,
    "metadata": {
      "title": "AI Revolution in Healthcare: What Changes in 2026",
      "description": "AI is transforming diagnostics, triage and treatment planning. Here is what hospitals report.",
      "keywords": "ai, healthcare, diagnostics"
    },
    "relatedStories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f740",
        "title": "Hospitals Cut Waiting Times with AI Triage",
        "slug": "hospitals-cut-waiting-times-with-ai-triage",
        "summary": "Emergency departments using AI triage report shorter waits and fewer missed cases.",
        "language": "en-US",
        "publishedAt": "2026-08-12T09:10:00.000Z",
        "mainImageUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/generated_openai_1788125993651_0.png",
        "thumbnail": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f740/thumb_400x225.jpg",
        "score": 0.8412
      },
      {
        "id": "68b9b7c2f1a2b3c4d5e6f741",
        "title": "Regulators Draft Rules for Diagnostic AI",
        "slug": "regulators-draft-rules-for-diagnostic-ai",
        "summary": "A draft framework would require clinical trials before diagnostic models reach patients.",
        "language": "en-US",
        "publishedAt": "2026-08-09T15:30:00.000Z",
        "mainImageUrl": null,
        "thumbnail": null,
        "score": 0.7761
      }
    ],
    "images": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f701",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "originalUrl": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
        "width": 1024,
        "height": 683,
        "format": "JPEG",
        "contentType": "image/jpeg",
        "fileSize": 214532,
        "imageType": "main",
        "origin": "source",
        "aiGenerated": false,
        "generation": null,
        "sourceType": "story",
        "parentId": null,
        "title": "AI Revolution in Healthcare",
        "description": null,
        "altText": null,
        "caption": null,
        "author": null,
        "source": "https://techcrunch.com/2026/07/30/ai-healthcare/",
        "license": null,
        "creditLine": null,
        "tags": [],
        "createdAt": "2026-08-15T10:30:00.000Z",
        "updatedAt": "2026-08-15T10:30:00.000Z"
      },
      {
        "id": "68b9b7c2f1a2b3c4d5e6f702",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
        "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
        "originalUrl": null,
        "width": 1024,
        "height": 576,
        "format": "PNG",
        "contentType": "image/png",
        "fileSize": 1583022,
        "imageType": "main",
        "origin": "generated",
        "aiGenerated": true,
        "generation": {
          "provider": "openai",
          "model": "gpt-image-1",
          "prompt": "Editorial illustration of AI-assisted medical diagnostics in a modern hospital"
        },
        "sourceType": "generated",
        "parentId": null,
        "title": "AI Generated Image - openai",
        "description": null,
        "altText": null,
        "caption": null,
        "author": "openai AI",
        "source": "openai",
        "license": null,
        "creditLine": null,
        "tags": [
          "ai-generated",
          "openai",
          "healthcare"
        ],
        "createdAt": "2026-08-15T11:02:00.000Z",
        "updatedAt": "2026-08-15T11:02:00.000Z"
      }
    ],
    "authors": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f720",
        "name": "Jane Doe",
        "status": "active",
        "avatarUrl": "https://cdn.news-factory.app/authors/jane.jpg",
        "topicKey": "tech"
      }
    ],
    "categories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f730",
        "name": "Health Tech",
        "slug": "health-tech",
        "parentId": null
      }
    ],
    "translations": [
      {
        "code": "en-US",
        "storyId": "68b9b7c2f1a2b3c4d5e6f700",
        "default": true,
        "slug": "ai-revolution-in-healthcare",
        "title": "AI Revolution in Healthcare"
      },
      {
        "code": "de-DE",
        "storyId": "68b9b7c2f1a2b3c4d5e6f710",
        "default": false,
        "slug": "ki-revolution-im-gesundheitswesen",
        "title": "KI-Revolution im Gesundheitswesen"
      },
      {
        "code": "pt-BR",
        "storyId": "68b9b7c2f1a2b3c4d5e6f711",
        "default": false,
        "slug": "revolucao-da-ia-na-saude",
        "title": "Revolução da IA na saúde"
      }
    ]
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/slug/ai-revolution-in-healthcare?include=images%2Ctranslations" \
  -H "Authorization: Bearer nfk_xxx..."

List Story Media

GET /v1/stories/{storyId}/media · operationId listStoryMedia · scopes: stories:read

All images attached to a story as public Image objects. Each carries origin, aiGenerated and generation, so you can tell the images News Factory generated (safe to publish as your own) from the publisher's photo (origin: "source").

Path parameters

Responses

• 200 The story's images

{
  "success": true,
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f701",
      "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
      "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
      "originalUrl": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
      "width": 1024,
      "height": 683,
      "format": "JPEG",
      "contentType": "image/jpeg",
      "fileSize": 214532,
      "imageType": "main",
      "origin": "source",
      "aiGenerated": false,
      "generation": null,
      "sourceType": "story",
      "parentId": null,
      "title": "AI Revolution in Healthcare",
      "description": null,
      "altText": null,
      "caption": null,
      "author": null,
      "source": "https://techcrunch.com/2026/07/30/ai-healthcare/",
      "license": null,
      "creditLine": null,
      "tags": [],
      "createdAt": "2026-08-15T10:30:00.000Z",
      "updatedAt": "2026-08-15T10:30:00.000Z"
    },
    {
      "id": "68b9b7c2f1a2b3c4d5e6f702",
      "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
      "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
      "originalUrl": null,
      "width": 1024,
      "height": 576,
      "format": "PNG",
      "contentType": "image/png",
      "fileSize": 1583022,
      "imageType": "main",
      "origin": "generated",
      "aiGenerated": true,
      "generation": {
        "provider": "openai",
        "model": "gpt-image-1",
        "prompt": "Editorial illustration of AI-assisted medical diagnostics in a modern hospital"
      },
      "sourceType": "generated",
      "parentId": null,
      "title": "AI Generated Image - openai",
      "description": null,
      "altText": null,
      "caption": null,
      "author": "openai AI",
      "source": "openai",
      "license": null,
      "creditLine": null,
      "tags": [
        "ai-generated",
        "openai",
        "healthcare"
      ],
      "createdAt": "2026-08-15T11:02:00.000Z",
      "updatedAt": "2026-08-15T11:02:00.000Z"
    }
  ],
  "meta": {
    "count": 2
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media" \
  -H "Authorization: Bearer nfk_xxx..."

Upload Media

POST /v1/stories/{storyId}/media · operationId uploadStoryMedia · scopes: stories:write

Store an image and attach it to the story. Send either a base64 fileData with fileName and mimeType, or a url to import from.

Path parameters

Request body (JSON): Either fileData (with fileName and mimeType) or url

{
  "title": "Hero image",
  "tags": [
    "photo",
    "hero"
  ],
  "imageType": "content",
  "url": "https://example.com/image.jpg"
}

Responses

• 201 Image stored and attached

{
  "success": true,
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f705",
    "url": "https://cdn.news-factory.app/organizations/acme/hero.jpg",
    "s3Url": "https://cdn.news-factory.app/organizations/acme/hero.jpg",
    "originalUrl": null,
    "width": 1024,
    "height": 683,
    "format": "JPEG",
    "contentType": "image/jpeg",
    "fileSize": 214532,
    "imageType": "content",
    "origin": "upload",
    "aiGenerated": false,
    "generation": null,
    "sourceType": "user-upload",
    "parentId": null,
    "title": "Hero image",
    "description": null,
    "altText": null,
    "caption": null,
    "author": null,
    "source": null,
    "license": null,
    "creditLine": null,
    "tags": [
      "photo",
      "hero"
    ],
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T10:30:00.000Z"
  },
  "message": "Image imported from URL and attached to story"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Hero image","tags":["photo","hero"],"imageType":"content","url":"https://example.com/image.jpg"}'

Import Image from URL

POST /v1/stories/{storyId}/media/from-url · operationId importImageUrl · scopes: stories:write

Download an image from a public URL, store it and attach it to the story.

Path parameters

Request body (JSON): The URL and optional metadata

{
  "url": "https://example.com/image.jpg",
  "title": "Hero image",
  "imageType": "main"
}

Responses

• 201 Image stored and attached

{
  "success": true,
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f705",
    "url": "https://cdn.news-factory.app/organizations/acme/hero.jpg",
    "s3Url": "https://cdn.news-factory.app/organizations/acme/hero.jpg",
    "originalUrl": null,
    "width": 1024,
    "height": 683,
    "format": "JPEG",
    "contentType": "image/jpeg",
    "fileSize": 214532,
    "imageType": "content",
    "origin": "upload",
    "aiGenerated": false,
    "generation": null,
    "sourceType": "user-upload",
    "parentId": null,
    "title": "Hero image",
    "description": null,
    "altText": null,
    "caption": null,
    "author": null,
    "source": null,
    "license": null,
    "creditLine": null,
    "tags": [
      "photo",
      "hero"
    ],
    "createdAt": "2026-08-15T10:30:00.000Z",
    "updatedAt": "2026-08-15T10:30:00.000Z"
  },
  "message": "Image imported from URL and attached to story"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/from-url" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/image.jpg","title":"Hero image","imageType":"main"}'

Generate Image (AI)

POST /v1/stories/{storyId}/media/generate · operationId generateImage · scopes: ai:generate + stories:write

Generate an image with an AI model and attach it to the story. Providers: OpenAI (GPT Image), Google Gemini and Ideogram. Story context (title, summary) is added to the prompt unless includeStoryContext is false. The saved image is flagged aiGenerated: true with origin: "generated"; read it back with GET /stories/{storyId}/media. Costs AI credits.

Path parameters

Request body (JSON): Generation parameters

{
  "prompt": "A photorealistic editorial photograph of a hospital diagnostics lab",
  "provider": "openai",
  "aspectRatio": "16:9",
  "quality": "high"
}

Responses

• 200 Image generated and attached

{
  "success": true,
  "data": {
    "storyId": "68b9b7c2f1a2b3c4d5e6f700",
    "provider": "openai",
    "model": "gpt-image-1",
    "processingTimeMs": 4500,
    "images": [
      {
        "imageId": "68b9b7c2f1a2b3c4d5e6f702",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/generated_openai_1788425993651_0.png",
        "width": 1792,
        "height": 1024,
        "format": "png",
        "prompt": "A photorealistic editorial photograph of a hospital diagnostics lab. Story: AI Revolution in Healthcare"
      }
    ]
  },
  "message": "Image generated successfully"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/generate" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A photorealistic editorial photograph of a hospital diagnostics lab","provider":"openai","aspectRatio":"16:9","quality":"high"}'

Set Thumbnail

POST /v1/stories/{storyId}/media/thumbnail · operationId setThumbnail · scopes: stories:write

Generate the story thumbnail from an attached image (imageId), from any image URL (imageUrl), or from the story's first attached image when both are omitted. The previous thumbnail image is deleted when no other story uses it.

Path parameters

Request body (JSON): All fields optional

{
  "imageId": "68b9b7c2f1a2b3c4d5e6f702",
  "preset": "standard",
  "quality": 85
}

Responses

• 200 Thumbnail set

{
  "success": true,
  "data": {
    "storyId": "68b9b7c2f1a2b3c4d5e6f700",
    "thumbnailUrl": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/thumb_800x450.jpg",
    "thumbnailImageId": "68b9b7c2f1a2b3c4d5e6f703",
    "width": 800,
    "height": 450,
    "format": "jpeg",
    "fileSize": 61234,
    "preset": "standard",
    "sourceImage": "68b9b7c2f1a2b3c4d5e6f702",
    "previousThumbnail": {
      "imageId": "68b9b7c2f1a2b3c4d5e6f6ff",
      "deleted": true
    }
  },
  "message": "Thumbnail set successfully"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/thumbnail" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"imageId":"68b9b7c2f1a2b3c4d5e6f702","preset":"standard","quality":85}'

Remove Thumbnail

DELETE /v1/stories/{storyId}/media/thumbnail · operationId removeThumbnail · scopes: stories:write

Clear the story's thumbnail and thumbnailImageId. The image record itself is kept.

Path parameters

Responses

• 200 Thumbnail cleared

{
  "success": true,
  "message": "Thumbnail removed"
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X DELETE "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/thumbnail" \
  -H "Authorization: Bearer nfk_xxx..."

Attach Media

POST /v1/stories/{storyId}/media/{imageId} · operationId attachStoryMedia · scopes: stories:write

Attach an image that already exists in the organization (for example one uploaded to another story) to this story.

Path parameters

Responses

• 200 Image attached

{
  "success": true,
  "data": {
    "storyId": "68b9b7c2f1a2b3c4d5e6f700",
    "imageId": "68b9b7c2f1a2b3c4d5e6f702",
    "imageIds": [
      "68b9b7c2f1a2b3c4d5e6f701",
      "68b9b7c2f1a2b3c4d5e6f702"
    ]
  },
  "message": "Image attached to story"
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story or image not found

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/68b9b7c2f1a2b3c4d5e6f702" \
  -H "Authorization: Bearer nfk_xxx..."

Detach Media

DELETE /v1/stories/{storyId}/media/{imageId} · operationId removeStoryMedia · scopes: stories:write

Detach an image from the story. The image record is kept and stays attached to any other story that uses it.

Path parameters

Responses

• 200 Image detached

{
  "success": true,
  "message": "Image removed from story"
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story or image not found

Example

curl -X DELETE "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/media/68b9b7c2f1a2b3c4d5e6f702" \
  -H "Authorization: Bearer nfk_xxx..."

Suggest Titles

POST /v1/stories/{storyId}/content/suggest-titles · operationId suggestTitles · scopes: ai:generate + stories:read

AI title suggestions grounded in the story's content sources. The story needs at least one content source. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "count": 3,
  "language": "en-US"
}

Responses

• 200 Suggestions

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "storyTitle": "AI Revolution in Healthcare",
  "count": 3,
  "titleSuggestions": [
    "AI Revolution Reshapes Modern Healthcare",
    "How Artificial Intelligence Is Transforming Medicine",
    "The Future of Healthcare: AI-Driven Diagnostics"
  ],
  "language": "en-US",
  "model": "claude-sonnet-5"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/suggest-titles" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"count":3,"language":"en-US"}'

Suggest Summary

POST /v1/stories/{storyId}/content/suggest-summary · operationId suggestSummary · scopes: ai:generate + stories:read

AI summary suggestions grounded in the story's content sources. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "count": 3,
  "language": "en-US"
}

Responses

• 200 Suggestions

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "storySummary": "How artificial intelligence is transforming medical diagnostics.",
  "count": 2,
  "summarySuggestions": [
    "Hospitals across Europe report faster triage and lower costs after adopting AI diagnostics.",
    "AI diagnostic tools now reach 95% accuracy in pilot programmes, cutting costs by 40%."
  ],
  "language": "en-US",
  "model": "claude-sonnet-5"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/suggest-summary" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"count":3,"language":"en-US"}'

Suggest SEO Title

POST /v1/stories/{storyId}/content/suggest-seo-title · operationId suggestSeoTitle · scopes: ai:generate + stories:read

Search engine optimised title suggestions (under 60 characters, keyword first). Write the pick to metadata.title with PATCH /stories/{id}. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "count": 3
}

Responses

• 200 Suggestions

{
  "success": true,
  "count": 3,
  "seoTitleSuggestions": [
    "AI in Healthcare 2026: Diagnostics, Costs and Results",
    "AI Diagnostics Hit 95% Accuracy in Hospital Pilots",
    "How AI Is Cutting Hospital Costs by 40%"
  ],
  "language": "en-US"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/suggest-seo-title" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"count":3}'

Suggest Meta Description

POST /v1/stories/{storyId}/content/suggest-meta-description · operationId suggestMetaDescription · scopes: ai:generate + stories:read

Meta description suggestions (under 160 characters). Write the pick to metadata.description with PATCH /stories/{id}. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "count": 3
}

Responses

• 200 Suggestions

{
  "success": true,
  "count": 2,
  "metaDescriptionSuggestions": [
    "AI diagnostics reach 95% accuracy and cut hospital costs by 40%. See what the European pilots found.",
    "How hospitals use AI for triage and diagnostics, and what it means for patients in 2026."
  ],
  "language": "en-US"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/suggest-meta-description" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"count":3}'

Generate Social Post

POST /v1/stories/{storyId}/content/social-post/{platform} · operationId generateSocialPost · scopes: ai:generate + stories:read

Platform specific social media posts for the story. Generated posts are also saved on the story for the app's social tab. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "count": 2,
  "targetUrl": "https://news.example.com/ai-revolution-in-healthcare"
}

Responses

• 200 Posts

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "storyTitle": "AI Revolution in Healthcare",
  "platform": "linkedin",
  "count": 2,
  "targetURL": "https://news.example.com/ai-revolution-in-healthcare",
  "socialMediaPosts": [
    "AI is no longer the future of healthcare. It is the present. From diagnostics to treatment planning, here is what European hospitals report. https://news.example.com/ai-revolution-in-healthcare",
    "95% diagnostic accuracy. 40% lower costs. The numbers behind AI in hospitals: https://news.example.com/ai-revolution-in-healthcare"
  ],
  "model": "claude-sonnet-5",
  "additionalInstructions": null
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/social-post/linkedin" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"count":2,"targetUrl":"https://news.example.com/ai-revolution-in-healthcare"}'

Translate Story

POST /v1/stories/{storyId}/content/translate · operationId translateStory · scopes: ai:generate + stories:write

Create a translated copy of the story as a new story linked through parentId. The target must be one of the organization's supported languages, given as a full locale code. Translating a language that already exists answers 409. Costs AI credits.

Path parameters

Request body (JSON): Target language and options

{
  "languageCode": "de-DE"
}

Responses

• 200 Translation created

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f710",
  "translatedStory": {
    "id": "68b9b7c2f1a2b3c4d5e6f710",
    "title": "KI-Revolution im Gesundheitswesen",
    "language": "de-DE",
    "slug": "ki-revolution-im-gesundheitswesen"
  }
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 Forbidden: the credential cannot act on this organization or Topic Workspace Or: The API key lacks a scope this endpoint needs

• 404 Story not found

• 409 Conflict

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/translate" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"languageCode":"de-DE"}'

Run Quality Check

POST /v1/stories/{storyId}/content/quality-check · operationId qualityCheck · scopes: ai:generate + stories:read

Run the editorial quality check: fact check against the content sources, writing quality, and topic match. The result is stored in the story's history (GET /stories/{storyId}/content/quality-checks) and each finding can be applied with the apply-fix endpoint. Stories under minWords words fail without calling the model. Costs AI credits.

Path parameters

Request body (JSON): Options

{
  "effort": "normal",
  "language": "en-US"
}

Responses

• 200 Quality report

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "wordCounts": {
    "story": 640,
    "minRequired": 100,
    "sources": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f760",
        "wordCount": 1250
      }
    ]
  },
  "minimumContentOk": true,
  "qualityFindings": {
    "summary": "Two claims need a source and one paragraph repeats the lead.",
    "factCheck": {
      "findings": [
        {
          "field": "content",
          "severity": "high",
          "claim": "AI diagnostics accuracy reaches 99%",
          "sourceEvidence": "The source reports 95% accuracy in the pilot.",
          "action": "rewrite",
          "suggestedFix": "AI diagnostics accuracy reaches 95%"
        }
      ]
    },
    "writingQuality": {
      "score": 78,
      "findings": [
        {
          "field": "content",
          "severity": "low",
          "category": "repetition",
          "excerpt": "AI is transforming healthcare.",
          "rewrite": ""
        }
      ]
    },
    "topicMatch": {
      "expectedTopicKey": "tech",
      "matches": true,
      "modelTopicKey": "tech",
      "confidence": 92,
      "recommendedAction": "keep",
      "details": "The story is about AI in healthcare, which matches the technology topic."
    }
  },
  "findings": {
    "discrepancies": [
      {
        "description": "AI diagnostics accuracy reaches 99% (source: 95%)",
        "severity": "high"
      }
    ],
    "writingQuality": {
      "score": 78,
      "issues": [
        "Repeated lead paragraph"
      ],
      "flags": []
    },
    "topicMatch": {
      "confidence": 92,
      "details": "Matches the technology topic."
    }
  },
  "overall": "warn",
  "summary": "Two claims need a source and one paragraph repeats the lead."
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/quality-check" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"effort":"normal","language":"en-US"}'

Quality Check History

GET /v1/stories/{storyId}/content/quality-checks · operationId listQualityChecks · scopes: stories:read

Every quality check that ran on the story, newest first, including checks run by workflows. The same records are available inline with include=qualityChecks on the story endpoints.

Path parameters

Query parameters

Responses

• 200 History

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f740",
      "storyId": "68b9b7c2f1a2b3c4d5e6f700",
      "overall": "warn",
      "summary": "Two claims need a source and one paragraph repeats the lead.",
      "qualityFindings": {
        "summary": "Two claims need a source and one paragraph repeats the lead.",
        "factCheck": {
          "findings": [
            {
              "field": "content",
              "severity": "high",
              "claim": "AI diagnostics accuracy reaches 99%",
              "sourceEvidence": "The source reports 95% accuracy in the pilot.",
              "action": "rewrite",
              "suggestedFix": "AI diagnostics accuracy reaches 95%"
            }
          ]
        },
        "writingQuality": {
          "score": 78,
          "findings": [
            {
              "field": "content",
              "severity": "low",
              "category": "repetition",
              "excerpt": "AI is transforming healthcare.",
              "rewrite": ""
            }
          ]
        },
        "topicMatch": {
          "expectedTopicKey": "tech",
          "matches": true,
          "modelTopicKey": "tech",
          "confidence": 92,
          "recommendedAction": "keep",
          "details": "The story is about AI in healthcare, which matches the technology topic."
        }
      },
      "discrepancies": [
        {
          "description": "AI diagnostics accuracy reaches 99% (source: 95%)",
          "severity": "high"
        }
      ],
      "writingQuality": {
        "score": 78,
        "issues": [
          "Repeated lead paragraph"
        ],
        "flags": []
      },
      "topicMatch": {
        "confidence": 92,
        "details": "Matches the technology topic."
      },
      "effort": "normal",
      "checksRun": [
        "factCheck",
        "writingQuality",
        "topicMatch"
      ],
      "provider": "anthropic",
      "model": "claude-sonnet-5",
      "credits": 4,
      "createdAt": "2026-08-16T09:00:00.000Z"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "hasMore": false,
    "storyId": "68b9b7c2f1a2b3c4d5e6f700"
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/quality-checks" \
  -H "Authorization: Bearer nfk_xxx..."

Apply Quality Fix

POST /v1/stories/{storyId}/content/quality-check/apply-fix · operationId applyQualityFix · scopes: ai:generate + stories:write

Apply one finding from a quality check to the story. direct mode replaces the flagged text without a model; rewrite mode lets the model rewrite the field around the finding (costs credits). Topic findings with recommendedAction: reassign move the story to the suggested Topic Workspace.

Path parameters

Request body (JSON): The finding and the mode

{
  "finding": {
    "type": "factCheck",
    "field": "content",
    "severity": "high",
    "claim": "AI diagnostics accuracy reaches 99%",
    "sourceEvidence": "The source reports 95% accuracy.",
    "action": "rewrite",
    "suggestedFix": "AI diagnostics accuracy reaches 95%"
  },
  "mode": "direct"
}

Responses

• 200 Result

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "applied": true,
  "method": "direct",
  "field": "content",
  "before": "<p>AI diagnostics accuracy reaches 99% in the pilot.</p>",
  "after": "<p>AI diagnostics accuracy reaches 95% in the pilot.</p>"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/quality-check/apply-fix" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"finding":{"type":"factCheck","field":"content","severity":"high","claim":"AI diagnostics accuracy reaches 99%","sourceEvidence":"The source reports 95% accuracy.","action":"rewrite","suggestedFix":"AI diagnostics accuracy reaches 95%"},"mode":"direct"}'

Run SEO Audit

POST /v1/stories/{storyId}/content/seo-audit · operationId seoAudit · scopes: ai:generate + stories:read

Audit the story for search and answer engines: on-page checks, keyword placement against the Topic Workspace's SEO keywords, internal link candidates and AEO signals (direct answer, question headings, FAQs, entities). A model drafts concrete fixes unless skipSuggestions is true (then the audit is free). The report is stored in the story's history and each fix can be applied with the apply-fix endpoint.

Path parameters

Request body (JSON): Options

{
  "effort": "normal",
  "language": "en-US"
}

Responses

• 200 Audit report

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "report": {
    "storySnapshot": {
      "title": "AI Revolution in Healthcare",
      "seoTitle": "",
      "metaDescription": "",
      "slug": "ai-revolution-in-healthcare",
      "wordCount": 640,
      "locale": "en-US",
      "topicKey": "tech"
    },
    "checks": [
      {
        "id": "seoTitlePresent",
        "group": "onPage",
        "status": "fail",
        "impact": "high",
        "effort": "instant",
        "fix": {
          "kind": "setMetadataField",
          "target": "title",
          "after": "AI Revolution in Healthcare: What Changes in 2026"
        }
      },
      {
        "id": "metaDescriptionLength",
        "group": "onPage",
        "status": "warn",
        "impact": "medium",
        "effort": "instant"
      }
    ],
    "keywords": [
      {
        "term": "ai diagnostics",
        "primary": true,
        "bodyCount": 3,
        "present": [
          "h1",
          "body"
        ],
        "suggestion": {
          "placement": "seoTitle",
          "before": "",
          "after": "AI diagnostics"
        }
      }
    ],
    "linkCandidates": [
      {
        "storyId": "68b9b7c2f1a2b3c4d5e6f790",
        "title": "Hospitals adopt AI triage",
        "slug": "hospitals-adopt-ai-triage",
        "relevance": 81,
        "inboundLinks": 0,
        "anchor": "AI triage",
        "paragraphIndex": 2
      }
    ],
    "aeo": {
      "hasDirectAnswer": false,
      "proposedDirectAnswer": "AI is now used for diagnostics, triage and treatment planning in most large hospitals.",
      "questionHeadingCount": 0,
      "proposedQuestionHeadings": [],
      "faqs": [],
      "entities": [],
      "citedClaims": 2,
      "totalClaims": 5
    },
    "groupScores": {
      "onPage": 55,
      "keywords": 60,
      "links": 40,
      "aeo": 30
    },
    "overallScore": 48,
    "overall": "warn",
    "summary": "Add an SEO title, a meta description and one internal link.",
    "suggestionsAvailable": true
  },
  "overall": "warn",
  "overallScore": 48,
  "summary": "Add an SEO title, a meta description and one internal link.",
  "credits": 4
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/seo-audit" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"effort":"normal","language":"en-US"}'

SEO Audit History

GET /v1/stories/{storyId}/content/seo-audits · operationId listSeoAudits · scopes: stories:read

Every SEO audit that ran on the story, newest first, with the full report. Also available inline with include=seoAudits on the story endpoints.

Path parameters

Query parameters

Responses

• 200 History

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f750",
      "storyId": "68b9b7c2f1a2b3c4d5e6f700",
      "overallScore": 48,
      "overall": "warn",
      "summary": "Add an SEO title, a meta description and one internal link.",
      "groupScores": {
        "onPage": 55,
        "keywords": 60,
        "links": 40,
        "aeo": 30
      },
      "checksRun": [
        "onPage",
        "keywords",
        "links",
        "aeo"
      ],
      "report": {
        "storySnapshot": {
          "title": "AI Revolution in Healthcare",
          "seoTitle": "",
          "metaDescription": "",
          "slug": "ai-revolution-in-healthcare",
          "wordCount": 640,
          "locale": "en-US",
          "topicKey": "tech"
        },
        "checks": [
          {
            "id": "seoTitlePresent",
            "group": "onPage",
            "status": "fail",
            "impact": "high",
            "effort": "instant",
            "fix": {
              "kind": "setMetadataField",
              "target": "title",
              "after": "AI Revolution in Healthcare: What Changes in 2026"
            }
          },
          {
            "id": "metaDescriptionLength",
            "group": "onPage",
            "status": "warn",
            "impact": "medium",
            "effort": "instant"
          }
        ],
        "keywords": [
          {
            "term": "ai diagnostics",
            "primary": true,
            "bodyCount": 3,
            "present": [
              "h1",
              "body"
            ],
            "suggestion": {
              "placement": "seoTitle",
              "before": "",
              "after": "AI diagnostics"
            }
          }
        ],
        "linkCandidates": [
          {
            "storyId": "68b9b7c2f1a2b3c4d5e6f790",
            "title": "Hospitals adopt AI triage",
            "slug": "hospitals-adopt-ai-triage",
            "relevance": 81,
            "inboundLinks": 0,
            "anchor": "AI triage",
            "paragraphIndex": 2
          }
        ],
        "aeo": {
          "hasDirectAnswer": false,
          "proposedDirectAnswer": "AI is now used for diagnostics, triage and treatment planning in most large hospitals.",
          "questionHeadingCount": 0,
          "proposedQuestionHeadings": [],
          "faqs": [],
          "entities": [],
          "citedClaims": 2,
          "totalClaims": 5
        },
        "groupScores": {
          "onPage": 55,
          "keywords": 60,
          "links": 40,
          "aeo": 30
        },
        "overallScore": 48,
        "overall": "warn",
        "summary": "Add an SEO title, a meta description and one internal link.",
        "suggestionsAvailable": true
      },
      "effort": "normal",
      "provider": "anthropic",
      "model": "claude-sonnet-5",
      "credits": 4,
      "createdAt": "2026-08-16T09:30:00.000Z"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "hasMore": false,
    "storyId": "68b9b7c2f1a2b3c4d5e6f700"
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

Example

curl -X GET "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/seo-audits" \
  -H "Authorization: Bearer nfk_xxx..."

Apply SEO Fix

POST /v1/stories/{storyId}/content/seo-audit/apply-fix · operationId applySeoFix · scopes: ai:generate + stories:write

Apply one fix from an audit report. Fix kinds: setMetadataField, setSlug, setImageAlt, replaceText, insertParagraphTop, insertHeading, insertLink, setFaqs, setEntities. direct mode applies the fix without a model and answers 422 when the text changed since the audit; retry with rewrite mode to let the model apply it (costs credits).

Path parameters

Request body (JSON): The fix and the mode

{
  "fix": {
    "kind": "setMetadataField",
    "target": "title",
    "after": "AI in Healthcare 2026: Diagnostics, Costs and Results"
  },
  "mode": "direct"
}

Responses

• 200 Result

{
  "success": true,
  "storyId": "68b9b7c2f1a2b3c4d5e6f700",
  "applied": true,
  "method": "direct",
  "field": "metadata.title",
  "before": "",
  "after": "AI in Healthcare 2026: Diagnostics, Costs and Results"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Story not found

• 422 The story text drifted since the audit; retry with mode rewrite

• 429 The organization's AI credits are exhausted

Example

curl -X POST "https://client-api.news-factory.app/v1/stories/68b9b7c2f1a2b3c4d5e6f700/content/seo-audit/apply-fix" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"fix":{"kind":"setMetadataField","target":"title","after":"AI in Healthcare 2026: Diagnostics, Costs and Results"},"mode":"direct"}'

Content Sources

Articles, web pages, documents and images that stories are written from

List Content Sources

GET /v1/content-sources · operationId listContentSources · scopes: content-sources:read

Page through the Topic Workspace's content sources: articles saved from feeds, web pages, uploaded documents and images. usedIn tells how many stories were written from each source.

Query parameters

Responses

• 200 A page of content sources

{
  "data": [
    {
      "id": "68b9b7c2f1a2b3c4d5e6f760",
      "title": "Hospitals report 40% cost reduction with AI triage",
      "link": "https://techcrunch.com/2026/07/30/ai-healthcare/",
      "sourceType": "rss",
      "summary": "Pilot programmes across Europe report faster triage and lower costs.",
      "author": "Sarah Perez",
      "thumbnail": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
      "language": "en-US",
      "topicKey": "tech",
      "pubDate": "2026-07-30T06:00:00.000Z",
      "scraped": "2026-07-30T07:10:00.000Z",
      "processed": "2026-07-30T07:12:00.000Z",
      "repurposed": "2026-08-15T10:30:00.000Z",
      "flagged": false,
      "flagReason": null,
      "sourceMeta": {
        "feedId": "68b9b7c2f1a2b3c4d5e6f770",
        "feedName": "TechCrunch",
        "feedUrl": "https://techcrunch.com/feed/",
        "feedIcon": "https://cdn.news-factory.app/feeds/techcrunch/favicon.ico"
      },
      "usedIn": 1,
      "createdAt": "2026-07-30T07:00:00.000Z",
      "updatedAt": "2026-08-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "hasMore": false
  }
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

Example

curl -X GET "https://client-api.news-factory.app/v1/content-sources?sourceType=rss&limit=20" \
  -H "Authorization: Bearer nfk_xxx..."

Create Content Source

POST /v1/content-sources · operationId createContentSource · scopes: content-sources:write

Register an article, page or document as a source in the Topic Workspace. Scrape it afterwards to fetch and parse the page, then repurpose it into a story.

Request body (JSON): Content source data

{
  "title": "Hospitals report 40% cost reduction with AI triage",
  "link": "https://techcrunch.com/2026/07/30/ai-healthcare/",
  "sourceType": "website",
  "summary": "Pilot programmes across Europe report faster triage and lower costs.",
  "language": "en-US"
}

Responses

• 201 Content source created

{
  "success": true,
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f760",
    "title": "Hospitals report 40% cost reduction with AI triage",
    "link": "https://techcrunch.com/2026/07/30/ai-healthcare/",
    "sourceType": "website",
    "summary": "Pilot programmes across Europe report faster triage and lower costs.",
    "author": "Sarah Perez",
    "thumbnail": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
    "language": "en-US",
    "topicKey": "tech",
    "pubDate": "2026-07-30T06:00:00.000Z",
    "scraped": null,
    "processed": null,
    "repurposed": null,
    "flagged": false,
    "flagReason": null,
    "sourceMeta": {},
    "usedIn": 0,
    "createdAt": "2026-07-30T07:00:00.000Z",
    "updatedAt": "2026-08-15T10:30:00.000Z"
  },
  "message": "Content source created successfully"
}

• 400 Validation error: the request is missing or misusing a field

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 409 Conflict

• 503 API keys cannot be verified or signed right now; retry in a minute

Example

curl -X POST "https://client-api.news-factory.app/v1/content-sources" \
  -H "Authorization: Bearer nfk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Hospitals report 40% cost reduction with AI triage","link":"https://techcrunch.com/2026/07/30/ai-healthcare/","sourceType":"website","summary":"Pilot programmes across Europe report faster triage and lower costs.","language":"en-US"}'

Get Content Source

GET /v1/content-sources/{id} · operationId getContentSource · scopes: content-sources:read

One content source with its scraped text, images, catalogue feed and the stories written from it.

Path parameters

Query parameters

Responses

• 200 The content source

{
  "data": {
    "id": "68b9b7c2f1a2b3c4d5e6f760",
    "title": "Hospitals report 40% cost reduction with AI triage",
    "link": "https://techcrunch.com/2026/07/30/ai-healthcare/",
    "sourceType": "rss",
    "summary": "Pilot programmes across Europe report faster triage and lower costs.",
    "author": "Sarah Perez",
    "thumbnail": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
    "language": "en-US",
    "topicKey": "tech",
    "pubDate": "2026-07-30T06:00:00.000Z",
    "scraped": "2026-07-30T07:10:00.000Z",
    "processed": "2026-07-30T07:12:00.000Z",
    "repurposed": "2026-08-15T10:30:00.000Z",
    "flagged": false,
    "flagReason": null,
    "sourceMeta": {
      "feedId": "68b9b7c2f1a2b3c4d5e6f770",
      "feedName": "TechCrunch",
      "feedUrl": "https://techcrunch.com/feed/",
      "feedIcon": "https://cdn.news-factory.app/feeds/techcrunch/favicon.ico"
    },
    "usedIn": 1,
    "createdAt": "2026-07-30T07:00:00.000Z",
    "updatedAt": "2026-08-15T10:30:00.000Z",
    "content": null,
    "parsedSource": {
      "title": "Hospitals report 40% cost reduction with AI triage",
      "contentHTML": "<p>Pilot programmes across Europe...</p>",
      "contentText": "Pilot programmes across Europe...",
      "mainImage": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
      "excerpt": "Pilot programmes across Europe report faster triage and lower costs.",
      "wordCount": 1250
    },
    "images": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f701",
        "url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "s3Url": "https://cdn.news-factory.app/stories/68b9b7c2f1a2b3c4d5e6f700/gettyimages-1445867611.jpg",
        "originalUrl": "https://techcrunch.com/wp-content/uploads/gettyimages-1445867611.jpg",
        "width": 1024,
        "height": 683,
        "format": "JPEG",
        "contentType": "image/jpeg",
        "fileSize": 214532,
        "imageType": "main",
        "origin": "source",
        "aiGenerated": false,
        "generation": null,
        "sourceType": "story",
        "parentId": null,
        "title": "AI Revolution in Healthcare",
        "description": null,
        "altText": null,
        "caption": null,
        "author": null,
        "source": "https://techcrunch.com/2026/07/30/ai-healthcare/",
        "license": null,
        "creditLine": null,
        "tags": [],
        "createdAt": "2026-08-15T10:30:00.000Z",
        "updatedAt": "2026-08-15T10:30:00.000Z"
      }
    ],
    "feed": {
      "id": "68b9b7c2f1a2b3c4d5e6f770",
      "name": "TechCrunch",
      "url": "https://techcrunch.com/feed/",
      "favicon": "https://cdn.news-factory.app/feeds/techcrunch/favicon.ico"
    },
    "stories": [
      {
        "id": "68b9b7c2f1a2b3c4d5e6f700",
        "title": "AI Revolution in Healthcare",
        "createdAt": "2026-08-15T10:30:00.000Z"
      }
    ]
  }
}

• 401 Unauthorized: missing, invalid, revoked or expired credentials

• 403 The API key lacks a scope this endpoint needs

• 404 Content source not found

Example

curl -X GET "https://client-api.news-factory.app/v1/content-sources/68b9b7c2f1a2b3c4d5e6f760" \
  -H "Authorization: Bearer nfk_xxx..."

Update Content Source

PATCH /v1/content-sources/{id} · operationId updateContentSource · scopes: content-sources:write

Update editable fields (title, summary, content, author, thumbnail, language, pubDate, flagged, flagReason) and return the fresh record.

Path parameters

Request body (JSON): Fields to update (at least one)

{
  "flagged": true,
  "flagReason": "Duplicate of another source"
}

Responses

• 200 Content source updated