Substack by Cotlet

The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, signed in but not connected), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.

{
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "description": "Only this app, e.g. skool."
    }
  },
  "additionalProperties": false
}

Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.

{
  "type": "object",
  "properties": {
    "apps": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 10,
      "description": "App slugs, e.g. [\"skool\", \"substack\"]."
    }
  },
  "required": [
    "apps"
  ],
  "additionalProperties": false
}

Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "call_id from the earlier call"
    }
  },
  "required": [
    "call_id"
  ],
  "additionalProperties": false
}

Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "File name, e.g. photo.jpg."
    },
    "content_type": {
      "type": "string",
      "description": "MIME type, e.g. image/jpeg."
    }
  },
  "additionalProperties": false
}

Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.

{
  "type": "object",
  "properties": {
    "kind": {
      "description": "bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.",
      "enum": [
        "bug",
        "error",
        "feature_request",
        "missing_feature",
        "other"
      ],
      "title": "Kind",
      "type": "string"
    },
    "title": {
      "description": "One line, e.g. 'skool_list_members stops after 50 members'.",
      "maxLength": 200,
      "minLength": 3,
      "title": "Title",
      "type": "string"
    },
    "description": {
      "description": "What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.",
      "maxLength": 5000,
      "minLength": 10,
      "title": "Description",
      "type": "string"
    },
    "app": {
      "anyOf": [
        {
          "maxLength": 80,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "App slug the report is about, e.g. 'skool'.",
      "title": "App"
    },
    "tool": {
      "anyOf": [
        {
          "maxLength": 160,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Tool or endpoint name, e.g. 'skool_list_members'.",
      "title": "Tool"
    },
    "call_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "call_id of the call that went wrong, if any.",
      "title": "Call Id"
    },
    "client": {
      "anyOf": [
        {
          "maxLength": 80,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Agent or tool sending this, e.g. 'Claude Code'.",
      "title": "Client"
    }
  },
  "required": [
    "kind",
    "title",
    "description"
  ],
  "additionalProperties": false,
  "description": "Body of POST /api/v1/reports and the arguments of the MCP tool cotlet_report_issue.",
  "title": "AgentReportCreate"
}

Wakes the user's Substack Cloud Browser, a real Chrome hosted on Cotlet and signed in to Substack as the user. Use it for what the Substack tools do not cover. Opens `url` when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
    }
  },
  "additionalProperties": false
}

Opens a public http or https address in the user's Substack Cloud Browser and returns the URL and title it ended on. Only Substack pages open. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

Returns the current page of the user's Substack Cloud Browser: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Returns a JPEG image of the visible part of the current page in the user's Substack Cloud Browser, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Scrolls the current page in the user's Substack Cloud Browser with the mouse wheel, as a person does: down or up by `screens` viewport heights (default 0.8), to the top or the bottom, or until element `element` is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "direction": {
      "type": "string",
      "enum": [
        "down",
        "up",
        "top",
        "bottom"
      ],
      "description": "Where to scroll. Default: down."
    },
    "screens": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10,
      "description": "How far, in viewport heights, for down and up. Default: 0.8."
    },
    "element": {
      "type": "integer",
      "minimum": 1,
      "description": "Scroll until this element of the element list is in view."
    }
  },
  "additionalProperties": false
}

Clicks a link, button or other element of the current page in the user's Substack Cloud Browser, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "element": {
      "type": "integer",
      "minimum": 1,
      "description": "The element's number in the element list of the current page."
    }
  },
  "required": [
    "element"
  ],
  "additionalProperties": false
}

Types text into a field of the current page in the user's Substack Cloud Browser, by the field's number in the page's element list, and with `submit` presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "element": {
      "type": "integer",
      "minimum": 1,
      "description": "The element's number in the element list of the current page."
    },
    "text": {
      "type": "string",
      "maxLength": 5000,
      "description": "The text to type."
    },
    "submit": {
      "type": "boolean",
      "description": "Press Enter after typing, e.g. to search."
    }
  },
  "required": [
    "element",
    "text"
  ],
  "additionalProperties": false
}

