Narrareach
Draft, schedule, and analyze content for Substack, Medium, LinkedIn, X, Bluesky, and Threads. Requires an eligible Narrareach account and OAuth sign-in; capabilities vary by platform.
Hosted MCP Server
npx add-mcp 'https://www.narrareach.com/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
How the connector works
Narrareach uses the Model Context Protocol over HTTPS. Claude, ChatGPT, Gemini, and Notion Agents discover the endpoint, register an OAuth client dynamically, send the user through Narrareach sign-in, and authorize future MCP requests. MCP is included on paid plans with scheduling and analytics.
One URL
Users provide /mcp. The client discovers the rest.
OAuth
Users grant permissions through Narrareach. No shared secrets are exposed.
DCR + PKCE
Dynamic client registration and PKCE S256 handle client setup safely.
Claude
Connect the official Narrareach connector
Narrareach is an official Claude connector. In Claude, open Connectors, find Narrareach, select Connect, and complete Narrareach sign-in.
If Narrareach isn't listed for your account, add it as a custom connector in Claude: open Settings, then Connectors, choose Add custom connector, copy the values below into Claude's form, and select Add there. Leave Advanced settings closed. Claude registers the OAuth client automatically.
Name
Narrareach
Connector URL
https://www.narrareach.com/mcp

Screenshot from Claude, for reference. Fill in this form in Claude, not on this page.
ChatGPT
Connect Narrareach to ChatGPT
Connect directly — Recommended
Add Narrareach using its server URL to load the current tools. Your ChatGPT account must support custom MCP connections.
- Open ChatGPT Plugins in your browser. Click Add (or the plus button), then Add custom MCP server.
- In the form that opens, use Narrareach as the name and the server address below. Choose OAuth for authentication; leave client ID and client secret empty.
- Review the warning, choose I understand and want to continue, then Create as a plugin. Finish Narrareach sign-in and install the resulting plugin.
- Start a new chat, select Narrareach with @, and ask it to show your connected accounts.
Show setup screenshots

