Create, read, update, and delete knowledge base articles.

Endpoints

Method Path Description
GET /api/v1/teams/{teamId}/articles List articles
POST /api/v1/teams/{teamId}/articles Create an article
GET /api/v1/teams/{teamId}/articles/{articleId} Get an article
PATCH /api/v1/teams/{teamId}/articles/{articleId} Update an article
DELETE /api/v1/teams/{teamId}/articles/{articleId} Delete an article

The single-resource endpoints accept both prefixed IDs (art_abc123) and UUIDs.

List Articles

GET /api/v1/teams/{teamId}/articles

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
pageSize integer Results per page (default: 20, max: 100)
status string Filter: draft, published, archived
category string Filter by category UUID
isPublic boolean Filter by public visibility (true or false)
search string Search in title and content
tag string Filter by tag (exact match)

The category parameter takes a UUID only. Slugs aren't accepted (a slug value silently returns an empty list because the underlying column is the UUID).

Example

curl "https://www.cstar.help/api/v1/teams/{teamId}/articles?status=published&isPublic=true" \
  -H "Authorization: Bearer sk_live_xxx"

Response

{
  "success": true,
  "data": [
    {
      "id": "art_m3N4o5P6q7R8",
      "object": "article",
      "title": "How to Reset Your Password",
      "slug": "how-to-reset-password",
      "excerpt": "Step-by-step guide to resetting your account password.",
      "content": "# How to Reset Your Password\n\nFollow these steps...",
      "categoryId": null,
      "status": "published",
      "tags": ["account", "password"],
      "notes": null,
      "viewCount": 1234,
      "useCount": 56,
      "readTime": "2 min",
      "isPublic": true,
      "publishedAt": "2025-12-01T10:00:00Z",
      "metaDescription": "Learn how to reset your account password.",
      "metadata": {},
      "createdAt": "2025-11-15T10:00:00Z",
      "updatedAt": "2026-03-30T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

readTime is computed automatically from content length.

Create Article

POST /api/v1/teams/{teamId}/articles

Requires a secret key.

Field Type Required Description
title string Yes Article title
content string No Article body (Markdown)
excerpt string No Short summary (auto-generated from title if omitted)
categoryId string No Category UUID
status string No draft (default), published, archived
tags string[] No Array of tags
notes string No Internal notes
isPublic boolean No See "Public visibility default" below
slug string No URL slug (auto-generated from title if omitted)
metaDescription string No SEO meta description
metadata object No Developer metadata (max 50 keys, string values)

Public visibility default

If status is draft (or omitted), isPublic defaults to false.

If status is published and isPublic is omitted, isPublic defaults to true. Pass isPublic: false explicitly to publish an internal-only article.

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/articles" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to Contact Support",
    "content": "# How to Contact Support\n\nYou can reach us via...",
    "status": "draft"
  }'

Returns 201 Created. If the generated slug conflicts with an existing article, a random suffix is appended automatically.

Setting status to published during creation sets publishedAt to the current time.

Get Article

GET /api/v1/teams/{teamId}/articles/{articleId}

Returns the full article including content.

Update Article

PATCH /api/v1/teams/{teamId}/articles/{articleId}

Requires a secret key. Send only the fields you want to change.

All create fields are accepted, plus:

  • Changing status to published (when it wasn't before) sets publishedAt automatically
  • Changing slug checks for conflicts and returns 409 Conflict if the slug is taken
  • metadata is merged with existing metadata (set a key to null to remove it)
  • categoryId can be set to null to remove the category
  • Setting status to archived hides the article from the public library without deleting it

Delete Article

DELETE /api/v1/teams/{teamId}/articles/{articleId}

Requires a secret key with delete permissions.

Returns:

{
  "success": true,
  "data": { "deleted": true, "id": "art_m3N4o5P6q7R8" }
}

Webhook Events

Event Fires When
article.created Article is created
article.updated Article fields change
article.published Article is published to the public library
article.deleted Article is deleted

Related