Chooses an option of a drop-down list on the current page in the user's Substack Cloud Browser, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "element": {
      "type": "integer",
      "minimum": 1,
      "description": "The element's number in the element list of the current page."
    },
    "option": {
      "type": "string",
      "maxLength": 300,
      "description": "The option."
    }
  },
  "required": [
    "element",
    "option"
  ],
  "additionalProperties": false
}

Presses one key on the current page in the user's Substack Cloud Browser, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "enum": [
        "Enter",
        "Tab",
        "Shift+Tab",
        "Escape",
        "Backspace",
        "Delete",
        "Space",
        "ArrowDown",
        "ArrowUp",
        "ArrowLeft",
        "ArrowRight",
        "PageDown",
        "PageUp",
        "Home",
        "End"
      ],
      "description": "The key."
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false
}

Puts files into a file field of the current page in the user's Substack Cloud Browser, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in the browser.

{
  "type": "object",
  "properties": {
    "element": {
      "type": "integer",
      "minimum": 1,
      "description": "The element's number in the element list of the current page."
    },
    "files": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "A public file URL."
          },
          "file_id": {
            "type": "string",
            "description": "A file uploaded to Cotlet."
          }
        },
        "additionalProperties": false
      },
      "description": "The files."
    }
  },
  "required": [
    "element",
    "files"
  ],
  "additionalProperties": false
}

Ends the session in the user's Substack Cloud Browser: the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

The full subscriber list as a CSV download link, with the row count. Builds the same CSV as Export in the subscriber dashboard: email, name, subscription type, activity rating and start date. Substack builds the file in the background; the call waits up to about a minute and otherwise asks you to try again later. The link needs no sign-in and works until expires_at, 24 hours when we recorded it. For filtered pages use list_subscribers.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Where your subscribers live, and which publications share your readers. Returns Analytics > Statistics > Audience: subscriber counts per country (region world, ISO codes such as us, gb) or per US state (region usa, codes such as ny, ca), all subscribers or paid only, the number of countries and states with any subscriber, and the publications whose readers overlap most with yours. Substack computes these in the background; a new publication has empty lists for a while.

{
  "type": "object",
  "properties": {
    "region": {
      "enum": [
        "world",
        "usa"
      ],
      "type": "string",
      "description": "world (by country) or usa (by state). Default: world."
    },
    "paid_only": {
      "type": "boolean",
      "description": "Count paid subscribers only. Default: false."
    }
  },
  "required": [],
  "additionalProperties": false
}

The latest messages of one direct-message conversation, oldest first. Returns who is in the conversation and its latest messages as the chat window first shows them, oldest first, with sender, text and time. Opening a conversation this way marks nothing read.

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "Conversation ID from list_conversations."
    }
  },
  "required": [
    "conversation_id"
  ],
  "additionalProperties": false
}

Day by day: total and paid subscribers, followers and views. Returns one row per day of the period, as the charts on the dashboard home and in Audience: total subscribers, paid subscribers and followers at the end of the day, and the day's views across your site and the app. Days Substack has no number for are null; a young publication starts on the day it was made.

{
  "type": "object",
  "properties": {
    "period": {
      "enum": [
        "7d",
        "30d",
        "90d",
        "365d"
      ],
      "type": "string",
      "description": "Default: 30d."
    }
  },
  "required": [],
  "additionalProperties": false
}

Your Substack home feed: posts and Notes, For you or Following. Returns one page of the home feed of the Substack app, split into posts and Notes in feed order. for_you is Substack's own mix; following holds only people and publications you follow or subscribe to. Suggestions of people to follow are left out. Reading marks nothing seen. Page with next_cursor; the feed is personal and changes between calls.

{
  "type": "object",
  "properties": {
    "tab": {
      "enum": [
        "for_you",
        "following"
      ],
      "type": "string",
      "description": "for_you (Substack's picks) or following (whom you follow). Default: for_you."
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    }
  },
  "required": [],
  "additionalProperties": false
}

