Posts API

Use these endpoints to manage your own drafts and published posts.

Endpoints

• POST /api/v1/posts create draft
• GET /api/v1/posts list posts (?status=draft|published optional)
• GET /api/v1/posts/:id get post by UUID
• PATCH /api/v1/posts/:id update post fields
• DELETE /api/v1/posts/:id delete draft

Create draft

POST /api/v1/posts

Required body fields:

• paidContentMarkdown or freeContentMarkdown

Common optional fields:

• title, description
• freeContentMarkdown
• enablePaywall, priceRaw
• primaryCategoryId, secondaryCategoryId
• slug, canonicalUrl, language, commentsEnabled
• ogTitle, ogDescription, ogImage

Behavior:

• If paidContentMarkdown is omitted or empty, enablePaywall is treated as false.
• Non-paywalled posts keep paidContentMarkdown and freeContentMarkdown aligned.

List posts

GET /api/v1/posts?status=draft&page=1&per_page=20

Returns:

{
  "data": [{ "id": "uuid", "status": "draft" }],
  "total": 1,
  "page": 1,
  "perPage": 20
}

Get post

GET /api/v1/posts/:id

Returns a full resource including:

• paidContentMarkdown
• freeContentMarkdown
• ogImageEffective

ogImageEffective follows this order:

1. Explicit metadata.og.image
2. First image found in freeContentMarkdown

Update post

PATCH /api/v1/posts/:id

Partial updates are supported. Slug updates are rejected when the post is already published.

Delete post

DELETE /api/v1/posts/:id

Rules:

• Only drafts can be deleted.
• Published posts must be unpublished first.
• Posts with paid purchases cannot be deleted.

Integration Recipe: Post with 2 Images

Use this when you want one clear, copy-safe flow from draft to published.

1. Create draft
2. Upload image 1 (intent=content)
3. Upload image 2 (intent=content)
4. Patch markdown with both image URLs
5. Publish with Idempotency-Key

Step 1: create draft

curl -X POST "https://subnano.me/api/v1/posts" \
  -H "Authorization: Bearer $SUBNANO_PUBLISH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My post with two images",
    "description": "Example flow",
    "paidContentMarkdown": "Draft body placeholder",
    "enablePaywall": true,
    "priceRaw": "100000000000000000000000000000",
    "primaryCategoryId": 4,
    "language": "en"
  }'

Save the returned id as POST_ID.

Step 2: upload image 1

curl -X POST "https://subnano.me/api/v1/posts/$POST_ID/images?intent=content" \
  -H "Authorization: Bearer $SUBNANO_PUBLISH_KEY" \
  -F "file=@/path/to/image-1.jpg"

Save returned url as IMG_1.

Step 3: upload image 2

curl -X POST "https://subnano.me/api/v1/posts/$POST_ID/images?intent=content" \
  -H "Authorization: Bearer $SUBNANO_PUBLISH_KEY" \
  -F "file=@/path/to/image-2.jpg"

Save returned url as IMG_2.

Step 4: patch markdown with both image URLs

curl -X PATCH "https://subnano.me/api/v1/posts/$POST_ID" \
  -H "Authorization: Bearer $SUBNANO_PUBLISH_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"paidContentMarkdown\": \"# Final title\n\nIntro text.\n\n![Image 1]($IMG_1)\n\nMore text.\n\n![Image 2]($IMG_2)\"
  }"

Tip: if building payloads in shell, use \n (not \\n) for markdown line breaks.

Step 5: publish

curl -X POST "https://subnano.me/api/v1/posts/$POST_ID/publish" \
  -H "Authorization: Bearer $SUBNANO_PUBLISH_KEY" \
  -H "Idempotency-Key: 6d65f0f8-6897-4d8e-a3cb-f6f12f947f99"

Optional: if you want a dedicated social preview image, upload with intent=og (or set ogImage via PATCH).