{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Narrareach Automation API","version":"1.0.0","description":"Scoped REST API for authenticated Narrareach agents and automations. Create tokens in Narrareach settings and grant only the permissions required by the client.","contact":{"name":"Narrareach Support","url":"https://www.narrareach.com/contact"}},"servers":[{"url":"https://www.narrareach.com","description":"Production"}],"externalDocs":{"description":"Connector and API setup","url":"https://www.narrareach.com/api-docs"},"tags":[{"name":"Authentication","description":"Validate a scoped automation token."},{"name":"Notes","description":"Create, read, update, and delete short-form posts."},{"name":"Articles","description":"Schedule and manage long-form article publishing."},{"name":"Operations","description":"Read asynchronous operation state."},{"name":"Stats","description":"Read stored Stats outcomes, engagement peaks, and audience snapshots."},{"name":"Reader Activity","description":"Pull, reply to, and triage Substack reader activity."}],"paths":{"/api/v1/auth/check":{"get":{"tags":["Authentication"],"summary":"Validate an automation token","description":"Returns the permissions attached to a valid token. No particular scope is required.","operationId":"checkAutomationToken","security":[{"scopedBearerToken":[]}],"responses":{"200":{"description":"The token is valid.","content":{"application/json":{"schema":{"type":"object","required":["success","scopes"],"properties":{"success":{"type":"boolean","const":true},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/AutomationScope"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/notes":{"post":{"tags":["Notes"],"summary":"Create or schedule Notes","description":"Creates review-ready short-form posts and either publishes them now or schedules them.","operationId":"createNotes","security":[{"scopedBearerToken":["notes:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotesRequest"}}}},"responses":{"201":{"description":"The Notes were accepted for immediate publishing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotesResponse"}}}},"202":{"description":"The Notes were accepted for scheduled publishing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/notes/{id}":{"get":{"tags":["Notes"],"summary":"Get a Note","description":"Returns one Note owned by the authenticated Narrareach account.","operationId":"getNote","security":[{"scopedBearerToken":["notes:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Notes"],"summary":"Update a Note","description":"Updates editable Note fields before publishing.","operationId":"updateNote","security":[{"scopedBearerToken":["notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNoteRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Notes"],"summary":"Delete a Note","description":"Deletes a Note owned by the authenticated Narrareach account.","operationId":"deleteNote","security":[{"scopedBearerToken":["notes:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/articles":{"post":{"tags":["Articles"],"summary":"Schedule an article","description":"Creates or reuses an article draft and schedules it on the selected long-form platforms.","operationId":"scheduleArticle","security":[{"scopedBearerToken":["articles:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleArticleRequest"}}}},"responses":{"202":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/linkedin/destinations":{"get":{"tags":["Notes"],"summary":"List LinkedIn Note destinations","description":"Lists personal profiles and Company Pages available for Notes. The Settings posting target takes precedence; otherwise, the only available personal profile is the default. Narrareach never guesses among Company Pages.","operationId":"listLinkedInNoteDestinations","security":[{"scopedBearerToken":["notes:write"]}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/linkedin/article-destinations":{"get":{"tags":["Articles"],"summary":"List LinkedIn Article destinations","description":"Lists the signed-in personal profile and administered Company Pages. Pass authorUrn to also list that author’s newsletters.","operationId":"listLinkedInArticleDestinations","security":[{"scopedBearerToken":["articles:write"]}],"parameters":[{"name":"authorUrn","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/medium/publications":{"get":{"tags":["Articles"],"summary":"List Medium publications","description":"Lists the Medium publications the connected account can submit stories to. Pass the returned id as mediumPublicationId on POST /api/v1/articles.","operationId":"listMediumPublications","security":[{"scopedBearerToken":["articles:write"]}],"parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to 1 to check Medium for publication changes instead of using the saved list."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"connected":{"type":"boolean"},"publications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"avatarId":{"type":"string","nullable":true},"canPublish":{"type":"boolean","description":"true publishes directly under the publication; false submits the story for editorial review instead."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/article-schedules/{id}":{"get":{"tags":["Articles"],"summary":"Get an article schedule","description":"Returns the current state of an article publishing schedule.","operationId":"getArticleSchedule","security":[{"scopedBearerToken":["articles:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Articles"],"summary":"Reschedule an article","description":"Changes the publication time for a scheduled article.","operationId":"rescheduleArticle","security":[{"scopedBearerToken":["articles:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleArticleRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Articles"],"summary":"Cancel an article schedule","description":"Cancels a pending article schedule without deleting its draft.","operationId":"cancelArticleSchedule","security":[{"scopedBearerToken":["articles:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/operations/{id}":{"get":{"tags":["Operations"],"summary":"Get Note operation state","description":"Polls the state of an asynchronous Note creation request.","operationId":"getNoteOperation","security":[{"scopedBearerToken":["notes:read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/reader-activities":{"get":{"tags":["Reader Activity"],"summary":"List reader activity","description":"Lists Substack likes, comments, and restacks owned by the authenticated account.","operationId":"listReaderActivities","security":[{"scopedBearerToken":["activity:read"]}],"parameters":[{"name":"state","in":"query","schema":{"type":"string","enum":["inbox","history"],"default":"inbox"}},{"name":"type","in":"query","schema":{"type":"string","enum":["all","like","comment","restack"],"default":"all"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["time","relevance"],"default":"time"}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":191}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"substackConnectionId","in":"query","description":"Optional connected Substack publication id.","schema":{"type":"string","maxLength":191}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReaderActivityListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/reader-activities/{id}":{"patch":{"tags":["Reader Activity"],"summary":"Triage reader activity","description":"Moves an owned reader activity item between Inbox and History.","operationId":"updateReaderActivity","security":[{"scopedBearerToken":["activity:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}},{"name":"substackConnectionId","in":"query","schema":{"type":"string","maxLength":191}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateReaderActivityRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateReaderActivityResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/reader-activities/{id}/replies":{"post":{"tags":["Reader Activity"],"summary":"Reply to reader activity","description":"Publishes a reply to an owned, replyable Substack comment activity and moves it to History.","operationId":"replyToReaderActivity","security":[{"scopedBearerToken":["activity:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Narrareach resource identifier.","schema":{"type":"string","minLength":1}},{"name":"substackConnectionId","in":"query","schema":{"type":"string","maxLength":191}},{"name":"Idempotency-Key","in":"header","description":"Optional retry key. Must match body idempotencyKey when both are sent.","schema":{"type":"string","minLength":1,"maxLength":191}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyToReaderActivityRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyToReaderActivityResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/stats/outcomes":{"get":{"tags":["Stats"],"summary":"Get Stats insights","description":"Returns stored Stats outcomes for a period, including reach, engagement, conversion, publishing rhythm, the honest engagement peak, the other-writers timing benchmark, and the latest audience snapshot. Does not live-fetch Substack. Requires notes:read.","operationId":"getStatsOutcomes","security":[{"scopedBearerToken":["notes:read"]}],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["1d","7d","30d","90d","custom"],"default":"30d"}},{"name":"from","in":"query","description":"Inclusive start date (YYYY-MM-DD). Required when period is custom.","schema":{"type":"string"}},{"name":"to","in":"query","description":"Inclusive end date (YYYY-MM-DD). Required when period is custom.","schema":{"type":"string"}},{"name":"platforms","in":"query","description":"Comma-separated connected platforms to include.","schema":{"type":"string"}},{"name":"contentTypes","in":"query","description":"Comma-separated content types: article, note, social_post.","schema":{"type":"string"}},{"name":"publicationId","in":"query","description":"Optional connected Substack publication id.","schema":{"type":"string","maxLength":191}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsInsightsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"scopedBearerToken":{"type":"http","scheme":"bearer","bearerFormat":"Narrareach automation token","description":"Send `Authorization: Bearer nrr_api_…`. Tokens are user-created and restricted to the operation scopes listed in each Security Requirement Object.","x-available-scopes":{"notes:read":"Read Notes, Note operation state, and stored Stats insights.","notes:write":"Create, update, schedule, publish, and delete Notes.","articles:write":"Create, schedule, reschedule, and cancel articles.","activity:read":"Read connected Substack reader activity.","activity:write":"Reply to and triage connected Substack reader activity.","webhooks:write":"Manage webhook subscriptions in supported automation surfaces."}}},"schemas":{"AutomationScope":{"type":"string","enum":["notes:read","notes:write","articles:write","activity:read","activity:write","webhooks:write"]},"ApiError":{"type":"object","required":["error"],"properties":{"code":{"type":"string","deprecated":true,"description":"Compatibility alias for error.code. New clients should use error.code."},"message":{"type":"string","deprecated":true,"description":"Compatibility alias for error.message. New clients should use error.message."},"resolution":{"type":"string","deprecated":true,"description":"Compatibility alias for error.resolution. New clients should use error.resolution."},"error":{"type":"object","required":["code","message","resolution"],"properties":{"code":{"type":"string","example":"TOKEN_MISSING_SCOPE"},"message":{"type":"string","example":"This API token does not include the notes:write permission."},"resolution":{"type":"string","example":"Create a token with notes:write and retry the request."},"details":{"description":"Optional validation or recovery details."}}}}},"CreateNotesRequest":{"type":"object","required":["content","platforms"],"properties":{"content":{"type":"string","minLength":1,"maxLength":20000},"platforms":{"type":"array","minItems":1,"items":{"type":"string"}},"scheduledFor":{"type":"string","format":"date-time"},"timezone":{"type":"string","example":"America/Toronto"},"mode":{"type":"string","enum":["now","schedule"],"description":"Omit to publish now when scheduledFor is absent, or to schedule when scheduledFor is present."},"idempotencyKey":{"type":"string","maxLength":200},"linkedInAccountId":{"type":"string","description":"LinkedIn account id returned by GET /api/v1/linkedin/destinations. Omit together with linkedInOrganizationUrn to use the Settings default or the only available personal profile. Narrareach never guesses among Company Pages."},"linkedInOrganizationUrn":{"type":"string","description":"Company Page URN returned by GET /api/v1/linkedin/destinations. Requires linkedInAccountId."},"platformVersions":{"type":"object","description":"Text for a selected platform with a character limit (Bluesky 300, Threads 500, LinkedIn 3000, X 25000), keyed by platform. Each must fit as written or the request fails with INVALID_PLATFORM_VERSION. A platform over its limit without a version is shortened automatically and listed in adjustedPlatforms.","additionalProperties":{"type":"string","minLength":1},"example":{"BLUESKY":"A version of the note written to fit 300 characters."}}},"additionalProperties":true},"NotePlatformAdjustment":{"type":"object","description":"A platform that will post other text than the note as written.","required":["platform","label","kind","limit","originalLength","postedLength","text"],"properties":{"platform":{"type":"string","example":"BLUESKY"},"label":{"type":"string","example":"Bluesky"},"kind":{"type":"string","enum":["shortened","written"],"description":"shortened: cut automatically to fit. written: a supplied or saved version."},"limit":{"type":["integer","null"],"example":300},"originalLength":{"type":"integer","example":612},"postedLength":{"type":"integer","example":298},"text":{"type":"string","description":"The exact text the platform will post."}}},"CreateNotesResponse":{"type":"object","required":["success","mode","draftId","adjustedPlatforms","notes"],"properties":{"success":{"type":"boolean"},"mode":{"type":"string","enum":["now","schedule"]},"draftId":{"type":"string"},"adjustedPlatforms":{"type":"array","items":{"$ref":"#/components/schemas/NotePlatformAdjustment"}},"notes":{"type":"array","items":{"type":"object"}}},"additionalProperties":true},"UpdateNoteRequest":{"type":"object","required":["scheduledFor"],"properties":{"scheduledFor":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"additionalProperties":false},"ScheduleArticleRequest":{"type":"object","required":["platforms"],"allOf":[{"anyOf":[{"required":["draftId"]},{"required":["title","contentHtml"]}]},{"anyOf":[{"required":["scheduledFor"]},{"required":["platformSchedules"]}]}],"properties":{"draftId":{"type":"string"},"title":{"type":"string","maxLength":500},"subtitle":{"type":"string","maxLength":500,"description":"Optional article subtitle. Substack delivery omits subtitles over 250 characters and returns a warning; the saved draft remains unchanged."},"contentHtml":{"type":"string","maxLength":250000,"description":"For a native Substack paywall, use <hr data-type=\"paywall\"> at the chosen paragraph boundary. A single {{NARRAREACH_PAYWALL}} in article text is translated automatically; paywallMarker is only needed for custom tokens. If placement is unclear, ask where the free preview ends before scheduling. For a native subscribe block, use <div data-type=\"button\" data-kind=\"subscribeCaption\" data-text=\"Subscribe\" data-caption=\"Your caption\"></div> at the requested position, escaping attribute values as HTML. Use data-kind=\"subscribe\" for no caption. Ordinary subscription links remain links, not native widgets."},"tags":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":50},"description":"Optional article tags. Substack receives all supplied tags. Medium receives its supported first 5 topics and returns a warning when extras are omitted. The saved draft remains unchanged."},"paywallMarker":{"type":"string","minLength":1,"maxLength":200,"description":"Optional exact marker in contentHtml where a Substack free preview ends. It must appear exactly once. Narrareach replaces it with a native Substack paywall and enables paid delivery."},"linkedinPublicationType":{"type":"string","enum":["article","newsletter"]},"linkedinAuthorUrn":{"type":"string","description":"Personal profile or Company Page author URN returned by the LinkedIn Article destinations endpoint."},"linkedinNewsletterUrn":{"type":"string","description":"Newsletter URN returned for the selected LinkedIn Article author."},"platforms":{"type":"array","minItems":1,"items":{"type":"string","enum":["SUBSTACK","MEDIUM","LINKEDIN","X"]}},"mediumPublicationId":{"type":"string","maxLength":200,"description":"Optional Medium publication to submit this story to instead of the personal profile. Only valid when platforms includes MEDIUM. When the account only has writer access (canPublish false), the story is submitted for editorial review and left unscheduled — it goes live when an editor accepts it, not at the requested time. An explicit publication rejection allows personal-profile delivery with a warning. An ambiguous submission remains unpublished for review. Draft-only delivery does not submit to a publication."},"mediumNotifyFollowers":{"type":"boolean","description":"Whether to email Medium subscribers about this story. Only valid when platforms includes MEDIUM. Defaults to false. Best-effort: a failure to apply this setting is returned in warnings, not as a failure."},"scheduledFor":{"type":"string","format":"date-time"},"platformSchedules":{"type":"array","minItems":1,"maxItems":4,"description":"One schedule for every selected platform. Platforms must be unique and match platforms exactly.","items":{"type":"object","required":["platform","scheduledFor"],"properties":{"platform":{"type":"string","enum":["SUBSTACK","MEDIUM","LINKEDIN","X"]},"scheduledFor":{"type":"string","format":"date-time"}},"additionalProperties":false}},"timezone":{"type":"string"},"idempotencyKey":{"type":"string","maxLength":200}},"additionalProperties":true},"RescheduleArticleRequest":{"type":"object","required":["scheduledFor"],"properties":{"scheduledFor":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"additionalProperties":false},"UpdateReaderActivityRequest":{"type":"object","required":["triageState"],"properties":{"triageState":{"type":"string","enum":["INBOX","HISTORY"]}},"additionalProperties":false},"ReplyToReaderActivityRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":5000},"idempotencyKey":{"type":"string","minLength":1,"maxLength":191}},"additionalProperties":false},"ReaderActivity":{"type":"object","required":["id","type","triageState","senderCount","occurredAt","content","targetContent","canReply","actors"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["LIKE","COMMENT","RESTACK","OTHER"]},"triageState":{"type":"string","enum":["INBOX","HISTORY"]},"senderCount":{"type":"integer","minimum":0},"occurredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"content":{"anyOf":[{"type":"string"},{"type":"null"}]},"targetContent":{"anyOf":[{"type":"string"},{"type":"null"}]},"canReply":{"type":"boolean"},"actors":{"type":"array","maxItems":5,"items":{"type":"object","required":["name","handle","photoUrl"],"properties":{"name":{"type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}]},"photoUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}},"additionalProperties":false},"ReaderActivityListResponse":{"type":"object","required":["success","activities","page","sync","summary"],"properties":{"success":{"type":"boolean","const":true},"activities":{"type":"array","items":{"$ref":"#/components/schemas/ReaderActivity"}},"page":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"hasMore":{"type":"boolean"}},"additionalProperties":false},"sync":{"type":"object","additionalProperties":true},"summary":{"type":"object","required":["inbox","history","all","likes","comments","restacks"],"properties":{"inbox":{"type":"integer","minimum":0},"history":{"type":"integer","minimum":0},"all":{"type":"integer","minimum":0},"likes":{"type":"integer","minimum":0},"comments":{"type":"integer","minimum":0},"restacks":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"UpdateReaderActivityResponse":{"type":"object","required":["success","triageState"],"properties":{"success":{"type":"boolean","const":true},"triageState":{"type":"string","enum":["INBOX","HISTORY"]}},"additionalProperties":false},"ReplyToReaderActivityResponse":{"type":"object","required":["success","status","deduplicated","replyId"],"properties":{"success":{"type":"boolean","const":true},"status":{"type":"string","const":"succeeded"},"deduplicated":{"type":"boolean"},"replyId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"StatsInsightsResponse":{"type":"object","required":["schemaVersion","generatedAt","scope","outcomes","nicheTiming","audience"],"properties":{"schemaVersion":{"type":"integer","const":1},"generatedAt":{"type":"string","format":"date-time"},"scope":{"type":"object","additionalProperties":true},"outcomes":{"type":"array","items":{"type":"object","additionalProperties":true}},"engagementPeak":{"anyOf":[{"type":"object","additionalProperties":true,"properties":{"hour":{"type":"integer"},"weekday":{"anyOf":[{"type":"integer"},{"type":"null"}]},"weekdayLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"displayLabel":{"type":"string"},"engagements":{"type":"number"},"averageEngagements":{"type":"number"},"share":{"type":"number"},"sampleCount":{"type":"integer"}}},{"type":"null"}]},"nicheTiming":{"type":"object","required":["title","summary","comparison","alignment","windows"],"additionalProperties":false,"properties":{"title":{"type":"string"},"summary":{"type":"string"},"comparison":{"type":"string"},"alignment":{"type":"string","enum":["no_peak","weekend_peak","weekday_reliable","crowded_morning","other"]},"windows":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string"},"window":{"type":"string"},"detail":{"type":"string"}}}}}},"audience":{"type":"object","required":["date","subscribers","paidSubscribers","emailOpenRate","arr"],"additionalProperties":false,"properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}]},"subscribers":{"anyOf":[{"type":"number"},{"type":"null"}]},"paidSubscribers":{"anyOf":[{"type":"number"},{"type":"null"}]},"emailOpenRate":{"anyOf":[{"type":"number"},{"type":"null"}]},"arr":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Annual recurring revenue. Null for non-owners."}}}},"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is malformed or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"The bearer token is missing, invalid, revoked, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"PaymentRequired":{"description":"The account needs an active subscription or a plan with Automation API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Forbidden":{"description":"The token is valid but lacks the required scope or workspace role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"The requested resource or API route does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Conflict":{"description":"The request conflicts with current resource or idempotency state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"The request exceeded the current rate limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalError":{"description":"The request could not be completed safely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}