Full post: title, subtitle, body as Markdown, audience, URL and dates. Returns one post of your publication, draft, scheduled or published, with its full body as Markdown, including the paywalled part. Images come back as URLs. Buttons, embeds and footnotes come back as plain text, so writing the body back with update_draft drops them. A scheduled post also has publish_at.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Who liked and commented on a post, and the subscribers it won and lost. Returns the Engagement and Growth parts of a post's stats: like and comment counts with the people behind them (name and handle, never email), and the free signups, paid subscriptions and unsubscribes Substack credits to the post. Counts keep changing for days after a send.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Recipients, opens, open rate, views, likes, restacks and subscribers gained. Returns the engagement numbers of one published post, as on its stats page in the dashboard. Email numbers cover the send; views include the web; likes are reactions. A draft or scheduled post returns an error. Numbers keep growing for days after a send, so check again later.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Where a post's readers came from: sources, categories and devices. Returns the Traffic part of a post's stats: each source (app, email, a website, search) with its views, share of all views and the free and paid subscribers it brought, the share per source category and per device. A post nobody has read yet returns empty lists.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Total and paid subscribers, new subscribers, paid cancellations and estimated revenue for a period. Totals are from the publisher dashboard at the end of the period (7, 30 or 90 days). subscribers_churned counts paid cancellations only; Substack keeps no count of free unsubscribes. subscribers_new is the growth in total subscribers plus those cancellations. revenue_usd is not money received: it is the dashboard's annualized revenue at the end of the period, times the period's share of a year.

{
  "type": "object",
  "properties": {
    "period": {
      "enum": [
        "7d",
        "30d",
        "90d"
      ],
      "type": "string",
      "description": "7d, 30d or 90d. Default: 30d."
    }
  },
  "required": [],
  "additionalProperties": false
}

How many unread direct messages, message requests and activity notifications you have. Returns the badges of the Substack app: unread direct messages, pending message requests and unread activity (likes, replies, new followers, restacks). Reading them marks nothing read.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Your Substack notifications: replies, likes, new followers, restacks, newest first. Returns the Activity tab of the Substack app, newest first. type is Substack's own name, e.g. note_reply, note_like, comment_reply, comment_like, post_like, follow, restack or mention. from lists the latest people behind a grouped item and people counts all of them. A reply or mention carries its comment_id and text; on_comment_id and on_post_id point at what it was about. Reading the list marks nothing read. Page with next_cursor.

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    },
    "filter": {
      "enum": [
        "all",
        "replies",
        "restacks"
      ],
      "type": "string",
      "description": "all, replies (replies and mentions) or restacks. Default: all."
    }
  },
  "required": [],
  "additionalProperties": false
}

Comments on a post, with author, text and whether you replied. Returns all comments of one post at once, oldest first, with replies nested under their parent. Deleted comments are left out. replied is true when you answered anywhere in the thread under the comment; unanswered_only keeps only top-level comments where you did not. Pass comment_id to reply_to_comment.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    },
    "unanswered_only": {
      "type": "boolean",
      "description": "Skip threads you already replied to."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Your direct-message conversations, latest first, with the last message. Returns your Substack chat inbox: one-to-one and group direct messages with who they are with, the last message, its time, your unread count and whether it is a message request from someone you do not follow. Publication chats are left out. Reading the list does not mark anything read. Pass conversation_id to get_conversation or send_message.

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    },
    "unread_only": {
      "type": "boolean",
      "description": "Only conversations with unread messages."
    }
  },
  "required": [],
  "additionalProperties": false
}

Replies under a Note, with author, text and likes. Returns the direct replies under one Note (yours or anyone's), in Substack's order. replies is the count under each reply; list those by passing its note_id. Substack sends no handle with replies, so author.handle is empty and url is null. Page with next_cursor.

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    },
    "note_id": {
      "type": "string",
      "description": "Note ID from list_notes or search_substack."
    }
  },
  "required": [
    "note_id"
  ],
  "additionalProperties": false
}

