# Manage your account (/account/manage-account)



Everything about your account lives in Settings in the [app](https://app.paragraph.com). This page covers what you can manage there, and how to leave with your data if you ever want to.

## Settings at a glance [#settings-at-a-glance]

| Area        | What it covers                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| Account     | Your personal details and login                                                                                    |
| Agent       | How your agent behaves, its [voice and memory](/agent/voice-and-memory), and its [connections](/agent/connections) |
| Billing     | Your plan and credits (see [plans and credits](/account/plans-and-credits))                                        |
| Permissions | Who can access your workspace, and what your agent can do on its own                                               |
| Publication | Your publication's name and logo                                                                                   |
| Website     | How your public site looks and works (see [website](/publishing/website))                                          |

## Your account [#your-account]

Your account details, including how you log in, live in Settings under Account. Update them there whenever something changes.

## Your publication [#your-publication]

Your publication's identity lives in Settings under Publication. Set your publication's name and logo here. Both appear on your website and in the emails you send, so readers see a consistent identity everywhere your writing shows up.

For how your public site looks and behaves, see [website](/publishing/website). To put your site on your own domain (available on Starter and above), see [custom domains](/publishing/custom-domains).

## Team and permissions [#team-and-permissions]

If you work with other people, manage their access in Settings under Permissions. The same area controls what your agent can do on its own and what needs your approval. See [approvals](/agent/approvals) for how agent permissions work in practice.

## Billing [#billing]

Your plan and credits live in Settings under Billing. For what each plan includes and how credits work, see [plans and credits](/account/plans-and-credits).

## Your data is yours [#your-data-is-yours]

Paragraph is built on a simple promise: your writing and your audience belong to you.

### Export your subscribers [#export-your-subscribers]

You can export your subscriber list at any time, on any plan. There's no waiting period and no gatekeeping. If you ever decide to publish somewhere else, your list goes with you.

### Delete your workspace [#delete-your-workspace]

If you want to leave entirely, you can delete your workspace from Settings.

<Callout type="warn">
  Deleting your workspace is permanent. Export your subscriber list and save copies of anything you want to keep before you delete.
</Callout>

## Need a hand? [#need-a-hand]

For anything you can't sort out in Settings, email [support@paragraph.com](mailto:support@paragraph.com). Account questions, billing puzzles, and export help all welcome.


# Plans and credits (/account/plans-and-credits)



Paragraph has four plans. Every plan, including Free, gives you a hosted site, posts, and a subscriber list you own. Paid plans unlock more of the agent and more room to grow.

You can compare plans on the [pricing page](https://paragraph.com/pricing), and manage your own plan in Settings, under Billing, in the [app](https://app.paragraph.com).

## Plans at a glance [#plans-at-a-glance]

| Plan    | Monthly | Annual                              | Credits per month |
| ------- | ------- | ----------------------------------- | ----------------- |
| Free    | $0      | $0                                  | 500               |
| Starter | $20     | $16/mo billed annually ($192/yr)    | 1,500             |
| Growth  | $100    | $80/mo billed annually ($960/yr)    | 8,500             |
| Scale   | $200    | $160/mo billed annually ($1,920/yr) | 17,500            |

Annual billing saves 20% on every paid plan.

## What each plan includes [#what-each-plan-includes]

### Free [#free]

A permanent home for your site, posts, and subscribers.

* Hosted website for your writing
* Subscriber capture, so readers can sign up
* A taste of the agent, with 500 credits a month
* Limited [API and MCP access](/developers)

Free is genuinely free, and your work stays yours. There's no time limit and no pressure to upgrade before you're ready.

### Starter [#starter]

For writers getting started with Paragraph.

* Everything in Free
* Full agent access
* [Custom domain](/publishing/custom-domains)
* X posting, so your agent can share your work
* Recurring workflows through [scheduled tasks](/agent/scheduled-tasks)
* Email support

### Growth [#growth]

For writers publishing every week and building an audience.

* Everything in Starter
* Advanced models for agent work
* Bigger job headroom for larger and longer-running tasks
* Priority support

### Scale [#scale]

For audience businesses that run on content.

* Everything in Growth
* Advanced analytics
* Onboarding support
* Migration help from our team (see [import your publication](/getting-started/import-your-publication))
* A private Slack channel with us
* Optional credit top-ups

## How credits work [#how-credits-work]

Credits are what your agent runs on. Whenever it does work for you, it uses credits. That includes:

* Drafting and editing posts
* Research
* Recurring tasks, like a weekly digest or regular social sharing
* Image generation

Each plan includes a monthly credit allowance, shown in the table above. Bigger plans include more credits because they're built for writers who lean on the agent more. On Scale, you can also add optional credit top-ups when you need extra headroom.

Writing and publishing yourself doesn't use credits. Credits only cover work the agent does for you.

## Managing your plan [#managing-your-plan]

Open Settings in the app and go to Billing. From there you can see your current plan and credits, switch plans, and choose monthly or annual billing.

## Common questions [#common-questions]

<Accordions>
  <Accordion title="What happens to my site and subscribers on the Free plan?">
    They stay put. Free is a permanent home for your site, posts, and subscribers. You don't lose your work or your list by staying on Free.
  </Accordion>

  <Accordion title="Do I need a paid plan to use the agent?">
    No. Free includes 500 credits a month, enough to try the agent on real work. Starter and above unlock full agent access, recurring workflows, and social posting.
  </Accordion>

  <Accordion title="Which plan do I need for a custom domain?">
    Custom domains are available on Starter and above. See [custom domains](/publishing/custom-domains) for setup.
  </Accordion>

  <Accordion title="Can I buy more credits?">
    Optional credit top-ups are available on the Scale plan. On other plans, your credits refresh monthly. If you're regularly running out, the next plan up is usually the better fit.
  </Accordion>

  <Accordion title="Can I leave and take my data?">
    Yes, at any time, on any plan. Your subscriber list is exportable whenever you want it. See [manage your account](/account/manage-account).
  </Accordion>
</Accordions>

Questions about billing we didn't answer here? Email [support@paragraph.com](mailto:support@paragraph.com).


# Approvals (/agent/approvals)



An agent is only useful if you can trust it. Paragraph's answer is a simple approval model: the agent shows you everything it does, asks before anything big ships, and earns more freedom only as you grant it.

You're never handing over the keys. You're delegating, one kind of work at a time, at whatever pace feels right.

## What waits for you [#what-waits-for-you]

New posts, campaigns, and visible changes wait for your yes, edit, or no. If readers would see it, you see it first. That includes:

* Publishing a new post or essay
* Sending a newsletter
* Posting to X or LinkedIn
* Visible changes to your site

Each of these arrives as something to review: a [suggestion](/agent/suggestions), a draft, or output from a [scheduled task](/agent/scheduled-tasks). You can approve it as-is, edit it first, or turn it down. Your answer is always the last word.

## What just happens [#what-just-happens]

Routine upkeep doesn't need a meeting. Small maintenance work, like fixing a broken link, just happens. The agent handles it on its own and records what it did, so you can always see the trail.

The line is visibility. Invisible upkeep proceeds; anything readers would notice waits for you.

## One-tap review [#one-tap-review]

Reviewing shouldn't be a chore. You can approve, edit, or decline with one tap, from your workspace or straight from your inbox. Most reviews take seconds: read what the agent wants to do, and answer.

## Standing approvals [#standing-approvals]

Standing approvals are how the agent earns more freedom. Say yes to a kind of work a few times, and it stops asking for that kind of work.

For example, if you approve the agent's X threads week after week without edits, a standing approval lets future threads go out on schedule without a review step. The same applies to any category of work you've come to trust.

Two things to know:

* **You set the pace.** Nothing becomes automatic until you've said yes enough times to grant it.
* **Any standing yes can be revoked at any time.** Take back a standing approval, and that work goes back to waiting for your review.

<Callout type="info">
  Start narrow. Grant standing approvals for one kind of work at a time, beginning with whatever you've been rubber-stamping anyway.
</Callout>

## The daily report [#the-daily-report]

Trust also means never wondering what happened while you were away. Your agent sends a daily report covering:

* **What shipped.** Everything that went out, whether you approved it or a standing approval covered it.
* **What's queued.** Suggestions and scheduled output waiting for your review.
* **What it plans next.** The work it intends to take on.

The report is your check-in point. If something in it surprises you, that's your cue to revoke a standing approval or steer the agent in [chat](/agent/chat).

## Common questions [#common-questions]

<Accordions>
  <Accordion title="Can the agent publish without me?">
    Only if you've granted a standing approval for that kind of work. Out of the box, everything visible waits for your yes.
  </Accordion>

  <Accordion title="What if I miss a review?">
    Nothing ships. Pending work waits in your queue and shows up in the daily report until you act on it.
  </Accordion>

  <Accordion title="How do I take back a standing approval?">
    Any standing yes can be revoked at any time. Ask the agent in chat, or manage it from your workspace, and that work returns to manual review.
  </Accordion>

  <Accordion title="Can I stop the agent mid-task?">
    Yes. You can steer or stop the agent at any time, and suggestions always wait for your approval.
  </Accordion>
</Accordions>


# Chat with your agent (/agent/chat)



Chat is the fastest way to put your agent to work. Open your workspace at [app.paragraph.com](https://app.paragraph.com), start a conversation, and ask for what you need in plain English.

Your agent already knows your publication. It keeps your goals, brand, and voice in mind across every chat, so you don't have to re-explain yourself each time. See [Voice and memory](/agent/voice-and-memory) for how to shape that context.

## What you can ask for [#what-you-can-ask-for]

Chat covers the full range of what your agent can do:

* **Write and create.** Draft posts and newsletters, repurpose existing pieces, write video scripts, and generate images.
* **Publish and grow.** Post to X, schedule recurring tasks, and analyze how your posts and readers are doing.
* **Research and decide.** Run web research, and work through your daily inbox and suggestions together.
* **Power tools.** Use a code and data workspace, call connected services via MCP, and upload files for the agent to work with.

If you're not sure whether something is possible, just ask. The agent will tell you what it can do and what it needs from you.

## Starter prompts [#starter-prompts]

These prompts come straight from the in-app guide. Copy one, or use it as a template for your own.

| Goal               | Prompt                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| Plan my day        | "What should I focus on today? Give me a short plan and a few post ideas I can start now."           |
| Draft a post       | "Draft a short post about something trending in my niche this week, with a strong opening."          |
| Set a weekly recap | "Every Friday at 5pm, review my best posts from the week and suggest one follow-up to write."        |
| Make a cover image | "Generate a clean, modern cover image for my next post."                                             |
| Find a fresh angle | "Search the web for what people are saying about my topic, then suggest three angles I could write." |

Notice the third prompt: anything you phrase as a recurring request ("every Friday at 5pm…") becomes a [scheduled task](/agent/scheduled-tasks) that keeps running without you.

## How sessions work [#how-sessions-work]

Each conversation is a session. Within a session, the agent remembers everything you've discussed, so you can build on earlier messages ("make it shorter", "now turn that into a thread").

Across sessions, the agent still remembers who you are. Your goals, brand voice, and notes carry over, so a new chat starts informed, not blank.

A few habits that help:

* Keep one topic per session when you can. It keeps the thread easy to follow.
* Start a fresh session when you switch to something unrelated.
* If the agent should remember something permanently, ask it to save a note, or add it yourself in Settings → Agent.

## Chat from anywhere [#chat-from-anywhere]

You don't have to be at your desk. Connect Telegram to message your agent from your phone, or add it to your team's Slack and mention it in a channel or thread. Either way, the conversation stays linked to the same session on Paragraph.

Setup for both lives in [Connections](/agent/connections).

## Steering and stopping [#steering-and-stopping]

You stay in control. Suggestions the agent makes wait for your approval, and you can steer or stop the agent at any time, mid-task included. Anything visible, like publishing a post or sending a newsletter, goes through [approvals](/agent/approvals) first.

<Callout type="info">
  Chat and the work it kicks off use the monthly credits included with your plan. See [Plans and credits](/account/plans-and-credits).
</Callout>


# Connections (/agent/connections)



Connections give your agent reach beyond your Paragraph site. Some let it publish and read on social channels, some let you chat with it from other apps, and some give it access to the tools your work already lives in.

All of them are managed in Settings → Agent in your workspace.

## X [#x]

Connect an X account and your agent can post and read on X: publishing threads, checking how they perform, and folding results back into what it writes next.

A few things to know:

* The connected account is the one your agent uses when working on this publication.
* It's shared with everyone on your team, so the whole team's agent work posts from the same account.
* Connecting X requires the Starter plan or above. See [Plans and credits](/account/plans-and-credits).

Once connected, X becomes a distribution channel. Threads the agent drafts go through [approvals](/agent/approvals) like everything else, unless you've granted a standing approval.

## Telegram [#telegram]

Connect Telegram and message your agent right from your phone. It replies in the chat, and your conversation stays linked to the same session on Paragraph.

That means no context is lost between surfaces. Start a thread from the couch, and pick it up in your workspace later with the full history intact. It's the same agent, same memory, same [voice settings](/agent/voice-and-memory).

## Slack [#slack]

Add your agent to your team's Slack. Mention it in a channel or thread and it replies inline, with everything saved back to your Paragraph session.

This works well for teams: anyone in the channel can see the exchange, and the conversation still lands in your Paragraph session history.

## Tools via MCP [#tools-via-mcp]

MCP (Model Context Protocol) is an open standard for connecting AI agents to outside tools. Connect a service over MCP, and your agent can use it directly in chat and in tasks.

Paragraph ships presets for common tools:

| Preset | What your agent gets                     |
| ------ | ---------------------------------------- |
| Slack  | Channels, messages, and workspace search |
| Linear | Issues, projects, and comments           |
| Notion | Pages, databases, and workspace search   |
| GitHub | Repositories, issues, and pull requests  |

With these connected, you can ask things like "summarize this week's Linear issues into a changelog post" or "pull the outline from my Notion page and draft the essay".

<Callout type="info">
  The Slack preset is different from the Slack chat connection above. The chat connection lets you talk to your agent in Slack; the MCP preset lets your agent read your Slack workspace as a tool.
</Callout>

### Custom MCP servers [#custom-mcp-servers]

Beyond the presets, you can connect any remote MCP server. Paragraph supports three ways to authenticate:

* **OAuth**, for servers that support a standard sign-in flow
* **Bearer token**, for servers that use an API key
* **No auth**, for open servers

Add a custom server in Settings → Agent with the server's URL and the auth method it expects. If you're building your own tools, see [MCP for developers](/developers/mcp).

## Getting started [#getting-started]

<Steps>
  <Step>
    Open Settings → Agent at [app.paragraph.com](https://app.paragraph.com).
  </Step>

  <Step>
    Pick a connection and follow the sign-in flow for that service.
  </Step>

  <Step>
    Test it in [chat](/agent/chat): ask the agent to use the new connection, and confirm it responds the way you expect.
  </Step>
</Steps>

Having trouble with a connection? Write to [support@paragraph.com](mailto:support@paragraph.com) and we'll help you sort it out.


# Meet your agent (/agent)



Every Paragraph publication comes with an agent. It reads everything you've published, learns how you write, and works on your publication every day, not just when you're in the app.

The agent's work falls into three areas: drafting, distributing, and maintaining. A fourth idea, approval, ties them together. You see everything it does, and anything visible waits for your yes.

## Draft [#draft]

Your agent reads your archive, then drafts what should come next. That includes:

* Weekly newsletter drafts built from what you've already published
* New posts and essays built around ideas your readers respond to
* Refreshes of older posts that are losing traffic
* Titles and descriptions written to be found, and to sound like you
* A handful of on-brand cover image options for each post
* Series and follow-ups queued up so you're never staring at a blank page

Nothing ships without your OK. Drafts land as [suggestions](/agent/suggestions) you can review, edit, or dismiss.

## Distribute [#distribute]

Publishing a post is the start, not the finish. Your agent turns each post into threads, clips, and newsletter sends, shaped for each channel and scheduled while you write the next one.

Today it can distribute to X, LinkedIn, and your Paragraph newsletter:

* X threads that earn the click back to the full piece
* LinkedIn versions written for a professional feed
* Newsletter sends to your [subscribers](/audience/subscribers)
* A standing queue, so a week of posts is spaced out and ready
* Scheduling at the times your readers actually show up

It also folds results back in. Formats that earn readers get repeated, and ones that don't get retired. See [Distribution](/audience/distribution) for the full picture.

## Maintain [#maintain]

Your agent patrols your site every day, fixes small problems on its own, and keeps your content easy for readers and AI to find:

* Broken links repaired
* Slow pages trimmed
* Missing titles and descriptions written
* Posts quietly losing traffic refreshed before they fall off
* Clean structure and sitemaps, so search engines can do their job

Every fix is measured against traffic, so you can see whether the upkeep is paying off. Learn more in [SEO](/publishing/seo).

## Approve [#approve]

An agent is only useful if you can trust it. Paragraph shows you everything the agent does, asks before anything big ships, and earns more freedom only as you grant it.

* New posts, campaigns, and visible changes wait for your yes, edit, or no
* Review takes one tap, from your workspace or your inbox
* Standing approvals: say yes to a kind of work a few times, and it stops asking
* Routine upkeep, like fixing a broken link, just happens
* A daily report covers what shipped, what's queued, and what it plans next

You can revoke any standing yes at any time. The full model is covered in [Approvals](/agent/approvals).

<Callout type="info">
  Agent work uses the monthly credits that come with your plan. See [Plans and credits](/account/plans-and-credits) for what's included.
</Callout>

## Explore this section [#explore-this-section]

<Cards>
  <Card title="Chat with your agent" href="/agent/chat">
    What to ask, starter prompts, and how sessions work.
  </Card>

  <Card title="Voice and memory" href="/agent/voice-and-memory">
    Set goals, brand voice, social voice, and notes so the agent sounds like you.
  </Card>

  <Card title="Suggestions" href="/agent/suggestions">
    Review the drafts and proposals your agent queues up for you.
  </Card>

  <Card title="Scheduled tasks" href="/agent/scheduled-tasks">
    Set recurring workflows that run while you're away.
  </Card>

  <Card title="Approvals" href="/agent/approvals">
    What waits for you, standing approvals, and the daily report.
  </Card>

  <Card title="Connections" href="/agent/connections">
    Connect X, Telegram, Slack, and other tools via MCP.
  </Card>
</Cards>

New to Paragraph? Start with the [quickstart](/getting-started/quickstart), then take the [workspace tour](/getting-started/workspace-tour).


# Scheduled tasks (/agent/scheduled-tasks)



Scheduled tasks are recurring workflows your agent runs on a schedule you set. Describe the routine once, and it keeps happening: daily recaps, weekly post ideas, Monday planning sessions, whatever fits how you work.

This is how the agent works while you're away. Set a task before a busy week, and drafts are waiting when you come back.

## Creating a task [#creating-a-task]

You create scheduled tasks by asking in [chat](/agent/chat). Phrase the request with a schedule, and the agent sets it up as a recurring task.

<Steps>
  <Step>
    Open a chat with your agent at [app.paragraph.com](https://app.paragraph.com).
  </Step>

  <Step>
    Describe the task with a schedule. For example: "Every Friday at 5pm, review my best posts from the week and suggest one follow-up to write."
  </Step>

  <Step>
    The agent confirms the task. It now runs on that schedule, and you'll find it in the Schedule area of your workspace, alongside your [suggestions](/agent/suggestions).
  </Step>
</Steps>

## Ideas worth scheduling [#ideas-worth-scheduling]

| Rhythm | Example request                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------- |
| Daily  | "Every morning, give me a short plan for the day and a few post ideas I can start now."              |
| Weekly | "Every Friday at 5pm, review my best posts from the week and suggest one follow-up to write."        |
| Weekly | "Every Monday, draft my newsletter from what I published last week."                                 |
| Weekly | "Each Wednesday, search the web for what people are saying about my topic and suggest three angles." |

Anything you'd ask for in chat can become a routine. If you find yourself making the same request twice, schedule it.

## What happens when a task runs [#what-happens-when-a-task-runs]

When a task runs, its output waits for your approval before anything ships. A weekly newsletter task produces a draft for review, not a send. A recap task produces a suggestion, not a published post.

That changes only if you've granted a standing approval for that kind of work. Approve the same output a few times, and the agent stops asking for it. See [Approvals](/agent/approvals) for how standing approvals work and how to revoke them.

Completed runs also show up in your daily report, so you always know what your tasks produced.

## Managing your tasks [#managing-your-tasks]

Your tasks live in the Schedule area of your workspace. From there, or from chat, you can adjust them:

* **Change the schedule.** Ask the agent to move a task to a different day or time.
* **Refine the instructions.** Tell it what to do differently ("shorter recaps", "focus on my essays, not my link posts").
* **Pause or delete.** Ask the agent to stop a task that's no longer useful.

<Callout type="info">
  Scheduled runs use the monthly credits included with your plan, just like chat. See [Plans and credits](/account/plans-and-credits).
</Callout>

## Tips for reliable routines [#tips-for-reliable-routines]

* **Be specific about timing.** "Every Friday at 5pm" beats "weekly". Include the time you actually want it.
* **One job per task.** A task that drafts a recap and researches trends and plans your week is harder to steer than three focused ones.
* **Review the first few runs closely.** Early feedback shapes the routine. Once it's reliably right, consider a standing approval.
* **Lean on your voice settings.** Task output follows your [brand voice and goals](/agent/voice-and-memory), so tuning those improves every run.


# Suggestions (/agent/suggestions)



Suggestions are proposals your agent generates on its own: work it thinks should happen next, queued up and waiting for your review. Nothing in a suggestion ships until you say so.

They appear alongside your scheduled tasks in the Schedule area of your workspace, so you can see everything the agent has planned in one place.

## What the agent suggests [#what-the-agent-suggests]

Suggestions come from the agent reading your archive, your goals, and how your posts are performing. Typical examples:

* **Newsletter drafts.** A weekly newsletter built from what you've published, ready to edit and send.
* **New posts and essays.** Pieces built around ideas your readers respond to.
* **Refreshes.** Updates to older posts that are quietly losing traffic, proposed before they fall off.
* **Titles and descriptions.** Rewrites for posts that are missing them, or could be found more easily.
* **Cover images.** A handful of on-brand options per post.
* **Series and follow-ups.** Next installments queued so a good idea doesn't stall after one post.
* **Distribution.** X threads, LinkedIn versions, and newsletter sends shaped from a post you've published.

The mix follows your [goals](/agent/voice-and-memory). If your goals emphasize newsletter growth, expect more newsletter suggestions. Change your goals and the suggestions shift with them.

## Reviewing a suggestion [#reviewing-a-suggestion]

Open a suggestion to see the full details of what the agent wants to do. From there you can:

* **Approve** it, so the agent carries it out.
* **Execute now**, when you want it done immediately.
* **Schedule for later**, picking a time that fits your calendar.
* **Dismiss** it, if it's not right.

For drafts, approval isn't all-or-nothing. You can edit the piece in the [editor](/publishing/editor) before it goes anywhere. Your yes, edit, or no is always the last word, as covered in [Approvals](/agent/approvals).

## Making suggestions better [#making-suggestions-better]

Suggestions improve as the agent learns what you accept and what you dismiss. You can speed that up:

* **Tune your voice.** If drafts miss your tone, update your brand voice in Settings → Agent. See [Voice and memory](/agent/voice-and-memory).
* **Sharpen your goals.** Vague goals produce vague suggestions. Specific goals focus the queue.
* **Say why in chat.** Tell the agent why you dismissed something ("too promotional", "wrong audience"), and ask it to save a note.
* **Grant standing approvals.** Once a kind of suggestion is reliably right, a standing yes lets it proceed without asking. See [Approvals](/agent/approvals).

<Callout type="info">
  Suggestions don't expire the moment you see them, but timely ones (like a refresh for a post losing traffic) work best acted on soon.
</Callout>

## Suggestions and scheduled tasks [#suggestions-and-scheduled-tasks]

Suggestions and [scheduled tasks](/agent/scheduled-tasks) live side by side in the Schedule area, and they feed each other. A scheduled task like a weekly recap produces output that arrives as a suggestion for your review. And a suggestion you like can become a recurring task: just ask in [chat](/agent/chat) to make it a routine.

<Cards>
  <Card title="Scheduled tasks" href="/agent/scheduled-tasks">
    Turn one-off suggestions into recurring workflows.
  </Card>

  <Card title="Approvals" href="/agent/approvals">
    How review works, and when the agent can act on its own.
  </Card>
</Cards>


# Voice and memory (/agent/voice-and-memory)



Your agent is only as good as what it knows about you. Voice and memory settings are where you teach it what you're working toward and how you sound, once, instead of repeating it in every chat.

Everything here lives in Settings → Agent in your workspace. The agent keeps your goals, brand, and voice in mind across every chat, so updates you make apply everywhere: drafts, [suggestions](/agent/suggestions), [scheduled tasks](/agent/scheduled-tasks), and social posts.

## Goals [#goals]

Goals tell your agent what to focus on. You can set up to 20.

Good goals are specific enough to act on:

* "Grow my newsletter to 5,000 subscribers"
* "Publish one deep essay a month"
* "Turn my best posts into an X audience"

The agent uses goals to prioritize. If growing your newsletter is a goal, expect more suggestions about [newsletter sends](/publishing/newsletters) and [subscriber](/audience/subscribers) growth. If a goal changes, update it, and the agent's priorities follow.

## Brand voice [#brand-voice]

Brand voice describes how the agent writes for your site: posts, newsletters, titles, and descriptions. You have up to 10,000 characters, so there's room to be thorough.

Things worth including:

* **Tone.** Formal or conversational? Playful or restrained?
* **Structure.** Short punchy paragraphs, or long-form argument?
* **Vocabulary.** Words you love, and words you never use.
* **Point of view.** First person? Do you address the reader directly?
* **Examples.** A few sentences of your writing that capture the sound you want.

The more concrete you are, the closer the drafts land. "Warm but direct, short sentences, no buzzwords" beats "professional".

## Social voice [#social-voice]

Social voice covers how the agent sounds on social channels like X and LinkedIn. It's separate from brand voice because most writers sound different in a thread than in an essay.

Use it to set the register for [distribution](/audience/distribution): looser or tighter than your site, whether you use emoji, how you open a thread, and what you'd never post.

## Notes [#notes]

Notes hold extra context that doesn't fit the other fields: your posting cadence, topics to avoid, ongoing projects, or facts about your niche.

Notes are shared memory. You can write them, and the agent also writes its own notes here as it learns things worth keeping. If you spot a note that's wrong or stale, edit or remove it, and the agent moves on with the corrected version.

You can also add to memory from a conversation. If something comes up in chat that the agent should remember permanently, ask it to save a note.

## How it all fits together [#how-it-all-fits-together]

<Steps>
  <Step>
    Set your goals so the agent knows what success looks like.
  </Step>

  <Step>
    Write your brand voice and social voice so drafts sound like you from day one.
  </Step>

  <Step>
    Add notes for anything else, and let the agent keep them current as you work together.
  </Step>

  <Step>
    Review drafts and suggestions, and refine these settings whenever something feels off.
  </Step>
</Steps>

<Callout type="info">
  Voice takes a little tuning. If a draft misses your tone, don't just fix the draft. Update your brand voice too, so the next one starts closer.
</Callout>

You stay in control throughout. Suggestions wait for your approval, and you can steer or stop anytime. See [Approvals](/agent/approvals) for how review works.


# Analytics (/audience/analytics)



The Analytics area in [app.paragraph.com](https://app.paragraph.com) shows how your writing performs across every channel: your website, your newsletter, social, and search. Use it to answer the questions that actually matter: what's working, who's reading, and what to do next.

## Reading the analytics page [#reading-the-analytics-page]

Analytics is organized by channel, with a tab for each:

| Tab         | What it shows                                                          |
| ----------- | ---------------------------------------------------------------------- |
| Web         | Traffic to your site and posts                                         |
| Newsletter  | How sends perform, including delivery rate and opens                   |
| Social      | Your X presence: followers, impressions, and recent post engagement    |
| Campaigns   | Traffic by channel, clickthroughs, and signups attributed to sends     |
| Search & AI | Visits from search engines and AI assistants, plus AI crawler activity |

You can view each tab daily, weekly, monthly, or all time, and narrow from all published posts down to a single post to see how one piece is doing.

A few notes on the less obvious tabs:

* **Social** needs your X account connected to report followers and post engagement. See [Connections](/agent/connections).
* **Search & AI** separates visits from search engines, visits from AI assistants (ChatGPT, Perplexity, and friends), and AI crawler hits. New sites usually see crawler visits within a few days of publishing.

Need the numbers outside the app? You can export a PDF report from the analytics page.

## Subscriber analytics [#subscriber-analytics]

Subscriber growth and list health have their own view within Analytics. See how your list is trending, and pair it with the Subscribers area for the list itself. More in [Subscribers](/audience/subscribers).

## Ask your agent [#ask-your-agent]

Dashboards show you what happened. Your agent helps with why, and what to do about it. Ask in [chat](/agent/chat):

* "What's my top post from the last month, and why do you think it worked?"
* "How many active subscribers do I have, and how's that trending?"
* "Which posts are quietly losing traffic?"

Your agent also uses these numbers on its own: [distribution](/audience/distribution) repeats the formats that earn readers, and [site maintenance](/publishing/seo) measures every fix against traffic.

## Making sense of the numbers [#making-sense-of-the-numbers]

A few honest framings that help:

* **Watch trends, not days.** Any single day is noise. The weekly and monthly views tell you the truth.
* **Judge each channel by its own job.** A thread's job is the click back to the piece. A newsletter's job is delivery and opens. A post's job is being read.
* **Small lists aren't a problem.** Delivery rate and opens matter more than raw counts while you grow.

## Advanced analytics [#advanced-analytics]

Advanced analytics come with the Scale plan. See [Plans and credits](/account/plans-and-credits) for what's included in each plan.

## Next steps [#next-steps]

<Cards>
  <Card title="Distribution" href="/audience/distribution">
    Act on what the numbers tell you.
  </Card>

  <Card title="Suggestions" href="/agent/suggestions">
    Let your agent turn insights into daily next steps.
  </Card>
</Cards>


# Distribution (/audience/distribution)



Publishing a post is half the job. The other half, turning it into the formats each channel rewards, is work most writers skip because it's tedious. Your agent does it for you.

## What your agent creates from each post [#what-your-agent-creates-from-each-post]

For every post, your agent can produce:

* **X threads** written to earn the click back to the full piece, not to replace it.
* **LinkedIn versions** rewritten for a professional feed, as drafts you can post.
* **Newsletter sends** that deliver the post to your [subscribers](/audience/subscribers) by email.

Each one is an adaptation, not a copy-paste. A thread reads like a thread, and a LinkedIn post reads like it belongs there.

## Nothing posts without you [#nothing-posts-without-you]

Drafts arrive as [suggestions](/agent/suggestions) you can review, edit, or skip. Posting to X, sending an email, anything public, waits for your explicit approval. See [Approvals](/agent/approvals).

## The queue and best-time scheduling [#the-queue-and-best-time-scheduling]

Instead of publishing everything the moment it's ready, your agent keeps a standing queue that spaces out a week of posts. Best-time scheduling slots each piece into the moment your audience is most likely to see it.

The result: a steady presence on your channels from each post you write, without you managing a content calendar.

## Set up each channel [#set-up-each-channel]

**X.** Posting to X requires connecting your X account, available on Starter and above. See [Connections](/agent/connections). Once connected, your agent can post approved threads for you and track how they perform.

**LinkedIn.** Your agent writes LinkedIn versions as drafts for you to post. Ask for one in chat, or let suggestions surface them after you publish.

**Email.** Newsletter delivery works out of the box. See [Newsletters](/publishing/newsletters).

## Ask for it, or let it come to you [#ask-for-it-or-let-it-come-to-you]

Two ways to use distribution:

* **Ask in [chat](/agent/chat).** "Turn my latest post into a thread." "Write a LinkedIn version of my latest post." "Draft a three-post thread about the lessons from my latest piece."
* **Let suggestions surface it.** After you publish, distribution drafts show up in your [daily suggestions](/agent/suggestions), ready to review.

You can also make it recurring with a [scheduled task](/agent/scheduled-tasks), like "Every Monday at 9am, turn my newest post into a thread."

## The learning loop [#the-learning-loop]

Results feed back in. Your agent watches how each format performs, and the formats that earn readers get repeated. Over time your distribution gets more like the things that work for your audience, not a generic playbook.

You can see the numbers yourself in the Social and Newsletter tabs of [Analytics](/audience/analytics), or ask directly: "What did my recent posts on X do well? Suggest one to follow up on."

## Next steps [#next-steps]

<Cards>
  <Card title="Connections" href="/agent/connections">
    Connect your X account so your agent can post for you.
  </Card>

  <Card title="Analytics" href="/audience/analytics">
    See which formats and channels earn readers.
  </Card>
</Cards>


# Subscribers (/audience/subscribers)



Your subscribers are the readers who asked to hear from you. Paragraph treats that list as yours: you can bring it with you, see it clearly, and take it with you at any time.

## The Subscribers area [#the-subscribers-area]

The Subscribers area in [app.paragraph.com](https://app.paragraph.com) lists everyone on your list, with when they joined and where they came from. You can:

* **Search** for a specific subscriber.
* **Filter by status**: active, unsubscribed, or all.
* **Filter by source**: organic, imported, or manual.

The sources mean what you'd expect:

| Source   | What it means                          |
| -------- | -------------------------------------- |
| Organic  | Subscribed through your site or a post |
| Imported | Came in with a list you imported       |
| Manual   | Added by hand                          |

## How readers subscribe [#how-readers-subscribe]

Your [website](/publishing/website) includes subscribe prompts, so readers can join your list from any post or page. Once subscribed, they receive the posts you [deliver by email](/publishing/newsletters).

Readers can unsubscribe from any email you send. Unsubscribed readers stay visible in your list (filtered under "Unsubscribed"), but they don't receive sends.

## Import your list [#import-your-list]

Moving from Substack, or anywhere else? Bring your list with you as a CSV.

<Steps>
  <Step>
    Export your subscribers from your current platform. Every major platform offers a CSV export.
  </Step>

  <Step>
    Check the file has an email column. That's the only thing Paragraph needs, extra columns are fine.
  </Step>

  <Step>
    Open Chat, attach the CSV, and ask your agent to import the subscribers from it. CSV files can be up to 10 MB, and the import continues in the background. The [import guide](/getting-started/import-your-publication) walks through bringing over subscribers and posts together.
  </Step>
</Steps>

<Callout type="info">
  Imported subscribers start receiving your future sends, the same as they did on your old platform, and they show up in your list with the "Imported" source.
</Callout>

If your import is large or the file is unusual, email [support@paragraph.com](mailto:support@paragraph.com) and we'll help you bring it across.

## Export your list [#export-your-list]

Export is always available. Your list is yours, full stop, and you can download it whenever you like: as a backup, for analysis, or to leave (though we'd rather you stayed). If you can't find what you need, [support@paragraph.com](mailto:support@paragraph.com) will get you a copy.

## Understand your list [#understand-your-list]

Subscriber analytics live in the [Analytics](/audience/analytics) area, where you can see growth over time and how your list is trending.

Your agent is often the fastest route to an answer, though. Ask in [chat](/agent/chat):

* "How many active subscribers do I have, and how's that trending?"
* "How many subscribers joined this month, and from where?"

## Next steps [#next-steps]

<Cards>
  <Card title="Newsletters" href="/publishing/newsletters">
    Send your posts to this list by email.
  </Card>

  <Card title="Analytics" href="/audience/analytics">
    See subscriber growth and engagement over time.
  </Card>
</Cards>


# Agent skills (/developers/agent-skills)



[Paragraph agent skills](https://github.com/paragraph-xyz/skill) are portable instructions that teach AI agents (Claude Code, Cursor, and others) how to work with Paragraph. They follow the [Agent Skills](https://agentskills.io) standard.

The skills include working agreements, commands and endpoints with examples, JSON response shapes, and common patterns.

## Available skills [#available-skills]

| Skill           | Covers                                                       | Install required                          |
| --------------- | ------------------------------------------------------------ | ----------------------------------------- |
| `paragraph-cli` | The [CLI](/developers/cli) and [MCP server](/developers/mcp) | Yes (`npm install -g @paragraph-com/cli`) |
| `paragraph-api` | The REST API and [TypeScript SDK](/developers/sdk)           | No                                        |

## Install [#install]

Install all skills:

```bash
npx skills add paragraph-xyz/skill
```

Install a specific skill:

```bash
npx skills add paragraph-xyz/skill --skill paragraph-api
npx skills add paragraph-xyz/skill --skill paragraph-cli
```

Or manually copy the `SKILL.md` file into your agent's skills directory:

| Agent       | Path                                     |
| ----------- | ---------------------------------------- |
| Claude Code | `~/.claude/skills/<skill-name>/SKILL.md` |
| Cursor      | `.cursor/skills/<skill-name>/SKILL.md`   |
| Any agent   | Check your agent's skill directory       |

## No install: paste a prompt [#no-install-paste-a-prompt]

If you can't install skills, you can paste a short prompt into your agent's context instead. It covers the MCP server, CLI, REST API, and SDK.

<Accordions>
  <Accordion title="Copy agent prompt">
    ```text title="Paragraph agent prompt"
    # Paragraph — Publishing & Newsletter Platform

    You can manage posts, publications, subscribers, and coins on paragraph.com.

    Use the **MCP server** for the best experience, the **CLI** for shell access, or the **REST API** directly.

    ## MCP Server (recommended)

    Connect to the hosted server — no installation or API key management needed:

    claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp

    Or add {"url": "https://mcp.paragraph.com/mcp"} to your MCP config for Claude Desktop, Cursor, or VS Code.

    ## CLI (shell access)

    Install: npm install -g @paragraph-com/cli

    Authenticate: paragraph login

    ### Posts
    paragraph post create --title "My Post" --file ./draft.md
    paragraph post list --json
    paragraph post get <id> --json
    paragraph post update <id> --title "New Title"
    paragraph post publish <id>
    paragraph post schedule <id> --at "2026-05-01T09:00:00Z"
    paragraph post unschedule <id>
    paragraph post delete <id> --yes
    paragraph search post --query "ethereum" --json

    ### Subscribers
    paragraph subscriber list --json
    paragraph subscriber add --email user@example.com
    paragraph subscriber add --wallet 0x1234...abcd
    paragraph subscriber count <publication-id>

    ### Publications & Coins
    paragraph publication get <slug> --json
    paragraph coin get <id-or-address> --json
    paragraph coin popular --json

    Always use --json for structured output when processing results programmatically.

    ## REST API (no install)

    Base URL: https://public.api.paragraph.com/api

    Auth: pass API key as Bearer token in Authorization header.
    Get a key at app.paragraph.com -> Settings -> Publication -> Developer.

    ### Key endpoints
    GET  /v1/posts/<id>                              — get post
    GET  /v1/publications/slug/<slug>                — get publication
    POST /v1/posts                                   — create post (auth required)
    PUT  /v1/posts/<id>                              — update post (auth required)
    GET  /v1/subscribers                             — list subscribers (auth required)
    POST /v1/subscribers                             — add subscriber (auth required)
    GET  /v1/discover/search?q=<query>               — search posts

    ### Create a post (curl)
    curl -X POST https://public.api.paragraph.com/api/v1/posts \
      -H "Authorization: Bearer <api-key>" \
      -H "Content-Type: application/json" \
      -d '{"title": "My Post", "markdown": "# Hello World"}'

    ### Schedule a post for future publication
    curl -X POST https://public.api.paragraph.com/api/v1/posts \
      -H "Authorization: Bearer <api-key>" \
      -H "Content-Type: application/json" \
      -d '{"title": "My Post", "markdown": "# Hello", "scheduledAt": 1746090000000}'

    PUT /v1/posts/<id> with {"scheduledAt": <unix-ms>} to schedule a draft.
    PUT /v1/posts/<id> with {"scheduledAt": null} to cancel.

    ## TypeScript SDK

    npm install @paragraph-com/sdk

    import { ParagraphAPI } from "@paragraph-com/sdk"
    const api = new ParagraphAPI({ apiKey: "<api-key>" })

    const post = await api.posts.create({ title: "My Post", markdown: "# Hello" })
    const scheduled = await api.posts.create({ title: "My Post", markdown: "# Hello", scheduledAt: Date.now() + 86400000 })
    const { items } = await api.posts.list()
    const pub = await api.publications.get({ slug: "@blog" }).single()
    const results = await api.search.posts("ethereum")

    OpenAPI spec: https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json
    Full docs: https://docs.paragraph.com/llms-full.txt
    ```
  </Accordion>
</Accordions>

You can also give your agent complete knowledge of Paragraph's API by sharing [llms-full.txt](https://docs.paragraph.com/llms-full.txt). Every page on this docs site also has a Markdown variant (append `.md` to the URL).

## Prefer MCP? [#prefer-mcp]

For MCP-compatible clients, you can skip skills entirely and use the hosted Paragraph MCP server. No CLI or API key required:

```bash
claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp
```

See the [MCP server guide](/developers/mcp) for client-specific setup.

## Resources [#resources]

<Cards>
  <Card title="View on GitHub" href="https://github.com/paragraph-xyz/skill">
    Explore the skills, contribute, or report issues.
  </Card>

  <Card title="Agent Skills standard" href="https://agentskills.io">
    Learn about the portable skill format these skills follow.
  </Card>
</Cards>


# CLI (/developers/cli)



The Paragraph CLI is a command-line tool for managing posts, publications, subscribers, and coins. It works for both human and programmatic (agent) usage.

<Callout type="info">
  **Prerequisites**: Node.js version 18 or higher (not needed for the Homebrew install).
</Callout>

## Install [#install]

<Tabs items="[&#x22;npm&#x22;, &#x22;Homebrew&#x22;]">
  <Tab value="npm">
    ```bash
    npm install -g @paragraph-com/cli
    ```
  </Tab>

  <Tab value="Homebrew">
    ```bash
    brew tap paragraph-xyz/tap && brew install paragraph
    ```
  </Tab>
</Tabs>

## Authentication [#authentication]

Get your API key in the app at [app.paragraph.com](https://app.paragraph.com) under **Settings -> Publication -> Developer**.

<Steps>
  <Step>
    ### Authenticate [#authenticate]

    ```bash
    paragraph login
    ```

    Or provide the key directly:

    ```bash
    paragraph login --token <your-api-key>
    ```
  </Step>

  <Step>
    ### Verify [#verify]

    ```bash
    paragraph whoami
    ```
  </Step>
</Steps>

For CI or agent environments, you can pipe the token or set an environment variable:

```bash
echo "<your-api-key>" | paragraph login --with-token

PARAGRAPH_API_KEY=<your-api-key> paragraph post list
```

Credentials are stored in `~/.paragraph/config.json` (mode 0600).

## Quick examples [#quick-examples]

```bash
paragraph post create --title "My Post" --file ./draft.md

paragraph post publish my-post

paragraph post list

paragraph search post --query "ethereum"
```

Run `paragraph --help` for all commands, or `paragraph <command> --help` for details on any command.

<Callout type="info">
  Using an AI agent like Claude Code or Cursor? Install the [Paragraph CLI skill](/developers/agent-skills) to teach it how to use the CLI:

  ```bash
  npx skills add paragraph-xyz/skill --skill paragraph-cli
  ```
</Callout>

## Command reference [#command-reference]

### Posts [#posts]

#### List posts [#list-posts]

```bash
paragraph post list
paragraph post list --status draft
paragraph post list --limit 50 --cursor <cursor>

# List posts from any publication (public, no auth required)
paragraph post list --publication <id-or-slug>
```

#### Get a post [#get-a-post]

Accepts an ID, URL, or `@publication/slug`:

```bash
paragraph post get <post-id>
paragraph post get @yearn/some-post-slug
paragraph post get https://paragraph.com/@yearn/some-post-slug
```

Extract a single field (raw value to stdout, pipeable):

```bash
paragraph post get <id> --field markdown > post.md
paragraph post get <id> --field title
```

#### Create a post [#create-a-post]

Creates a draft by default:

```bash
paragraph post create --title "My Post" --text "# Hello World"
paragraph post create --title "My Post" --file ./draft.md
cat draft.md | paragraph post create --title "From Stdin"
paragraph post create --title "Post" --text "Content" --subtitle "Summary" --tags "web3,defi"
```

#### Update a post [#update-a-post]

```bash
paragraph post update <id-or-slug> --title "New Title"
paragraph post update <id-or-slug> --file ./updated.md --tags "new,tags"
```

#### Post lifecycle [#post-lifecycle]

```bash
paragraph post publish <id-or-slug>
paragraph post publish <id-or-slug> --newsletter     # publish + email subscribers
paragraph post draft <id-or-slug>                     # revert to draft
paragraph post archive <id-or-slug>
```

#### Preview and test [#preview-and-test]

```bash
paragraph post publish <id-or-slug> --dry-run
paragraph post delete <id-or-slug> --dry-run
paragraph post test-email <id>                        # send test email (drafts only)
```

#### Delete a post [#delete-a-post]

```bash
paragraph post delete <id-or-slug>
paragraph post delete <id-or-slug> --yes              # skip confirmation
```

#### Browse posts [#browse-posts]

```bash
paragraph post by-tag defi --limit 20
paragraph post feed --limit 10
```

#### Shortcuts [#shortcuts]

Top-level shortcuts for common operations:

```bash
paragraph create --title "Quick Post" --text "Content"
paragraph update my-post-slug --title "Updated"
paragraph delete my-post-slug --yes
```

### Publications [#publications]

```bash
paragraph publication get @variantwriting
paragraph publication get blog.variant.fund
paragraph publication get <publication-id>
```

### Search [#search]

```bash
paragraph search post --query "ethereum"
paragraph search blog --query "web3"
```

### Subscribers [#subscribers]

```bash
paragraph subscriber list --limit 100
paragraph subscriber count <publication-id>
paragraph subscriber add --email user@example.com
paragraph subscriber add --wallet 0x1234...abcd
paragraph subscriber import --csv subscribers.csv
```

### Coins [#coins]

```bash
paragraph coin get <id-or-address>
paragraph coin popular --limit 10
paragraph coin search --query "test"
paragraph coin holders <id-or-address> --limit 50
paragraph coin quote <id-or-address> --amount <wei>
```

### Users [#users]

```bash
paragraph user get <user-id>
paragraph user get 0x1234...    # by wallet address
```

## Agent and programmatic usage [#agent-and-programmatic-usage]

The CLI is designed for use by AI agents and scripts.

### JSON output [#json-output]

All commands support `--json`. Data goes to **stdout**, status messages to **stderr**:

```bash
paragraph --json post list | jq '.data[0].title'
paragraph --json post get <id> | jq '.markdown'
paragraph --json search post --query "web3" | jq '.length'
```

Paginated commands return:

```json
{
  "data": [{ "id": "...", "title": "..." }],
  "pagination": { "cursor": "abc123", "hasMore": true }
}
```

Single-item commands return the object directly:

```json
{ "id": "...", "title": "...", "markdown": "..." }
```

### Structured errors [#structured-errors]

In `--json` mode, errors are structured JSON on **stderr** with a non-zero exit code:

```json
{ "error": "Not found.", "code": "NOT_FOUND", "status": 404 }
```

Error codes: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMITED`, `SERVER_ERROR`, `REQUEST_FAILED`, `CLIENT_ERROR`, `UNKNOWN`.

### Non-interactive safety [#non-interactive-safety]

* `delete` requires `--yes` in non-TTY environments
* `login` supports `--with-token` for stdin piping and `--token` for direct input
* Destructive commands support `--dry-run`
* Set `PARAGRAPH_NON_INTERACTIVE=1` or `CI=true` to force CLI mode

### Environment variables [#environment-variables]

| Variable                    | Purpose                          |
| --------------------------- | -------------------------------- |
| `PARAGRAPH_API_KEY`         | API key (alternative to `login`) |
| `PARAGRAPH_API_URL`         | Custom API base URL              |
| `PARAGRAPH_NON_INTERACTIVE` | Set to `1` to disable TUI        |
| `CI`                        | Set to `true` to disable TUI     |

## Interactive TUI [#interactive-tui]

Running `paragraph` with no arguments launches an interactive terminal UI with menus, scrollable lists, and keyboard navigation.

The TUI is disabled automatically when:

* `--json`, `--help`, or `--version` flags are used
* stdout is not a TTY (e.g., piped output)
* `CI=true` or `PARAGRAPH_NON_INTERACTIVE=1` is set

## Resources [#resources]

<Cards>
  <Card title="View on GitHub" href="https://github.com/paragraph-xyz/paragraph-cli">
    Explore the source code or report issues.
  </Card>

  <Card title="npm package" href="https://www.npmjs.com/package/@paragraph-com/cli">
    View on npm.
  </Card>
</Cards>


# Build with Paragraph (/developers)



Paragraph provides an API for building applications on top of its publishing platform. Access publication data, manage posts, work with coins, and integrate user profiles, all through a simple REST API or our TypeScript SDK.

<Callout type="info">
  A few things to know before you start:

  * The API is in alpha. There may be breaking changes until we finalize the design.
  * The API is rate-limited. If you're hitting rate limits and want to request an increase, reach out to [support@paragraph.com](mailto:support@paragraph.com).
  * Some endpoints require authentication via an API key. Generate one in the app at [app.paragraph.com](https://app.paragraph.com) under **Settings -> Publication -> Developer**.
</Callout>

## Pick your tool [#pick-your-tool]

<Cards>
  <Card title="TypeScript SDK" href="/developers/sdk">
    Install our TypeScript SDK and start building in minutes with full type safety and intuitive methods.
  </Card>

  <Card title="CLI" href="/developers/cli">
    Manage posts, publications, and subscribers from the command line. Works with AI agents and CI pipelines.
  </Card>

  <Card title="MCP server" href="/developers/mcp">
    Let AI agents interact with Paragraph directly via the Model Context Protocol.
  </Card>

  <Card title="Agent skills" href="/developers/agent-skills">
    Install portable skills that teach any AI agent how to use the Paragraph API, CLI, or MCP server.
  </Card>
</Cards>

## The REST API [#the-rest-api]

Prefer raw HTTP? The API is served at `https://public.api.paragraph.com/api`. Authenticated endpoints take your API key as a Bearer token in the `Authorization` header.

Every endpoint is described in the [OpenAPI spec](https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json), which you can also use for code generation and API exploration. The spec lives in the [SDK repository](https://github.com/paragraph-xyz/paragraph-sdk-js).

## Core features [#core-features]

* **Publications**: access publication metadata, settings, and content collections.
* **Posts**: fetch posts with pagination, filtering, and full content support.
* **Coins**: integrate coin functionality for monetization and community support.
* **User profiles**: retrieve user data including wallet addresses and Farcaster profiles.

## Use with AI tools [#use-with-ai-tools]

Building with an AI assistant like Claude Code, Cursor, or ChatGPT? A few things make that easier:

* **This docs site is agent-readable.** We serve [llms.txt](https://docs.paragraph.com/llms.txt) and [llms-full.txt](https://docs.paragraph.com/llms-full.txt), and every page has a Markdown variant (append `.md` to any page URL). Paste llms-full.txt into your LLM conversation to give it complete knowledge of Paragraph's API endpoints, data models, and capabilities.
* **The [MCP server](/developers/mcp)** connects agents directly to Paragraph, with hosted and local options.
* **The [agent skills](/developers/agent-skills)** teach agents the CLI, REST API, SDK, and MCP server, including commands with examples, JSON response shapes, and common patterns.
* **The [CLI](/developers/cli)** is designed for agent and programmatic usage. All commands support `--json` for structured output.

## Resources [#resources]

<Cards>
  <Card title="SDK on GitHub" href="https://github.com/paragraph-xyz/paragraph-sdk-js">
    Explore the SDK source code, contribute, or report issues.
  </Card>

  <Card title="OpenAPI spec" href="https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json">
    The complete API surface, ready for code generation and exploration.
  </Card>
</Cards>


# MCP server (/developers/mcp)



The Paragraph MCP server lets AI agents interact with Paragraph directly. Manage posts, publications, subscribers, coins, and more from any MCP-compatible client.

<Callout type="info">
  This page is about giving your AI tools (Claude Code, Cursor, and so on) access to Paragraph's API. If you want the opposite (connecting external tools to your Paragraph agent so it can use them), see [agent connections](/agent/connections).
</Callout>

## Quick start [#quick-start]

The fastest way to get started is with the hosted server at `mcp.paragraph.com`. No installation or API key management needed. You authenticate through your Paragraph account in the browser.

<Tabs items="[&#x22;Claude Code&#x22;, &#x22;Claude Desktop&#x22;, &#x22;Cursor&#x22;, &#x22;VS Code&#x22;]">
  <Tab value="Claude Code">
    ```bash
    claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp
    ```
  </Tab>

  <Tab value="Claude Desktop">
    Add to your `claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "paragraph": {
          "url": "https://mcp.paragraph.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab value="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json
    {
      "mcpServers": {
        "paragraph": {
          "url": "https://mcp.paragraph.com/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab value="VS Code">
    Add to `.vscode/mcp.json` in your project root:

    ```json
    {
      "servers": {
        "paragraph": {
          "url": "https://mcp.paragraph.com/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Local server [#local-server]

If you prefer to run the server locally, use npx. Requires Node.js 18+.

```bash
npx @paragraph-com/mcp
```

The server runs over stdio and works with any MCP client.

<Tabs items="[&#x22;Claude Code&#x22;, &#x22;Claude Desktop&#x22;, &#x22;Cursor&#x22;, &#x22;VS Code&#x22;]">
  <Tab value="Claude Code">
    ```bash
    claude mcp add paragraph -- npx @paragraph-com/mcp
    ```

    To include your API key:

    ```bash
    claude mcp add --env PARAGRAPH_API_KEY=your-key paragraph -- npx @paragraph-com/mcp
    ```
  </Tab>

  <Tab value="Claude Desktop">
    Add to your `claude_desktop_config.json`:

    ```json
    {
      "mcpServers": {
        "paragraph": {
          "command": "npx",
          "args": ["@paragraph-com/mcp"],
          "env": {
            "PARAGRAPH_API_KEY": "your-key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json
    {
      "mcpServers": {
        "paragraph": {
          "command": "npx",
          "args": ["@paragraph-com/mcp"],
          "env": {
            "PARAGRAPH_API_KEY": "your-key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab value="VS Code">
    Add to `.vscode/mcp.json` in your project root:

    ```json
    {
      "servers": {
        "paragraph": {
          "command": "npx",
          "args": ["@paragraph-com/mcp"],
          "env": {
            "PARAGRAPH_API_KEY": "your-key"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Authentication [#authentication]

The remote server at `mcp.paragraph.com` handles authentication automatically. When you first connect, you'll be redirected to approve access through your Paragraph account in the browser.

For the local server, the MCP server resolves your API key in this order:

1. **`PARAGRAPH_API_KEY` environment variable** (highest priority)
2. **Shared CLI config** at `~/.paragraph/config.json` (set via `npx @paragraph-com/cli login`)

Get your API key in the app at [app.paragraph.com](https://app.paragraph.com) under **Settings -> Publication -> Developer**.

<Callout type="info">
  Read-only tools like search, feed, and public post fetching work without authentication. You only need to authenticate for write operations and accessing your own publication data.
</Callout>

## Available tools [#available-tools]

The server exposes 18 tools organized into toolsets:

| Toolset          | Tools                                                                                    | Auth required  |
| ---------------- | ---------------------------------------------------------------------------------------- | -------------- |
| **posts**        | `get-post`, `list-posts`, `create-post`, `update-post`, `delete-post`, `send-test-email` | Write ops only |
| **publications** | `get-publication`                                                                        | No             |
| **subscribers**  | `list-subscribers`, `get-subscriber-count`, `add-subscriber`                             | Yes            |
| **users**        | `get-user`                                                                               | No             |
| **coins**        | `get-coin`, `list-coin-holders`                                                          | No             |
| **search**       | `search-posts`, `search-blogs`, `search-coins`                                           | No             |
| **feed**         | `get-feed`                                                                               | No             |
| **me**           | `get-me`                                                                                 | Yes            |

## Filtering toolsets [#filtering-toolsets]

Expose only the tools your agent needs to reduce context usage:

```bash
npx @paragraph-com/mcp --toolsets posts,search
```

Available toolset names: `posts`, `publications`, `subscribers`, `users`, `coins`, `search`, `feed`, `me`

## HTTP mode [#http-mode]

For server deployments, run the MCP server over HTTP instead of stdio:

```bash
npx @paragraph-com/mcp --http --port 3100
```

The HTTP server binds to `127.0.0.1` (localhost only) and accepts POST requests. A health check is available at `GET /health`.

## Resources [#resources]

<Cards>
  <Card title="View on GitHub" href="https://github.com/paragraph-xyz/paragraph-mcp">
    Explore the source code or report issues.
  </Card>

  <Card title="npm package" href="https://www.npmjs.com/package/@paragraph-com/mcp">
    View on npm.
  </Card>
</Cards>


# TypeScript SDK (/developers/sdk)



The Paragraph SDK is a TypeScript wrapper around our REST API. All functionality in the SDK is described in the [OpenAPI spec](https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json), in the repository on [GitHub](https://github.com/paragraph-xyz/paragraph-sdk-js), and in the documentation on [npm](https://www.npmjs.com/package/@paragraph-com/sdk).

<Callout type="info">
  **Prerequisites**: Node.js version 18 or higher.
</Callout>

## Getting started [#getting-started]

<Steps>
  <Step>
    ### Install the SDK [#install-the-sdk]

    ```bash
    npm i @paragraph-com/sdk
    ```
  </Step>

  <Step>
    ### Instantiate the class [#instantiate-the-class]

    Instantiate the `ParagraphAPI` class.

    ```typescript
    import { ParagraphAPI } from "@paragraph-com/sdk"

    // For public endpoints (no API key required)
    const api = new ParagraphAPI()

    // For protected endpoints (API key required)
    const apiWithAuth = new ParagraphAPI({ apiKey: "your-api-key" })
    ```

    You can generate an API key in the app at [app.paragraph.com](https://app.paragraph.com) under **Settings -> Publication -> Developer**.
  </Step>

  <Step>
    ### Query data [#query-data]

    ```typescript
    // Fetch a publication by slug (use .single() for single object)
    const publication = await api.publications.get({ slug: "@blog" }).single()
    console.log(`Fetched publication: ${publication}`)

    // Fetch posts (paginated list)
    const { items: posts, pagination } = await api.posts.get({ publicationId: publication.id })

    console.log(`Fetched ${posts.length} posts from @blog, out of ${pagination.total} posts: ${JSON.stringify(posts)}`)
    ```
  </Step>
</Steps>

## Examples [#examples]

Practical examples for common use cases. Each one assumes you've installed and initialized the SDK as shown above.

### Fetching paginated posts [#fetching-paginated-posts]

Retrieve posts from a publication with pagination support. This example demonstrates how to fetch multiple pages of posts using cursor-based pagination.

```typescript
/**
 * Given a Paragraph publication slug, fetch the first two
 * pages of posts.
 */
async function fetchParagraphPosts(slug: string) {
  const publication = await api.publications.get({ slug }).single()
  console.log("Publication:", publication)

  const posts = []

  const firstBatch = await api.posts.get({ publicationId: publication.id })
  posts.push(...firstBatch.items)

  console.log("Posts:", firstBatch.items)

  if (firstBatch.pagination.hasMore && firstBatch.pagination.cursor) {
    const secondBatch = await api.posts.get({
      publicationId: publication.id,
      cursor: firstBatch.pagination.cursor
    })
    posts.push(...secondBatch.items)
  }

  console.log(`Last ${posts.length} posts from ${slug}, out of ${firstBatch.pagination.total} posts: ${JSON.stringify(firstBatch.items)}`)
}
```

<Accordions>
  <Accordion title="Example response">
    ```json
    Last 2 posts from @blog, out of 39 posts: [
      {
        "id": "jBY6aEvHXTneYkxnHQ9k",
        "title": "What We're Learning from Coins on Paragraph",
        "slug": "what-were-learning-from-coins-on-paragraph",
        "staticHtml": "<h3>Why coins?</h3><p>It's been a little over a month since we...[truncated]",
        "json": "{\"type\":\"doc\",\"content\":[{\"type\":\"heading\",\"attrs\":{\"textAlign\":\"left\",\"level\":3}...[truncated]",
        "markdown": "### Why coins?\n\nIt's been a little over a month since we [shipped]...[truncated]",
        "coinId": "MTmpnfHJWMTcd84d9kWB",
        "publishedAt": "2025-09-03T14:30:09.640Z",
        "updatedAt": "2025-09-04T20:33:28.966Z"
      },
    ]

    Pagination: {
      "cursor": "eyJjcmVhdGVkQXQiOiIyMDI1LTA5LTA1VDEwOjE1OjMyLjAwMFoifQ",
      "hasMore": true,
      "total": 39
    }
    ```
  </Accordion>
</Accordions>

### Working with coins and holders [#working-with-coins-and-holders]

Fetch coin information and holder data associated with a specific post. This example shows how to retrieve monetization details for content.

```typescript
/**
 * Given a publication & post slug, fetch coin & holders.
 */
async function fetchCoinFromPost(publicationSlug: string, postSlug: string) {
  const publication = await api.publications.get({ slug: publicationSlug }).single()
  const publicationId = publication.id

  const post = await api.posts.get({
    publicationId: publicationId,
    slug: postSlug
  }).single()

  if (post.coinId) {
    const [coin, holders] = await Promise.all([
      api.coins.get({ id: post.coinId }).single(),
      api.coins.getHolders({ id: post.coinId })
    ])
    console.log("Fetched coin & holders from post:", coin, holders)
  }
}
```

<Accordions>
  <Accordion title="Example response">
    ```json
    Fetched coin & holders from post:
    {
      "id": "N3j7OrRYuRKZQM1rhYEh",
      "contractAddress": "0xe9bb3166ff5f96381e257d509a801303b68e5d34",
      "symbol": "WDLA8I",
      "postId": "WDla8iypUlssljGYjk3h"
    }
    {
      "items": [
        {
          "walletAddress": "0xf3EA0031318D72bc1094F1F7757eA0C21AB7B9d8",
          "balance": "692968251623303893599919671",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0xe9bb3166ff5F96381E257d509a801303b68E5D34",
          "balance": "100000000000000000000000000",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0x7f9E22F20dcFC3DeC17b46399cc584efB8c5A258",
          "balance": "20199589120082817066031281",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0x34D600129974704933a7E2619FB98c9fe030Fcb5",
          "balance": "17897201041146921014305499",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0x11111113eA761E8605CE2bb5051F74D2940E3B6B",
          "balance": "15009842364429493492778480",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0xAf328cD95630B34fc7E3f38d268666F3EbD78cC7",
          "balance": "14140720297880197457303025",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0xF0344f61EDF4599a46743A92fBBa74d365B16352",
          "balance": "13730282600000000000000000",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0x44dF085447dBEBCf69C6675c3B8A795c7fdeB3F4",
          "balance": "12301804207719445739306739",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0xd53c3e1e2c76165C675Aa7ADd2630f4c78B8C8aE",
          "balance": "10900130118020538645621876",
          "supportedAt": "2025-09-09T18:17:55.599Z"
        },
        {
          "walletAddress": "0x74BE1a3d4C5aF15a22ca1BFc27C1fA6084caDd78",
          "balance": "10336598882089679867027544",
          "supportedAt": "2025-09-09T18:17:55.599Z",
          "userId": "UwjHeDkUp0tGTvgCd585"
        }
      ],
      "pagination": {
        "cursor": "0x000000000000000000000000000000000000000000084595163347d29334c08faee989fda15dfa276bebf116b81d26ba233235ce",
        "hasMore": true,
        "total": 205
      }
    }
    ```
  </Accordion>
</Accordions>

### User profile lookup [#user-profile-lookup]

Retrieve user profile information by wallet address, including any associated Farcaster profiles.

```typescript
/**
 * Given a wallet address, fetch the user profile including
 * any associated Farcaster profile.
 */
async function getUserProfileByWallet(walletAddress: string) {
  const user = await api.users.get({ wallet: walletAddress }).single()

  console.log("User profile:", user)
}
```

<Accordions>
  <Accordion title="Example response">
    ```json
    User profile: {
      "id": "AeAOtR8TqKWyzG5apA1R",
      "walletAddress": "0xc9ddb5E37165827BBBFf15b582E232C06862C4E8",
      "avatarUrl": "https://storage.googleapis.com/papyrus_images/cb027d7a045c7c1d6b6700d9c95b2f56",
      "publicationId": "BMV6abfvCSUl51ErCVzd",
      "name": "Colin Armstrong",
      "farcaster": {
        "fid": 12312,
        "username": "paragraph",
        "displayName": "Paragraph"
      }
    }
    ```
  </Accordion>
</Accordions>

## Next steps [#next-steps]

* Browse the [OpenAPI spec](https://github.com/paragraph-xyz/paragraph-sdk-js/blob/main/openapi.json) for the full API surface.
* View the [SDK repository](https://github.com/paragraph-xyz/paragraph-sdk-js) for more examples.
* Check out the [npm package](https://www.npmjs.com/package/@paragraph-com/sdk) for version information.


# Import your publication (/getting-started/import-your-publication)



Already publishing somewhere else? You can bring your writing and your subscriber list with you. Nothing gets locked in on the way out of your old platform, and nothing gets locked in here either. On Paragraph, your list is yours, and you can [export it any time](/account/manage-account).

## Before you start [#before-you-start]

Export your data from your current platform. Most platforms (including Substack and Beehiiv) let you download:

* **A subscriber list** as a CSV file of email addresses.
* **A post archive**, usually as a file containing your published posts.

Grab both before you begin. If your platform buries the export option, its help docs will point you to it.

## Import your subscribers [#import-your-subscribers]

<Steps>
  <Step>
    ### Check your CSV [#check-your-csv]

    Your file needs a column of email addresses. If your export includes extra columns (names, signup dates, and so on), that's fine.
  </Step>

  <Step>
    ### Upload it [#upload-it]

    Open Chat, attach the CSV, and ask your agent to import the subscribers from it. CSV files can be up to 10 MB. The agent starts the import in the background, so you can keep working while it runs.
  </Step>

  <Step>
    ### Confirm the results [#confirm-the-results]

    Once the import finishes, your subscribers appear in [Subscribers](/audience/subscribers). Spot-check the count against your old platform to make sure everyone made it over.
  </Step>
</Steps>

<Callout type="info">
  Only import lists of people who signed up to hear from you. Purchased or scraped lists hurt your deliverability and aren't allowed.
</Callout>

## Import your posts [#import-your-posts]

Your agent can help you migrate your content. Share your export file, or tell it where your old publication lives, and ask it to bring your posts over. It helps carry your writing across so you don't have to rebuild your archive by hand.

After the import, skim a few posts to check formatting, especially images and embeds. If something didn't survive the trip, your agent can help clean it up.

<Callout type="info">
  On the [Scale plan](/account/plans-and-credits), migration help from our team is included. We'll help move your publication over with you.
</Callout>

## After you import [#after-you-import]

* **Point your domain at Paragraph.** If your old publication used a custom domain, set it up here so old links keep working. See [custom domains](/publishing/custom-domains).
* **Tell your readers.** Send a short post letting subscribers know where you've moved. Email delivery continues from Paragraph, so most readers won't need to do anything.
* **Check your SEO basics.** See [SEO](/publishing/seo) to keep search traffic flowing to your new home.

## Need help? [#need-help]

If an import misbehaves, or your old platform's export is in an odd format, email [support@paragraph.com](mailto:support@paragraph.com). We've moved a lot of publications and we're happy to help with yours.


# Quickstart (/getting-started/quickstart)



This guide takes you from zero to a published post. It takes about ten minutes, and most of that is writing.

<Steps>
  <Step>
    ### Create your account [#create-your-account]

    Go to [app.paragraph.com](https://app.paragraph.com) and sign up. You can use your email address or another login option. No password required.
  </Step>

  <Step>
    ### Meet your agent [#meet-your-agent]

    When you first sign in, Paragraph sets up your personal agent and starts a short onboarding conversation. This is worth doing properly, not rushing.

    Tell your agent who you are, what you write about, and who you write for. It uses this to set up your publication and to sound like you later, in drafts, suggestions, and social posts. You can refine all of this any time in [voice and memory](/agent/voice-and-memory).
  </Step>

  <Step>
    ### Land in your workspace [#land-in-your-workspace]

    After onboarding, you arrive in your workspace. Home gives you an overview and a place to start a chat. The sidebar holds everything else: the editor, your subscribers, analytics, and settings.

    Not sure where things live? Take the [workspace tour](/getting-started/workspace-tour).
  </Step>

  <Step>
    ### Write your first post [#write-your-first-post]

    You have two good options:

    * **Write it yourself.** Open the Editor and start typing. It's a clean, focused writing surface. See [the editor](/publishing/editor) for what it can do.
    * **Start with your agent.** In Chat, describe the post you want. Your agent can research the topic, propose an outline, or write a first draft for you to shape.

    Most writers end up mixing both. Draft with the agent, then rewrite in your own words in the editor.
  </Step>

  <Step>
    ### Publish [#publish]

    When your post is ready, publish it. It goes live on your website right away. You can also send it to your subscribers as a newsletter, so it lands in their inboxes too. See [newsletters](/publishing/newsletters) for how sending works.

    That's it. You have a site, a post, and a list ready to grow.
  </Step>
</Steps>

<Callout type="info">
  Your agent never publishes or sends anything important without your sign-off. You review its work in [suggestions](/agent/suggestions), and you can tune what needs approval in [approvals](/agent/approvals).
</Callout>

## What's next [#whats-next]

<Cards>
  <Card title="Import your publication" href="/getting-started/import-your-publication">
    Bring your posts and subscribers from Substack or another platform.
  </Card>

  <Card title="Set up a custom domain" href="/publishing/custom-domains">
    Put your site on your own domain (available on Starter and above).
  </Card>

  <Card title="Connect your accounts" href="/agent/connections">
    Let your agent share your posts to social and work across your tools.
  </Card>

  <Card title="Set up recurring work" href="/agent/scheduled-tasks">
    Hand off research digests, social sharing, and other repeat tasks.
  </Card>
</Cards>


# Workspace tour (/getting-started/workspace-tour)



Your workspace at [app.paragraph.com](https://app.paragraph.com) is where you write, talk to your agent, and manage your publication. Here's what each area does and when you'll use it.

## Home [#home]

Your overview and starting point. Home shows you what's going on across your publication and gives you a quick way into a conversation with your agent.

## Chat [#chat]

Where you talk to your agent. Ask it to research a topic, draft a post, share something to social, or change your website. Conversations are organized into sessions, so you can keep separate threads for separate projects. See [chat](/agent/chat).

## Editor [#editor]

Where you write. Posts and pages both live here. Draft, edit, and publish to your site and newsletter. See [the editor](/publishing/editor).

## Schedule [#schedule]

Your agent's calendar. Schedule shows scheduled tasks (recurring work you've handed off, like a weekly research digest) and queued suggestions waiting for their turn. See [scheduled tasks](/agent/scheduled-tasks).

## Suggestions [#suggestions]

Proposals from your agent, waiting for your review. Drafts, social posts, site changes, and other work land here before anything ships. Approve what you like, edit what's close, and dismiss the rest. See [suggestions](/agent/suggestions) and [approvals](/agent/approvals).

## Subscribers [#subscribers]

Your list. See who's subscribed, import readers from another platform, and export your list whenever you want. It's yours. See [subscribers](/audience/subscribers).

## Analytics [#analytics]

How your writing is doing. Track your posts and your audience, including subscriber analytics, so you can see what's resonating and where readers come from. See [analytics](/audience/analytics).

## Files [#files]

Files you've uploaded or that your agent is working with, all in one place.

## Notifications [#notifications]

Activity that needs your attention, like agent work that's ready for review.

## Settings [#settings]

Everything configurable lives here:

* **Account**: your personal details and login.
* **Agent**: how your agent behaves, including [voice and memory](/agent/voice-and-memory) and [connections](/agent/connections).
* **Billing**: your plan and credits. See [plans and credits](/account/plans-and-credits).
* **Permissions**: who can access your workspace and what your agent can do on its own.
* **Publication**: your publication's name and logo, shown on your site and in your emails.
* **Website**: how your public site looks and works. See [website](/publishing/website).

For account details, teams, and exporting your data, see [manage your account](/account/manage-account).

## Where to start [#where-to-start]

If you're brand new, open Chat and talk to your agent, or head straight to the Editor and write. The rest of the workspace fills in around your writing as you go.


# Welcome to Paragraph (/)



Paragraph is a publishing platform built for writers. You get a website, a newsletter, and a subscriber list that belongs to you.

You also get an agent. It helps you research ideas, share your posts to social, customize your website, improve your SEO, and run recurring workflows that would otherwise eat your week. It works with your approval: run by AI, approved by you.

## Explore the docs [#explore-the-docs]

<Cards>
  <Card title="Getting started" href="/getting-started/quickstart">
    Sign up, meet your agent, and publish your first post.
  </Card>

  <Card title="Your agent" href="/agent">
    Chat, voice and memory, suggestions, scheduled tasks, and approvals.
  </Card>

  <Card title="Writing and publishing" href="/publishing/editor">
    The editor, newsletters, your website, custom domains, and SEO.
  </Card>

  <Card title="Grow your audience" href="/audience/subscribers">
    Subscribers, distribution, and analytics.
  </Card>

  <Card title="Developers" href="/developers">
    The SDK, CLI, MCP server, and agent skills.
  </Card>
</Cards>

## Where to go next [#where-to-go-next]

* **New to Paragraph?** Start with the [quickstart](/getting-started/quickstart).
* **Moving from another platform?** [Import your posts and subscribers](/getting-started/import-your-publication).
* **Curious what the agent can do?** See [your agent](/agent) and [suggestions](/agent/suggestions).
* **Comparing plans?** Read [plans and credits](/account/plans-and-credits).

If you get stuck anywhere, email [support@paragraph.com](mailto:support@paragraph.com). A real person will help.


# Custom domains (/publishing/custom-domains)



A custom domain puts your site on an address you own, like `example.com` or `blog.example.com`, instead of your paragraph.com address. It strengthens your brand, and the search value you build over time accrues to a domain that's yours.

Custom domains are included with Starter and above. See [Plans and credits](/account/plans-and-credits).

## Before you start [#before-you-start]

You'll need:

* A domain you own, registered anywhere (Namecheap, Cloudflare, GoDaddy, and so on).
* Access to that domain's DNS settings at your registrar.

A subdomain like `blog.example.com` is the easiest to set up and works with every DNS provider. A root domain like `example.com` works too, with one caveat covered below.

## Connect your domain [#connect-your-domain]

<Steps>
  <Step>
    In **Settings → Website**, find the custom domain section and enter your domain.
  </Step>

  <Step>
    Paragraph shows the DNS records to add: a CNAME record that points your domain at Paragraph, and TXT records that verify you own it. Copy each one exactly as shown.
  </Step>

  <Step>
    Add those records in your registrar's DNS dashboard, then save.
  </Step>

  <Step>
    Wait a little while (30 minutes is a good first check), then refresh the verification status in Paragraph. Once every record verifies, your site loads at your new domain.
  </Step>
</Steps>

DNS changes can take up to 24 to 48 hours to propagate everywhere, though most domains resolve within a few hours.

You can remove the domain later from the same page, and your site goes back to its paragraph.com address.

## Common DNS mistakes [#common-dns-mistakes]

**Entering the full domain in the Name field.** Most DNS providers append your domain to whatever you type:

| You enter          | What gets created              |
| ------------------ | ------------------------------ |
| `blog`             | `blog.example.com` (correct)   |
| `@`                | `example.com` (correct)        |
| `blog.example.com` | `blog.example.com.example.com` |

**Leaving an old A record in place.** If the same name already has an A record (from a previous website), delete it before adding the CNAME. A records take precedence and will keep traffic from reaching Paragraph.

**Wildcard records.** A `*` record pointing elsewhere can interfere with your subdomain. Remove it, or make sure your specific record wins.

**Root domains without CNAME support.** Some DNS providers don't allow CNAME records at the root (`@`). If yours doesn't, use an ALIAS record instead, use a subdomain like `www.example.com`, or move your DNS to a provider that supports CNAME at the root (Cloudflare does, for free, and your domain can stay registered where it is).

## Troubleshooting [#troubleshooting]

<Accordions>
  <Accordion title="My domain won't verify">
    Check that every record matches what Paragraph shows, character for character, and that your changes are saved at the registrar. Then give propagation more time and refresh the verification status again. Most verification failures are a typo in the Name field or an unsaved change.
  </Accordion>

  <Accordion title="Verified, but the site doesn't load">
    Verification checks the TXT records, but traffic follows the CNAME. Make sure the CNAME record exists, points at the value Paragraph gave you, and isn't shadowed by an old A record on the same name.
  </Accordion>

  <Accordion title="It works on my phone but not my laptop (or the reverse)">
    That's DNS propagation. Different networks pick up changes at different times. If it works anywhere, the records are right, and the rest will follow within a day or two.
  </Accordion>
</Accordions>

Still stuck after 48 hours? Email [support@paragraph.com](mailto:support@paragraph.com) with your domain, a screenshot of your DNS records, and what you're seeing. We'll get you sorted.


# Editor (/publishing/editor)



The editor is where your posts take shape. Open the Editor area in [app.paragraph.com](https://app.paragraph.com) to see everything you've written: drafts, scheduled posts, and published pieces. Open any post to keep working on it.

Everything you publish lands on your [website](/publishing/website), and any post can also go out to your subscribers [by email](/publishing/newsletters).

## Start a post [#start-a-post]

There are two ways to begin:

* **Start from scratch.** Create a new post in the Editor area and start typing.
* **Start with your agent.** Ask for a draft in [chat](/agent/chat) ("Help me outline a post about what I've been working on lately"). The draft lands in the editor, where you can shape it however you like.

Drafts and agent edits live in the same document. When your agent works on a post, you'll see its changes in the editor, and you can edit right over them. While chatting, the post opens in a side panel next to the conversation, and you can expand it into the full editor at any time.

Your work saves automatically as you write.

## Write and format [#write-and-format]

Give your post a title, then write the body below it. The editor supports the formatting you'd expect: headings, lists, quotes, images, embeds (like X posts), and buttons. Select text to bring up formatting options.

## Cover images [#cover-images]

Every post can have a cover image. You can:

* **Upload one.** Add an image file, or drag and drop it onto the cover area.
* **Generate one.** Your agent can generate cover options from your post. Pick the one you like, or ask for new options until it feels right.

You can swap or remove the cover at any time before or after publishing.

## Publish a post [#publish-a-post]

<Steps>
  <Step>
    Click **Publish** in the editor. Before anything goes live, you'll review the final settings.
  </Step>

  <Step>
    Check the social preview: the cover, title, and description readers will see when your post is shared or found in search.
  </Step>

  <Step>
    Set the post URL. Paragraph suggests a slug from your title, and you can edit it.
  </Step>

  <Step>
    Choose whether to deliver the post as a newsletter. If it's on, you'll see how many subscribers will receive it. See [Newsletters](/publishing/newsletters) for details.
  </Step>

  <Step>
    Publish now, or schedule for later.
  </Step>
</Steps>

## Schedule for later [#schedule-for-later]

Instead of publishing right away, pick a date and time and Paragraph publishes the post for you. Scheduled posts show up in the Schedule area, alongside your agent's [scheduled tasks](/agent/scheduled-tasks), so you can see your whole week at a glance.

## Get a post ready with your agent [#get-a-post-ready-with-your-agent]

When a draft feels close, ask your agent to help you get it ready to publish. It reviews the post and surfaces:

* A settings recap where you can adjust the slug, newsletter delivery, and cover in place.
* Review suggestions you can apply or skip.
* A publish bar to publish or schedule when you're happy.

Nothing publishes until you say so. Your agent always [asks before](/agent/approvals) anything goes public.

## Next steps [#next-steps]

<Cards>
  <Card title="Newsletters" href="/publishing/newsletters">
    Send your posts to subscribers by email.
  </Card>

  <Card title="Distribution" href="/audience/distribution">
    Turn each post into X threads, LinkedIn versions, and newsletter sends.
  </Card>
</Cards>


# Newsletters (/publishing/newsletters)



Paragraph is a full newsletter platform. Any post you publish can also land in your subscribers' inboxes, and every email you send is archived on your [website](/publishing/website) so new readers can catch up.

## Send a post by email [#send-a-post-by-email]

Email delivery is a choice you make when you publish. In the publish settings, turn on newsletter delivery and you'll see exactly how many subscribers will receive the post. Leave it off for posts that should only live on your site.

This works the same whether you publish right away or [schedule for later](/publishing/editor): the email goes out when the post goes live.

<Callout type="info">
  The recipient count reflects active subscribers who receive your emails. Readers who unsubscribed, or opted out of email, aren't included.
</Callout>

## Your email archive [#your-email-archive]

Every newsletter you send stays readable on your site. That matters more than it sounds: new readers can browse your back catalog, search engines can find it, and a post keeps earning readers long after the send.

## Grow your list [#grow-your-list]

Your site includes subscribe prompts, so readers who find a post can join your list right there. Each new subscriber then gets your future sends automatically.

To bring an existing list with you, see [Subscribers](/audience/subscribers). You can import a CSV from Substack or anywhere else.

## Deliverability [#deliverability]

Getting email into inboxes is genuinely hard, so Paragraph handles it for you: sender reputation, infrastructure, and monitoring are all managed on our end.

A few habits on your side help too:

* **Publish consistently.** Regular sends at similar times build reader engagement, and engaged readers keep you out of spam folders.
* **Ask new subscribers to reply or move your email to their primary inbox.** One small action teaches their email provider that you're wanted.
* **Keep your list healthy.** A smaller list of real readers beats a large list of dormant addresses.

## Newsletters and your agent [#newsletters-and-your-agent]

Your agent can help with email beyond publishing posts:

* Draft a standalone email to your subscribers, like a reader update or an announcement.
* Fold newsletter sends into your [distribution](/audience/distribution) plan for each post.
* Answer questions like "How did my last send perform?" in [chat](/agent/chat).

Nothing is sent without your explicit go-ahead. Emails to your list are exactly the kind of action your agent always [confirms first](/agent/approvals).

## See how sends perform [#see-how-sends-perform]

The Newsletter tab in [Analytics](/audience/analytics) shows how each send did, including delivery rate and opens. Use it to learn which topics and subject lines your readers respond to.

## Next steps [#next-steps]

<Cards>
  <Card title="Subscribers" href="/audience/subscribers">
    Manage, import, and export your list.
  </Card>

  <Card title="Analytics" href="/audience/analytics">
    Understand how your sends and posts perform.
  </Card>
</Cards>


# SEO and site maintenance (/publishing/seo)



Being found is half of being read. Your Paragraph site ships with solid technical SEO out of the box, and your agent maintains it every day, so your writing keeps showing up in search engines and AI tools without you thinking about it.

## What's built in [#whats-built-in]

Every Paragraph site ships with:

* **Clean structure.** Fast pages that search engines can crawl and understand.
* **Sitemaps.** Every post is listed, so crawlers find new work quickly.
* **Structured data.** Machine-readable metadata that helps search engines present your posts well.
* **llms.txt.** A guide for AI tools, so assistants like ChatGPT can find and cite your work accurately.

None of this needs configuration. It's part of publishing on Paragraph.

## What you control [#what-you-control]

The publish settings for each post are where your input matters most:

* **Title and description.** These become your search snippet and social preview. Clear beats clever.
* **Post URL.** Paragraph suggests a slug from your title. Keep it short and descriptive.

Ask your agent for help here. It's good at writing descriptions that summarize a post honestly, and it can suggest better titles when you're stuck.

If you're on a [custom domain](/publishing/custom-domains), the search value you build accrues to a domain you own.

## Your agent's daily patrol [#your-agents-daily-patrol]

Sites decay quietly: links rot, pages bloat, old posts slip in rankings. Your agent patrols your site every day and does the maintenance work most writers never get to:

* **Repairs broken links and redirect chains** before readers or crawlers hit them.
* **Trims slow, oversized pages** so everything stays fast.
* **Writes missing titles and descriptions** where posts lack them.
* **Refreshes posts that are quietly losing traffic**, updating them so they keep earning readers.
* **Measures every fix against traffic**, so you can see whether the work paid off.

You don't need to schedule any of this. It's part of what your agent does for your publication.

## What happens automatically, and what waits for you [#what-happens-automatically-and-what-waits-for-you]

The line is simple: routine upkeep happens on its own, and anything readers would notice waits for your approval.

| Happens automatically       | Waits for your approval            |
| --------------------------- | ---------------------------------- |
| Link and redirect repairs   | Rewrites to a post's content       |
| Page performance trims      | Visible changes to your site       |
| Filling in missing metadata | Anything a reader would see as new |

Pending changes show up for review, and nothing visible ships without your sign-off. See [Approvals](/agent/approvals) for how that works.

## See the results [#see-the-results]

The **Search & AI** tab in [Analytics](/audience/analytics) shows how discovery is going: visits from search engines, visits from AI assistants like ChatGPT and Perplexity, and which posts are being found. It's the scoreboard for all of the above.

You can also just ask in [chat](/agent/chat): "How's my search traffic trending?" or "Which posts are losing readers?"

## Next steps [#next-steps]

<Cards>
  <Card title="Analytics" href="/audience/analytics">
    Track search, AI, web, and newsletter performance.
  </Card>

  <Card title="Approvals" href="/agent/approvals">
    How your agent asks before making visible changes.
  </Card>
</Cards>


# Your website (/publishing/website)



Publishing on Paragraph gives you a real website, not just a feed. It includes your posts, your pages, and an archive of every newsletter you've sent. Readers can browse, subscribe, and share from it, and search engines can find it. See [SEO and site maintenance](/publishing/seo) for what's built in.

You have two options for how it looks:

* **A Paragraph website.** The default design. Clean, fast, and ready the moment you publish.
* **A custom site.** A site your agent designs, builds, and deploys just for you.

## Website settings [#website-settings]

Everything lives in **Settings → Website**, where you choose what readers see on your publication URL.

The main control is the **Use a Paragraph website** toggle. When on, readers see the new Paragraph website instead of your classic blog. If you've been on Paragraph a while, this is how you move from the classic design to the new one.

Once you have a custom site deployed, a second toggle appears: **Use custom website**. It switches readers between your custom site and the default design. Turning it off doesn't delete anything, your custom site stays saved and you can switch back any time.

The same page shows your public URL and the status of your site, including your custom site's build and deploy state, so you can see when it's active.

## Build a custom site [#build-a-custom-site]

Ask your agent to build your website in [chat](/agent/chat). A typical flow:

<Steps>
  <Step>
    Tell your agent what you want ("Build me a website" is enough to start). It offers a set of themes to start from, or you can start from scratch.
  </Step>

  <Step>
    Your agent builds the site using your real posts and pages, and shows you its progress. Ask for changes in plain English: layout, colors, typography, new pages, anything.
  </Step>

  <Step>
    When you're happy, tell your agent to publish. It deploys the site, and you can watch the status (build, deploy, active) in Settings → Website.
  </Step>
</Steps>

Your agent never publishes website changes on its own. Deploys wait for your explicit go-ahead, like every other public action (see [Approvals](/agent/approvals)).

## Change your site later [#change-your-site-later]

Your website isn't one-and-done:

* **Restyle it.** Ask your agent to adjust anything, from a single page to the whole look.
* **Switch themes.** Your agent can rebuild on a new theme. This replaces the current site's customizations (your posts and subscribers are untouched), so it confirms with you first.
* **Fall back safely.** Turn off **Use custom website** to show the default design while you rework your custom site.

<Callout type="info">
  Your posts, pages, and subscribers live in your publication, not in any one design. Switching designs or themes never touches your content or your list.
</Callout>

## Use your own domain [#use-your-own-domain]

By default your site lives at your paragraph.com address. On Starter and above, you can point your own domain at it instead. See [Custom domains](/publishing/custom-domains).

## Next steps [#next-steps]

<Cards>
  <Card title="Custom domains" href="/publishing/custom-domains">
    Put your site on a domain you own.
  </Card>

  <Card title="SEO and site maintenance" href="/publishing/seo">
    How your site stays fast, findable, and healthy.
  </Card>
</Cards>