TypechoApi — REST API Documentation

Base URL: https://your-site.com/typecho-api/v1
Content-Type: application/json (except uploads: multipart/form-data)
Response Header: X-Typecho-Api-Version: 1.0.0

Authentication

All endpoints require authentication. Two methods are supported, controlled by the authMode plugin setting.

Basic Auth

Authorization: Basic <base64(username:password)>

Uses Typecho's user database. Only users with roles listed in allowedRoles (default: administrator,editor) are permitted.

Bearer Token

X-Typecho-Token: <token-secret>

Tokens are configured in plugin settings as label:secret pairs (one per line).

IP Allow-List (Optional)

If configured, only listed IPv4/IPv6 addresses can access any endpoint. All others receive 403.

Endpoints

1. List Posts

GET /typecho-api/v1/posts

Query Parameters:

Response 200:

{
  "data": [
    {
      "id": 12,
      "title": "Hello World",
      "slug": "hello-world",
      "status": "publish",
      "text": "<!--markdown-->\n\n# Hello",
      "markdown": "# Hello",
      "contentFormat": "markdown",
      "authorId": 1,
      "authorName": "Admin",
      "allowComment": true,
      "allowPing": true,
      "allowFeed": true,
      "created": 1773102541,
      "createdAt": "2026-03-10T00:29:01+00:00",
      "modified": 1773102541,
      "modifiedAt": "2026-03-10T00:29:01+00:00",
      "categories": [
        { "id": 2, "name": "News", "slug": "news", "type": "category" }
      ],
      "tags": [
        { "id": 5, "name": "api", "slug": "api", "type": "tag" }
      ],
      "fields": {},
      "excerpt": "Hello content excerpt..."
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 42
  }
}

2. Get Single Post

GET /typecho-api/v1/post?id={id}

Response 200: Single post object wrapped in { "data": { ... } } (same shape as list items, without excerpt).

Response 404: { "error": { "code": 404, "message": "Post not found." } }

3. Create Post

POST /typecho-api/v1/posts

Request Body:

*One of markdown, text, or content is required.

Example:

curl -X POST https://your-site.com/typecho-api/v1/posts \
  -H "X-Typecho-Token: my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from API",
    "markdown": "# Heading\n\n**Bold** content here.",
    "status": "publish",
    "categories": ["News", "Announcements"],
    "tags": ["api", "typecho"],
    "fields": { "priority": 5 }
  }'

Response 201:

{
  "message": "Post created.",
  "data": { /* full post object */ }
}

Taxonomy Input Formats

Categories and tags accept flexible input:

// Comma-separated string
"categories": "News, Announcements"

// Array of names
"categories": ["News", "Announcements"]

// Array of objects
"categories": [{ "name": "News", "slug": "news" }, { "id": 2 }]

// Mixed
"categories": ["News", { "name": "Announcements", "slug": "announcements" }]

Non-existent categories/tags are auto-created.

4. Update Post (Full Replace)

PUT /typecho-api/v1/post?id={id}

Replaces all fields. Same body format as Create.

Response 200: { "message": "Post updated.", "data": { ... } }

5. Update Post (Partial)

PATCH /typecho-api/v1/post?id={id}

Updates only the provided fields; all others are preserved.

Example — change only status:

curl -X PATCH https://your-site.com/typecho-api/v1/post?id=12 \
  -H "X-Typecho-Token: my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{ "status": "publish" }'

Response 200: { "message": "Post updated.", "data": { ... } }

6. Delete Post

DELETE /typecho-api/v1/post?id={id}

Hard-deletes the post and cascades to relationships, comments, and custom fields.

Response 200:

{
  "message": "Post deleted.",
  "data": { "id": 12 }
}

7. Upload Image

POST /typecho-api/v1/upload
Content-Type: multipart/form-data

Form Fields:

Allowed types: JPEG, PNG, GIF, WebP, SVG, BMP, AVIF
Max size: 10 MB

Example:

curl -X POST https://your-site.com/typecho-api/v1/upload \
  -H "X-Typecho-Token: my-secret-token" \
  -F "[email protected]" \
  -F "destination=r2"

Response 200:

{
  "message": "Image uploaded.",
  "data": {
    "url": "https://cdn.example.com/2026/03/photo-a1b2c3d4.jpg",
    "path": "/usr/uploads/2026/03/photo-a1b2c3d4.jpg",
    "filename": "photo-a1b2c3d4.jpg",
    "size": 45678,
    "mimeType": "image/jpeg",
    "destination": "r2",
    "embed": {
      "markdown": "![](https://cdn.example.com/2026/03/photo-a1b2c3d4.jpg)",
      "html": "<img src=\"https://cdn.example.com/2026/03/photo-a1b2c3d4.jpg\" alt=\"\" />"
    },
    "urls": {
      "r2": "https://r2cdn.example.com/2026/03/14/photo.jpg",
      "bunny": null
    }
  }
}

Storage destinations:

8. Increment Agree

POST /typecho-api/v1/agree

Increments the agree counter on a random published post. Has a 10% chance of skipping (no-op).

Response 200:

{
  "data": {
    "updated": true,
    "postId": 42,
    "agree": 7,
    "skipped": false
  }
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": 401,
    "message": "Authentication failed."
  }
}

Error Code Reference

Plugin Configuration

Configure in Typecho admin panel under Plugins → TypechoApi → Settings.

Authentication

Cloud Storage

Quick Reference