Notes posted by you or any other Substack user, newest first, with likes and replies. Returns the Notes on a profile's Notes tab, newest first: text, time, likes, restacks, reply count and link. Without user it lists yours. Posts and restacks of posts on the profile are left out. Page with next_cursor. Pass note_id to list_note_replies, like_comment or reply_to_note.

{
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "Handle (e.g. @mayachen) or user ID. Default: you."
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    }
  },
  "required": [],
  "additionalProperties": false
}

Tags your publication uses to group posts. Returns every post tag of your publication with its ID, name and slug; readers see tagged posts on /t/{slug}. hidden tags group posts without a public page. Pass tag_id to tag_post.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Posts of your publication, newest first, with status and audience. Lists posts of your publication, newest first. Filter by status to see drafts or scheduled posts. Scheduled posts include their publish time. Pages hold up to 50 posts; pass next_cursor back as cursor for the next page.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "1 to 50. Default: 20."
    },
    "cursor": {
      "type": "string",
      "description": "Next page cursor from the previous call."
    },
    "status": {
      "enum": [
        "published",
        "draft",
        "scheduled"
      ],
      "type": "string",
      "description": "published, draft or scheduled. Default: published."
    }
  },
  "required": [],
  "additionalProperties": false
}

Publications you recommend, or that recommend you, with the subscribers each sent. Returns Audience > Recommendations: with direction given, the publications you recommend; with received, the ones recommending you, and whether you recommend them back (mutual). subscribers_sent counts subscribers the recommendation brought. The table is rebuilt by Substack in the background, so a recommendation made minutes ago may be missing while counts already include it; publication_id checks one recommendation of yours directly.

{
  "type": "object",
  "properties": {
    "direction": {
      "enum": [
        "given",
        "received"
      ],
      "type": "string",
      "description": "given (publications you recommend) or received (that recommend you). Default: given."
    },
    "publication_id": {
      "type": "string",
      "description": "Check one publication instead: does yours recommend it (given only)."
    }
  },
  "required": [],
  "additionalProperties": false
}

Sections of your publication, the separate newsletters inside it. Returns each section with its ID, name, description and slug. live is false while Substack still sets a new section up. subscribed_by_default tells whether new subscribers get its emails. A publication without sections returns an empty list.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Tags you use to group subscribers. Returns the subscriber tags of your publication with their IDs, as Audience > Subscribers > Tags shows them. Subscribers never see tags. Pass tag_id to tag_subscribers.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Subscribers with plan, start date and activity rating. Lists subscribers, newest first, from the subscriber dashboard. Activity rating is the 0 to 5 score Substack shows there. Pages hold up to 500 rows; pass next_cursor back as cursor. The plan and since filters apply inside each page, so a filtered page can be short or empty while next_cursor still points further. Someone added a minute ago may not show yet: Substack fills the table in the background. paid includes founding members.

{
  "type": "object",
  "properties": {
    "plan": {
      "enum": [
        "all",
        "free",
        "paid",
        "comp",
        "founding"
      ],
      "type": "string",
      "description": "all, free, paid, comp or founding. Default: all."
    },
    "limit": {
      "type": "integer",
      "description": "1 to 500. Default: 100."
    },
    "since": {
      "type": "string",
      "format": "date",
      "description": "Only subscribers who joined on or after this date."
    },
    "cursor": {
      "type": "string",
      "description": "Next page cursor from the previous call."
    }
  },
  "required": [],
  "additionalProperties": false
}

Publications you subscribe to, with your plan and whether their emails reach you. Returns every publication your account subscribes to, as Settings > Subscriptions lists them: name, link, plan (free, paid, comp, founding or gift, as Substack names the membership) and whether you get its emails. Your own publications are left out.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Where your publication's visitors came from in a period, most views first. Returns Analytics > Traffic > Traffic sources: each source (the app, email, a website, search, social) with its category, views, unique visitors and the free and paid subscribers it brought. Sorted by views; page with next_cursor.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Default: 20."
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    },
    "period": {
      "enum": [
        "7d",
        "30d",
        "90d",
        "365d"
      ],
      "type": "string",
      "description": "Default: 30d."
    }
  },
  "required": [],
  "additionalProperties": false
}

