Skip to main content
This guide covers best practices for using AI and Large Language Models (LLMs) to accelerate your development workflow with Paragraph’s API.

​
Quick start: give your agent Paragraph access

The fastest way to connect any AI agent to Paragraph. Copy the prompt below and paste it into your agent’s context:
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 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")

Full API reference: https://paragraph.com/docs/api-reference/
Full docs: https://paragraph.com/docs/llms-full.txt
Or install the Agent Skill for a more structured setup: 
npx skills add paragraph-xyz/skill

​
Context for LLMs

When working with AI assistants like Claude, ChatGPT, or Cursor, you can provide comprehensive API context by sharing our full documentation: 
https://paragraph.com/docs/llms-full.txt
Simply paste this URL or its contents into your LLM conversation to give it complete knowledge of Paragraph’s API endpoints, data models, and capabilities.

​
MCP Server

The Paragraph MCP server (@paragraph-com/mcp) connects AI agents directly to the Paragraph API. Manage posts, search content, work with coins, and more from any MCP-compatible client. 
npx @paragraph-com/mcp
Works with Claude Code, Claude Desktop, Cursor, VS Code, and any MCP client. See the full MCP setup guide for client-specific instructions and configuration.

​
CLI for Agents

The Paragraph CLI (@paragraph-com/cli) is designed for agent and programmatic usage. All commands support --json for structured output: 
npm install -g @paragraph-com/cli
PARAGRAPH_API_KEY=<your-api-key> paragraph --json post list
See the full command reference for details.

​
Agent Skills

Install the Paragraph Agent Skills to teach AI agents (Claude Code, Cursor, etc.) how to use the CLI, REST API, SDK, and MCP server: 
npx skills add paragraph-xyz/skill
The skills include working agreements, commands and endpoints with examples, JSON response shapes, and common patterns.

​
Best Practices for AI-Assisted Development

​
1. Provide Clear Context

When prompting AI tools, include:
  • Specific API endpoints you’re working with
  • Example responses or data structures
  • Your programming language and framework
  • Any authentication requirements

​
2. Validate Generated Code

Always review AI-generated code for:
  • Error Handling: Add proper error handling for API responses
  • Rate Limiting: Implement appropriate rate limiting and retry logic
  • Type Safety: Verify types match the API’s expected request/response formats

​
3. Iterative Development

  • Start with simple API calls and gradually add complexity
  • Test each integration point before moving to the next
  • Use the AI to explain error messages and suggest fixes

​
4. Common Prompting Patterns

​
For API Integration

"Help me integrate Paragraph's [endpoint name] endpoint in [language/framework].
I need to [specific use case]. Include error handling and type definitions."

​
For Debugging

"I'm getting [error message] when calling Paragraph's [endpoint].
Here's my code: [code snippet]. What's wrong?"

​
For Data Modeling

"Based on Paragraph's API, help me create [language] models/interfaces
for [specific data types] with proper type annotations."

​
Example Workflow

  1. Initial Setup: Share the llms-full.txt context with your AI assistant
  2. Describe Your Goal: Explain what you want to build with Paragraph’s API
  3. Generate Boilerplate: Have the AI create initial client setup and authentication
  4. Implement Features: Work through each API endpoint you need
  5. Add Error Handling: Ask the AI to add comprehensive error handling
  6. Create Tests: Generate test cases for your integration
  7. Optimize: Request performance improvements and best practices

​
Troubleshooting

If AI-generated code isn’t working:
  • Verify you’re using the latest API version
  • Check that all required headers are included
  • Ensure proper JSON formatting in request bodies
  • Review rate limits and implement appropriate delays

​
Additional Resources