Articles

Articles power your knowledge base. Create, publish, and manage help content that customers and agents can search.

The Article object

id string

Unique article identifier (art_ prefix)

title string

Article title

content string

Article body (Markdown)

category string

Category name

status string

Publication status "draft" | "published"

isPublic boolean

Whether visible in public knowledge base

tags string[]

Array of tag strings

viewCount integer

Number of times viewed

useCount integer

Number of times used in replies

createdAt datetime

When the article was created

updatedAt datetime

Last modification timestamp

Endpoints

GET List Articles GET Get Article POST Create Article PATCH Update Article DELETE Delete Article

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

List Articles

Try it

Retrieve a paginated list of knowledge base articles with optional filtering.

Query Parameters

category string

Filter by category name

status string

Filter by publication status

isPublic boolean

Filter by public visibility

search string

Full-text search in title and content

page integer

Page number (1-indexed)

Default: 1

pageSize integer

Results per page (max 100)

Default: 20

Code Examples

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/articles?status=published" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Paginated list of articles

{
  "success": true,
  "data": [
    {
      "id": "art_a1b2c3d4e5f67890abcdef1234567890",
      "title": "How to reset your password",
      "category": "Account",
      "status": "published",
      "isPublic": true,
      "viewCount": 342,
      "useCount": 28,
      "createdAt": "2025-11-15T09:00:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z",
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 142,
      "totalPages": 8
    }
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Get Article

Try it

Retrieve a single article by ID with full content.

Path Parameters

articleId string required

The article ID (art_ prefix)

Code Examples

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/articles/{articleId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 The article object

{
  "success": true,
  "data": {
    "id": "art_a1b2c3d4e5f67890abcdef1234567890",
    "title": "How to reset your password",
    "content": "# Password Reset\n\n1. Go to login page\n2. Click \"Forgot Password\"...",
    "category": "Account",
    "status": "published",
    "isPublic": true,
    "tags": [
      "password",
      "account",
      "security"
    ],
    "viewCount": 342,
    "useCount": 28,
    "createdAt": "2025-11-15T09:00:00Z",
    "updatedAt": "2025-12-01T11:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Article not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Article not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Create Article

Try it

Create a new knowledge base article. Articles start as drafts by default.

Requires a secret API key.

Request Body

title string required

Article title

content string

Article body (Markdown)

category string

Category name

status string

Publication status

Default: draft

isPublic boolean

Whether visible publicly

Default: false

tags string[]

Array of tag strings. Also accepts comma-separated string via curl.

metadata object

Arbitrary key-value metadata (max 50 keys)

Code Examples

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/articles" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started Guide",
    "content": "# Welcome\n\nHere is how to get started...",
    "category": "Onboarding",
    "status": "draft"
  }'

Responses

201 Article created

{
  "success": true,
  "data": {
    "id": "art_a1b2c3d4e5f67890abcdef1234567890",
    "title": "Getting Started Guide",
    "status": "draft",
    "isPublic": false,
    "createdAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Update Article

Try it

Update one or more fields on an existing article.

Requires a secret API key.

Path Parameters

articleId string required

The article ID (art_ prefix)

Request Body

title string

Article title

content string

Article body (Markdown)

category string

Category name

status string

Publication status

isPublic boolean

Whether visible publicly

tags string[]

Array of tag strings. Also accepts comma-separated string via curl.

metadata object

Key-value metadata to merge. Existing keys preserved, new keys added. Set a key to null to remove it.

Code Examples

curl -X PATCH "https://www.cstar.help/api/v1/teams/{teamId}/articles/{articleId}" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published", "isPublic": true }'

Responses

200 Updated article

{
  "success": true,
  "data": {
    "id": "art_a1b2c3d4e5f67890abcdef1234567890",
    "title": "Getting Started Guide",
    "status": "published",
    "updatedAt": "2025-12-10T16:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T16:00:00Z"
  }
}

404 Article not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Article not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

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

Delete Article

Try it

Permanently delete an article from the knowledge base.

Requires a secret API key. This is a destructive operation.

Path Parameters

articleId string required

The article ID (art_ prefix)

Code Examples

curl -X DELETE "https://www.cstar.help/api/v1/teams/{teamId}/articles/{articleId}" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Article deleted

{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Article not found

{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Article not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

401 Authentication failed — missing or invalid API key

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions — wrong key type or team access

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}