# News Factory API

> REST API for News Factory: stories, content sources, RSS feeds, AI writing, quality and SEO checks, and workflows, scoped by API key.

Base URL: https://client-api.news-factory.app/v1. Authenticate every request with `Authorization: Bearer <API key>` (keys start with `nfk_`; an organization admin creates them in the News Factory app under Organization settings, API keys). Start with `GET /v1/me`: it tells you the organization, the key's scopes, the Topic Workspaces you can use and any problem with the plan. Errors are JSON `{ "error": { "code", "message", "details", "requestId", "docs" } }`.

## Docs

- [Full reference as one Markdown file](https://client-api.news-factory.app/llms-full.txt): every guide and endpoint, best for loading into context
- [OpenAPI 3.1 specification](https://client-api.news-factory.app/openapi.json): machine-readable; operationIds work as tool names
- [HTML reference](https://client-api.news-factory.app/docs)
- [MCP server](https://client-api.news-factory.app/mcp): every endpoint as a tool (Streamable HTTP; send the same Authorization header)
- [Quickstart](https://client-api.news-factory.app/docs#guide-quickstart)
- [Authentication and scopes](https://client-api.news-factory.app/docs#guide-authentication)
- [Topic Workspaces](https://client-api.news-factory.app/docs#guide-topic-workspaces)
- [Errors](https://client-api.news-factory.app/docs#guide-errors)
- [Pagination and filtering](https://client-api.news-factory.app/docs#guide-pagination-and-filtering)
- [Limits](https://client-api.news-factory.app/docs#guide-limits)
- [Recipes for agents](https://client-api.news-factory.app/docs#guide-agent-recipes)
- [Images and provenance](https://client-api.news-factory.app/docs#guide-images)
- [Connect an AI agent (MCP)](https://client-api.news-factory.app/docs#guide-mcp)
- [Rendering stories on your site](https://client-api.news-factory.app/docs#guide-rendering-stories)

## Account

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

- [Account reference (Markdown)](https://client-api.news-factory.app/docs/account.md)
- [GET /v1/me](https://client-api.news-factory.app/docs/account.md#op-getMe): Who Am I

## Stories

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

- [Stories reference (Markdown)](https://client-api.news-factory.app/docs/stories.md)
- [GET /v1/stories](https://client-api.news-factory.app/docs/stories.md#op-listStories): List Stories (scopes: stories:read)
- [POST /v1/stories](https://client-api.news-factory.app/docs/stories.md#op-createStory): Create Story (scopes: stories:write)
- [GET /v1/stories/by-language/{language}](https://client-api.news-factory.app/docs/stories.md#op-listStoriesByLanguage): List Stories by Language (scopes: stories:read)
- [GET /v1/stories/translation-map](https://client-api.news-factory.app/docs/stories.md#op-translationMap): Translation Map (scopes: stories:read)
- [GET /v1/stories/{id}](https://client-api.news-factory.app/docs/stories.md#op-getStoryById): Get Story (scopes: stories:read)
- [PATCH /v1/stories/{id}](https://client-api.news-factory.app/docs/stories.md#op-updateStory): Update Story (scopes: stories:write)
- [DELETE /v1/stories/{id}](https://client-api.news-factory.app/docs/stories.md#op-deleteStory): Delete Story (scopes: stories:write)
- [GET /v1/stories/slug/{slug}](https://client-api.news-factory.app/docs/stories.md#op-getStoryBySlug): Get Story by Slug (scopes: stories:read)
- [GET /v1/stories/{storyId}/media](https://client-api.news-factory.app/docs/stories.md#op-listStoryMedia): List Story Media (scopes: stories:read)
- [POST /v1/stories/{storyId}/media](https://client-api.news-factory.app/docs/stories.md#op-uploadStoryMedia): Upload Media (scopes: stories:write)
- [POST /v1/stories/{storyId}/media/from-url](https://client-api.news-factory.app/docs/stories.md#op-importImageUrl): Import Image from URL (scopes: stories:write)
- [POST /v1/stories/{storyId}/media/generate](https://client-api.news-factory.app/docs/stories.md#op-generateImage): Generate Image (AI) (scopes: ai:generate + stories:write)
- [POST /v1/stories/{storyId}/media/thumbnail](https://client-api.news-factory.app/docs/stories.md#op-setThumbnail): Set Thumbnail (scopes: stories:write)
- [DELETE /v1/stories/{storyId}/media/thumbnail](https://client-api.news-factory.app/docs/stories.md#op-removeThumbnail): Remove Thumbnail (scopes: stories:write)
- [POST /v1/stories/{storyId}/media/{imageId}](https://client-api.news-factory.app/docs/stories.md#op-attachStoryMedia): Attach Media (scopes: stories:write)
- [DELETE /v1/stories/{storyId}/media/{imageId}](https://client-api.news-factory.app/docs/stories.md#op-removeStoryMedia): Detach Media (scopes: stories:write)
- [POST /v1/stories/{storyId}/content/suggest-titles](https://client-api.news-factory.app/docs/stories.md#op-suggestTitles): Suggest Titles (scopes: ai:generate + stories:read)
- [POST /v1/stories/{storyId}/content/suggest-summary](https://client-api.news-factory.app/docs/stories.md#op-suggestSummary): Suggest Summary (scopes: ai:generate + stories:read)
- [POST /v1/stories/{storyId}/content/suggest-seo-title](https://client-api.news-factory.app/docs/stories.md#op-suggestSeoTitle): Suggest SEO Title (scopes: ai:generate + stories:read)
- [POST /v1/stories/{storyId}/content/suggest-meta-description](https://client-api.news-factory.app/docs/stories.md#op-suggestMetaDescription): Suggest Meta Description (scopes: ai:generate + stories:read)
- [POST /v1/stories/{storyId}/content/social-post/{platform}](https://client-api.news-factory.app/docs/stories.md#op-generateSocialPost): Generate Social Post (scopes: ai:generate + stories:read)
- [POST /v1/stories/{storyId}/content/translate](https://client-api.news-factory.app/docs/stories.md#op-translateStory): Translate Story (scopes: ai:generate + stories:write)
- [POST /v1/stories/{storyId}/content/quality-check](https://client-api.news-factory.app/docs/stories.md#op-qualityCheck): Run Quality Check (scopes: ai:generate + stories:read)
- [GET /v1/stories/{storyId}/content/quality-checks](https://client-api.news-factory.app/docs/stories.md#op-listQualityChecks): Quality Check History (scopes: stories:read)
- [POST /v1/stories/{storyId}/content/quality-check/apply-fix](https://client-api.news-factory.app/docs/stories.md#op-applyQualityFix): Apply Quality Fix (scopes: ai:generate + stories:write)
- [POST /v1/stories/{storyId}/content/seo-audit](https://client-api.news-factory.app/docs/stories.md#op-seoAudit): Run SEO Audit (scopes: ai:generate + stories:read)
- [GET /v1/stories/{storyId}/content/seo-audits](https://client-api.news-factory.app/docs/stories.md#op-listSeoAudits): SEO Audit History (scopes: stories:read)
- [POST /v1/stories/{storyId}/content/seo-audit/apply-fix](https://client-api.news-factory.app/docs/stories.md#op-applySeoFix): Apply SEO Fix (scopes: ai:generate + stories:write)

## Content Sources

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

- [Content Sources reference (Markdown)](https://client-api.news-factory.app/docs/content-sources.md)
- [GET /v1/content-sources](https://client-api.news-factory.app/docs/content-sources.md#op-listContentSources): List Content Sources (scopes: content-sources:read)
- [POST /v1/content-sources](https://client-api.news-factory.app/docs/content-sources.md#op-createContentSource): Create Content Source (scopes: content-sources:write)
- [GET /v1/content-sources/{id}](https://client-api.news-factory.app/docs/content-sources.md#op-getContentSource): Get Content Source (scopes: content-sources:read)
- [PATCH /v1/content-sources/{id}](https://client-api.news-factory.app/docs/content-sources.md#op-updateContentSource): Update Content Source (scopes: content-sources:write)
- [DELETE /v1/content-sources/{id}](https://client-api.news-factory.app/docs/content-sources.md#op-deleteContentSource): Delete Content Source (scopes: content-sources:write)
- [POST /v1/content-sources/{id}/scrape](https://client-api.news-factory.app/docs/content-sources.md#op-scrapeContentSource): Scrape Content Source (scopes: content-sources:write)
- [POST /v1/content-sources/{id}/repurpose](https://client-api.news-factory.app/docs/content-sources.md#op-repurposeContentSource): Repurpose into a Story (scopes: ai:generate + content-sources:read + stories:write)

## RSS Feeds

Subscribe to catalogue feeds and read their articles with the topic's evaluation

- [RSS Feeds reference (Markdown)](https://client-api.news-factory.app/docs/rss-feeds.md)
- [GET /v1/feeds](https://client-api.news-factory.app/docs/rss-feeds.md#op-listFeeds): List Subscribed Feeds (scopes: feeds:read)
- [POST /v1/feeds](https://client-api.news-factory.app/docs/rss-feeds.md#op-subscribeFeed): Subscribe to Feed (scopes: feeds:write)
- [GET /v1/feeds/catalog](https://client-api.news-factory.app/docs/rss-feeds.md#op-searchFeedCatalog): Search Feed Catalog (scopes: feeds:read)
- [GET /v1/feeds/{id}](https://client-api.news-factory.app/docs/rss-feeds.md#op-getFeed): Get Feed (scopes: feeds:read)
- [DELETE /v1/feeds/{id}](https://client-api.news-factory.app/docs/rss-feeds.md#op-unsubscribeFeed): Unsubscribe from Feed (scopes: feeds:write)
- [POST /v1/feeds/{id}/fetch](https://client-api.news-factory.app/docs/rss-feeds.md#op-fetchFeedArticles): Fetch Feed Now (scopes: feeds:write)
- [GET /v1/feeds/articles](https://client-api.news-factory.app/docs/rss-feeds.md#op-listFeedArticles): List Articles (scopes: feeds:read)
- [GET /v1/feeds/articles/{id}](https://client-api.news-factory.app/docs/rss-feeds.md#op-getArticleDetails): Get Article (scopes: feeds:read)
- [GET /v1/feeds/scheduler/status](https://client-api.news-factory.app/docs/rss-feeds.md#op-schedulerStatus): Scheduler Status (scopes: feeds:read)

## Workflows

Run the automation workflows designed in the app and follow their runs step by step

- [Workflows reference (Markdown)](https://client-api.news-factory.app/docs/workflows.md)
- [GET /v1/workflows](https://client-api.news-factory.app/docs/workflows.md#op-listWorkflows): List Workflows (scopes: workflows:read)
- [GET /v1/workflows/{id}](https://client-api.news-factory.app/docs/workflows.md#op-getWorkflow): Get Workflow (scopes: workflows:read)
- [POST /v1/workflows/{id}/run](https://client-api.news-factory.app/docs/workflows.md#op-runWorkflow): Run Workflow (scopes: workflows:run)
- [GET /v1/workflows/{id}/runs](https://client-api.news-factory.app/docs/workflows.md#op-listWorkflowRuns): List Workflow Runs (scopes: workflows:read)
- [GET /v1/workflow-runs/{runId}](https://client-api.news-factory.app/docs/workflows.md#op-getWorkflowRun): Get Workflow Run (scopes: workflows:read)
- [GET /v1/workflow-runs/{runId}/node-runs](https://client-api.news-factory.app/docs/workflows.md#op-listNodeRuns): List Node Runs (scopes: workflows:read)
- [POST /v1/workflow-runs/{runId}/cancel](https://client-api.news-factory.app/docs/workflows.md#op-cancelWorkflowRun): Stop Run (scopes: workflows:run)
- [POST /v1/workflow-runs/{runId}/pause](https://client-api.news-factory.app/docs/workflows.md#op-pauseWorkflowRun): Pause Run (scopes: workflows:run)
- [POST /v1/workflow-runs/{runId}/resume](https://client-api.news-factory.app/docs/workflows.md#op-resumeWorkflowRun): Resume Run (scopes: workflows:run)

## Optional

- [News Factory](https://news-factory.app/): the product, plans and pricing
- [Developers](https://news-factory.app/developers): overview for developers and AI agents