Halo CMS Post Search

Search posts on any Halo-powered website via its public REST API (no authentication required).

Workflow

1. Extract the base URL from the user (e.g., https://example.com)
2. Ask for the search keyword if not provided
3. Call the search API using curl via the Shell tool
4. Parse the JSON response and present results to the user

Search API

Endpoint: POST {baseUrl}/apis/api.halo.run/v1alpha1/indices/-/search

Request Body (JSON):

{
  "keyword": "search term",
  "limit": 10,
  "highlightPreTag": "<B>",
  "highlightPostTag": "</B>"
}

Request Fields

Response Structure

{
  "hits": [
    {
      "id": "...",
      "metadataName": "post-abc",
      "title": "Post Title with <B>keyword</B> highlighted",
      "description": "Post description...",
      "content": "Plain text content...",
      "categories": ["category-name"],
      "tags": ["tag-name"],
      "ownerName": "author-name",
      "permalink": "/archives/post-slug",
      "type": "post.content.halo.run",
      "creationTimestamp": "2025-01-01T00:00:00Z",
      "updateTimestamp": "2025-01-15T00:00:00Z"
    }
  ],
  "keyword": "search term",
  "total": 5,
  "limit": 10,
  "processingTimeMillis": 42
}

Example curl Command

curl -s -X POST '{baseUrl}/apis/api.halo.run/v1alpha1/indices/-/search' \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"your keyword","limit":10,"highlightPreTag":"**","highlightPostTag":"**"}' | python3 -m json.tool

Use highlightPreTag / highlightPostTag set to ** for markdown-friendly bold highlighting in output.

Post Detail API

When the user wants to read the full content of a search result, fetch the post detail.

Endpoint: GET {baseUrl}/apis/api.content.halo.run/v1alpha1/posts/{name}

The {name} is the metadataName field from a search hit.

curl -s '{baseUrl}/apis/api.content.halo.run/v1alpha1/posts/{metadataName}' | python3 -m json.tool

Key Response Fields

Presenting Post Detail

Display:

1. Title (spec.title) with full URL ({baseUrl} + status.permalink)
2. Author (owner.displayName)
3. Date (spec.publishTime)
4. Categories / Tags (from categories[].spec.displayName and tags[].spec.displayName)
5. Content — prefer content.raw for readable text; use content.content (rendered HTML) as fallback
6. Stats (visits, comments, upvotes) if relevant

Presenting Search Results

For each hit, display:

1. Title (with permalink as full URL: {baseUrl}{permalink})
2. Description or a snippet of content
3. Tags / Categories if present
4. Date (creationTimestamp)

If the user wants the full post, call the Post Detail API using metadataName.

If total is 0, inform the user that no results were found.

If the request fails with a connection error, verify the URL is correct and the site is accessible. If it returns a search engine error, the site may not have a search plugin enabled.