# Site articles

This endpoint lets you manage your knowledge base articles. Public articles can be retrieved without authentication.

# The article object

id integer

The system-generated ID of the article.
site_id integer

The system-generated ID of the site.
status enum: published, unpublished

The status of the article revision.
title string

The title of the article in the requested locale.
summary string

A short summary of the article in the requested locale.
content string

The content of the article in the requested locale.
source_locale string

The source locale of the article, which determines the main translation other translations should be based on.
locale string

The locale of the current translation being served.
sort_order decimal

The position of the article in a sorted list. This value can be either incremental (automatically assigned), or custom.
revision integer

The article's revision number.
has_draft boolean

Whether the article has a draft revision.
url string

The URL of the article.
views integer

The revision's view count.
collection_id integer

The system-generated ID of the collection.
collection object expandable

The collection object attached to the article.
categories array
The list of categories attached to the article.
Show child attributes
categories.* object expandable

The category object attached to the article.
translations array
The list of translations of the article.
Show child attributes
translations.[en, es, ...] object

The translation object.

Show child attributes
[en, es, ...].id integer

The system-generated ID of the translation.

[en, es, ...].locale string

The locale of the translation.

[en, es, ...].title string

The title of the article.

[en, es, ...].summary string

A short summary of the article.

[en, es, ...].content string

The content of the article.
reactions object
The reactions count for the current article revision.
Show child attributes
reactions.total integer

The total count of reactions.

reactions.positive integer

The total count of positive reactions.

reactions.negative integer

The total count of negative reactions.
feedback object
The feedback count for the current article revision.
Show child attributes
feedback.total integer

The total count of feedback.
created_at string

The timestamp when the article was created.
updated_at string

The timestamp when the article was last updated.

# The article object

{
  "id": 3,
  "site_id": 1,
  "status": "published",
  "title": "Sample article",
  "summary": "This is a summary of the article.",
  "content": "<p>Content...</p>",
  "source_locale": "en",
  "locale": "en",
  "sort_order": 1.5,
  "revision": 1,
  "has_draft": false,
  "url": "https://docs.example.com/en/article/123/sample-article",
  "views": 0,
  "collection_id": 1,
  "collection": {...},
  "categories": [],
  "translations": {
    "en": {
      "id": 5,
      "locale": "en",
      "title": "Sample article",
      "summary": "This is a summary of the article.",
      "content": "<p>Content...</p>"
    },
    "es-PR": {
      "id": 6,
      "locale": "es-PR",
      "title": "Requisitos del Servidor",
      "summary": "Resumen del artículo.",
      "content": "<p>Contenido...</p>"
    }
  },
  "reactions": {
    "total": 0,
    "positive": 0,
    "negative": 0
  },
  "feedback": {
    "total": 0,
  },
  "created_at": "2019-04-24T01:27:22+00:00",
  "updated_at": "2019-04-24T01:27:22+00:00"
}

# Create an article

source_locale string required

The source locale of the article, which determines the main translation other translations should be based on.
collection_id integer required

The system-generated ID of the collection.
status enum: published, unpublished optional

The status of the article revision. Articles are published by default when no status is provided.
sort_order decimal optional

The position of the article in a sorted list. New articles will be placed in the end of the list when this attribute is empty.
categories array optional
The list of categories attached to the article.
Show child attributes
categories.* integer

The ID of the article.
translations array
The list of translations of the article.
Show child attributes
translations.[en, es, ...] object

The translation object.

Show child attributes
[en, es, ...].title string required for source locale

The title of the article.

[en, es, ...].summary string optional

A short summary of the article.

[en, es, ...].content string required for source locale

The content of the article.

# Sample request