Search all of Substack for people, posts and Notes. Runs Substack's search as the search box does and splits the results into people, posts and Notes. Use the IDs with follow_user, like_post, like_comment, reply_to_note, send_message or recommend_publication. Page with next_cursor; later pages may hold only posts and Notes.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Words to search for."
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from the previous page."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Add one email to your list as a free subscriber. Adds one email as a free subscriber, the same as Add subscribers in the dashboard, and Substack sends its usual welcome email. Substack adds the email in the background, so list_subscribers may show it a minute later. Add only people who agreed to hear from you. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Subscriber email."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

Stop a scheduled post from going out; it stays as a draft. Removes the scheduled time from a post, so nothing is published or emailed then; the post stays a draft with its content. Schedule it again with schedule_post. A post with no schedule returns an error.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

New draft from Markdown. Nothing is sent until you publish or schedule it. Creates a draft in your publication and returns its post_id and editor link. Markdown covers headings, paragraphs, bullet and numbered lists, quotes, code blocks, rules, images by public URL, bold, italic, strikethrough, inline code and links; local image files cannot be used. Sending is a separate step: schedule_post or publish_post. A draft reaches no one, so it runs without asking.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Post title."
    },
    "audience": {
      "enum": [
        "everyone",
        "only_paid",
        "founding"
      ],
      "type": "string",
      "description": "everyone, only_paid or founding. Default: everyone."
    },
    "subtitle": {
      "type": "string",
      "description": "Shown under the title and in the email preview."
    },
    "body_markdown": {
      "type": "string",
      "description": "Post body in Markdown. Images by public URL."
    }
  },
  "required": [
    "title",
    "body_markdown"
  ],
  "additionalProperties": false
}

New tag for grouping your posts. Creates a post tag on your publication; Substack makes the slug from the name. A tag with no posts shows nowhere. Put posts under it with tag_post.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Tag name, e.g. Habits."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

New private tag for grouping subscribers. Creates a subscriber tag on your publication. Tags are private: subscribers never see them. Put subscribers under it with tag_subscribers.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Tag name, e.g. Early readers."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Delete one of your own comments, Notes or Note replies. Deletes something you wrote: a comment under a post, a Note or a reply to a Note. Replies other people wrote under it stay, under a deleted placeholder. Someone else's comment returns an error; on your own posts remove it with remove_comment. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "comment_id": {
      "type": "string",
      "description": "ID of your comment, Note or Note reply."
    }
  },
  "required": [
    "comment_id"
  ],
  "additionalProperties": false
}

Delete a draft, scheduled or published post, with its comments. Deletes one post of your publication for good: a draft, a scheduled post (its send is cancelled) or a published post, which leaves the web, the archive and the app with its comments and stats. Emails already sent stay in inboxes. Substack has no undo; unpublish_post keeps the post as a draft instead. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Copy any post into a new draft. Makes a new draft with the title, subtitle, body and settings of a draft or published post, as Duplicate in the post list does. Substack puts [COPY] in front of the title; change it with update_draft. Nothing is published or sent.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Follow or unfollow a Substack user, so their Notes reach your feed. Follows a person on Substack, as Follow on their profile does, or unfollows them. Following is not subscribing: you get their Notes and activity in the app, not their newsletter by email. They see the follow.

{
  "type": "object",
  "properties": {
    "user": {
      "type": "string",
      "description": "Handle (e.g. @mayachen) or user ID."
    },
    "unfollow": {
      "type": "boolean",
      "description": "Unfollow instead. Default: false."
    }
  },
  "required": [
    "user"
  ],
  "additionalProperties": false
}

Like or unlike a comment or a Note as you. Adds your heart to any Note or Note reply, or to a comment under a post of your publication, or removes it with unlike. Comments and Notes share one ID space, so a Note ID from list_notes or search_substack works too. The author sees your like in their activity.

