Developing with AI & LLMs

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:

Copy agent prompt

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

Initial Setup: Share the llms-full.txt context with your AI assistant
Describe Your Goal: Explain what you want to build with Paragraph’s API
Generate Boilerplate: Have the AI create initial client setup and authentication
Implement Features: Work through each API endpoint you need
Add Error Handling: Ask the AI to add comprehensive error handling
Create Tests: Generate test cases for your integration
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

API Reference - Complete endpoint documentation
Authentication Guide - API key setup and usage
Rate Limits - Understanding and handling rate limits
SDKs - Official client libraries for various languages

​Quick start: give your agent Paragraph access

​Context for LLMs

​MCP Server

​CLI for Agents

​Agent Skills

​Best Practices for AI-Assisted Development

​1. Provide Clear Context

​2. Validate Generated Code

​3. Iterative Development

​4. Common Prompting Patterns

​For API Integration

​For Debugging

​For Data Modeling

​Example Workflow

​Troubleshooting

​Additional Resources