Agent API

Mint a key in Dashboard → API keys. Hearof shows the secret once and stores only a SHA-256 hash. The key is bound to that workspace. Owners and co-owners can create and revoke keys. The feature is available on the Free plan.

Authentication

Send Authorization: Bearer hf_… on every /api/v1/* request. Missing, unknown, and revoked keys return 401. The widget publicSlug is read-only and is never accepted as a write credential.

Each key allows 60 requests per minute. A 429 response includes Retry-After.

Posts

• POST /api/v1/posts — create a draft (default) or a published post
• GET /api/v1/posts — list posts. Optional ?status=draft or ?status=published
• GET /api/v1/posts/:id — one post in this workspace
• PATCH /api/v1/posts/:id — update title, body, excerpt, categories, author, status, publishedAt, or cover

Slugs, categories, authors, and scheduling follow the same rules as the dashboard editor. A published post with a future publishedAt requires Pro. Markdown is stored as written and sanitized when Hearof renders the public page.

Create and publish

curl -X POST https://hearof.dev/api/v1/posts \
  -H "Authorization: Bearer hf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Search is faster",
    "bodyMarkdown": "We cut query time in half.",
    "categories": ["improvement"],
    "status": "published"
  }'

Or create a draft, then publish it:

curl -X PATCH https://hearof.dev/api/v1/posts/pst_YOUR_POST_ID \
  -H "Authorization: Bearer hf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Machine-readable spec

OpenAPI 3.1: https://hearof.dev/openapi.json. A short brief for agents also lives at https://hearof.dev/llms.txt.