REST API endpoints

This reference covers all available REST API overview endpoints. Every request requires REST API authentication.

Before you begin #

Topics #

List topics #

GET /api/v1/topics

Query parameters: offset, limit, status (draft, review, published), type.

curl https://topicary.com/api/v1/topics?status=published \
  -H "Authorization: Bearer tk_your_key"

const res = await fetch(
  "https://topicary.com/api/v1/topics?status=published",
  { headers: { Authorization: "Bearer tk_your_key" } }
);
const { data, meta } = await res.json();

import requests

res = requests.get(
    "https://topicary.com/api/v1/topics",
    params={"status": "published"},
    headers={"Authorization": "Bearer tk_your_key"},
)
data = res.json()["data"]

Get a topic #

GET /api/v1/topics/:id

Returns the topic with its content_json (TipTap/ProseMirror JSON) — always the main content, never a branch.

Create a topic #

POST /api/v1/topics

Body: { "title": "...", "content_json": {...} }

Update a topic #

PATCH /api/v1/topics/:id

Body: any combination of title, content_json, status.

A content update writes the topic's main content. To write a branch instead, add branch_id:

{ "content_json": { "type": "doc", "content": [] }, "branch_id": "<branch uuid>" }

Rules for branch_id:

• It targets one branch of this topic. If the branch does not exist, belongs to another topic, or cannot be written, the request returns 404.

• It requires content_json in the same request — title, status, topic_type, and metadata_json belong to the topic itself and are always written to the topic even when a branch is targeted.

• A branch write does not create a version snapshot, does not mark translations stale, and does not update reference or search data. Those follow the main content, so they update when the branch is merged.

Which branch a person has open in the editor never affects the API. Without branch_id, a content update always writes main.

Delete a topic #

DELETE /api/v1/topics/:id

Returns 204 No Content on success.

Components #

List components #

GET /api/v1/components

Query parameters: offset, limit.

Get a component #

GET /api/v1/components/:id

Create a component #

POST /api/v1/components

Body: { "title": "...", "content_json": {...} }

Update a component #

PATCH /api/v1/components/:id

Delete a component #

DELETE /api/v1/components/:id

Maps #

List maps #

GET /api/v1/maps

Get a map #

GET /api/v1/maps/:id

Returns the map with its items (topic references and hierarchy).

Create a map #

POST /api/v1/maps

Body: { "title": "...", "description": "..." }

Update a map #

PATCH /api/v1/maps/:id

Delete a map #

DELETE /api/v1/maps/:id

Publication targets #

Publication targets are read-only through the API. Create, configure, and publish targets in the Topicary publish manager. The API exposes them for inspection only.

List targets #

GET /api/v1/targets

Each target includes map_id, name, output_format, subdomain, custom_domain, is_published, published_at, and access_mode.

Get a target #

GET /api/v1/targets/:id

Returns the full target configuration, including seo_json, variable_overrides_json, locale, search_config_json, and pdf_config_json.

Webhooks #

List webhooks #

GET /api/v1/webhooks

Create a webhook #

POST /api/v1/webhooks

Body: { "url": "https://...", "events": ["topic.status_changed", "map.published"] }

See Configure webhooks for the full list of event types.

Update a webhook #

PATCH /api/v1/webhooks/:id

Delete a webhook #

DELETE /api/v1/webhooks/:id

See also #

• REST API overview: base URL, rate limits, response format, and error codes

• REST API authentication: generate and manage API keys

• Configure webhooks: event-driven notifications as an alternative to polling

• Plans and limits: the REST API requires a Business plan