posting API

A Posting API For Articles, Notes, And Social Distribution

Ian Kiprono, Founder of NarrareachUpdated July 16, 2026

Narrareach is a posting API and publishing workflow for full articles, Substack Notes, and shorter social posts. Authenticated applications can schedule content into a writer-visible queue while Narrareach handles supported destination connections, media validation, platform-specific payloads, queue state, and delivery processing.

At a glance

Posting API for publishing workflows

Use Narrareach REST API, MCP, and webhook workflows to create, schedule, reschedule, cancel, and track publishing jobs across supported writing and social platforms.

Read the API docs See social media posting API

Article and Notes endpoints: so applications can schedule long-form and short-form publishing work through one authenticated product
Writer-visible queue state: so API-created items remain reviewable, movable, cancellable, and visible outside developer logs
Media and destination validation: so unsupported files and platform combinations fail before becoming silent delivery problems
MCP and webhook workflows: so AI assistants can request controlled actions and external systems can react to supported events

What this page covers

What a production posting API must handleSchedule full articles through the Narrareach APISchedule Notes and social posts with imagesChoose REST API, MCP, or webhooks for the right integration job

API access is available for authenticated Narrareach workflows.

The problem

The manual version gets old fast.

Posting API searches usually begin with a simple requirement: send text, a destination, and a time. Production systems immediately add authentication, account connections, timezones, media transfer, destination-specific validation, duplicate protection, rate limits, queue state, retry behavior, cancellation, and final delivery URLs.

Direct platform APIs offer the most destination-specific control, but every platform has its own approval process and object model. Broad social APIs reduce integration count but usually center on short social posts. Writers also need long-form articles, Substack Notes, tags, article metadata, drafts, and a queue they can inspect without developer tools.

Narrareach combines those jobs in a writer-facing publishing system. An external application can hand off a supported publishing job, while the writer can still review the content, see what is scheduled, and identify items that need attention.

What a production posting API must handle

A reliable posting API defines more than a create endpoint. It needs a stable content model, clear destination identifiers, timezone-aware scheduling, media rules, validation errors, authentication scopes, request limits, and an item identifier that can be read after the initial response.

The API also needs to separate submission from delivery. Accepting a scheduled job means the content entered the queue; it does not prove that a third-party destination later returned a live post. Clients should store the Narrareach item identifier and check the final state or consume supported webhook events.

Retries require special care. Narrareach article requests support an idempotency key so a caller can safely retry a timed-out submission without intentionally creating the same article twice. Clients should also back off on rate-limit and transient failures rather than sending an immediate request loop.

Treat the queue response and final destination result as separate states.
Store the Narrareach identifier and your own source identifier together.
Use a stable idempotency key for supported article requests that may be retried.

Schedule full articles through the Narrareach API

REST callers can use POST /api/v1/articles for supported long-form publishing workflows. The request can include a title, optional subtitle, HTML content, selected platforms, scheduled time, timezone, newsletter and paid-content settings, LinkedIn share commentary, and an idempotency key.

Current article scheduling documentation covers Substack, Medium, LinkedIn, and X workflows. Article tokens require the articles:write scope, and LinkedIn articles must be scheduled more than ten minutes ahead. Destination-specific fields remain optional unless that platform and publishing mode require them.

A scheduled article can later be moved with PATCH /api/v1/article-schedules/:id or cancelled with DELETE /api/v1/article-schedules/:id before publication. The writer can also see the item in Narrareach rather than leaving the entire workflow inside an opaque integration log.

Create one test draft for each destination before enabling automatic publication.
Send destination-specific metadata only where the destination supports it.
Keep article HTML self-contained and use durable public media URLs.

Schedule Notes and social posts with images

The Narrareach Notes API accepts short-form content, selected supported platforms, a scheduled time, timezone, and image URLs. MCP callers can also use schedule_note with imageUrls or inline media where supported, while REST callers can send note imageUrls to POST /api/v1/notes.

Media limits differ by destination. Narrareach validates the supported image count and rejects local blob or file URLs that a server cannot fetch. Upload the asset first or use the documented inline-media path instead of handing the queue a browser-only reference.

Short-form posts should still be adapted by destination. The API makes distribution programmable; it does not make identical copy, unsupported formatting, or unreviewed AI output appropriate for every network.

Use public HTTPS media URLs or the documented inline upload format.
Validate selected platforms before creating a large batch.
Preserve separate destination versions when length, formatting, or context differs.

Choose REST API, MCP, or webhooks for the right integration job

REST API routes fit an application, CMS, script, or internal tool that already knows the action it needs to request. MCP exposes explicit tools for assistants that need to list, draft, schedule, reschedule, or cancel supported publishing work through a controlled interface.