{
  "type": "object",
  "properties": {
    "unlike": {
      "type": "boolean",
      "description": "Remove your like instead. Default: false."
    },
    "comment_id": {
      "type": "string",
      "description": "Comment ID from list_comments, or a Note ID."
    }
  },
  "required": [
    "comment_id"
  ],
  "additionalProperties": false
}

Like or unlike any Substack post as you. Adds your heart to a post on any publication, as the heart under a post does, or removes it with unlike. The author sees your like in their activity. Liking twice keeps one like.

{
  "type": "object",
  "properties": {
    "unlike": {
      "type": "boolean",
      "description": "Remove your like instead. Default: false."
    },
    "post_id": {
      "type": "string",
      "description": "Post ID from search_substack, list_posts or a post's data."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Pin a comment to the top of your post's comments, or unpin it. Pins one comment on a post of your publication above all others, as Pin in the comment menu does, or unpins it. A comment on someone else's post returns an error.

{
  "type": "object",
  "properties": {
    "unpin": {
      "type": "boolean",
      "description": "Unpin instead. Default: false."
    },
    "comment_id": {
      "type": "string",
      "description": "Comment ID from list_comments."
    }
  },
  "required": [
    "comment_id"
  ],
  "additionalProperties": false
}

Short post in Substack Notes, now or at a set time, optionally with a link card to one of your posts. Posts a Note under your name. Without publish_at it goes out now; with it, the Note waits in your scheduled Notes, status is scheduled and published_at is that time. Text is 1 to 1,000 characters. link_post_id must be a published post. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Note text, up to 1,000 characters."
    },
    "publish_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with time zone. Omit to post now."
    },
    "link_post_id": {
      "type": "string",
      "description": "Attach one of your published posts as a link card."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false
}

Publish a draft now. Publishes a draft immediately, on the web and, unless send_email is false, by email, to the audience set on the draft. Substack's own pre-publish check runs first; a missing title or an empty body stops the call. A sent email cannot be recalled. On a publication with sections the post goes to section_id, else to the section already set on the draft, else to the main publication. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    },
    "section_id": {
      "type": "string",
      "description": "Section ID from list_sections, or main. Default: the draft's section, else main."
    },
    "send_email": {
      "type": "boolean",
      "description": "Email it to subscribers. Default: true."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Recommend another publication to your readers, or stop recommending it. Adds a publication to your Recommendations, as Growth > Recommendations does: Substack suggests it to people who subscribe to you and notifies its author. blurb is the short reason readers see. With remove it takes the recommendation back. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "blurb": {
      "type": "string",
      "description": "Why you recommend it, shown to your readers (optional)."
    },
    "remove": {
      "type": "boolean",
      "description": "Stop recommending it instead. Default: false."
    },
    "publication_id": {
      "type": "string",
      "description": "Publication ID, e.g. from search_substack posts."
    }
  },
  "required": [
    "publication_id"
  ],
  "additionalProperties": false
}

Remove someone's comment from your post as the publication's moderator. Hides a comment on a post of your publication, as Remove in the comment menu does: readers see that a moderator removed it, the text is gone, replies under it stay. Use delete_comment for your own comments. A comment on someone else's post returns an error. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "comment_id": {
      "type": "string",
      "description": "Comment ID from list_comments."
    }
  },
  "required": [
    "comment_id"
  ],
  "additionalProperties": false
}

Remove one email from your subscriber list. Removes a subscriber from your list, as Remove in the subscriber's menu does: they get no more emails from you and no notice. A paid subscription is cancelled and Substack refunds the unused part. An email not on your list returns an error; add_subscriber takes about a minute before the address is listed. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Subscriber's email address."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

Reply as you under a comment on your post. Posts a reply under one comment on a post of your publication, under your name, visible to everyone who can read the post. A comment elsewhere on Substack returns an error. The author gets Substack's usual reply notification. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Reply text."
    },
    "comment_id": {
      "type": "string",
      "description": "Comment ID from list_comments."
    }
  },
  "required": [
    "comment_id",
    "body"
  ],
  "additionalProperties": false
}