curl https://www.yourdomain.com/api/v1/site/1/articles \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d collection_id=1 \
  -d sort_order=3 \
  -d categories[0]=1 \
  -d categories[1]=2 \
  -d translations[en][title]="Sample article" \
  -d translations[en][summary]="This is a summary of the article" \
  -d translations[en][content]="<p>Content...</p>" \
  -d translations[es-PR][title]="Ejemplo de artículo" \
  -d translations[es-PR][summary]="Resumen del artículo." \
  -d translations[es-PR][content]="<p>Contenido...</p>"

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "status": "published",
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "revision": 1,
    "has_draft": false,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Retrieve a live article

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \ 
  -G

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "status": "published",
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "revision": 1,
    "has_draft": false,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Retrieve a draft article

You will get the current article's live revision if there's no draft. The system will not create a draft automatically by using this endpoint.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1/draft \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \ 
  -G

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "status": "published",
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "revision": 1,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Update an article's live revision

This endpoint will update the LIVE VERSION of the article. An update using this endpoint will not generate a revision. If you would like to update an article without affecting the live version, use the draft update endpoint instead.

source_locale string required

The source locale of the article, which determines the main translation other translations should be based on.
collection_id integer required

The system-generated ID of the collection.
status enum: published, unpublished optional

The status of the article revision.
sort_order decimal optional

The position of the article in a sorted list. New articles will be placed in the end of the list when this attribute is empty.
categories array optional
The list of categories attached to the article.
Show child attributes
categories.* integer

The ID of the article.
translations array
The list of translations of the article.
Show child attributes
translations.[en, es, ...] object

The translation object.

Show child attributes
[en, es, ...].title string required for source locale

The title of the article.

[en, es, ...].summary string optional

A short summary of the article.

[en, es, ...].content string required for source locale

The content of the article.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d collection_id=1 \
  -d sort_order=3 \
  -d categories[0]=1 \
  -d categories[1]=2 \
  -d translations[en][title]="Sample article" \
  -d translations[en][summary]="This is a summary of the article" \
  -d translations[en][content]="<p>Content...</p>" \
  -d translations[es-PR][title]="Ejemplo de artículo" \
  -d translations[es-PR][summary]="Resumen del artículo." \
  -d translations[es-PR][content]="<p>Contenido...</p>"

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "status": "published",
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "revision": 1,
    "has_draft": false,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Update an article's draft

Updates applied using this endpoint will not be visible publicly unless the draft is published. When a draft is published, the previous revision is left intact, and the draft revision becomes the live one.

source_locale string required

The source locale of the article, which determines the main translation other translations should be based on.
collection_id integer required

The system-generated ID of the collection.
status enum: published, unpublished optional

The status of the article revision. When you publish a draft revision, it becomes the article's live revision.
sort_order decimal optional

The position of the article in a sorted list. New articles will be placed in the end of the list when this attribute is empty.
categories array optional
The list of categories attached to the article.
Show child attributes
categories.* integer

The ID of the article.
translations array
The list of translations of the article.
Show child attributes
translations.[en, es, ...] object

The translation object.

Show child attributes
[en, es, ...].title string required for source locale

The title of the article.

[en, es, ...].summary string optional

A short summary of the article.

[en, es, ...].content string required for source locale

The content of the article.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles/1/draft \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d source_locale="en" \
  -d collection_id=1 \
  -d sort_order=3 \
  -d categories[0]=1 \
  -d categories[1]=2 \
  -d translations[en][title]="Sample article" \
  -d translations[en][summary]="This is a summary of the article" \
  -d translations[en][content]="<p>Content...</p>" \
  -d translations[es-PR][title]="Ejemplo de artículo" \
  -d translations[es-PR][summary]="Resumen del artículo." \
  -d translations[es-PR][content]="<p>Contenido...</p>"

# Sample successful response

