{"openapi":"3.1.0","info":{"title":"Hearof Agent API","version":"1.0.0","description":"Create and update changelog posts for one workspace. Authenticate with an API key from Dashboard → API keys (`Authorization: Bearer hf_…`). The widget publicSlug is not a write credential. Rate limit: 60 requests per 60 seconds per key."},"servers":[{"url":"https://hearof.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"hf_","description":"Workspace API key. Shown once at creation."}}},"paths":{"/api/v1/posts":{"get":{"operationId":"listPosts","summary":"List posts in the key's workspace","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published"]}}],"responses":{"200":{"description":"Posts, newest update first","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"authorId":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"announcedAt":{"type":"string","format":"date-time","nullable":true,"description":"Reader-facing revision. First publish uses publishedAt."},"coverImageUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publicPath":{"type":"string"}},"required":["id","title","slug","status"]}}},"required":["posts"]}}}},"401":{"description":"Missing, invalid, or revoked key"},"429":{"description":"Per-key rate limit"}}},"post":{"operationId":"createPost","summary":"Create a draft or published post","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"authorId":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601. A future date on a published post requires Pro."},"coverImageUrl":{"type":"string","nullable":true},"notifyReaders":{"type":"boolean","description":"PATCH only. Re-announce a post that is already published. Ignored on create."},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string"},"title":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true}},"required":["languageCode","title"]}}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"authorId":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":"string","format":"date-time","nullable":true},"announcedAt":{"type":"string","format":"date-time","nullable":true,"description":"Reader-facing revision. First publish uses publishedAt."},"coverImageUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"publicPath":{"type":"string"}},"required":["id","title","slug","status"]}},"required":["post"]}}}},"401":{"description":"Missing, invalid, or revoked key"},"422":{"description":"Validation or plan error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Per-key rate limit"}}}},"/api/v1/posts/{id}":{"get":{"operationId":"getPost","summary":"Get one post in the key's workspace","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post"},"401":{"description":"Missing, invalid, or revoked key"},"404":{"description":"Not in this workspace"}}},"patch":{"operationId":"updatePost","summary":"Update title, body, status, categories, date, or author","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"authorId":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published"]},"publishedAt":{"type":"string","format":"date-time","nullable":true,"description":"ISO-8601. A future date on a published post requires Pro."},"coverImageUrl":{"type":"string","nullable":true},"notifyReaders":{"type":"boolean","description":"PATCH only. Re-announce a post that is already published. Ignored on create."},"translations":{"type":"array","items":{"type":"object","properties":{"languageCode":{"type":"string"},"title":{"type":"string"},"bodyMarkdown":{"type":"string"},"excerpt":{"type":"string","nullable":true}},"required":["languageCode","title"]}}}}}}},"responses":{"200":{"description":"Updated"},"401":{"description":"Missing, invalid, or revoked key"},"404":{"description":"Not in this workspace"},"422":{"description":"Validation or plan error"}}}}}}