Polyblog API reference

Every endpoint of the Polyblog REST API, generated from the API itself.

All endpoints are relative to https://api.polyblog.io. Create an API key in your Polyblog dashboard, then authenticate every request with it.

apiKey — HTTP Basic auth carrying only the API key secret: Authorization: Basic base64(<key secret>).

accessToken — Operator session token issued by the Polyblog dashboard: Authorization: Token <access token>.

Download the OpenAPI specification for use with your own tooling.

Articles

GET/api/articles

List articles

Lists the articles of a blog. Requires the articles:read scope. Anonymous (unauthenticated) callers only ever see published articles; drafts are visible only to an API key or operator token of the owning organization.

articles:readapiKeyaccessToken
Parameters
NameInTypeDescription
blogIdrequiredquerystring
localequerystring
publishedqueryboolean
slugquerystring
limitqueryinteger
skipqueryinteger
Responses
StatusMeaning
200A list of articles
401Missing or invalid credentials
403API key is missing the articles:read scope
429API key rate limit exceeded
POST/api/articles

Create or update an article

Creates an article (or updates one when the body carries an existing _id). Requires the articles:write scope. Fires the article.created webhook.

articles:writeapiKeyaccessToken
Request body
FieldTypeDescription
blogIdstring
titlestring
contentstring
slugstring
localestring
publishedboolean
Responses
StatusMeaning
200The created or updated article
401Missing or invalid credentials
403API key is missing the articles:write scope
429API key rate limit exceeded
GET/api/articles/{idOrSlug}

Get an article

Returns a single article by id or slug. Requires the articles:read scope. An article belonging to another organization responds 404 so ids cannot be probed. Anonymous callers can only read a published article; a draft responds 404 unless the caller is an API key or operator token of the owning organization.

articles:readapiKeyaccessToken
Parameters
NameInTypeDescription
idOrSlugrequiredpathstring
Responses
StatusMeaning
200The article
404Not found (or owned by another organization / unpublished)
POST/api/articles/generate

Generate an article with AI

Generates (and by default publishes) an SEO article for a blog. Requires the articles:write scope. Fires the article.created webhook when the generated article is persisted.

articles:writeapiKeyaccessToken
Responses
StatusMeaning
200The generated article and metadata
403API key is missing the articles:write scope
DELETE/api/articles/{articleId}

Delete an article

Deletes an article. Requires the articles:write scope. An article owned by another organization responds 404. Fires the article.deleted webhook.

articles:writeapiKeyaccessToken
Parameters
NameInTypeDescription
articleIdrequiredpathstring
Responses
StatusMeaning
200The deleted article id
404Not found (or owned by another organization)

Blogs

GET/api/blogs

List blogs

Lists the blogs of your organization. Requires the blogs:read scope.

blogs:readapiKeyaccessToken
Responses
StatusMeaning
200A list of blogs
403API key is missing the blogs:read scope
POST/api/blogs

Create a blog

Creates a blog for your organization. Requires the blogs:write scope. Fires the blog.created webhook.

blogs:writeapiKeyaccessToken
Responses
StatusMeaning
200The created blog
403API key is missing the blogs:write scope
PUT/api/blogs/{blogId}

Update a blog

Updates a blog owned by your organization. Requires the blogs:write scope.

blogs:writeapiKeyaccessToken
Parameters
NameInTypeDescription
blogIdrequiredpathstring
Responses
StatusMeaning
200The updated blog
403Not your organization's blog, or missing the blogs:write scope

Topics

GET/api/topics

List topic ideas

Lists the topic ideas of a blog you own. Requires the topics:read scope.

topics:readapiKeyaccessToken
Parameters
NameInTypeDescription
blogIdrequiredquerystring
Responses
StatusMeaning
200The topic ideas
403API key is missing the topics:read scope

Webhook subscriptions

GET/api/webhooksubscriptions

List webhook subscriptions

Webhook subscriptions deliver article.created, article.updated, article.deleted, blog.created and contact.created events to your server as signed POST requests (X-Polyblog-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the secret is only returned once, on create.

accessToken
Responses
StatusMeaning
200Array of webhook subscriptions (without secrets)
POST/api/webhooksubscriptions

Create a webhook subscription

Pass a blogId to receive only that blog's events, or omit it for an organization-wide subscription. The response includes the signing secret exactly once — store it; it cannot be retrieved again.

accessToken
Request body
FieldTypeDescription
blogIdstring
urlrequiredstring
eventsarray (article.created | article.updated | article.deleted | blog.created | contact.created)Empty array subscribes to all events
Responses
StatusMeaning
200The created subscription, including its secret
PUT/api/webhooksubscriptions/{webhookSubscriptionId}

Update a webhook subscription

url, events and active are editable; the secret, organization and blog are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200The updated subscription (without secret)
DELETE/api/webhooksubscriptions/{webhookSubscriptionId}

Delete a webhook subscription

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200Deleted