API Documentation

JSON API (v1)

Recommended for apps and scripts: predictable JSON, rich filters, and explicit blog selection via blog_id on the query string when you are not using the selected blog.

BASE URL https://scribbles.page/api/v1

Note: Replace YOUR_API_KEY in examples with a key from API settings. Paths below are shown from the base URL.

Discover blogs and metadata

GET https://scribbles.page/api/v1/info

Returns API metadata and the blogs available to your account.

Example Request

curl "https://scribbles.page/api/v1/info" \
  -H "Authorization: Bearer YOUR_API_KEY"

List posts

GET https://scribbles.page/api/v1/posts

List, filter, and paginate posts. List responses omit heavy body fields unless you opt in with include_content.

Example Request

curl "https://scribbles.page/api/v1/posts?limit=10&sort=-published_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://scribbles.page/api/v1/posts?include_content=true&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Name	Type	Required	Description
blog_id	integer	No	Target a specific blog by id.
status	string	No	published (default), draft, archived, or all.
type	string	No	posts or pages.
category	string	No	Filter to one category (name).
category_id	integer	No	Filter to one category (id).
exclude_category	string	No	Exclude one category (name).
exclude_category_id	integer	No	Exclude one category (id).
uncategorized	boolean	No	true for posts with no category.
search	string	No	Search title and content.
from_date	date	No	Start of date range filter.
to_date	date	No	End of date range filter.
page	integer	No	Page number for pagination.
limit	integer	No	Page size (max 100).
sort	string	No	Sort field; prefix with - for descending (title, created_at, updated_at, published_at).
include_content	boolean	No	When true, list items include HTML/text bodies.

Note: Do not combine category filters with exclude_category* or uncategorized=true; those combinations return 400 Bad Request.

Create and update posts

POST https://scribbles.page/api/v1/posts

Create a post with a JSON body wrapped under post. Use PUT or PATCH on /posts/:id to update.

Example Request

curl -X POST "https://scribbles.page/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post":{"title":"Hello","content":"This is **markdown**.","content_type":"markdown","status":"published"}}'

PATCH https://scribbles.page/api/v1/posts/:id

Example (update)

curl -X PATCH "https://scribbles.page/api/v1/posts/123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"post":{"title":"Updated title"}}'

DELETE https://scribbles.page/api/v1/posts/:id

Example (delete)

curl -X DELETE "https://scribbles.page/api/v1/posts/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish and unpublish

PATCH https://scribbles.page/api/v1/posts/:id/publish

PATCH https://scribbles.page/api/v1/posts/:id/unpublish

Example Request

curl -X PATCH "https://scribbles.page/api/v1/posts/123/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PATCH "https://scribbles.page/api/v1/posts/123/unpublish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Attachments and rich HTML

POST https://scribbles.page/api/v1/attachments

Upload with multipart form data, then embed the returned ActionText snippet in post HTML.

Example Request

curl -X POST "https://scribbles.page/api/v1/attachments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "blog_id=YOUR_BLOG_ID" \
  -F "attachment[file][email protected]" \
  -F "attachment[caption]=Optional caption"

Note: Use HTML content when inserting action-text-attachment blobs. Sending that HTML through content_type=markdown can strip attachments during conversion.

Note: Images: JPEG, PNG, GIF, WebP, AVIF up to 20 MB. Video: MP4, MOV, WebM up to 250 MB. SVG is not accepted.

Response shape (sketch)

Single post payloads wrap attributes under post, including nested content (html, text), blog, category, meta, and optional attachments. Lists return posts plus pagination (page, limit, total, pages).

Errors

401 — Missing or invalid API key.
403 — Authenticated but not allowed for the resource or action.
404 — Unknown blog or post.
400 — Bad query combination (for example category filters that exclude each other) or missing upload fields.
422 — Validation errors; JSON body often includes errors / message.

← API overview · Micropub guide →