Reply as you under any Note or Note reply. Posts a reply under a Note (yours or anyone's) or under a reply to one, visible to everyone who sees the Note. Text is 1 to 1,000 characters; Markdown bold, italics and links work. The author gets Substack's usual notification. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Reply text, up to 1,000 characters."
    },
    "note_id": {
      "type": "string",
      "description": "Note ID from list_notes, list_note_replies or search_substack."
    }
  },
  "required": [
    "note_id",
    "body"
  ],
  "additionalProperties": false
}

Publish a draft at a set time, on the web and by email. Schedules a draft to go live at the time you set, on the web and, unless send_email is false, by email, to the audience set on the draft. The time needs a time zone and must be in the future. Substack's own pre-publish check runs first; a missing title or an empty body stops the call. A scheduled post stays editable until it goes out. On a publication with sections the post goes to section_id, else to the section already set on the draft, else to the main publication. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    },
    "publish_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 with time zone."
    },
    "section_id": {
      "type": "string",
      "description": "Section ID from list_sections, or main. Default: the draft's section, else main."
    },
    "send_email": {
      "type": "boolean",
      "description": "Email it to subscribers. Default: true."
    }
  },
  "required": [
    "post_id",
    "publish_at"
  ],
  "additionalProperties": false
}

Send a direct message on Substack, in a conversation or to a person. Sends a private chat message under your name. With conversation_id it replies there; with user it writes to that person, in your existing conversation with them or a new one. Someone who does not follow you gets it as a message request. Give one of conversation_id or user. A sent message cannot be recalled. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "Message text."
    },
    "user": {
      "type": "string",
      "description": "Or start one with this handle (e.g. @mayachen) or user ID."
    },
    "conversation_id": {
      "type": "string",
      "description": "Reply in this conversation from list_conversations."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false
}

Add a tag to a post, or take it off. Puts one of your post tags on a draft or published post, or removes it with remove. A post can have several tags. Tagging twice keeps one tag.

{
  "type": "object",
  "properties": {
    "remove": {
      "type": "boolean",
      "description": "Take the tag off instead. Default: false."
    },
    "tag_id": {
      "type": "string",
      "description": "Tag ID from list_post_tags or create_post_tag."
    },
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id",
    "tag_id"
  ],
  "additionalProperties": false
}

Put a tag on subscribers by email, or take it off. Adds one of your subscriber tags to up to 50 subscribers, or removes it with remove. Emails not on your list come back in not_found and nothing else fails. A subscriber added a minute ago may not be findable yet; try again shortly.

{
  "type": "object",
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Subscribers' email addresses, up to 50."
    },
    "remove": {
      "type": "boolean",
      "description": "Take the tag off instead. Default: false."
    },
    "tag_id": {
      "type": "string",
      "description": "Tag ID from list_subscriber_tags or create_subscriber_tag."
    }
  },
  "required": [
    "tag_id",
    "emails"
  ],
  "additionalProperties": false
}

Take a published post off the web and back to drafts. Turns a published post back into a draft, as Unpublish in the editor does: it leaves your site, archive and the Substack app, and its link stops working. Comments and stats stay with the draft. Emails already sent stay in inboxes. Publish it again with publish_post. A post that is not published returns an error. By default you confirm each call; you can switch that off for this tool. Waits for the owner's approval.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id"
  ],
  "additionalProperties": false
}

Change the title, subtitle, body or audience of a draft. Changes the fields you pass and leaves the others as they are. body_markdown replaces the whole body. Drafts and scheduled posts only: a published post returns an error. Nothing reaches your subscribers, so it runs without asking.

{
  "type": "object",
  "properties": {
    "fields": {
      "type": "string",
      "description": "JSON object with any of title, subtitle, body_markdown, audience, e.g. {\"title\": \"New title\"}."
    },
    "post_id": {
      "type": "string",
      "description": "Post ID from list_posts."
    }
  },
  "required": [
    "post_id",
    "fields"
  ],
  "additionalProperties": false
}