Model Specification
Space
A space is a top-level entity that contains every other resources that are managed in the Documents feature.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the space. | "1" |
channelId | string | Y | channelId is the unique identifier of the channel that the space belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the space was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the space was last updated in epoch milliseconds. | 1704067200000 |
publishState | 'published' | 'unpublished' | Y | publishState determines whether the space is open to public. "published" spaces are open to public, while "unpublished" spaces are not. | "published" |
name | map<string, string> | Y | name is the map of localized names of the space. | { "en": "User Guide", "ko": "사용 가이드" } |
avatarUrl | string | N | avatarUrl is the URL for the space's profile image, which can be used as favicon or logo in the published website. | "https://cf.channel.io/path/to/image.png" |
defaultLanguage | string | Y | defaultLanguage is the default language of the space. | "ko" |
supportedLanguages | string[] | Y | supportLanguages is the list of supported languages of the space. | ["ko", "en"] |
website | { url: string } | N | website is metadata for the space's published website. | { "url": "https://docs.channel.io/help" } |
Example
{
"avatarUrl": "https://cf.channel.io/path/to/image.png",
"channelId": "1",
"createdAt": 1704067200000,
"defaultLanguage": "ko",
"id": "1",
"name": {
"en": "User Guide",
"ko": "사용 가이드"
},
"publishState": "published",
"supportedLanguages": [
"ko",
"en"
],
"updatedAt": 1704067200000,
"website": {
"url": "https://docs.channel.io/help"
}
}
Article
An article represents a single document, which consists of multiple versions (revisions) in different languages. The content of the article is derived from its "current revision" in the requested language, which is the published revision (if any), or the most recently updated unpublished revision (if any), or the most recently updated draft revision.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the article. However, an article has multiple revisions (versions) and there could be a published (a.k.a. live) version for each language. (id, language) could work as a key for identifying a live content. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the article belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the revision of the article in the requested language was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the revision of the article in the requested language was last updated in epoch milliseconds. | 1704067200000 |
state | 'draft' | 'published' | 'unpublished' | Y | state is the current state of the current revision of the article in the requested language. "draft": the article can be edited and is not visible to the public. "published": the article is visible to the public and cannot be edited. "unpublished": the article is not visible to the public and cannot be edited. | "published" |
publishedRevisionId | string | N | publishedRevisionId is the identifier of the published (live) revision of the article in the requested language. If the article is not published, this field is empty. | "1" |
publishedAt | number | N | publishedAt is the timestamp when the article was published in epoch milliseconds. This timestamp is only available when the article is published. publishedAt could be updated when a new revision is published, but it can be configured manually by the user. | 1704067200000 |
currentRevisionId | string | Y | currentRevisionId is the identifier of the current revision of the article in the requested language. An article could contain multiple revisions in a single language, but only one of them is considered as the "current" revision. - If there is a published revision, the current revision is the published revision. - If there are unpublished revisions, the current revision is the one with the latest updatedAt timestamp. - If there are only draft revisions, the current revision is the one with the latest updatedAt timestamp. | "1" |
slug | string | Y | slug is the unique key of the article within the space, which can be used in the URL. | "192a233f" |
topicIds | string[] | Y | topicIds is the list of ids of the topics that the article is associated with. | ["1", "2", "3"] |
website | { url: string } | N | ||
authorId | string | Y | authorId is the identifier of the author of the article. | "1" |
name | string | Y | name is the name of the current revision of the article in the requested language. | "한국어20240701_0000" |
coverImageUrl | string | N | body is the block-formatted content of this article. | "https://cf.channel.io/path/to/image.png" |
title | string | N | title is the title of this article. | "사용 가이드" |
subtitle | string | N | subtitle is the subtitle of this article. | "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." |
summary | string | N | summary is the plaintext summary of this article. | "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." |
body | Blocks | N | body is the block-formatted content of this article. | [{ "type": "text", "content": [{ "type": "plain", "attrs": { "text": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." } }] }] |
bodyHtml | string | N | bodyHtml is the HTML-formatted content of this article. | <p>채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.</p> |
Example
{
"authorId": "1",
"body": [
{
"type": "text",
"content": [
{
"type": "plain",
"attrs": {
"text": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요."
}
}
]
}
],
"bodyHtml": "<p>채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.</p>",
"coverImageUrl": "https://cf.channel.io/path/to/image.png",
"createdAt": 1704067200000,
"currentRevisionId": "1",
"id": "1",
"name": "한국어20240701_0000",
"publishedAt": 1704067200000,
"publishedRevisionId": "1",
"slug": "192a233f",
"spaceId": "1",
"state": "published",
"subtitle": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.",
"summary": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.",
"title": "사용 가이드",
"topicIds": [
"1",
"2",
"3"
],
"updatedAt": 1704067200000,
"website": {
"url": "https://docs.channel.io/help/article/192a233f"
}
}
Author
Authors are creators of articles, with profile information shown as the writer of the document.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the author. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the author belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the author was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the author was last updated in epoch milliseconds. | 1704067200000 |
avatarUrl | string | N | avatarUrl is the URL for the author's profile image. | "https://cf.channel.io/path/to/image.png" |
profile | map<string, { name: string, bio?: string }> | Y | profile is the map of localized profiles of the author. | { "en": { "name": "Channel Talk", "bio": "Channel Talk is all-in-one live chat messenger for businesses." } } |
Example
{
"avatarUrl": "https://cf.channel.io/path/to/image.png",
"createdAt": 1704067200000,
"id": "1",
"profile": {
"en": {
"bio": "Channel Talk is all-in-one live chat messenger for businesses.",
"name": "Channel Talk"
}
},
"spaceId": "1",
"updatedAt": 1704067200000
}
Category
Categories form the top-level navigation and groups articles with similar topics.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the category. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the category belongs to | "1" |
createdAt | number | Y | createdAt is the timestamp when the category was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the category was last updated in epoch milliseconds. | 1704067200000 |
slug | string | Y | slug is the unique key of the category within the space, which can be used in the URL. | "192a233f" |
name | map<string, string> | Y | name is the map of localized names of the category. | { "en": "FAQ", "ko": "자주 묻는 질문" } |
description | map<string, string> | Y | description is the map of localized descriptions of the category. | { "en": "Category for frequently asked questions.", "ko": "자주 묻는 질문을 모아둔 카테고리입니다." } |
coverImageUrl | map<string, string> | Y | coverImageUrl is the map of cover image URLs for each language. | { "en": "https://cf.channel.io/path/to/image-en.png", "ko": "https://cf.channel.io/path/to/image-ko.png" } |
publishState | map<string, 'published' | 'unpublished'> | Y | publishState is the setting whether the category is open to public for each language. "published" categories are open to public, while "unpublished" categories are not. | { "en": "unpublished", "ko": "published" } |
Example
{
"coverImageUrl": {
"en": "https://cf.channel.io/path/to/image-en.png",
"ko": "https://cf.channel.io/path/to/image-ko.png"
},
"createdAt": 1704067200000,
"description": {
"en": "Category for frequently asked questions.",
"ko": "자주 묻는 질문을 모아둔 카테고리입니다."
},
"id": "1",
"name": {
"en": "FAQ",
"ko": "자주 묻는 질문"
},
"publishState": {
"en": "unpublished",
"ko": "published"
},
"slug": "192a233f",
"spaceId": "1",
"updatedAt": 1704067200000
}
Language
A data model for supported languages.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
code | string | Y | Language code. | "ko" |
name | string | Y | Language name in english. | "Korean" |
localizedName | string | Y | Language name in target language. | "한국어" |
{
"code": "ko",
"name": "Korean",
"localizedName": "한국어"
}
NavNode
NavNodes (navigation nodes) compose the hierarchical navigation for a website in category layout.
- A navigation node is a tree node which can have a parent node and many children nodes.
- A node can be connected to either a category or an article. Articles can only be connected to leaf nodes.
- There exists a special root node for each space.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the navigation node. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the navigation node belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the navigation node was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the navigation node was last updated in epoch milliseconds. | 1704067200000 |
nodeType | 'root' | 'article' | 'category' | Y | nodeType is the type of the navigation node. It can be one of the following: - root: The root node of the navigation tree. There is only one root node in a navigation tree. - category: A category node in the navigation tree. - article: An article node in the navigation tree. | "category" |
rootNodeId | string | Y | ||
parentNodeId | string | N | parentNodeId is the id of the parent node of this node. The root node does not have a parent node. | "1" |
rank | number | Y | rank is the order of the node within the siblings in the navigation tree. | 0 |
entityType | 'article' | 'category' | N | entityType is the type of the entity that is connected to this node. The root node does not have an entity connected to it. It can be one of the following: - category: The attached entity is a category. - article: The attached entity is an article. | "category" |
entityId | string | N | entityId is the id of the entity that is connected to this node. The root node does not have an entity connected to it. | "1" |
{
"createdAt": 1704067200000,
"entityId": "1",
"entityType": "category",
"id": "1",
"nodeType": "category",
"parentNodeId": "1",
"rank": 0,
"spaceId": "1",
"updatedAt": 1704067200000
}
Revision
A revision is a version of an article. An article can have a single published revision in each language.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the revision. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the revision belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the revision was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the revision was last updated in epoch milliseconds. | 1704067200000 |
articleId | string | Y | articleId is the identifier of the article that the revision belongs to. | "1" |
language | string | Y | language is the language of the revision. | "ko" |
state | 'draft' | 'published' | 'unpublished' | Y | state is the current state of the revision. - "draft": the revision can be edited and is not visible to the public. - "published": the revision is visible to the public and cannot be edited. - "unpublished": the revision is not visible to the public and cannot be edited. | "published" |
authorId | string | Y | authorId is the identifier of the author of the revision. | "1" |
name | string | Y | name is the name of the revision. | "한국어20240701_0000" |
coverImageUrl | string | N | coverImageUrl is the URL of the cover image of the revision. | "https://cf.channel.io/path/to/image.png" |
title | string | N | title is the title of this revision. | "사용 가이드" |
subtitle | string | N | subtitle is the subtitle of this revision. | "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." |
summary | string | N | summary is the plaintext summary of this revision's content. | "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." |
body | Blocks | N | body is the block-formatted content of this revision. | [{ "type": "text", "content": [{ "type": "plain", "attrs": { "text": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요." } }] }] |
bodyHtml | string | N | bodyHtml is the HTML-formatted content of this revision. | <p>채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.</p> |
{
"articleId": "1",
"authorId": "1",
"body": [
{
"type": "text",
"content": [
{
"type": "plain",
"attrs": {
"text": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요."
}
}
]
}
],
"bodyHtml": "<p>채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.</p>",
"coverImageUrl": "https://cf.channel.io/path/to/image.png",
"createdAt": 1704067200000,
"id": "1",
"language": "ko",
"name": "한국어20240701_0000",
"spaceId": "1",
"state": "published",
"subtitle": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.",
"summary": "채널톡을 처음 시작할 때 필요한 세팅 과정을 모두 알려드려요.",
"title": "사용 가이드",
"updatedAt": 1704067200000
}
Topic
Topics can be attached to articles to group them.
| Field Name | Type | Required? | Description | Example |
|---|---|---|---|---|
id | string | Y | id is the unique identifier of the topic. | "1" |
spaceId | string | Y | spaceId is the unique identifier of the space that the topic belongs to. | "1" |
createdAt | number | Y | createdAt is the timestamp when the topic was created in epoch milliseconds. | 1704067200000 |
updatedAt | number | Y | updatedAt is the timestamp when the topic was last updated in epoch milliseconds. | 1704067200000 |
name | map<string, string> | Y | name is the map of localized names of the topic. | { "en": "Documents", "ko": "도큐먼트" } |
description | map<string, string> | Y | id is the unique identifier of the topic. | { "en": "Your Knowledge Base in One Place", "ko": "사용 가이드 개발자 문서 블로그까지 도큐먼트 하나면 끝" } |
{
"createdAt": 1704067200000,
"description": {
"en": "Your Knowledge Base in One Place",
"ko": "사용 가이드 개발자 문서 블로그까지 도큐먼트 하나면 끝"
},
"id": "1",
"name": {
"en": "Documents",
"ko": "도큐먼트"
},
"spaceId": "1",
"updatedAt": 1704067200000
}
Updated 5 months ago