Webhooks move supported events in the other direction. Instead of polling constantly, an external system can react when a Note publishes or fails. Consumers should verify the configured request, store event identifiers where available, and make handlers idempotent because delivery systems can retry.

The interfaces can be combined: an internal application creates a scheduled item through REST, the writer reviews it in Narrareach, and a webhook updates the source system after a supported delivery event. This keeps automation and editorial visibility in the same lifecycle.

Use REST for deterministic application actions and MCP for assistant tool use.
Use webhooks for supported downstream reactions, not as the original publishing command.
Give every token the least scope and plan access required for the workflow.

How to evaluate a posting API

Compare supported content types before counting platform logos. A social API may publish short posts but not long-form articles, newsletter Notes, publication drafts, tags, paid-content settings, or destination-specific search metadata.

Inspect operational behavior next: OAuth ownership, token scope, scheduling horizon, timezones, media upload, idempotency, rate limits, rescheduling, cancellation, delivery state, retries, and failure visibility. Ask which responsibilities remain with the client and which are handled by the provider.

Finally evaluate the human workflow. If writers cannot inspect, edit, or recover an API-created item without engineering help, the endpoint has reduced integration work while preserving an operations problem. Narrareach keeps API-created jobs in the same queue as manually created work.

Run a create, reschedule, cancel, publish, and failure test before production use.
Document which system owns the source content and which owns final delivery state.
Budget for destination changes even when using a unified API.

Sources and methodology

Definitions grounded in current platform documentation

Narrareach API documentationCurrent Narrareach REST article routes, MCP tools, media rules, authentication, rate limits, and plan access.Buffer: social media APIs for developersA current developer-oriented comparison of direct social platform APIs, access requirements, and common limitations.

How Narrareach solves it

Keep the publishing system close to the writing.

Article and Notes endpoints - so applications can schedule long-form and short-form publishing work through one authenticated product

Writer-visible queue state - so API-created items remain reviewable, movable, cancellable, and visible outside developer logs

Media and destination validation - so unsupported files and platform combinations fail before becoming silent delivery problems

MCP and webhook workflows - so AI assistants can request controlled actions and external systems can react to supported events

Posting API options trade control for integration coverage

Direct platform APIs, broad social APIs, and Narrareach are designed around different content and operating models.

Capability	Direct platform APIs	Unified social API	Narrareach
Destination-specific control	Highest	Normalized surface	Supported writer-focused fields
Full article and newsletter workflows	Platform-dependent	Often limited	Articles and Notes alongside social posts
Number of integrations to maintain	One per platform	One provider integration	One Narrareach publishing workflow
Writer review and queue UI	You build it	Varies	Included
MCP assistant tools	You build them	Varies	Included for eligible workflows
Destination change maintenance	Your responsibility	Provider responsibility	Narrareach maintains supported paths

Every provider remains subject to destination-platform policies and changes. Confirm current endpoint, plan, token scope, and channel support before implementation.

Start here

Give your tools a real publishing queue

API access is available for authenticated Narrareach workflows.

Read the API docs

Questions writers ask

What is a posting API?

A posting API lets an authenticated application create or schedule content for connected destinations. A production API also needs validation, media handling, timezones, duplicate protection, queue state, delivery status, rate limits, and failure recovery.

Does Narrareach provide a posting API?

Yes. Narrareach provides authenticated REST API and MCP workflows for supported article and Notes scheduling, plus queue controls and supported webhook events for eligible plans.

Can the Narrareach API schedule full articles?

Yes. POST /api/v1/articles supports documented article workflows for Substack, Medium, LinkedIn, and X, subject to the connected accounts, token scope, plan, required fields, and current destination availability.

Can the posting API schedule Notes with images?

Yes. Supported Notes workflows accept public image URLs, and MCP also documents inline media formats. Platform media limits are validated before Narrareach creates scheduled rows.

How do I prevent duplicate posts when retrying?

Use a stable idempotency key on supported article requests, store the original response identifier, and read the existing item before retrying an uncertain request. Do not generate a new key for the same intended article submission.

Can API-created articles be rescheduled or cancelled?

Yes. Narrareach documents PATCH /api/v1/article-schedules/:id for moving a queued article and DELETE /api/v1/article-schedules/:id for cancelling it before publication.

Does a successful API response mean the post is live?

Not necessarily. A create or schedule response confirms that Narrareach accepted the job. Read the final item state or use supported webhook events to confirm the destination outcome and URL.

What is the difference between the posting API and MCP?

REST API routes fit deterministic application requests. MCP exposes named publishing tools to compatible AI assistants. Both should use authenticated, least-privilege access and keep the resulting work visible to the writer.

Narrareach LLM connector

Connect Claude, ChatGPT, or any MCP-compatible agent to read drafts, schedule posts, and automate Substack, Medium, LinkedIn, X, Bluesky, and Threads workflows.

Read the docs