Developing with AI & LLMs - Paragraph

Guide to Using AI and Large Language Models with Paragraph's API

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)
```bash
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/ with {"scheduledAt": } to schedule a draft. PUT /v1/posts/ 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:

2. Validate Generated Code

Always review AI-generated code for:

3. Iterative Development

4. Common Prompting Patterns

For API Integration

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

For Debugging

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

For Data Modeling

"Based on Paragraph's API, help me create [language] models/interfaces\nfor [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:

Additional Resources