Articles
/api/knowledgebase/articles
Resource-oriented WebAPI for readable and editable knowledge base articles.
The endpoint deliberately stages writable values in memory. A commit re-reads the article and applies only the values supplied by the request so that PUT and PATCH preserve fields omitted by the client.
GET /api/knowledgebase/articles
Searches articles or loads front-page articles.
Parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
query |
query | string |
no | optional search query |
searchId |
query | string |
no | optional search request identifier |
categoryId |
query | integer (int32) |
no | optional category filter, or null for all categories |
language |
query | string |
no | optional language filter |
limit |
query | integer (int32) |
no | optional result limit, capped at 100 |
fields |
query | string |
no | Comma-separated readable properties to include in the JSON response. |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
200 |
application/json |
SearchResult |
compact search result data |
Example Request
# Request
GET /api/knowledgebase/articles HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
# Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"languages": [
{
"displayName": "string",
"key": "string"
}
],
"previews": [
{
"publishState": "INREVIEW",
"pinned": true,
"problem": "string",
"locationId": 0,
"articleId": 0
}
],
"hasMore": true,
"suggestions": [
{
"displayName": "string",
"tag": "string",
"type": "string",
"key": "string"
}
],
"categories": [
{
"displayName": "string",
"id": 0,
"key": "string"
}
]
}
POST /api/knowledgebase/articles
Creates a new staged article.
Request Body
| Content Type | Schema | Required | Description |
|---|---|---|---|
application/json |
KnowledgeBaseArticleCreate |
yes | — |
Response
| Status | Content Type | Schema | Description |
|---|---|---|---|
201 |
application/json |
KnowledgeBaseArticleRead |
staged article with creation defaults |
Example Request
# Request
POST /api/knowledgebase/articles HTTP/1.1
Accept: application/json
Authorization: Bearer <access-token>
Content-Type: application/json
{
"pinned": true,
"title": "string",
"categoryId": 0,
"publishState": "INREVIEW",
"locationId": 0
}
# Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"pinned": true,
"lastModified": 0,
"lastEditor": "string",
"resolved": "string",
"title": "string"
}
Common Error Responses
The status codes 400, 403, 404, 405, 406, 409, 413, 415, and 500 use the same ApiError JSON error format:
{
"status": 404,
"code": "route_not_found",
"message": "The requested API route does not exist.",
"details": []
}
Schemas
Request and response schemas used on this page.
SearchResult
| Property | Type | Required | Description |
|---|---|---|---|
languages |
array<LanguagePreview> |
no | — |
previews |
array<ArticlePreview> |
no | — |
hasMore |
boolean |
no | — |
suggestions |
array<SearchSuggestion> |
no | — |
categories |
array<CategoryPreview> |
no | — |
LanguagePreview
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
key |
string |
no | — |
ArticlePreview
| Property | Type | Required | Description |
|---|---|---|---|
publishState |
string [INREVIEW, SUPPORTER, LOCATION, ALL] |
no | — |
pinned |
boolean |
no | — |
problem |
string |
no | — |
locationId |
integer (int32) |
no | — |
articleId |
integer (int32) |
no | — |
languageId |
string |
no | — |
lastModified |
number (int64) |
no | — |
title |
string |
no | — |
createdOn |
number (int64) |
no | — |
favorite |
boolean |
no | — |
categoryId |
integer (int32) |
no | — |
SearchSuggestion
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
tag |
string |
no | — |
type |
string |
no | — |
key |
string |
no | — |
CategoryPreview
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
id |
integer (int32) |
no | — |
key |
string |
no | — |
ApiError
| Property | Type | Required | Description |
|---|---|---|---|
status |
integer (int32) |
yes | — |
code |
string |
yes | — |
message |
string |
yes | — |
details |
array<object> |
no | — |
KnowledgeBaseArticleCreate
| Property | Type | Required | Description |
|---|---|---|---|
pinned |
boolean |
no |
Stages a pin change. Pinning is an edit operation even though it is stored separately from the article text. |
title |
string |
no |
Stages a title change. |
categoryId |
integer (int32) |
no |
Stages a category change. |
publishState |
string [INREVIEW, SUPPORTER, LOCATION, ALL] |
no |
Stages a publication state change. |
locationId |
integer (int32) |
no |
Stages a location change. |
problem |
string |
no |
Stages a problem HTML change. |
solution |
string |
no |
Stages a solution HTML change. |
languageId |
string |
no |
Stages a language change. |
refTicketId |
integer (int32) |
no |
Stages a ticket reference change. |
KnowledgeBaseArticleRead
| Property | Type | Required | Description |
|---|---|---|---|
pinned |
boolean |
no |
Returns whether the article is pinned. |
lastModified |
number (int64) |
no |
Returns the server-maintained last-modified timestamp. |
lastEditor |
string |
no |
Returns the safe account identifier of the last editor. |
resolved |
ResolvedDisplay |
no |
Returns safe category, location, editor, and ticket display information. |
title |
string |
no |
Returns the staged or persistent article title. |
categoryId |
integer (int32) |
no |
Returns the article category identifier. |
attachments |
array<AttachmentMetadata> |
no |
Returns attachment metadata without internal attachment identifiers. The attachments plugin is optional; an unavailable plugin is represented by an empty list. |
publishState |
string [INREVIEW, SUPPORTER, LOCATION, ALL] |
no |
Returns the article publication state. |
articleId |
integer (int32) |
no |
Returns the article identifier, which is assigned by the server. |
locationId |
integer (int32) |
no |
Returns the article location identifier. |
createdOn |
number (int64) |
no |
Returns the immutable article creation timestamp. |
problem |
string |
no |
Returns problem HTML with attachment URLs adapted for the client. |
solution |
string |
no |
Returns solution HTML with attachment URLs adapted for the client. |
languageId |
string |
no |
Returns the article language identifier. |
refTicketId |
integer (int32) |
no |
Returns the referenced ticket identifier only when the current user can access that ticket. |
favorite |
boolean |
no |
Returns whether the current user marked this article as a favorite. |
ResolvedDisplay
| Property | Type | Required | Description |
|---|---|---|---|
editor |
EditorDisplay |
no | — |
referenceTicket |
TicketDisplay |
no | — |
location |
LocationDisplay |
no | — |
category |
CategoryDisplay |
no | — |
EditorDisplay
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
id |
string |
no | — |
TicketDisplay
| Property | Type | Required | Description |
|---|---|---|---|
subject |
string |
no | — |
id |
integer (int32) |
no | — |
LocationDisplay
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
id |
integer (int32) |
no | — |
CategoryDisplay
| Property | Type | Required | Description |
|---|---|---|---|
displayName |
string |
no | — |
id |
integer (int32) |
no | — |
key |
string |
no | — |
AttachmentMetadata
| Property | Type | Required | Description |
|---|---|---|---|
size |
number (int64) |
no | — |
name |
string |
no | — |
lastModified |
number (int64) |
no | — |
type |
string |
no | — |
embedded |
boolean |
no | — |
url |
string |
no | — |