PasteMD API

Create and share markdown documents programmatically. Manage documents, projects, and more via REST API.

Quick Start

Get started with a simple API call to create a document.

curl -X POST https://api.pastemd.io/api/v1/documents \
  -H "X-API-Key: pm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello World\n\nYour markdown content here."}'

Authentication

All API requests require an API key in the X-API-Key header. API keys are available for Pro plan users.

Header Format

X-API-Key: pm_your_api_key

You can create API keys in your Settings

Endpoints Overview

The API provides 13 endpoints organized into three categories.

Method	Path	Description
Documents
POST	`/api/v1/documents`	Create a new markdown document
GET	`/api/v1/documents`	List your documents with pagination
GET	`/api/v1/documents/{id}`	Get a document by ID (UUID)
GET	`/api/v1/documents/slug/{slug}`	Get a document by slug
PATCH	`/api/v1/documents/{id}`	Update a document (partial update)
DELETE	`/api/v1/documents/{id}`	Delete a document
Projects
POST	`/api/v1/projects`	Create a new project
GET	`/api/v1/projects`	List your projects
GET	`/api/v1/projects/{id}`	Get project details with document list
PATCH	`/api/v1/projects/{id}`	Update a project (owner only)
DELETE	`/api/v1/projects/{id}`	Delete a project (owner only)
Usage & Profile
GET	`/api/v1/me`	Get your profile information
GET	`/api/v1/usage`	Get your API usage for the current month

Documents

POST/api/v1/documents

Create a new markdown document

Request Body

Field	Type	Required	Description
`content`	string	Yes	Markdown content (max 500,000 characters)
`title`	string	No	Document title (max 200 characters, extracted from content if omitted)
`expiration`	string	No	Expiration period: 1h, 1d, 7d, 30d, or never
`password`	string	No	Password protection for the shared link
`project_id`	string	No	Project ID (UUID) to attach the document to
`is_public`	boolean	No	Make document publicly indexable by search engines
`show_ai_chat`	boolean	No	Show AI chat in viewer (Pro)
`show_toc`	boolean	No	Show table of contents in viewer (Pro)
`show_notes`	boolean	No	Show notes in viewer (Pro)
`show_comments`	boolean	No	Show comments/feedback in viewer (Pro)
`show_summary`	boolean	No	Show AI summary in viewer (Pro)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "abc123",
  "title": "Hello World",
  "content": "# Hello World\n\nYour markdown content here.",
  "url": "https://pastemd.io/s/abc123",
  "edit_url": "https://pastemd.io/e/550e8400-e29b-41d4-a716-446655440000",
  "view_count": 0,
  "created_at": "2025-01-04T12:00:00Z",
  "updated_at": "2025-01-04T12:00:00Z",
  "is_password_protected": false,
  "is_public": false,
  "project_id": null
}

This endpoint counts toward your monthly document creation quota (100/month).

GET/api/v1/documents

List your documents with pagination

Query Parameters

Field	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`page_size`	integer	No	Items per page, max 100 (default: 20)
`project_id`	string	No	Filter by project ID

Response

{
  "items": [
    {
      "id": "550e8400-...",
      "slug": "abc123",
      "title": "Hello World",
      "url": "https://pastemd.io/s/abc123",
      "view_count": 42,
      "created_at": "2025-01-04T12:00:00Z",
      "updated_at": "2025-01-04T12:00:00Z",
      "is_password_protected": false,
      "is_public": false,
      "project_id": null
    }
  ],
  "total": 15,
  "page": 1,
  "page_size": 20,
  "has_next": false
}

GET/api/v1/documents/{id}

Get a document by ID (UUID)

Returns the full document response including content. Only your own documents are accessible.

GET/api/v1/documents/slug/{slug}

Get a document by slug

Query Parameters

Field	Type	Required	Description
`password`	string	No	Password for protected documents

PATCH/api/v1/documents/{id}

Update a document (partial update)

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Required	Description
`content`	string	No	Markdown content (max 500,000 characters)
`title`	string	No	Document title (max 200 characters, extracted from content if omitted)
`expiration`	string	No	Expiration period. Use 'never' to remove expiration
`password`	string	No	Password. Use empty string '' to remove password
`project_id`	string	No	Project ID. Use empty string '' to detach from project
`is_public`	boolean	No	Make document publicly indexable by search engines
`show_ai_chat`	boolean	No	Show AI chat in viewer (Pro)
`show_toc`	boolean	No	Show table of contents in viewer (Pro)
`show_notes`	boolean	No	Show notes in viewer (Pro)
`show_comments`	boolean	No	Show comments/feedback in viewer (Pro)
`show_summary`	boolean	No	Show AI summary in viewer (Pro)

DELETE/api/v1/documents/{id}

Delete a document

Permanently deletes the document. Returns 204 No Content on success.

Projects

POST/api/v1/projects

Create a new project

Request Body

Field	Type	Required	Description
`name`	string	Yes	Project name (max 100 characters)
`description`	string	No	Project description (max 500 characters)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Project",
  "description": "Project description",
  "document_count": 0,
  "member_count": 1,
  "documents": [],
  "created_at": "2025-01-04T12:00:00Z",
  "updated_at": "2025-01-04T12:00:00Z"
}

GET/api/v1/projects

List your projects

Response

{
  "items": [
    {
      "id": "550e8400-...",
      "name": "My Project",
      "description": "Project description",
      "document_count": 5,
      "member_count": 3,
      "created_at": "2025-01-04T12:00:00Z",
      "updated_at": "2025-01-04T12:00:00Z"
    }
  ],
  "total": 2
}

GET/api/v1/projects/{id}

Get project details with document list

Returns project details including all documents. Accessible by owner and members.

PATCH/api/v1/projects/{id}

Update a project (owner only)

Request Body

Field	Type	Required	Description
`name`	string	No	Project name (max 100 characters)
`description`	string	No	Project description. Use empty string '' to remove

Only the project owner can update project settings.

DELETE/api/v1/projects/{id}

Delete a project (owner only)

Deletes the project. Documents are detached, not deleted. Returns 204 No Content.

Usage & Profile

GET/api/v1/me

Get your profile information

Response

{
  "id": 12345,
  "email": "user@example.com",
  "display_name": "John Doe",
  "plan": "pro",
  "is_pro": true,
  "created_at": "2025-01-01T00:00:00Z"
}

GET/api/v1/usage

Get your API usage for the current month

Response

{
  "month": "2025-01",
  "docs_created": 23,
  "docs_limit": 100,
  "remaining": 77
}

Error Codes

All errors follow a consistent JSON format with error code and message.

Status	Description
`401`	Invalid or missing API key
`403`	Insufficient permissions (e.g., not project owner)
`404`	Resource not found or not owned by you
`422`	Invalid request body or parameters
`429`	Monthly document creation limit reached

Rate Limits

Only document creation counts toward your monthly quota. All other operations are unlimited.

Operation	Limit
Document Creation (POST)	100 per month
Read / Update / Delete	Unlimited
AI Chat (per document)	50 questions

Ready to get started? Create your API key now.

Go to Settings