Skip to main content
The Content Management APIs allow you to create, read, update and delete various content types in Halo CMS including posts, single pages, comments, replies, tags and attachments.

​
Posts

​
List Posts

Retrieve a paginated list of posts with optional filtering. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number. Default is 0.
​
size
integer
default:"0"
Size number. Default is 0.
​
publishPhase
string
Posts filtered by publish phase. Values: DRAFT, PENDING_APPROVAL, PUBLISHED, FAILED
​
keyword
string
Posts filtered by keyword.
​
categoryWithChildren
string
Posts filtered by category including sub-categories.
​
labelSelector
array
Label selector. e.g.: hidden!=true
​
fieldSelector
array
Field selector. e.g.: metadata.name==halo
​
sort
array
Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.
​
items
array
Array of post objects
​
page
integer
Current page number
​
size
integer
Size of each page
​
total
integer
Total number of posts
​
totalPages
integer
Total number of pages

​
Create Draft Post

Create a new draft post. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "spec": {
        "title": "My New Post",
        "slug": "my-new-post",
        "categories": ["category-1"],
        "tags": ["tag-1", "tag-2"]
      }
    },
    "content": {
      "raw": "# Hello World\n\nThis is my post content.",
      "content": "<h1>Hello World</h1><p>This is my post content.</p>",
      "rawType": "markdown"
    }
  }'
​
post
object
The created post object

​
Update Post

Update an existing post. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "spec": {
        "title": "Updated Post Title"
      }
    },
    "content": {
      "raw": "Updated content",
      "content": "<p>Updated content</p>",
      "rawType": "markdown"
    }
  }'
​
name
string
required
Post name/identifier

​
Publish Post

Publish a draft post. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}/publish" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Post name to publish
​
headSnapshot
string
Head snapshot name of content
​
async
boolean
Whether to publish asynchronously

​
Unpublish Post

Unpublish a published post. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}/unpublish" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Post name to unpublish

​
Recycle Post

Move a post to recycle bin. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}/recycle" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Post name to recycle

​
Fetch Post Content

Retrieve the content of a post. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}/content?snapshotName={snapshotName}" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Post name
​
snapshotName
string
required
Snapshot name of the content version

​
Update Post Content

Update the content of a post. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts/{name}/content" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "raw": "# Updated Content",
    "content": "<h1>Updated Content</h1>",
    "rawType": "markdown"
  }'
​
name
string
required
Post name

​
Single Pages

​
List Single Pages

Retrieve a paginated list of single pages. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/singlepages?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number
​
size
integer
default:"0"
Size of each page
​
publishPhase
string
Filter by publish phase: DRAFT, PENDING_APPROVAL, PUBLISHED, FAILED
​
visible
string
Filter by visibility: PUBLIC, INTERNAL, PRIVATE
​
keyword
string
Filter by keyword
​
contributor
array
Filter by contributor names

​
Create Single Page

Create a new single page. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/singlepages" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": {
      "spec": {
        "title": "About Page",
        "slug": "about"
      }
    },
    "content": {
      "raw": "# About Us",
      "content": "<h1>About Us</h1>",
      "rawType": "markdown"
    }
  }'

​
Update Single Page

Update an existing single page. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/singlepages/{name}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "page": {
      "spec": {
        "title": "Updated About Page"
      }
    },
    "content": {
      "raw": "Updated content",
      "content": "<p>Updated content</p>",
      "rawType": "markdown"
    }
  }'
​
name
string
required
Single page name

​
Publish Single Page

Publish a single page. 
curl -X PUT "http://localhost:8091/apis/api.console.halo.run/v1alpha1/singlepages/{name}/publish" \
  -H "Authorization: Bearer {token}"
​
name
string
required
Single page name to publish

​
Comments

​
List Comments

Retrieve a paginated list of comments. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/comments?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number
​
size
integer
default:"0"
Size of each page
​
keyword
string
Filter comments by keyword
​
ownerKind
string
Filter by commenter kind
​
ownerName
string
Filter by commenter name

​
Create Comment

Create a new comment. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/comments" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectRef": {
      "group": "content.halo.run",
      "kind": "Post",
      "name": "post-name"
    },
    "raw": "This is a comment",
    "content": "<p>This is a comment</p>",
    "allowNotification": true
  }'
​
comment
object
The created comment object

​
Create Reply

Create a reply to a comment. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/comments/{name}/reply" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "raw": "This is a reply",
    "content": "<p>This is a reply</p>",
    "allowNotification": true
  }'
​
name
string
required
Comment name to reply to

​
List Replies

List all replies for a comment. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/replies?commentName={commentName}" \
  -H "Authorization: Bearer {token}"
​
commentName
string
required
Comment name to get replies for
​
page
integer
default:"0"
Page number
​
size
integer
default:"0"
Size of each page

​
Tags

​
List Tags

Retrieve a paginated list of tags. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/tags?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number
​
size
integer
default:"0"
Size of each page
​
keyword
string
Filter tags by keyword
​
labelSelector
array
Label selector for filtering
​
fieldSelector
array
Field selector for filtering
​
sort
array
Sorting criteria

​
Attachments

​
Search Attachments

Search and list attachments with filtering options. 
curl -X GET "http://localhost:8091/apis/api.console.halo.run/v1alpha1/attachments?page=0&size=20" \
  -H "Authorization: Bearer {token}"
​
page
integer
default:"0"
Page number
​
size
integer
default:"0"
Size of each page
​
keyword
string
Keyword for searching attachments
​
accepts
array
Acceptable media types for filtering
​
ungrouped
boolean
Filter attachments without group. This parameter will ignore group parameter.

​
Upload Attachment

Upload a new attachment file. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/attachments/upload" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/file.jpg" \
  -F "policyName=default-policy" \
  -F "groupName=images"
​
metadata.name
string
Unique identifier for the attachment
​
spec.displayName
string
Display name of the attachment
​
spec.size
integer
Size of attachment in bytes
​
spec.mediaType
string
MIME type of the attachment
​
status.permalink
string
Public URL of the attachment

​
Upload from URL

Upload an attachment from an external URL. 
curl -X POST "http://localhost:8091/apis/api.console.halo.run/v1alpha1/attachments/-/upload-from-url" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.jpg",
    "policyName": "default-policy",
    "groupName": "images"
  }'
​
attachment
object
The created attachment object

Build docs developers (and LLMs) love

Get started for freeTalk to us