API Documentation

Use the Paper Studio API to programmatically publish markdown documents as beautiful web pages.

Authentication

All API requests require an API key. Get your API key from the Dashboard.

Include your API key in the Authorization header:

Authorization: Bearer ps_your_api_key_here

Base URL

https://paperstudio.ink/api/v1

Publish Document

POST /publish

Convert markdown to a beautifully styled web document. Your brand settings are automatically applied.

Request Body

{
  "markdown": "# Your Document\n\nYour content here...",
  "title": "Optional custom title",
  "password": "optional-password",
  "slug": "existing-slug-to-update",
  "handle": "your-handle",
  "custom_suffix": "my-page"
}

Parameter	Type	Required	Description
markdown	string	Yes	The markdown content to convert (max 2MB)
title	string	No	Custom title (defaults to first heading)
password	string	No	Password protect the document
slug	string	No	Update existing document instead of creating new
handle	string	No	Your handle name for a vanity URL (e.g. "blog"). You must own this handle.
custom_suffix	string	No	Custom URL suffix (e.g. "my-post"). Requires handle. Lowercase alphanumeric and hyphens, 1-50 chars.

Response

// Without handle (random URL)
{
  "success": true,
  "slug": "abc123xy",
  "url": "/abc123xy",
  "title": "Your Document Title",
  "protected": false,
  "created": true
}

// With handle + custom_suffix (vanity URL)
{
  "success": true,
  "slug": "abc123xy",
  "url": "/blog-my-post",
  "title": "Your Document Title",
  "protected": false,
  "created": true,
  "handle": "blog",
  "custom_suffix": "my-post"
}

Field	Description
success	Whether the operation succeeded
slug	The unique document identifier
url	Relative URL path to the document
title	The document title
protected	Whether the document is password protected
created / updated	Whether this was a new document or an update

Example Request

# Basic publish (random URL)
curl -X POST https://paperstudio.ink/api/v1/publish \
  -H "Authorization: Bearer ps_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Q4 Report\n\n## Summary\n\nGreat quarter!",
    "title": "Q4 2024 Report"
  }'

# Publish with vanity URL (requires handle ownership)
curl -X POST https://paperstudio.ink/api/v1/publish \
  -H "Authorization: Bearer ps_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# My Blog Post\n\nHello world!",
    "handle": "blog",
    "custom_suffix": "hello-world",
    "password": "optional-secret"
  }'
# → https://paperstudio.ink/blog-hello-world

Read Document

GET /read?slug=your-slug

Retrieve the source markdown of a published document. The document owner must enable markdown export for this to work.

Query Parameters

Parameter	Type	Required	Description
slug	string	Yes	The document slug or handle-based URL
password	string	No	Required for password-protected documents

Authentication

Authentication depends on the document's access level:

Document Type	Auth Required
Public	None
Password-protected	`?password=xxx`
Exclusive (PS Members)	API key (any user)
Exclusive (Pro Members)	API key (active subscriber)
Exclusive (Invited Members)	API key (on member list)

Document owners always have access via their API key regardless of access level.

Response

Returns raw markdown with Content-Type: text/markdown.

Example

# Public document
curl https://paperstudio.ink/api/v1/read?slug=abc123xy

# With API key (for exclusive content)
curl https://paperstudio.ink/api/v1/read?slug=abc123xy \
  -H "Authorization: Bearer ps_your_api_key"

# Password-protected document
curl "https://paperstudio.ink/api/v1/read?slug=abc123xy&password=secret"

Rate Limits

Free tier: 50 documents per day

Rate limits reset at midnight UTC.

Error Codes

Status	Description
400	Bad request - missing or invalid parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - you don't own this document, or markdown export is disabled
404	Not found - document doesn't exist
409	Conflict - vanity URL already taken
413	Payload too large - document exceeds 2MB
429	Too many requests - rate limit exceeded
500	Server error - something went wrong

Supported Features

✓Standard markdown (headings, lists, tables, links, images)
✓Mermaid diagrams (flowcharts, pie charts, etc.)
✓HTTPS images (automatically embedded)
✓Your brand colors and fonts
✓Custom styling instructions
✓Password protection
✓Vanity URLs via handles (e.g. paperstudio.ink/blog-my-post)

Ready to get started?

Create an account and get your API key to start publishing documents.