Auto Blogger
EN
Log in
Menu
Home Features Pricing Blog Docs

Content topics are keywords waiting in the queue for scheduled or manual article generation. The API lets agents add, list, update, and remove topics without using the dashboard.

Topics created through POST (source api) automatically receive the highest score on that website and are moved to position 1 in the approved queue—the next scheduled generation run uses them before lower-scored topics.

See REST API overview for authentication. Reads need websites:read; writes need websites:manage or integrations:manage. Writers may manage the topic queue; only Owners/Admins may change website settings.

Queue behaviour (important)

Scheduled generation picks the next approved topic from the queue, skipping keywords that already match a published post. Queue position is what matters for “who goes next.”

When you create a topic via the API:

  1. It receives a score higher than any other topic on that website.
  2. The queue is reordered so higher scores run first (same outcome as Sort queue by score in the dashboard).
  3. The new topic is placed at the front of the queue and is chosen before lower-priority topics.

Topics added manually in the dashboard start with a low default score unless you reorder the queue.

Status values

Value Meaning
approved Eligible for generation (default for API creates)
skipped Dismissed; not generated
consumed Already used for a post — cannot be updated or deleted via API

Source values

API-created rows use source: "api". Other sources (manual, search_console, ai_suggested, ai_brainstormed) come from the product internally or the dashboard.

List topics

GET /api/websites/{uuid}/content-topics
Authorization: Bearer TOKEN

Returns { "data": [ ... ] } sorted by score descending, then queue order.

Topic object

Field Type Description
id integer Stable ID for PATCH/DELETE
keyword string Target phrase for the article
status string approved, skipped, or consumed
source string e.g. api, manual
score integer Priority weight
order_column integer or null Position in the queue (lower runs sooner)
metadata object or null Optional extra data when present
created_at / updated_at ISO 8601 or null

Create a topic (priority enqueue)

POST /api/websites/{uuid}/content-topics
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "keyword": "best CRM for small teams"
}
Field Rules
keyword Required. Max 255 characters. Trimmed; duplicates match case-insensitively per website.
status Optional. Defaults to approved.

Success — 201 Created

{
  "data": {
    "id": 91,
    "keyword": "best CRM for small teams",
    "status": "approved",
    "source": "api",
    "score": 501,
    "order_column": 1,
    "metadata": { "created_via": "api" },
    "created_at": "2026-10-14T14:00:00+00:00",
    "updated_at": "2026-10-14T14:00:00+00:00"
  }
}

If another topic on the same site already has score 500, the new topic receives 501 and moves ahead of it in the queue.

Duplicate keyword — 422

{
  "message": "A topic with this keyword already exists for this website.",
  "errors": {
    "keyword": ["A topic with this keyword already exists for this website."]
  }
}

Get one topic

GET /api/websites/{uuid}/content-topics/{id}
Authorization: Bearer TOKEN

Returns { "data": { ... } }. 404 if the ID does not belong to that website.

Update a topic

PATCH /api/websites/{uuid}/content-topics/{id}
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "keyword": "updated keyword phrase",
  "status": "approved",
  "prioritize": true
}
Field Rules
keyword Optional. Same uniqueness rules as create.
status Optional. Cannot change consumed topics.
prioritize Optional boolean. When true and status is approved, recomputes max score + 1 and re-sorts the queue so this topic runs first.

Topics with source: api are automatically re-prioritized on update when they remain approved (even without prioritize).

422 with message body when the topic is consumed.

Delete a topic

DELETE /api/websites/{uuid}/content-topics/{id}
Authorization: Bearer TOKEN

204 No Content on success. Cannot delete consumed topics (422).

Agent workflow example

Typical automation: ensure site exists → push urgent keyword → optionally patch settings.

BASE="https://auto-blogger.ai/api"
TOKEN="YOUR_ACCESS_TOKEN"
SITE="550e8400-e29b-41d4-a716-446655440000"

# 1. Confirm account context
curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/me"

# 2. Enqueue high-priority topic
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"Product launch recap"}' \
  "$BASE/websites/$SITE/content-topics"

# 3. Verify queue head (first item should be the new topic)
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/websites/$SITE/content-topics"

Dashboard parity

Dashboard action API equivalent
Add topic manually POST .../content-topics (API topics score higher than default manual 0)
Edit keyword / status PATCH .../content-topics/{id}
Remove from queue DELETE .../content-topics/{id}
Sort queue by score Automatic on API create; optional prioritize on PATCH

Generation itself still runs on the schedule configured on the website (websites API) or when triggered manually in the dashboard—not instantly on POST.

Related