The simplest API
we could build.

Base URL

https://api.scratchthepad.com/api/{pad-id}

The pad ID is the 10-character hash in your pad's URL. If your pad lives at scratchthepad.com/#x7k2m9p4qw, your API endpoint is api.scratchthepad.com/api/x7k2m9p4qw.

Read a pad

Returns the full pad content as plain Markdown. No JSON wrapper — just the raw content your agent needs.

curl https://api.scratchthepad.com/api/x7k2m9p4qw

# Project brief

**Goal:** Redesign homepage and pricing page.

- [ ] Review current analytics
- [ ] Draft initial wireframes
- [x] Ship v1 homepage

---

↳ Waiting on: pricing page copy.

Write a pad

Replaces the pad content with the request body. Send Markdown — get Markdown back when you read it.

curl -X POST https://api.scratchthepad.com/api/x7k2m9p4qw \
  -H "Content-Type: text/plain" \
  -H "X-Pad-Key: EXAMPLE-KEY-replace-with-yours" \
  -d "# Updated brief

**Status:** in progress

- [x] Analytics reviewed
- [ ] Wireframes pending"

Saved.

curl -X POST "https://api.scratchthepad.com/api/x7k2m9p4qw?mode=append" \
  -H "Content-Type: text/plain" \
  -d "

---

## Agent summary — Apr 14

Analysis complete. Recommend leading with use case."

Pages

Pads support multiple named pages. Each page is a separate Markdown document within the same pad.

curl https://api.scratchthepad.com/api/x7k2m9p4qw/pages

# Returns JSON array:
["Project brief", "Open questions", "Decisions log"]

Metadata

Lightweight metadata about the pad — useful for agents checking freshness before reading full content.

{
  "id":         "x7k2m9p4qw",
  "created":     "2025-04-01T09:00:00Z",
  "modified":    "2025-04-14T14:32:00Z",
  "name":           "My Project",
  "pages":          4,
  "words":          847,
  "context_pct":    1,
  "context_health": "ok",   // "ok" | "warning" (70%+) | "critical" (90%+)
  "connections":    2,        // active WebSocket connections
  "last_by":        "human"
}

Create a pad

Agents can create pads programmatically. No authentication required.

{
  "id":        "x7k2m9p4qw",
  "url":       "https://scratchthepad.com/pad.html#x7k2m9p4qw",
  "api":       "https://api.scratchthepad.com/api/x7k2m9p4qw",
  "write_key": "EXAMPLE-KEY-replace-with-yours"
}

// Optional: send {"content": "initial content"} to pre-fill the pad
// Optional: send {"content": "# My pad"} for initial content

Changes & versions

Check what changed since your last read, and restore previous versions.

Webhooks

Get notified when a pad is written to. For server-based consumers. CLI agents should use /changes polling instead.

Webhook events: write, page-change, delete. Max 5 per pad. All require write key.

Setting up AI access

Set it once in custom instructions — every session starts with full pad context. Works for AI Agents (Claude Code, Claude Cowork, Codex, Manus — read + write) and AI Chat Assistants (Grok, Perplexity — read only). You explain yourself once.

Before we start each conversation, fetch the contents of my pad at https://api.scratchthepad.com/api/x7k2m9p4qw and use it as context for our work together.

Code examples

Reading and writing a pad from the most common environments.

// Read
const response = await fetch('https://api.scratchthepad.com/api/x7k2m9p4qw');
const markdown = await response.text();

// Write
await fetch('https://api.scratchthepad.com/api/x7k2m9p4qw', {
  method: 'POST',
  headers: { 'Content-Type': 'text/plain' },
  body: '# Updated content\n\nYour markdown here.'
});

import requests

PAD = 'https://api.scratchthepad.com/api/x7k2m9p4qw'

# Read
content = requests.get(PAD).text

# Write
requests.post(PAD,
  data='# Updated\n\nNew content here.',
  headers={'Content-Type': 'text/plain'}
)

# Add to your system prompt or custom instructions:

You have access to a shared pad at:
https://api.scratchthepad.com/api/x7k2m9p4qw

At the start of each conversation, fetch this URL
and use the contents as project context.

After completing significant work, POST a summary
back to the pad so the next session starts informed.

Auth & security

scratchthepad is intentionally open in v1 alpha. Here's what that means and what's coming.

Why not API keys?

Agents shouldn't need to manage rotating credentials. The pad key in the URL is the read credential. The write passphrase is the write credential. Both are simple strings — no OAuth, no token refresh, no headers for read-only access. The barrier to entry for reading a pad is exactly one fetch call with no modifications.