ℹ️ Micropub: Categories

This is very rough, preliminary documentation.

Full-featured blogging apps may need to rename or delete categories. We’ve extended the Micropub API with more access to categories.

To get a list of categories:

GET /micropub?q=category

Parameters:

• mp-destination: blog URL, for accounts with multiple blogs
• filter: prefix match for category names

Response:

{
  "categories": [
    "Photos",
    "Travel"
  ],
  "microblog-categories": [
    {
      "uid": 11,
      "name": "Photos",
      "posts_count": 123
    },
    {
      "uid": 12,
      "name": "Travel",
      "posts_count": 45
    }
  ]
}

Getting blog posts in a category:

GET /micropub?q=source&category=uid

Adding a category name to a blog post will create the category automatically if it doesn’t exist. You can also create a category manually:

POST /micropub

Parameters:

• mp-channel=categories
• name=Travel
• text=Optional intro text
• path=/categories/travel

JSON request:

{
  "mp-channel": "categories",
  "properties": {
    "name": ["Travel"],
    "content": ["Optional intro text"],
    "microblog-path": ["/categories/travel"]
  }
}

Response:

{
  "uid": 12,
  "name": "Travel",
  "path": "/categories/travel",
  "posts_count": 0
}

If path is omitted, Micro.blog generates one from the category name.

Update category:

POST /micropub

Parameters:

• mp-channel=categories
• action=update
• url=https://example.com/categories/12
• name=Trips
• text=Updated intro text
• path=/categories/trips

JSON request:

{
  "mp-channel": "categories",
  "action": "update",
  "url": "https://example.com/categories/12",
  "replace": {
    "name": ["Trips"],
    "content": ["Updated intro text"],
    "microblog-path": ["/categories/trips"]
  }
}

Response:

{
  "uid": 12,
  "name": "Trips",
  "path": "/categories/trips",
  "posts_count": 45
}

Delete a category:

POST /micropub

Parameters:

• mp-channel=categories
• action=delete
• url=https://example.com/categories/12

JSON request:

{
  "mp-channel": "categories",
  "action": "delete",
  "uid": 12
}