{
  "data": {
    "id": 3,
    "site_id": 1,
    "status": "published",
    "title": "Sample article",
    "summary": "This is a summary of the article",
    "content": "<p>Content...</p>",
    "source_locale": "en",
    "locale": "en",
    "sort_order": 1.5,
    "revision": 2,
    "has_draft": true,
    "url": "https://docs.example.com/en/article/123/sample-article",
    "views": 0,
    "collection_id": 1,
    "collection": {...},
    "categories": [...],
    "translations": {
      "en": {
        "id": 5,
        "locale": "en",
        "title": "Sample article",
        "summary": "This is a summary of the article",
        "content": "<p>Content...</p>"
      },
      "es-PR": {
        "id": 6,
        "locale": "es-PR",
        "title": "Ejemplo de artículo",
        "summary": "Resumen del artículo",
        "content": "<p>Contenido...</p>"
      }
    },
    "reactions": {
      "total": 0,
      "positive": 0,
      "negative": 0
    },
    "feedback": {
      "total": 0,
    },
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Delete an article

curl https://www.yourdomain.com/api/v1/sites/1/articles/1 \
  --request DELETE
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

# Delete an article's draft

curl https://www.yourdomain.com/api/v1/sites/1/articles/1/draft \
  --request DELETE
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

# List all articles

# Parameters

query string optional

A filter on the list based on keywords.
collection_id integer optional

A filter on the list based on the article's collection_id field.
ids array of integers optional

A filter on the list based on the article's id field.
sort_by enum: sort_order optional

A sort on the list based on the provided article's field.
sort_type enum: desc, asc optional

The type of the sort to perform.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/articles \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": [
    {
      "id": 3,
      "site_id": 1,
      "status": "published",
      "title": "Sample article",
      "summary": "This is a summary of the article",
      "content": "<p>Content...</p>",
      "source_locale": "en",
      "locale": "en",
      "sort_order": 1.5,
      "revision": 1,
      "has_draft": true,
      "url": "https://docs.example.com/en/article/123/sample-article",
      "views": 0,
      "collection_id": 1,
      "collection": {...},
      "categories": [...],
      "translations": {
        "en": {
          "id": 5,
          "locale": "en",
          "title": "Sample article",
          "summary": "This is a summary of the article",
          "content": "<p>Content...</p>"
        },
        "es-PR": {
          "id": 6,
          "locale": "es-PR",
          "title": "Ejemplo de artículo",
          "summary": "Resumen del artículo",
          "content": "<p>Contenido...</p>"
        }
      },
      "reactions": {
        "total": 0,
        "positive": 0,
        "negative": 0
      },
      "feedback": {
        "total": 0,
      },
      "created_at": "2019-04-24T01:27:22+00:00",
      "updated_at": "2019-04-24T01:27:22+00:00"
    },
    {...}
  ]
}

← Site collection categories Site article feedback →

# Site articles

# The article object

id integer

site_id integer

status enum: published, unpublished

title string

summary string

content string

source_locale string

locale string

sort_order decimal

revision integer

has_draft boolean

url string

views integer

collection_id integer

collection object expandable

categories array

categories.* object expandable

translations array

translations.[en, es, ...] object

[en, es, ...].id integer

[en, es, ...].locale string

[en, es, ...].title string

[en, es, ...].summary string

[en, es, ...].content string

reactions object

reactions.total integer

reactions.positive integer

reactions.negative integer

feedback object

feedback.total integer

created_at string

updated_at string

# The article object

# Create an article

source_locale string required

collection_id integer required

status enum: published, unpublished optional

sort_order decimal optional

categories array optional

categories.* integer

translations array

translations.[en, es, ...] object

[en, es, ...].title string required for source locale

[en, es, ...].summary string optional

[en, es, ...].content string required for source locale

# Sample request

# Sample successful response

# Retrieve a live article

# Sample request

# Sample successful response

# Retrieve a draft article

# Sample request

# Sample successful response

# Update an article's live revision

source_locale string required

collection_id integer required

status enum: published, unpublished optional

sort_order decimal optional

categories array optional

categories.* integer

translations array

translations.[en, es, ...] object

[en, es, ...].title string required for source locale

[en, es, ...].summary string optional

[en, es, ...].content string required for source locale

# Sample request

# Sample successful response

# Update an article's draft

source_locale string required

collection_id integer required

status enum: published, unpublished optional

sort_order decimal optional

categories array optional

categories.* integer

translations array

translations.[en, es, ...] object

[en, es, ...].title string required for source locale

[en, es, ...].summary string optional