Skip to content

REST API overview

The Topicary REST API lets you read and write project data programmatically. Use it to automate content workflows, build custom integrations, or sync Topicary with other systems.

Before you begin

This feature requires the Enterprise capability tier (the Business ). During the beta, every project is on the free Solo tier, so this feature is locked by default: go to Settings ▸ Billing and request Enterprise access to unlock it.

Only project members with the Admin can configure this feature. Authors and Reviewers do not have access to these settings.

Base URL

All API requests use the following base URL:

https://topicary.com/api/v1

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer tk_your_api_key_here

See for how to generate and manage API keys.

Rate limits

Each API key is limited to 1,000 requests per minute. Exceeding this limit returns a 429 Too Many Requests response. Back off and retry after a short delay.

If you consistently hit rate limits, batch your operations or add a delay between requests. For real-time event notifications, use Configure webhooks instead of polling.

Response envelope

Every response follows a standard JSON format:

Success (single resource):

{
  "data": { "id": "...", "title": "..." }
}

Success (list):

{
  "data": [{ "id": "...", "title": "..." }],
  "meta": { "total": 142, "offset": 0, "limit": 50 }
}

Error:

{
  "error": "Topic not found"
}

Pagination

List endpoints return up to 50 items by default. Use offset and limit query parameters to paginate:

GET /api/v1/topics?offset=50&limit=25

  • offset: 0-based index of the first item to return (default: 0)

  • limit: number of items to return, between 1 and 100 (default: 50)

The response includes a meta object with total, offset, and limit fields.

Error codes

The HTTP status code carries the error category. The response body is the error envelope shown above: a single error field with a human-readable message.

HTTP status

Meaning

400

Invalid request body or query parameters

401

Missing or invalid API key

403

Valid key but insufficient permissions, wrong plan, or a plan limit was reached

404

Resource does not exist or is not in this project

429

Too many requests, back off and retry

500

Unexpected server error

Content format

Topic and component content is returned as TipTap/ProseMirror JSON in a content_json field. This is the same structured format used by the Topicary editor. It preserves formatting, hierarchy, and metadata without relying on raw HTML.

The API does not accept or return raw Markdown or HTML. If you need Markdown output, use the Export content or the publishing pipeline.

See also

Was this page helpful?