Choose Add custom MCP server to open the connection form.
New Plugin
×
Icon (optional)
An icon is optional.
Connection
Server URLTunnel
https://www.narrareach.com/mcp
Authentication
OAuth▾
Advanced OAuth settings
Review discovered OAuth settings, or enter them manually.
Custom MCP servers introduce risk. Learn more
Create as a plugin
https://www.narrareach.com/mcp
If these controls are unavailable, use the directory option below or ask your workspace administrator about access.
OpenAI’s current custom connection guide
If Substack asks for a code, enter it once in the active verification form in ChatGPT or Narrareach. Opening Narrareach restores a code request already in progress. If the code was accepted but the connection is still saving, check its status before requesting another code. Keep your saved draft and check scheduling confirmation before trying again.
Official Narrareach connector — ChatGPT directory
Install the published Narrareach plugin. New or changed actions become available after OpenAI approves them.
- In ChatGPT, open Plugins, find Narrareach, and select Connect. The official Narrareach listing opens the same plugin.
- Sign in with the same email you use for Narrareach and review the requested permissions.
- In a new chat, type @ and select Narrareach. Ask it to show your connected accounts and existing drafts before scheduling.
On a phone or tablet, open the listing in your browser if you cannot find it in the app. Availability can depend on your ChatGPT account and workspace settings.
Already connected, but a tool is missing?
Official Narrareach plugin: new or changed tools become available after OpenAI approves them. Installing again or reconnecting does not bypass that review. Try a new chat with Narrareach selected once the update is available.
Custom connection: open its settings in ChatGPT in a browser. If Refresh is available, select it, check the tool list, then start a new conversation. Reconnect or Change connection may only repeat sign-in; they do not confirm that new tools were added.
If Refresh is missing or Substack verification is still unavailable, contact Narrareach support with the missing action and whether you use the official plugin or a custom connection. Keep your existing draft and publishing accounts connected. A managed workspace may need an administrator to review and enable new actions.
Common questions
Why does ChatGPT say “Resource not found” when the Narrareach tools are visible?
ChatGPT may be unable to resolve a cached plugin action or an earlier attachment before it sends the request to Narrareach. Start a new chat so ChatGPT reloads the available actions. If an image was attached, attach it again. If the error continues, contact Narrareach support with the exact message. Keep the existing draft; a successful account check alone does not confirm that scheduling is available.
How should I send a ChatGPT-generated image with an article?
Send the actual image bytes, not a temporary ChatGPT attachment reference or a blob: or file: URL. Ask ChatGPT to use schedule_article with coverImage or media as a data URI or base64 value. It can also call upload_media first and use the returned public URL.
Can create_draft save an article image by itself?
create_draft accepts a title and optional HTML body; it does not accept an attached image object. To keep the article as a draft, create it first and then call update_draft with coverImage. To schedule immediately, use schedule_article, which accepts cover and inline media.
Gemini
Add Narrareach as a Gemini custom app
In Narrareach, open Settings > Integrations > Gemini, then add a custom app in Gemini with the values below. Leave Advanced features closed unless Gemini asks for credentials. Gemini should register the OAuth client automatically.
- On a computer, open gemini.google.com and go to Settings → Connected Apps.
- If Connected Apps is hidden, open Personal Intelligence first, then Connected Apps.
- Under Custom apps, choose Add a custom app. Paste the Connector URL below, then click Next.
- Complete Narrareach sign-in with the same email as your Narrareach account.
- In a chat, type
@Narrareachto select the connector explicitly.
Connector URL
https://www.narrareach.com/mcp
Google account requirements
Google currently requires users to be 18 or older, located in the United States, using Gemini in English with a personal Google Account and Keep Activity on. Work or school accounts cannot connect custom apps. Connect the app in the Gemini web app first; after that it can also be used on mobile.
Admin note
Narrareach publishes Clerk's Dynamic Client Registration endpoint and PKCE S256 support through its OAuth metadata. Gemini should therefore register itself from the Connector URL; users do not need a client ID or secret. If Google changes its client onboarding method, verify the live authorization request before changing Clerk.
Notion
Use Narrareach in Notion Agents
This connects Narrareach's MCP tools to Notion Agent or an individual Notion Custom Agent. It is separate from the Notion page-import connection in Narrareach Settings. Notion requires a Business or Enterprise plan and web or desktop setup; custom MCP servers must be enabled by your workspace admin. No Narrareach API token or client secret is needed.
Connector URL
https://www.narrareach.com/mcp
Notion Agent
- On Notion web or desktop, open Settings → Connections → Discover → Add Custom MCP.
- Enter the Connector URL and sign in with your Narrareach account.
- Find Narrareach under All sources → MCP servers in chat. Mention it by name if the agent does not select it.
Custom Agent
- Open the agent's Settings → Tools & Access → Add connection → Custom MCP server.
- Enter the Connector URL, sign in with Narrareach, and choose the tools this agent can use.
- Keep write tools set to require confirmation, especially scheduling and publishing actions.
Access and troubleshooting
Notion Agent and every Custom Agent require separate connections. An admin must enable custom MCP servers and, in an approved-only workspace, approve this URL. A Custom Agent uses the Narrareach permissions of the person who connects it, including when teammates interact with that agent; limit agent access accordingly. If tools are missing, check the connection status and refresh the agent settings before reconnecting.
Notion Agent instructions Custom Agent instructions
Make
Connect a Make scenario through the REST API
Use Make's HTTP module with a scoped Narrareach automation token. Keep the token in Make's credential storage, map only approved content into the request, and preserve the returned Narrareach identifier for status checks and safe retries.
- Create a token in Narrareach Settings > Integrations > REST API & webhooks with only the required scopes.
- Add an HTTP request module and use the endpoint and body from the public OpenAPI contract.
- Store the token as a credential and send it in the Authorization header.
- Use a stable source-record ID as the idempotency key. Notes accept the
Idempotency-Keyheader oridempotencyKeyin the body; articles take it in the body. - Store the accepted item ID, then check status before retrying after a timeout.
n8n
Use the Narrareach community node in n8n
Install n8n-nodes-narrareach for native actions to schedule Articles and Notes, check status, reschedule, cancel, work with reader activity, and read Stats outcomes. n8n handles triggers and branching while Narrareach handles connected destinations and publishing state. To start a workflow when a Note publishes or fails, use n8n's Webhook node with a Narrareach webhook.
- Install
n8n-nodes-narrareachunder Community Nodes. - Create a scoped Narrareach automation token and save it only in the n8n credential.
- Map approved content, destination, schedule time, timezone, and a stable source ID.
- Run one future-dated canary and confirm it with Get Status before enabling the workflow.
LLM clients discover Narrareach auth from standards-based metadata. These endpoints must remain public and served over HTTPS.
MCP resource
https://www.narrareach.com/.well-known/oauth-protected-resource/mcp
Auth server (ChatGPT)
https://www.narrareach.com/.well-known/oauth-authorization-server/mcp
Auth server (Clerk)
https://clerk.narrareach.com/.well-known/oauth-authorization-server
Resource
https://www.narrareach.com/mcp
Required
The authorization metadata must include a registration_endpoint.
Required
PKCE support must advertise S256.
Publishing guide
Edit scheduled LinkedIn posts with ChatGPT
Use ChatGPT, Claude, or another connected MCP assistant to review and change a queued, text-only LinkedIn post in your personal Narrareach account. Publishing must not have started. This does not edit media posts, published posts, or scheduled articles.
- Ask your assistant to find the post with
list_scheduled_items, checkget_scheduled_item_readiness, and read the queued text withget_note. - Provide the replacement text and ask for a preview. The assistant uses
amend_scheduled_note_contentwith the schedule id, the current revision asexpectedRevision, and your full replacement text. Previewing alone does not change the post. - Review the preview and confirm before the assistant applies it with
apply: true. If the post has changed, review a fresh preview before confirming again.
Example request: “Show me tomorrow’s LinkedIn post. Preview this replacement text, but don’t apply it until I confirm.” To move a Note or article to a different time, use amend_scheduled_item instead. Team Note changes still use the team dashboard.
Inspect article drafts and change covers
Article readiness includes a draftId. Use it with get_draft to review the Narrareach draft, not a verified copy of what is scheduled on the publishing platform. For an unscheduled article, update_draft can change its title, body, or cover image. Cover-only edits preserve the body and existing subscribe controls. It cannot edit an active article schedule. Review the schedule status before making changes; do not cancel or recreate it without approval.
Existing connections
Get new tools in your MCP connection
Official Narrareach plugin: new or changed tools become available after OpenAI approves them. Installing again or reconnecting does not bypass that review. Try a new chat with Narrareach selected once the update is available.
Custom connection: open its settings in ChatGPT in a browser. If Refresh is available, select it, check the tool list, then start a new conversation. Reconnect or Change connection may only repeat sign-in; they do not confirm that new tools were added.
If Refresh is missing or Substack verification is still unavailable, contact Narrareach support with the missing action and whether you use the official plugin or a custom connection. Keep your existing draft and publishing accounts connected. A managed workspace may need an administrator to review and enable new actions.
OpenAI’s connection and refresh guide
Tool catalog
What LLMs can do
Connected clients can work with drafts, notes, scheduling, inspiration, analytics, and profile context across Substack, Medium, LinkedIn, X, Bluesky, Threads, Instagram, Facebook, TikTok, and Pinterest. Tool access is scoped to the authenticated Narrareach user. Scheduling responses include the Narrareach item URL; published platform URLs are returned once the destination confirms publish. Article responses may also include non-blocking advisories; relay these as status updates without treating the accepted schedule as a failure.
Choose the account before acting
Call list_workspaces to see the teams and writers you can access. The tool details below show which calls accept workspace and writer. Drafts, article scheduling, and schedule changes currently use your personal account. Keep the same workspace when listing, reading, and scheduling team Notes. If team access fails, do not switch to personal publishing to work around it.
Check Notes and articles separately
For Notes and social posts, use list_notes, then get_note with the returned id. For articles, use list_scheduled_posts and find the schedule id, not the draft id. After a timeout, an empty article list does not tell you whether a Note was scheduled. Check the right account, filters, and list limit before submitting again. Team Note changes currently use the team dashboard.
Tool
Description
list_workspaces
List the personal account and authorized team workspaces, writers, and publications.Account and fields
Discovers context from your signed-in account. No selectors needed.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_user_profile
Read the current user profile, plan, timezone, connection status, and available publishing context.Account and fields
Discovers context from your signed-in account. No selectors needed.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_settings
Read your main Settings: preferences such as UTM tagging and article link placement, the default account on each platform, connection health, and email notifications.Account and fields
Discovers context from your signed-in account. No selectors needed.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_settings
Change your timezone, generated Note capitalization, writing language, app language, article link placement, or UTM tagging for article links.Account and fields
Discovers context from your signed-in account. No selectors needed.
Required fields: None.
Accepted fields: preferredTimezone, capitalizeGeneratedNotes, writingLanguage, uiLanguage, articleLinkPlacement, articleFollowUpDelivery, tagArticleLinksWithUtm.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_drafts
Find drafts in your personal account by title or status.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: limit, status, query.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_draft
Read the complete content and metadata for one authorized draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_ai_visibility_audit
Check an article draft for what helps Google and AI search find and cite it.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId.
Accepted fields: draftId.
Use the schema supplied by your MCP client for field types, choices, and limits.
create_draft
Save an article draft in your personal account without scheduling it.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: title.
Accepted fields: title, contentHtml, coverFile, coverImage.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_draft
Update the title, body, or cover image of an unscheduled article draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id, title, contentHtml, coverFile, coverImage.
Use the schema supplied by your MCP client for field types, choices, and limits.
archive_draft
Archive an owned draft after active schedules have been handled.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_draft_comments
Read the comment threads collaborators and reviewers left on an owned draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId.
Accepted fields: draftId, status, limit.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_draft_comment_notifications
Find owned drafts with comments you have not read yet.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: limit, includeMuted.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_content_versions
List a saved Note and the article drafted from it, each with its own status and destinations.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: draftId.
Accepted fields: draftId, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
create_article_from_note
Create a linked article draft from a saved Note. The Note is kept, and nothing is published.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: draftId.
Accepted fields: draftId, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_notes
Find scheduled, published, or failed Notes and social posts, by date range or content tag, with their latest stored metrics.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: limit, status, platform, query, from, to, tag, cursor, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_note
Read one authorized Note and its destination state.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: id.
Accepted fields: id, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
create_generated_notes
Generate notes in the writer's voice with Narrareach's note generator, each with a suggested posting time. Saves and schedules nothing.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: source, postContent, postTitle, postUrl, count, days, tone, customInstructions, writingLanguage, platforms, timezone, cadenceResolution, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
schedule_note
Schedule short-form content to supported connected publishing destinations.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: scheduledFor, platforms.
Accepted fields: draftId, title, content, quoteUrl, scheduledFor, timezone, platforms, socialAccountIds, instagramDestinations, linkedInAccountId, linkedInOrganizationUrn, workspace, writer, publication, confirmProfileDestination, substackConnectionId, imageUrls, videoUrls, threadsTopicTag, firstReply, platformVersions, shortVersion, media, clientRequestId, generationId.
Conditional field: postingAs. Available only when your connected tool schema includes it. Select a connected Substack pen name, profile handle, or publication label. Use postingAs or publication, not both. This field does not grant access to another account.
Use the schema supplied by your MCP client for field types, choices, and limits.
schedule_notes
Schedule up to 50 notes in one call, each the way schedule_note would, with a result per note.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: notes.
Accepted fields: notes, workspace, writer, publication.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_scheduled_posts
List article schedules in your personal account.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: limit, status, from, to.
Use the schema supplied by your MCP client for field types, choices, and limits.
cancel_scheduled_post
Cancel an article schedule from list_scheduled_posts.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id.
Use the schema supplied by your MCP client for field types, choices, and limits.
schedule_article
Schedule a full article to supported connected long-form destinations.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: platforms.
Accepted fields: draftId, title, allowDuplicateTitle, contentHtml, subtitle, coverFile, coverImage, media, tags, sendToNewsletter, isPaidContent, freewall, paywallMarker, addSearchMetadata, linkedinShareCommentary, linkedinPublicationType, linkedinAuthorUrn, linkedinNewsletterUrn, publishNow, scheduledFor, platformSchedules, timezone, platforms, publication, substackConnectionId, mediumPublicationId, mediumNotifyFollowers, publishMode.
Conditional field: mediumPublicationId. Only valid when platforms includes MEDIUM; a blank value is ignored. Call list_medium_publications and pass its returned id; never guess one. When canPublish is false the story is submitted for editorial review and left unscheduled until an editor accepts it. A rejection by the publication is best-effort — the story still goes to the personal profile and the rejection is returned as a warning.
Conditional field: mediumNotifyFollowers. true is only valid when platforms includes MEDIUM; false is ignored. Defaults to false (no subscriber email).
Use the schema supplied by your MCP client for field types, choices, and limits.
get_substack_verification_status
Check whether your Substack connection needs a code.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: connectionId.
Accepted fields: connectionId, scheduledPostId.
Use the schema supplied by your MCP client for field types, choices, and limits.
start_substack_verification
Request a Substack verification code in this conversation.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: connectionId.
Accepted fields: connectionId, scheduledPostId.
Use the schema supplied by your MCP client for field types, choices, and limits.
complete_substack_verification
Submit the Substack code provided by the user.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: connectionId, id, code.
Accepted fields: connectionId, id, code, scheduledPostId.
Use the schema supplied by your MCP client for field types, choices, and limits.
cancel_substack_verification
Cancel one Substack code request.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: connectionId, id.
Accepted fields: connectionId, id, scheduledPostId.
Use the schema supplied by your MCP client for field types, choices, and limits.
verify_substack
Request and enter a Substack code in your current conversation.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: action, connectionId.
Accepted fields: action, connectionId, id, code, scheduledPostId.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_linkedin_article_destinations
Refresh and list LinkedIn article profiles, Company Pages, and newsletters. Does not publish content.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: authorUrn, refresh.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_medium_publications
List the Medium publications the connected account can submit stories to. Does not publish content.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: refresh.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_linkedin_destinations
Refresh and list connected LinkedIn profiles and Company Pages for short-form posts. Does not publish content.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_social_accounts
List connected Threads, Facebook, TikTok, Pinterest and X accounts for short-form posts. Does not publish content.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_instagram_destinations
List connected Instagram accounts for short-form posts. Does not publish content.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_hashtag_sets
List your saved hashtag sets.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
save_hashtag_sets
Save your hashtag sets: up to 20 sets of up to 30 hashtags each. Never inserts hashtags into content or publishes anything.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: sets.
Accepted fields: sets.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_scheduled_items
Review Notes and articles together with their destinations, times, and readiness checks.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: kind, status, from, to, limit, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_scheduled_item_readiness
Inspect one scheduled Note or article before making changes.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id, kind.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_substack_article_audience
Read a Substack article's audience, wall and email setting from Substack itself.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id.
Use the schema supplied by your MCP client for field types, choices, and limits.
amend_scheduled_item
Preview and confirm a time change for a scheduled Note or article.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id, expectedRevision, scheduledFor.
Accepted fields: id, kind, expectedRevision, scheduledFor, timezone, apply.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_scheduled_note_account
Send an already scheduled Threads, Facebook, TikTok, Pinterest, X or Instagram post from a different connected account.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id, accountId.
Accepted fields: id, accountId.
Use the schema supplied by your MCP client for field types, choices, and limits.
add_platform_to_scheduled_note
Add a platform, or another account on a platform, to a Note that is already scheduled, at the same time as its other versions.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id, platform.
Accepted fields: id, platform, accountId, linkedInOrganizationUrn, content, clientRequestId.
Use the schema supplied by your MCP client for field types, choices, and limits.
amend_scheduled_note_content
Preview and edit the text of a queued, text-only LinkedIn post.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id, expectedRevision, content.
Accepted fields: id, expectedRevision, content, apply.
Use the schema supplied by your MCP client for field types, choices, and limits.
reschedule_scheduled_item
Move an authorized queued Note or article to a new time.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id, scheduledFor.
Accepted fields: id, kind, scheduledFor, timezone.
Use the schema supplied by your MCP client for field types, choices, and limits.
cancel_scheduled_item
Cancel an authorized queued Note or article without deleting its source draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: id.
Accepted fields: id, kind.
Use the schema supplied by your MCP client for field types, choices, and limits.
upload_media
Upload supported image or video bytes for later use in an authorized publishing workflow.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: kind.
Accepted fields: kind, sourceType, url, data, mimeType, fileName, file.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_inspiration_posts
Browse inspiration posts saved by the authenticated user.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: limit, platform, tag.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_benchmark_inspiration
Read saved writing experiments and optional inspiration for eligible pilot accounts.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
prepare_benchmark_inspiration
Prepare low-confidence draft comparisons from saved examples for eligible pilot accounts.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: recordId, niche.
Accepted fields: recordId, niche.
Use the schema supplied by your MCP client for field types, choices, and limits.
create_reader_reply_draft
Save a reply for review; generate in the writer’s voice when text is omitted.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: activityId.
Accepted fields: activityId, text, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_reader_reply_draft
Edit a pending reply and record its revision.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId, text, expectedUpdatedAt.
Accepted fields: draftId, text, expectedUpdatedAt, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
send_reader_reply_draft
Publish one explicitly approved reply draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId, expectedUpdatedAt.
Accepted fields: draftId, expectedUpdatedAt, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_reader_reply_drafts
List saved replies for the selected publication.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: status, activityId, limit, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_reader_activities
List owned Substack likes, comments, restacks, and other notifications, and reader comments on LinkedIn, Threads, Facebook, Bluesky, Instagram and TikTok posts.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: state, type, sort, cursor, limit, substackConnectionId, intent, platform.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_conversations
List the writer's stored direct-message conversations from Instagram, Facebook, TikTok, Bluesky and Substack, newest message first.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: state, platform, kind, cursor, limit.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_conversation
Read one stored direct-message conversation and its messages, newest first.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: conversationId.
Accepted fields: conversationId, cursor, limit.
Use the schema supplied by your MCP client for field types, choices, and limits.
create_dm_reply_draft
Save a reply to a direct-message conversation for review; suggest one in the writer's voice when text is omitted.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: conversationId.
Accepted fields: conversationId, text.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_dm_reply_draft
Edit an unsent direct-message reply draft.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId, text, expectedUpdatedAt.
Accepted fields: draftId, text, expectedUpdatedAt.
Use the schema supplied by your MCP client for field types, choices, and limits.
send_dm_reply_draft
Send one approved direct-message reply from the writer's own account.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: draftId, expectedUpdatedAt.
Accepted fields: draftId, expectedUpdatedAt.
Use the schema supplied by your MCP client for field types, choices, and limits.
reply_to_reader_activity
Publish a reply to an owned, replyable Substack comment.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: activityId, text.
Accepted fields: activityId, text, idempotencyKey, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_reader_activity
Move an owned reader activity item between Inbox and History.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: activityId, triageState.
Accepted fields: activityId, triageState, substackConnectionId.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_platform_analytics
Read supported account and post analytics, or stored metrics. Metrics a platform does not report are null, not 0.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: platform.
Accepted fields: platform, recentLimit.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_social_posts
List your own posts on connected social accounts, including ones published outside Narrareach, with the latest metrics each platform reported.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: platform, source, from, to, includeDeleted, limit, cursor.
Use the schema supplied by your MCP client for field types, choices, and limits.
refresh_medium_stats
Sync Medium stats from Medium and store them. Does not publish content.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: recentLimit.
Use the schema supplied by your MCP client for field types, choices, and limits.
refresh_substack_benchmark
Recompute and save the Substack Notes benchmark from the latest public notes. Does not publish content.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: publicationUrl.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_article_stats
Read saved stats for published articles, including the links readers clicked.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: publicationId, platform, limit, cursor, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_stats_insights
Read stored Narrareach Stats insights for a selected period.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: period, from, to, platforms, contentTypes, publicationId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
start_research_desk_question
Ask the Research Desk a research question; it answers in the background.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: question.
Accepted fields: question, conversationId, clientRequestId, timezone, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_research_desk_answer
Check on a Research Desk question and read its answer once it is done.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: runId.
Accepted fields: runId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_transcript
Get the transcript of a YouTube video, podcast episode, or audio file.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: url, uploadUrl, episode, maxChars.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_transcript_status
Check on a transcript that is still being processed and read it once it is ready.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: transcriptId.
Accepted fields: transcriptId, maxChars.
Use the schema supplied by your MCP client for field types, choices, and limits.
generate_article_briefs
Plan 3 or 5 article briefs with an outline and evidence links.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: source.
Accepted fields: source, count, pillarId, topic.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_article_briefs
List article briefs and their draft progress.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: None.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_article_brief
Read one article brief and its draft status.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: briefId.
Accepted fields: briefId.
Use the schema supplied by your MCP client for field types, choices, and limits.
queue_article_draft
Write a brief into a full first draft in the background.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: briefId.
Accepted fields: briefId.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_topic_suggestions
Suggest timely topics for each of the writer's content pillars, with why now, a suggested angle, and evidence links.Account and fields
Personal account only. Do not send workspace or writer.
Required fields: None.
Accepted fields: pillarId, limit.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_audience_overview
Check whether Audience is ready for a Substack publication and which filters it supports, with tag and saved-segment counts.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: publicationId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
preview_audience_segment
Count how many subscribers match a set of filters, without listing them.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: predicates.
Accepted fields: predicates, includeAuthor, publicationId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_creator_matches
List Substack creator matches whose audience overlaps the publication, and who was already messaged.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: publicationId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_import_status
Read where the writer's imports stand: writing import, Substack imports, blog automation sources, and social history imports.Account and fields
Discovers context from your signed-in account. No selectors needed.
Required fields: None.
Accepted fields: workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_stats_snapshot
Read the stored daily audience series: subscribers, paid subscribers, followers, open rate, and the change over the period.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: days, publicationId, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_posting_schedule
Read the saved Note cadence, the effective schedule, its timezone, the next open queue slot, and open slots for the coming days.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: days, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_posting_schedule
Save the Note cadence for future notes: preferred times, posts per day, days, weekend skipping, mode, and timezone.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: timeSlots, postsPerDay, daysOfWeek, skipWeekends, scheduleMode, timezone, workspace.
Use the schema supplied by your MCP client for field types, choices, and limits.
get_voice_profile
Read the writer's voice profile: how they sound, their do and don't rules, topics, stances, real material, instructions, and a few of their own posts as examples.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: detail, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
save_voice_preference
Save one writing preference the writer has just stated as a rule in their voice profile.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: kind, text.
Accepted fields: kind, text, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
add_voice_material
Save a real story, number, opinion, or example the writer has just shared to their material bank.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: type, text.
Accepted fields: type, text, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
decide_voice_suggestion
Record the writer's answer to one suggestion about how they write: approve, dismiss, or ask later.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: suggestionId, decision.
Accepted fields: suggestionId, decision, text, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_voice_rule
Reword one rule in the writer's voice profile.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: ruleId, text.
Accepted fields: ruleId, text, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
remove_voice_rule
Remove one rule from the writer's voice profile.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: ruleId.
Accepted fields: ruleId, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
undo_voice_change
Undo the most recent change to the writer's voice profile.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: changeId, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_voice_profile
Set sections of the writer's voice profile: how they sound, niche, audience, instructions, or topics.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: howYouSound, niche, audience, instructions, topics, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_voice_stances
Add or remove stances: what the writer believes or would never say.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: add, remove, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
remove_voice_material
Remove one item from the writer's material bank.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: materialId.
Accepted fields: materialId, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
update_voice_examples
Pin, unpin, exclude, or restore the writer's own posts as examples of their voice, or reset to their most recent posts.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: pin, unpin, exclude, restore, reset, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_voice_examples
List the writer's own posts that can be pinned as voice examples, with their example ids.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: query, from, to, cursor, pageSize, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
list_voice_changes
List recent changes to the writer's voice profile: what changed, who made it, where, and when.Account and fields
Personal account by default; accepts an authorized team workspace.
Required fields: None.
Accepted fields: limit, workspace, writer.
Use the schema supplied by your MCP client for field types, choices, and limits.
Open the complete agent-ready MCP tool reference
Media
Scheduling with images and video
schedule_note accepts imageUrls for public HTTPS images and media for pasted clipboard images, data URIs, or raw base64. Inline media is uploaded first, then the scheduled note stores the returned public URL. Article images and videos are handled through article HTML or draft media, not a top-level imageUrls field on schedule_article. Server-to-server callers can pass note images to POST /api/v1/notes with imageUrls.
Platform
Note media limit
Substack
Up to 6 images
X
Up to 4 images or 1 video; images and video cannot be mixed
Bluesky
Up to 4 images or 1 video; images and video cannot be mixed
At least one media item is required; up to 10 total media items
TikTok
Up to 35 images or 1 video; images and video cannot be mixed
One media item is required
Images are supported through the connected posting path
Threads
Images are supported through the connected posting path
Images are supported through the connected posting path
{
"jsonrpc": "2.0",
"id": "schedule-image-note",
"method": "tools/call",
"params": {
"name": "schedule_note",
"arguments": {
"content": "A short note with an attached image.",
"platforms": ["SUBSTACK", "X", "THREADS"],
"scheduledFor": "2026-07-01T14:00:00.000Z",
"timezone": "America/New_York",
"threadsTopicTag": "Creator Economy",
"imageUrls": ["https://cdn.example.com/note-image.png"]
}
}
}
Local URLs
blob: and file: URLs cannot be fetched by Narrareach. Upload the media or pass it through media.
Validation
Platform media limits are checked before Narrareach creates scheduled rows.
REST API
Schedule articles from your server
REST callers can schedule full articles with POST /api/v1/articles. Article scheduling supports SUBSTACK, MEDIUM,LINKEDIN, X, WORDPRESS, and GHOST. Use an automation token with articles:write; note-only tokens cannot schedule articles. LinkedIn articles must be scheduled at least 20 minutes ahead. Set addSearchMetadata to generate SEO metadata for supported article destinations; X does not expose separate article SEO settings.
WordPress and Ghost use your personal connected site. For site-only schedules, set publishMode: "draft" to save a remote draft at the scheduled time. This completes delivery without publishing, creating a public URL, or sending email. Completed drafts report outcome: "saved_draft" and remoteEditUrl so you can open them in your site editor.
scheduledFor accepts an RFC 3339 timestamp with either Z or an explicit UTC offset; Narrareach normalizes it to UTC.
LinkedIn Notes can publish from the connected personal profile or an administered Company Page. Call GET /api/v1/linkedin/destinations and send the returned accountId as linkedInAccountId. For a Page, also send linkedInOrganizationUrn. Omit both to use the Settings default or the only available personal profile. Narrareach never guesses among Company Pages. If several destinations exist and none can be selected safely, the request fails with LINKEDIN_DESTINATION_REQUIRED.
To choose which Threads, Facebook, TikTok, Pinterest or X account a Note goes to, call GET /api/v1/social-accounts and send the returned accountId keyed by platform in socialAccountIds. Without it, the Note posts to that platform's only account or its default. If several accounts are connected and none is the default, the request fails with SOCIAL_ACCOUNT_CHOICE_REQUIRED.
To choose an Instagram account, or to send one Note to several, call GET /api/v1/instagram/destinations and send the returned accountId values in instagramDestinations. Without it, the Note posts to the defaultDestination that call reports. If defaultIsAmbiguous is true, name the account.
LinkedIn Articles can publish from the signed-in personal profile or an administered Company Page. Call GET /api/v1/linkedin/article-destinations, choose a returned authorUrn, and send it as linkedinAuthorUrn. Call the same endpoint with authorUrn to list that profile or Page's newsletters. For a newsletter issue, also send linkedinPublicationType: "newsletter" and the returned linkedinNewsletterUrn.
A Medium article publishes to the connected account's own profile by default. To submit it to a publication instead, call GET /api/v1/medium/publications and send a returned id as mediumPublicationId. The publication list is saved for this connection; use ?refresh=1 when publication access changes to check Medium again. When canPublish is false for that publication, the story is submitted for editorial review and left unscheduled — it goes live when an editor accepts it, not at the requested time, and never publishes to the personal profile behind the publication's back. Submitting is otherwise best-effort: if the publication rejects the story, it still publishes or schedules to the personal profile and the rejection is returned in warnings, not as a failure. Set mediumNotifyFollowers: true to email Medium subscribers about the story; it defaults to false and is applied on the same best-effort basis.
Identify the Substack destination with publication as an exact connected publication name, handle, or URL. If omitted, Narrareach can select a sole active publication. Otherwise, the caller must ask the user which publication to use.
When LinkedIn has a pending connection sync, create and reschedule requests return HTTP 409 with PLATFORM_SESSION_REFRESH_REQUIRED and canRetryAfterSync: true. New article input is saved first, and create responses include saved: true with the saved draftId. Nothing is scheduled until the connection is synced; sync LinkedIn in Platform connections, then retry the same request using that draft.
Uploaded article video is available for Substack-only article requests. Add kind: "video" to an item in media and place it with a 1-based {{media:N}} marker in contentHtml. Omitting kind remains backward-compatible and treats the item as an image. Narrareach accepts MP4, WebM, MOV, and M4V video up to 100MB when fetched from a public URL; inline REST data is additionally limited by the 15,000,000-character request field (about 10.7 MiB of decoded base64 bytes). A request containing article video is rejected with VIDEO_REQUIRES_SUBSTACK_ONLY if Medium, LinkedIn, or X is also selected, so uploaded video is never silently omitted. YouTube iframe input is normalized before saving: it publishes as a native inline embed on Substack and remains visible as a canonical link on selected destinations that cannot embed it. Vimeo iframe input is preserved as a canonical link on every selected destination. If saved structured content and HTML disagree about the number or identity of their videos, Narrareach returns CONTENT_OUT_OF_SYNC before publishing; re-save the draft and retry. Video preparation may continue after a schedule is accepted. Check the schedule status instead of submitting another article. A VIDEO_PROCESSING response means the video is not ready yet. VIDEO_DISABLED with HTTP 503 means video publishing is temporarily unavailable; retry after service is restored.
Successful article create and reschedule responses may include an advisories array when a selected platform is experiencing publishing delays. Advisories are informational: the request remains accepted, no acknowledgement is required, and actionRequired is false.
When a scheduled LinkedIn article will need the writer before it can publish, because LinkedIn signed them out or refused the saved LinkedIn Articles session, the request is still accepted. Its warnings array includes the message to show the writer (resync LinkedIn Articles in Settings → Platform connections → LinkedIn Articles → Update connection), and connectionWarnings includes an object with platform: "LINKEDIN",code: "LINKEDIN_SESSION_REFRESH_REQUIRED",action: "RESYNC_LINKEDIN_ARTICLES" and message. A replay with the same idempotencyKey checks the session again, so the warning is gone once the writer has resynced.
For retry-safe note creation, send a stable Idempotency-Key header to POST /api/v1/notes. The existing idempotencyKey body field remains supported and must match the header when both are present. New idempotent note responses include an operationId; use GET /api/v1/operations/:id with notes:read to inspect recovery status after a timeout.
Read the current delivery state with GET /api/v1/article-schedules/:id or GET /api/v1/notes/:id. Status responses are ownership-scoped and never cached. Integrations can validate a stored credential without scheduling content through GET /api/v1/auth/check.
Saved replies use /api/v1/reader-reply-drafts: GET lists, POST creates; GET/PATCH/DELETE on an id reads, edits or dismisses; POST to its /send endpoint publishes only after review. Reads require activity:read, writes activity:write. Edits and send require expectedUpdatedAt; DELETE takes it in the query. Mobile activity detail includes read-only readerActivities for the selected Note’s Inbox comments, with intent and pendingReplyDraft summaries. The paginated publishing-history list does not include reader summaries.
Reader activity is available through GET /api/v1/reader-activities with activity:read. Use POST /api/v1/reader-activities/:id/replies to reply to an owned comment and PATCH /api/v1/reader-activities/:id to move an item between Inbox and History; both require activity:write. The matching MCP tools are list_reader_activities,reply_to_reader_activity, and update_reader_activity. For review before publication, use create_reader_reply_draft, update_reader_reply_draft,list_reader_reply_drafts, and send_reader_reply_draft. Edits and sends require the draft’s updatedAt as expectedUpdatedAt. A SENDING result is unconfirmed. Recovery is app-only: open Activity in Narrareach, check reply status and the provider thread, then confirm the reply did not post.
Threads notes may include one optional threadsTopicTag through either schedule_note or POST /api/v1/notes. Include THREADS in platforms. The topic is limited to 50 characters and cannot contain periods, ampersands, or line breaks; it is stored only on the Threads destination when a note targets multiple platforms.
Notes may also include an optional firstReply through schedule_note or POST /api/v1/notes. Narrareach applies each destination's own length rules—including X weighted characters—and reports where the reply was accepted or omitted. A reply that cannot be used never cancels the root note.
Note character limits are Bluesky 300, Threads 500, LinkedIn 3,000, and X 25,000 weighted characters (posted as a thread); Substack and the other destinations have none. With schedule_note or POST /api/v1/notes, pass platformVersions, such as { "BLUESKY": "..." }, to supply text that fits a platform. A version that is still over its limit is rejected before anything is scheduled. A platform without a version gets an automatic cut at a sentence break. Every platform that posts different text from the note is listed in adjustedPlatforms with the exact text, and an automatic cut also adds a warning to relay to the user.
Create
POST /api/v1/articles creates or schedules an existing draft.
Move
PATCH /api/v1/article-schedules/:id changes the queued time.
Read
GET /api/v1/article-schedules/:id returns the current state.
Cancel
DELETE /api/v1/article-schedules/:id cancels a queued article.
curl -X POST https://www.narrareach.com/api/v1/articles \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "My full article",
"subtitle": "Optional subtitle",
"contentHtml": "<p>Free preview.</p>[[PAID_SECTION]]<p>Paid section.</p>",
"platforms": ["SUBSTACK"],
"publication": "@theainewsroom",
"scheduledFor": "2026-12-01T14:00:00.000Z",
"timezone": "America/New_York",
"sendToNewsletter": true,
"paywallMarker": "[[PAID_SECTION]]",
"addSearchMetadata": true,
"idempotencyKey": "article-2026-12-01-001"
}'
curl \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
"https://www.narrareach.com/api/v1/linkedin/article-destinations"
# Then list newsletters for one returned author:
curl \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
"https://www.narrareach.com/api/v1/linkedin/article-destinations?authorUrn=urn%3Ali%3Afsd_company%3A110374957"
curl \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
"https://www.narrareach.com/api/v1/medium/publications"
Schedule Medium article to a publication
curl -X POST https://www.narrareach.com/api/v1/articles \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "My Medium story",
"contentHtml": "<p>Full article body.</p>",
"platforms": ["MEDIUM"],
"mediumPublicationId": "the_id_from_list_medium_publications",
"mediumNotifyFollowers": false,
"scheduledFor": "2026-12-01T14:00:00.000Z",
"timezone": "America/New_York"
}'
curl -X POST https://www.narrareach.com/api/v1/articles \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Article with video",
"contentHtml": "<p>Watch the walkthrough:</p>{{media:1}}",
"media": [{
"kind": "video",
"sourceType": "url",
"url": "https://cdn.example.com/walkthrough.mp4",
"mimeType": "video/mp4",
"fileName": "walkthrough.mp4"
}],
"platforms": ["SUBSTACK"],
"publication": "@theainewsroom",
"scheduledFor": "2026-07-01T14:00:00.000Z",
"timezone": "America/New_York"
}'
curl -X PATCH https://www.narrareach.com/api/v1/article-schedules/scheduled_post_id \
-H "Authorization: Bearer $NARRAREACH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"scheduledFor": "2026-07-02T14:00:00.000Z",
"timezone": "America/New_York"
}'
REST API
Every REST endpoint
The list below is generated from /openapi.json, which holds the request and response schemas. Each operation needs one of the scopes shown.
POST /api/v1/transcripts (research:write) transcribes a YouTube video, podcast episode or feed, Apple Podcasts link, audio link, or uploaded file. Long audio returns 202 with a transcriptId; poll GET /api/v1/transcripts/:id (research:read or research:write) until it returns 200. GET /api/v1/topics lists timely topic suggestions for the writer's pillars; when emptyReason is refreshing, call again after Retry-After. Both share a per-user rate limit with MCP and can return 429 RESEARCH_RATE_LIMITED.
POST /api/v1/article-briefs (research:write) plans 3 or 5 long-form articles from timely topics, the writer's profile, or a topic you send, each with an outline and evidence. POST /api/v1/article-briefs/:id/draft has Narrareach write one into a full draft in the writer's voice, saved to their Drafts; poll GET /api/v1/article-briefs/:id until status is READY. Drafts count toward a monthly allowance (8 on Revenue Writer, 30 on Full Agentic).
GET /api/v1/stats/outcomes (notes:read) returns stored Stats outcomes for a period, the engagement peak with its basis and New York benchmarkHour / benchmarkWeekday, and the latest audience snapshot. A metric that was not measured is null, not 0.
When an article response asks for Substack verification, POST /api/v1/substack/verification (articles:write) checks status, requests the owner's code, and completes or cancels it. Pass the returned scheduledPostId on each action, then poll the same article schedule.
To move an already scheduled Threads, Facebook, TikTok, Pinterest, X or Instagram Note to another connected account, send { "accountId": "..." } to POST /api/v1/notes/:id/social-account with an id from GET /api/v1/social-accounts (or GET /api/v1/instagram/destinations). It is refused with SOCIAL_ACCOUNT_NOT_CHANGEABLE once the Note has been sent or attempted.
Reader reply drafts live at /api/v1/reader-reply-drafts: create a draft, review it, then send it with POST /api/v1/reader-reply-drafts/:id/send. A 409 DELIVERY_UNCONFIRMED means the outcome is unknown; check the thread before doing anything else.
GET /api/v1/notes/:id/versions (notes:read) lists a Note and its linked article with their published links; POST on the same path (articles:write) creates that article from the Note, or returns the existing one. GET and PUT /api/v1/notes/hashtag-sets (notes:read and notes:write) read and replace the saved hashtag sets, up to 20 named sets of up to 30 hashtags. These two endpoints return errors as { "error": "...", "code": "..." }, where error is a message and code appears only for token failures.
| Endpoint | What it does | Scope |
|---|---|---|
| GET /api/v1/reader-reply-drafts | List reply drafts | activity:read |
| POST /api/v1/reader-reply-drafts | Create a reply draft | activity:write |
| GET /api/v1/reader-reply-drafts/{id} | Read a reply draft and context | activity:read |
| PATCH /api/v1/reader-reply-drafts/{id} | Edit a pending reply draft | activity:write |
| DELETE /api/v1/reader-reply-drafts/{id} | Dismiss a pending reply draft | activity:write |
| POST /api/v1/reader-reply-drafts/{id}/send | Send an approved reply draft | activity:write |
| POST /api/v1/notes/quote-preview | Preview a Note quote | notes:read |
| GET /api/v1/auth/check | Validate an automation token | any |
| POST /api/v1/notes | Create or schedule Notes | notes:write |
| GET /api/v1/notes/{id} | Get a Note | notes:read |
| PATCH /api/v1/notes/{id} | Update a Note | notes:write |
| DELETE /api/v1/notes/{id} | Delete a Note | notes:write |
| GET /api/v1/notes/{id}/versions | List a Note's linked versions | notes:read |
| POST /api/v1/notes/{id}/versions | Create or reopen the article for a Note | articles:write |
| GET /api/v1/notes/hashtag-sets | List hashtag sets | notes:read |
| PUT /api/v1/notes/hashtag-sets | Replace hashtag sets | notes:write |
| POST /api/v1/articles | Schedule an article | articles:write |
| POST /api/v1/substack/verification | Confirm your Substack connection | articles:write |
| GET /api/v1/linkedin/destinations | List LinkedIn Note destinations | notes:write |
| POST /api/v1/notes/{id}/social-account | Change a scheduled Note's account | notes:write |
| GET /api/v1/social-accounts | List social accounts for Notes | notes:write |
| GET /api/v1/instagram/destinations | List Instagram Note destinations | notes:write |
| GET /api/v1/linkedin/article-destinations | List LinkedIn Article destinations | articles:write |
| GET /api/v1/medium/publications | List Medium publications | articles:write |
| GET /api/v1/article-schedules/{id} | Get an article schedule | articles:write |
| PATCH /api/v1/article-schedules/{id} | Reschedule an article | articles:write |
| DELETE /api/v1/article-schedules/{id} | Cancel an article schedule | articles:write |
| GET /api/v1/operations/{id} | Get Note operation state | notes:read |
| GET /api/v1/conversations | List direct-message conversations | activity:read |
| GET /api/v1/conversations/{id} | Read a direct-message conversation | activity:read |
| GET /api/v1/conversations/{id}/reply-drafts | Read a conversation's reply draft and reply window | activity:read |
| POST /api/v1/conversations/{id}/reply-drafts | Draft a direct-message reply | activity:write |
| GET /api/v1/conversation-reply-drafts/{id} | Read a direct-message reply draft | activity:read |
| PATCH /api/v1/conversation-reply-drafts/{id} | Edit a direct-message reply draft | activity:write |
| POST /api/v1/conversation-reply-drafts/{id}/send | Send an approved direct-message reply | activity:write |
| POST /api/v1/conversation-reply-drafts/{id}/dismiss | Dismiss a direct-message reply draft | activity:write |
| POST /api/v1/conversation-reply-drafts/{id}/release | Return an unconfirmed reply to review | activity:write |
| GET /api/v1/reader-activities | List reader activity | activity:read |
| PATCH /api/v1/reader-activities/{id} | Triage reader activity | activity:write |
| POST /api/v1/reader-activities/{id}/replies | Reply to reader activity | activity:write |
| POST /api/v1/transcripts | Get a transcript | research:write |
| GET /api/v1/topics | List topic suggestions | research:read or research:write |
| GET /api/v1/article-briefs | List article briefs | research:read or research:write |
| POST /api/v1/article-briefs | Generate article briefs | research:write |
| GET /api/v1/article-briefs/{id} | Get an article brief | research:read or research:write |
| POST /api/v1/article-briefs/{id}/draft | Queue an article draft | research:write |
| GET /api/v1/transcripts/{id} | Get transcript status | research:read or research:write |
| GET /api/v1/articles/stats | List article stats and clicked links | notes:read |
| GET /api/v1/stats/outcomes | Get Stats insights | notes:read |
Error codes
Branch on error.code. Warnings arrive in a successful response's warnings array, not as an error. New codes may be added.
UNAUTHORIZED401 No bearer token was sent. (All operations)INVALID_TOKEN401 The token is malformed or unknown. (All operations)TOKEN_REVOKED401 The token was revoked. Create a replacement. (All operations)TOKEN_EXPIRED401 The token has passed its expiry. (All operations)TOKEN_MISSING_SCOPE403 The token lacks every scope the operation accepts. (All operations)PAYMENT_REQUIRED402 The account has no active subscription. (All operations)UPGRADE_REQUIRED402 The account has no paid plan, so the REST API is unavailable. POST /api/v1/articles also returns it with 403 when a paid article is sent on a plan without paid newsletter publishing. (All operations)WORKSPACE_ROLE_FORBIDDEN403 The token user is not allowed to act for this workspace. (Owner-only operations)VALIDATION_ERROR400 The request failed validation; error.details lists the fields. (Operations with a request body or query)NOT_FOUND404 The resource does not exist or is not owned by the token user. (Operations on an id)IDEMPOTENCY_IN_PROGRESS409 A request with this idempotency key is still processing. (POST /api/v1/notes, POST /api/v1/articles)IDEMPOTENCY_CONFLICT409 The idempotency key was used with a different request body. (POST /api/v1/notes, POST /api/v1/articles)IDEMPOTENCY_ERROR409 The idempotency key could not be reserved. Retry with the same key. (POST /api/v1/notes, POST /api/v1/articles)INVALID_IDEMPOTENCY_KEY400 The Idempotency-Key header is longer than 200 characters. (POST /api/v1/notes)INTERNAL_ERROR500 The request could not be completed. Retry once, then contact support with the error code. (All operations)INVALID_SCHEDULE400 scheduledFor is missing, invalid, or not in the future. (Note and article scheduling)INVALID_PLATFORM_VERSION400 A platformVersions entry is for an unselected platform or over its character limit. (POST /api/v1/notes)PLATFORM_NOT_READY409 A selected platform is not connected or not ready. (POST /api/v1/notes, POST /api/v1/articles)SOCIAL_ACCOUNT_INVALID400 socialAccountIds names a platform that takes no account choice or is not selected, or the Note's platform has no account to choose. (POST /api/v1/notes, POST /api/v1/notes/{id}/social-account)SOCIAL_ACCOUNT_NOT_FOUND404 The accountId is not one of the writer's connected accounts for that platform. (POST /api/v1/notes, POST /api/v1/notes/{id}/social-account)SOCIAL_ACCOUNT_CHOICE_REQUIRED409 Several accounts are connected with no default. Name one in socialAccountIds. (POST /api/v1/notes)SOCIAL_ACCOUNT_NOT_CHANGEABLE409 The Note was already sent or attempted. (POST /api/v1/notes/{id}/social-account)SOCIAL_ACCOUNT_DUPLICATE409 Another scheduled version of the same draft already goes to that account. (POST /api/v1/notes/{id}/social-account)SOCIAL_ACCOUNT_CHANGE_FAILED500 The account could not be changed. Read the Note before retrying. (POST /api/v1/notes/{id}/social-account)INSTAGRAM_ACCOUNT_UPGRADE_REQUIRED409 The Instagram account is not included in the plan. (POST /api/v1/notes, POST /api/v1/notes/{id}/social-account)LINKEDIN_DESTINATION_REQUIRED409 Several LinkedIn destinations exist and none can be chosen safely. Send linkedInAccountId. (POST /api/v1/notes)SUBSTACK_PUBLICATION_REQUIRED400 Several Substack publications or profiles are connected. Send publication or substackConnectionId. (POST /api/v1/notes, POST /api/v1/articles)SUBSTACK_PUBLICATION_AMBIGUOUS400 publication matched more than one connected publication. (POST /api/v1/notes, POST /api/v1/articles)SUBSTACK_PUBLICATION_NOT_FOUND400 publication or substackConnectionId names no connected publication. Reader activity operations return it with 404. (POST /api/v1/notes, POST /api/v1/articles, reader activity and reply-draft operations)SUBSTACK_PUBLICATION_CONFLICT400 publication, substackConnectionId and metadata name different publications. (POST /api/v1/notes, POST /api/v1/articles)INVALID_SUBSTACK_PUBLICATION_SELECTION400 publication or substackConnectionId was sent without SUBSTACK in platforms. (POST /api/v1/notes)SUBSTACK_PROFILE_CONFIRMATION_REQUIRED409 The Substack profile for the chosen publication must be confirmed in Narrareach before scheduling. (POST /api/v1/articles)SUBSTACK_NOTE_PROFILE_RECONNECT_REQUIRED409 The publication is signed in as a different Substack profile than its Notes come from. Reconnect it as that profile, then retry. (POST /api/v1/notes)SUBSTACK_REAUTHENTICATION_REQUIRED409 The Substack owner must confirm a code with POST /api/v1/substack/verification. (POST /api/v1/articles, PATCH /api/v1/article-schedules/{id})PLATFORM_SESSION_REFRESH_REQUIRED409 A connection sync is pending. New article input is saved (saved: true, draftId); sync the platform, then retry with that draft. (POST /api/v1/articles, PATCH /api/v1/article-schedules/{id})INVALID_THREADS_TOPIC_TAG400 threadsTopicTag is not text, is over 50 characters, or contains a period, ampersand or line break. (POST /api/v1/notes)THREADS_TOPIC_TAG_REQUIRES_THREADS400 threadsTopicTag was sent without THREADS in platforms. (POST /api/v1/notes)INVALID_IMAGE_URL400 An image is not a public HTTPS image URL or a valid image data URI. (POST /api/v1/notes)MEDIA_REQUIRED400 A selected platform requires at least one image or video. (POST /api/v1/notes)UNSUPPORTED_MEDIA_TYPE400 A PDF carousel was sent to a platform other than LinkedIn. (POST /api/v1/notes)INVALID_REQUEST400 instagramDestinations was sent without INSTAGRAM in platforms. (POST /api/v1/notes)INVALID_INSTAGRAM_DESTINATIONS400 instagramDestinations must name up to five different accounts with valid captions. (POST /api/v1/notes)INSTAGRAM_ACCOUNT_UNAVAILABLE400 An Instagram destination is not one of the writer's connected accounts. (POST /api/v1/notes)INSTAGRAM_DESTINATION_DUPLICATE409 The Note is already scheduled for that Instagram account. (POST /api/v1/notes)SCHEDULED_VERSION_TIME_CHANGED409 The Note's scheduled time changed during the request. Read it again, then retry. (POST /api/v1/notes)SCHEDULED_STACK_CHANGED409 The Note's scheduled versions changed during the request. Read it again, then retry. (POST /api/v1/notes)IDEMPOTENCY_KEY_REUSED409 The key was already used for a different request. Use a new key. (POST /api/v1/notes, POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)LINKEDIN_ACCOUNT_REQUIRED400 A LinkedIn Company Page was named without linkedInAccountId. (POST /api/v1/notes)LINKEDIN_ACCOUNT_UNAVAILABLE409 The writer cannot post as the named LinkedIn account; 404 when it is not connected. (POST /api/v1/notes)LINKEDIN_ORGANIZATION_INVALID400 linkedInOrganizationUrn is not a LinkedIn organization URN. (POST /api/v1/notes)LINKEDIN_ORGANIZATION_UNAVAILABLE404 The LinkedIn account cannot post to that Company Page. (POST /api/v1/notes)LINKEDIN_DESTINATIONS_UNAVAILABLE502 LinkedIn destinations could not be loaded. Retry once, then reconnect LinkedIn. (POST /api/v1/notes, GET /api/v1/linkedin/destinations, GET /api/v1/linkedin/article-destinations)INSTAGRAM_DESTINATIONS_UNAVAILABLE502 Instagram destinations could not be loaded. Retry once. (GET /api/v1/instagram/destinations)SOCIAL_ACCOUNTS_UNAVAILABLE502 Connected accounts could not be loaded. Retry once. (GET /api/v1/social-accounts)NOT_RESCHEDULABLE409 Only pending or failed Notes can be rescheduled. (PATCH /api/v1/notes/{id})NATIVE_SUBSTACK_RESCHEDULE_UNSUPPORTED409 A Note scheduled natively on Substack cannot be rescheduled through the API. (PATCH /api/v1/notes/{id})SCHEDULE_CHANGED409 The Note changed during the request. Read it again, then retry. (PATCH /api/v1/notes/{id})NOT_DELETABLE409 Published or posting Notes cannot be deleted through the API. (DELETE /api/v1/notes/{id})UNCERTAIN_DELETE_CONFIRMATION_REQUIRED409 The Note may already be published. Pass confirm_uncertain=true to remove only the Narrareach record. (DELETE /api/v1/notes/{id})UNSUPPORTED_PLATFORM400 A platform does not take articles. (POST /api/v1/articles)INVALID_MEDIA400 An article image or video could not be used. (POST /api/v1/articles)INVALID_PAYWALL_MARKER400 The paywall marker is missing, repeated or misplaced. (POST /api/v1/articles, PATCH /api/v1/article-schedules/{id})PLACEMENT_TEXT_REMAINS400 The article still contains placement text such as "[PAYWALL HERE. REMOVE THIS TEXT.]", which would be published as written. Remove it, or replace it with native markup. (POST /api/v1/articles, PATCH /api/v1/article-schedules/{id})LINKEDIN_ARTICLE_LEAD_TIME_REQUIRED400 A LinkedIn article is scheduled too soon; error.details.earliestScheduledFor gives the earliest time. (POST /api/v1/articles)SCHEDULE_CONFLICT409 This draft is already scheduled or being scheduled. (POST /api/v1/articles)SCHEDULE_NOT_EDITABLE409 The article schedule can no longer be changed. (PATCH /api/v1/article-schedules/{id}, DELETE /api/v1/article-schedules/{id})MEDIUM_RECONNECT_REQUIRED409 Reconnect Medium, then retry with refresh=1. (GET /api/v1/medium/publications)MEDIUM_ACCOUNT_CHANGED409 Medium is signed in to a different account than the one connected. Reconnect Medium, then retry with refresh=1. (GET /api/v1/medium/publications)MEDIUM_SIGN_IN_UNCONFIRMED409 The Medium sign-in could not be confirmed. Reconnect Medium, then retry with refresh=1. (GET /api/v1/medium/publications)MEDIUM_PUBLICATIONS_BUSY429 Medium is busy. Wait a minute, then retry. (GET /api/v1/medium/publications)MEDIUM_PUBLICATIONS_UNAVAILABLE502 Medium publications could not be refreshed. (GET /api/v1/medium/publications)VIDEO_REQUIRES_SUBSTACK_ONLY422 Article video was sent with a destination other than Substack. (POST /api/v1/articles)VIDEO_PROCESSING503 The article video is not ready yet. Check the schedule instead of resubmitting. (POST /api/v1/articles)VIDEO_DISABLED503 Article video publishing is temporarily unavailable. (POST /api/v1/articles)CONTENT_OUT_OF_SYNC409 Saved structured content and HTML disagree about their videos. Re-save the draft and retry. (POST /api/v1/articles)not_connected409 The Substack publication is not connected or must be resynced; 404 when it is not one of the writer's publications. (POST /api/v1/substack/verification)cooldown429 A code was requested less than a minute ago. Wait Retry-After seconds. (POST /api/v1/substack/verification)publishing_cooldown429 Substack is briefly limiting the chosen article's scheduling. The code is kept; confirm it after Retry-After seconds. (POST /api/v1/substack/verification)hourly_limit429 Too many codes were requested this hour. Wait Retry-After seconds. (POST /api/v1/substack/verification)in_progress409 Another verification step is running. Check status, then continue. (POST /api/v1/substack/verification)expired409 The code request has ended. Start a new one. (POST /api/v1/substack/verification)invalid_code400 The request or code is malformed; 409 when the code request belongs to a different article. (POST /api/v1/substack/verification)code_rejected400 Substack did not accept the code. Ask the user to check it; never resubmit automatically. (POST /api/v1/substack/verification)unsupported_method409 Substack wants this confirmed on its own site. Publish once from Substack, then try again. (POST /api/v1/substack/verification)unavailable502 Substack could not send or confirm the code. Check status before trying again. (POST /api/v1/substack/verification)busy503 The Substack connection is updating. Try again in a moment. (POST /api/v1/substack/verification)ACTIVITY_NOT_FOUND404 The reader activity does not exist or is not the writer's. (Reader activity and reply-draft operations)INVALID_ACTIVITY_CURSOR422 The cursor no longer points to an available page. Start from the first page. (GET /api/v1/reader-activities)ACTIVITY_LEDGER_NOT_READY503 Reader activity is not available yet. (Reader activity and reply-draft operations)ACTIVITY_LIST_FAILED500 Reader activity could not be loaded. (GET /api/v1/reader-activities)CONVERSATION_NOT_FOUND404 The conversation does not exist or is not the writer's. (GET /api/v1/conversations/{id})INVALID_CONVERSATION_CURSOR400 The cursor is not valid. Start again without it. (GET /api/v1/conversations, GET /api/v1/conversations/{id})WINDOW_CLOSED422 The platform no longer takes a reply in this conversation (Instagram and Facebook: 7 days after the reader's last message; TikTok: 48 hours). (POST /api/v1/conversation-reply-drafts/{id}/send)SUBSTACK_CHECK_REQUIRED422 Substack sent a verification code. Enter it in Narrareach, then send again. (POST /api/v1/conversation-reply-drafts/{id}/send)DM_REPLY_UNAVAILABLE500 The reply could not be handled right now. (/api/v1/conversations/{id}/reply-drafts, /api/v1/conversation-reply-drafts/*)GROUP_CHAT_SUGGESTION_OFF422 Group chats get no suggestion. Send text to draft the writer's own reply. (POST /api/v1/conversations/{id}/reply-drafts)CONVERSATIONS_UNAVAILABLE500 Direct messages could not be loaded. (GET /api/v1/conversations, GET /api/v1/conversations/{id})ACTIVITY_UPDATE_FAILED500 Reader activity could not be updated. (PATCH /api/v1/reader-activities/{id})ACTIVITY_REPLY_FAILED500 The reply could not be published. Check the provider thread before any retry. (POST /api/v1/reader-activities/{id}/replies)NOT_REPLYABLE422 This reader activity cannot be replied to. (POST /api/v1/reader-activities/{id}/replies, reply-draft operations)ACTIVITY_ALREADY_REPLIED409 A reply to this comment is already in progress or complete. (POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)REPLY_IN_PROGRESS409 A reply to this comment is awaiting confirmation. (POST /api/v1/reader-activities/{id}/replies, reply-draft operations)IDEMPOTENCY_KEY_CONFLICT409 The Idempotency-Key header and the idempotencyKey field differ. (POST /api/v1/reader-activities/{id}/replies)DRAFT_NOT_FOUND404 The reply draft does not exist or is not the writer's. (Reply-draft operations on an id)DRAFT_CHANGED409 expectedUpdatedAt is stale. Read the draft again. (PATCH, DELETE /api/v1/reader-reply-drafts/{id}, POST /api/v1/reader-reply-drafts/{id}/send)DRAFT_PARENT_CHANGED409 The comment the draft replies to changed. Read the draft again. (Reply-draft operations on an id)DRAFT_NOT_EDITABLE409 Only pending drafts can be edited or dismissed. (PATCH, DELETE /api/v1/reader-reply-drafts/{id})DRAFT_NOT_SENDABLE409 The draft is not pending review. (POST /api/v1/reader-reply-drafts/{id}/send)GENERATION_RATE_LIMITED429 The reply-draft generation budget is spent (text omitted). Wait, or send text. (POST /api/v1/reader-reply-drafts)GENERATION_UNAVAILABLE503 The generation allowance could not be checked. Retry shortly. (POST /api/v1/reader-reply-drafts)GENERATION_QUALITY_FAILED422 No usable draft was generated. Send text or try again. (POST /api/v1/reader-reply-drafts)REPLY_DRAFT_UNAVAILABLE500 The reply draft is unavailable right now. (Reply-draft operations)REPLY_TOO_LONG422 The reply is longer than the social platform accepts (TikTok 150, Bluesky 300, Threads 500, LinkedIn 1,250, Instagram 2,200 characters). (POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)ACCOUNT_RECONNECT_REQUIRED409 The social account that published the post must be reconnected before replying. (POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)REPLY_NOT_DELIVERED409 The provider write did not succeed. (POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)DELIVERY_UNCONFIRMED409 The outcome is unknown. Check the provider thread before any recovery; never retry with a new key. (POST /api/v1/reader-activities/{id}/replies, POST /api/v1/reader-reply-drafts/{id}/send)TRANSCRIPT_UNSUPPORTED_URL422 The link cannot be transcribed (for example Spotify). (Transcripts)TRANSCRIPT_NOT_FOUND404 The video, episode or transcript was not found. (Transcripts)TRANSCRIPT_EMPTY422 The source has no speech to transcribe. (Transcripts)TRANSCRIPT_TOO_LONG422 The audio is over 3 hours long. (Transcripts)TRANSCRIPT_PLAN_REQUIRED402 Transcripts need the Revenue Writer plan or above. (Transcripts)TRANSCRIPT_PROVIDER_FAILED502 Transcription failed. Retry in a few minutes; finished parts are kept. (Transcripts)TRANSCRIPT_PROVIDER_UNAVAILABLE503 YouTube transcripts are unavailable right now. Retry later; it did not use your daily transcript allowance. (Transcripts)TOPICS_UNAVAILABLE500 Topic suggestions are unavailable. Retry in a moment. (GET /api/v1/topics)DAILY_LIMIT_REACHED429 The writer has generated the most briefs for today (10 runs). Try again after midnight UTC. (POST /api/v1/article-briefs)MONTHLY_ALLOWANCE_USED429 This month's article drafts are used. They reset on the 1st (UTC). (POST /api/v1/article-briefs/{id}/draft)RESEARCH_RATE_LIMITED429 The per-user research budget shared with MCP is spent. Wait Retry-After seconds. (POST /api/v1/transcripts, GET /api/v1/topics, POST /api/v1/article-briefs, POST /api/v1/article-briefs/{id}/draft)RESEARCH_RATE_LIMIT_UNAVAILABLE503 The allowance could not be checked. Retry after Retry-After seconds. (POST /api/v1/transcripts, GET /api/v1/topics)TRANSCRIPT_QUOTA_EXCEEDED429 The daily transcript allowance is used up; it resets at midnight UTC. (Transcripts)QUOTE_PREVIEW_RATE_LIMITED429 Too many quote previews. Wait Retry-After seconds. (POST /api/v1/notes/quote-preview)QUOTE_PREVIEW_UNAVAILABLE503 Quote preview is temporarily unavailable. (POST /api/v1/notes/quote-preview)UNSUPPORTED_URL422 Send a public Substack Note link or post link. (POST /api/v1/notes/quote-preview)WORKSPACE_NOT_FOUND404 No workspace is available. (POST /api/v1/notes/quote-preview)WORKSPACE_FORBIDDEN403 The token user has no access to workspaceId. (POST /api/v1/notes/quote-preview)PUBLICATION_FORBIDDEN403 substackConnectionId is not available in this workspace. (POST /api/v1/notes/quote-preview)ARTICLE_STATS_READ_FAILED500 Article stats could not be loaded. (GET /api/v1/articles/stats)STATS_INSIGHTS_READ_FAILED500 Stats insights could not be loaded. (GET /api/v1/stats/outcomes)PUBLICATION_NOT_ALLOWED403 The publication is not available to the token user. (GET /api/v1/stats/outcomes)INVALID_TIMEZONE400 The time zone used for the range is not a valid IANA time zone. (GET /api/v1/stats/outcomes)INVALID_PERIOD400 period is not supported. (GET /api/v1/stats/outcomes)INVALID_DATE_RANGE400 The date range is invalid. (GET /api/v1/stats/outcomes)DATE_RANGE_TOO_LARGE400 The date range is too long. (GET /api/v1/stats/outcomes)DATE_RANGE_NOT_COMPLETE400 to must be before today. (GET /api/v1/stats/outcomes)INVALID_COMPARISON400 comparison must be previous_period. (GET /api/v1/stats/outcomes)X_CASHTAG_LIMIT400 A Note going to X has more than one cashtag ($SYMBOL) in one post. X refuses such posts, so the Note is not created. Keep one cashtag in the X version (platformVersions.X) or leave X out. (POST /api/v1/notes)SUBSTACK_LINE_BREAKSwarning A Note going to Substack has lines written directly under each other. Substack shows each line as its own paragraph; join them or use a bulleted list to keep them together. (POST /api/v1/notes)SUBSTACK_SESSION_REFRESH_REQUIREDwarning The Note is scheduled, but the Substack session must be resynced so it can publish on time. (POST /api/v1/notes)LINKEDIN_SESSION_REFRESH_REQUIREDwarning The LinkedIn article is scheduled, but the writer must sign in to LinkedIn or resync LinkedIn Articles so it can publish on time. The message is in warnings; the structured entry (platform, code, message, action RESYNC_LINKEDIN_ARTICLES) is in connectionWarnings. (POST /api/v1/articles)
Schedule Substack posts and articles with the Narrareach API
Use Narrareach’s article scheduling API to publish a newsletter article at a chosen time, set its free preview, and include a native subscribe button. The same publishing workflow is available through the Narrareach MCP connector in ChatGPT or Claude. These are Narrareach endpoints for your connected publications—not endpoints supplied by Substack.
This guide covers long-form articles. For short Substack Notes, use schedule_note or POST /api/v1/notes instead. A paid article’s access setting, its paywall position, and its email-delivery setting are separate decisions.
Before your first article request
- Connect the intended publication in Narrareach and confirm it is ready. API access does not connect an account automatically.
- For REST, use an account with API access and an automation token with
articles:write. Send it asAuthorization: Bearer <token>. Keep it on your server, never in client-side code or shared examples. - For ChatGPT or Claude, use the authorized Narrareach connector. You do not need to paste an API token into the conversation.
- Choose the publication, a future publishing time and timezone, reader access, and whether to send email. Confirm these choices with the writer before scheduling.
Send publication as a connected publication name, handle or URL. Narrareach can select a sole active Substack publication when omitted; when there are multiple possibilities, choose explicitly. Sending it explicitly is the clearest option for repeatable automations. Check plan access and the OpenAPI reference for the current endpoint requirements.
Free preview, paid subscribers and newsletter email
Public article
Use isPaidContent: false without a paywall divider. Adding a subscribe button does not make an article paid.
Free and paid subscribers (Freewall)
Use freewall: true with Substack. Place <hr data-type="paywall" data-access="subscribers"> where the public preview ends, or use a single marker. Without a divider, the whole article requires a free or paid subscription. Do not combine this with isPaidContent: true.
Paid article with a free preview
Put <hr data-type="paywall"> after the free portion. Narrareach treats an explicit divider as paid access, even if isPaidContent was omitted or false. Select only Substack for this version.
Paid audience without a custom divider
Use isPaidContent: true. This selects paid access; it does not choose a custom preview boundary for you. Include a divider when you want a specific free excerpt.
Email delivery
sendToNewsletter defaults to true for a new article. Set it to false when you want to publish without sending the newsletter email. Adding a paywall does not change that choice.
Audience-specific sections preserve both alternatives. Use a div with data-dynamic-content="true" and data-dynamic-audiences="paid_sub", containing data-dynamic-content-match="true" and data-dynamic-content-else="true" blocks. Supported conditions are non_sub, free_sub, paid_sub, and founding_sub, separated by commas. Subscriber-tag targeting must be published in Substack. Unsupported imported blocks stay there so their content is not lost.
A Substack paywall is not a portable access control for LinkedIn, Medium or X. Create a separate public excerpt or public article for those destinations. Do not send protected text to another platform assuming the Substack divider will protect it there.
Add a subscribe button with a caption
Place this HTML where the reader should see the subscription invitation. Use your own caption and escape quotation marks and other special characters in attribute values.
<div data-type="button" data-kind="subscribeCaption"
data-text="Subscribe"
data-caption="Get the complete guide and future editions."></div>
For a button without a caption, use data-kind="subscribe" and omit data-caption. An ordinary link remains a link; a shortened subscription URL does not automatically become a native subscribe button. A button and a paywall serve different purposes: one invites a subscription, the other sets where paid content begins.
Example: schedule a paid Substack post without sending email
Send this JSON to POST https://www.narrareach.com/api/v1/articles with your authorization header and Content-Type: application/json. Replace the example publication and date. The timestamp’s Z means UTC: 14:00 UTC is 09:00 in New York on this example date. An explicit UTC offset is also accepted; keep it consistent with your named timezone.
{
"title": "A practical guide for newsletter writers",
"contentHtml": "<p>This introduction is the free preview.</p><div data-type=\"button\" data-kind=\"subscribeCaption\" data-text=\"Subscribe\" data-caption=\"Get the complete guide and future editions.\"></div><hr data-type=\"paywall\"><p>This section is for paid subscribers.</p>",
"platforms": [
"SUBSTACK"
],
"publication": "@your-publication",
"scheduledFor": "2026-12-01T14:00:00Z",
"timezone": "America/New_York",
"isPaidContent": true,
"sendToNewsletter": false,
"idempotencyKey": "newsletter-guide-december-01"
}
If your content system uses a custom placeholder, put it once in the article text at the intended boundary and supply the same string as paywallMarker. For example, [[PAID_SECTION]] in contentHtml with paywallMarker: "[[PAID_SECTION]]". Do not place it in a URL or button caption. Native divider HTML is the most direct option.
Read the scheduling response
A newly accepted request returns HTTP 202. The following is an illustrative response; your IDs, status and dates will differ. Save both draftId and every scheduled[].id. A schedule ID identifies a scheduled delivery, not the article draft.
{
"success": true,
"mode": "schedule",
"draftId": "draft_example",
"article": {
"id": "draft_example",
"title": "A practical guide for newsletter writers",
"status": "SCHEDULED"
},
"scheduled": [
{
"id": "schedule_example",
"platforms": [
"SUBSTACK"
],
"status": "PENDING",
"scheduledFor": "2026-12-01T14:00:00.000Z",
"timezone": "America/New_York",
"publishedAt": null,
"error": null
}
],
"idempotencyKey": "newsletter-guide-december-01"
}
Acceptance is not proof of publication. The article summary says SCHEDULED, while a newly queued delivery starts as PENDING. Read GET /api/v1/article-schedules/:id using the returned schedule ID to check delivery state. These article-schedule endpoints use articles:write. Display informational warnings or advisories when present, but do not treat an advisory alone as failure.
Schedule an existing draft, reschedule or cancel
To schedule a saved article, send draftId instead of new title and body fields. This schedules its saved content and audience settings; it is not an edit operation. Review or update the draft first if those settings should change. Do not supply paywallMarker or freewall with an existing draft. In n8n, select “Free and Paid Subscribers (Freewall)” when creating a new article.
{
"draftId": "draft_example",
"platforms": [
"SUBSTACK"
],
"publication": "@your-publication",
"scheduledFor": "2026-12-02T14:00:00Z",
"timezone": "America/New_York",
"idempotencyKey": "existing-draft-december-02"
}
To move an existing schedule, use PATCH /api/v1/article-schedules/:id with scheduledFor and, optionally, timezone. Do not create another schedule just to change the time. To cancel a queued delivery, use DELETE /api/v1/article-schedules/:id. Cancellation is not a way to retract an already-published article; read the current state before taking action.
Schedule a Substack newsletter from ChatGPT or Claude
With the Narrareach connector enabled, describe the result you want in ordinary language. You do not need to write HTML. For example:
Schedule my approved article to @your-publication on December 1 at 9 a.m. New York time. Keep the introduction free and put the paywall before “The complete guide.” Add a subscribe button just before the paywall with the caption “Get the complete guide and future editions.” Publish it without sending an email. Confirm the publication and these choices before scheduling.
The corresponding tool is schedule_article. It uses the same title, HTML content, destination, scheduling and audience fields; the REST idempotencyKey field and REST response envelope are not MCP tool arguments. If the intended boundary is unclear, the assistant should ask which paragraph ends the free preview. Clear placement should not require another formatting question. After scheduling, keep the returned result and use list_scheduled_posts, reschedule_scheduled_item or cancel_scheduled_item to manage it.
Handle errors and retries without duplicate articles
For REST article creation, send a stable idempotencyKey in the JSON body. After a timeout, check the queue and retry the same body with the same key rather than immediately creating a new request. A successful replay may return HTTP 200. If you intentionally change the request, first check whether the earlier schedule exists; then use a new key for the new operation. This article contract is separate from the Notes idempotency header.
For non-success responses, read error.code, error.message, error.resolution and any error.details. Keep useful recovery instructions visible to the writer.
400 · INVALID_PAYWALL_MARKER
Confirm one free-preview boundary. Remove conflicting positions or choose a separate public version for another platform; do not retry unchanged content.
400 · SUBSTACK_PUBLICATION_REQUIRED / SUBSTACK_PUBLICATION_AMBIGUOUS
Supply the exact connected publication name, handle or URL. Do not choose a publication on the writer’s behalf.
400 · VALIDATION_ERROR / INVALID_MEDIA
Check the fields identified by the response, your future publishing time, and the media requirements in the reference.
409 · PLATFORM_NOT_READY / PLATFORM_SESSION_REFRESH_REQUIRED
Reconnect the named platform in Narrareach. If the response includes a saved draftId, keep it and schedule that draft after reconnecting.
409 · CONTENT_OUT_OF_SYNC
Open and save the article in its editor, check the preview, then try scheduling again.
409 · IDEMPOTENCY_IN_PROGRESS
Wait and check the queue. Do not switch keys just to bypass an in-progress request.
409 · IDEMPOTENCY_CONFLICT
That key belongs to different request content. Check the earlier result before submitting an intentionally different request with a new key.
Authentication and access errors require a valid token, the required scope and an eligible account. For rate limits or temporary service errors, follow the returned retry guidance; do not continuously resubmit. Never send tokens, unpublished article bodies or account credentials in a support screenshot.
Next: review the REST endpoint examples, connect ChatGPT, or consult the complete request schemas.
Webhooks
Get notified when a Note publishes or fails
Narrareach can POST a signed JSON event to your HTTPS endpoint, such as a Make custom webhook or an n8n Webhook node, when a scheduled Note publishes or fails. Webhooks are included in Full Agentic Mode.
- Open Settings > Integrations > REST API & webhooks, paste your endpoint URL under Webhooks, and choose Add webhook.
- Copy the signing secret. It is shown once.
- Choose Test to send a
webhook.testevent and confirm the endpoint receives it. The test body carries only a message, not a Note. - Branch on
event:note.publishedornote.failed. The Note is indata.note.
Verify the signature
X-Narrareach-Signature is t=TIMESTAMP,v1=SIGNATURE. Compute an HMAC-SHA256 hex digest of TIMESTAMP.RAW_BODY with your signing secret and compare it with v1.
Retries and duplicates
Respond with a 2xx status within 8 seconds. Failed deliveries are retried, up to 5 attempts in total, so ignore events whose id you have already handled.
Scheduled Notes send events for Substack, LinkedIn, X, Threads, Instagram, Facebook, TikTok, and Pinterest. Notes posted right away through the REST API send events for every platform. Articles do not send webhook events yet, and scheduled Bluesky Notes may not send them, so check their status through the REST API.
Access
Plan and rate limits
Paid plans include MCP access, the REST API, image-capable scheduling, and analytics. Full Agentic Mode adds webhooks for event-driven server-to-server integrations.
MCP limit
Each user gets 120 MCP request units per 10 minutes. A JSON-RPC batch consumes one unit per item in the batch.
Bulk scheduling
This allows a 62-item bulk Notes run plus setup and status calls. For image-heavy batches, keep normal client retry/backoff behavior enabled.
Troubleshooting
Common connection issues
Redirect URI mismatch
Confirm dynamic client registration is enabled. Dynamically registered clients provide their callback during registration. For a manually pre-registered client, add only the exact callback URI supplied by that client at the provider level.
Missing openid scope
ChatGPT requests openid during authorize. If the Clerk OAuth application only allows profile/email, add openid (and usually offline_access) on that OAuth client.
OAuth verification fails
If server logs mention an invalid JWT form, the endpoint is trying to parse an opaque Clerk OAuth credential as a JWT. Validate it through Clerk's OAuth-aware flow instead.
Localhost does not work in hosted clients
Claude, ChatGPT, and Gemini require HTTPS for remote connectors. Use the production URL or expose local development through an HTTPS tunnel.