API Developer documentation

Writing to the help centre

Create and edit help-centre articles and categories — so content can be synced

from Notion, Google Docs or anywhere else instead of being copied by hand.

Requires the kb:write scope.

The body is Markdown

Not the editor's own format. Headings, paragraphs, lists and tables are parsed by the same code that reads uploaded files, so an article created through the API is indistinguishable from one written in the editor: same blocks, same chunking, same semantic index for the AI operator.

curl -X POST https://api.tg-desk.com/v1/kb/articles \
  -H "Authorization: Bearer $TGDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handbook_id": "hb_123",
    "title": "Returns",
    "markdown": "# Returns\n\nYou can return an item within 14 days.\n\n- unused\n- original packaging"
  }'

Headings matter. The content is cut into retrieval chunks on them: an article with headings answers more precisely, while a flat wall of text indexes as a single chunk.

Drafts by default

A new article is created as a draft. That is deliberate: a sync that goes wrong must not publish to customers.

Publishing is a separate decision, via status:

{ "status": "published" }

Publishing is also the moment the article enters the AI operator's semantic index. Before that, the agent cannot see it.

Editing

Every field is optional. If you send markdown, send title with it — in the help centre a title and a body live together, one record per language.

curl -X PATCH https://api.tg-desk.com/v1/kb/articles/art_456 \
  -H "Authorization: Bearer $TGDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Returns", "markdown": "# Returns\n\nUpdated text." }'

The language is the locale parameter; without it, the handbook's own language is used.

Categories

curl -X POST https://api.tg-desk.com/v1/kb/categories \
  -H "Authorization: Bearer $TGDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handbook_id": "hb_123",
    "slug": "returns",
    "translations": [{ "locale": "en", "title": "Returns" }]
  }'

Nest one category under another with parent_id.

There is no delete

kb:write allows creating and editing only. Deleting an article or a category through the API is impossible, and the key holds no permission for it at all. Removing published content is a decision a person makes in the app; that does not get in the way of a sync, and it does protect you from a bug in a script.

If an article is no longer needed, set status: "archived" — it disappears for customers and for the AI operator, and stays for you.

Handbooks

The handbooks themselves are not created through the API: they are set up once in the app. List the available ones with GET /v1/kb/handbooks.

← Previous: Analytics

Next: Meetings →