Article API Endpoint

0

Articles are organized into categories. Several articles can exist within a single category, which will display them together as an associated group. Each article must be assigned to a category, which controls access to readers via the user_groups settings.

Using the Article API, you can programmatically access article objects to organize these from your own applications and scripts. Possible uses include creating content, importing data from external sources, or exporting content for backup or any other purpose.


The article object


Attributes

article_id

This is the unique numeric reference for the article. This is used to identity an article in a number of API calls

This value is immutable and cannot be changed.

title

A descriptive title that is associated with the article and will be displayed at the top of the article when viewed. This value is also used when searching for content.

You should limit the length of this to be as short as practical.

Using article names that are too long may cause them to become truncated or displayed incorrectly on certain devices (think of mobile displays, which have less usable area)

slug

Unique string value associated with the article and used as part of the URL.

This value must contain no spaces or special characters. Only alphanumeric characters and hyphens.

You should also try to keep the length of this value well within the 55 character limit for optimal performance.

article_text

The article text is the raw HTML content of the article body.

The raw text contents from article_text will be extracted and indexed as part of the advanced lexical search mechanisms used within the GoGoWorx system.

There are no practical limits to the length of data that can be included in article_text, however you should consider your reader audience and decide whether it would be better to split up lengthy articles into several related articles.

creation_date

A Unix timestamp representing the time the article was created

For example, the value 1588698334 shown to the right represents May 5th 2020, 5:05pm (UTC)

modified_date

A Unix timestamp representing the last time the article was modified

views

A numeric value indicating the number of times readers have viewed the article.

rating

Value calculated by adding upvotes and subtracting downvotes values, indicating the overall rating of the article based on votes submitted.

published

A boolean value of true or false indicating whether the article is published or not. Articles that are not published cannot be seen by readers. Only editors and other staff will be able to view and edit them.

author

Numeric reference to an the account user that created the article.

Use the User API to obtain details of account users if needed.

editor

Numeric reference to an the account user that most recently updated the article.

Use the User API to obtain details of account users if needed.

featured

A boolean value of true or false indicating whether the article is marked as 'featured' or not.

Articles that are marked as 'featured' will be show in a special 'featured' list (when enabled) on the knowledge base homepage.

category_id

This is the unique numeric reference of the category this article is associated with.

This value is used to determine which articles are shown when a category is selected and is also used in conjunction with category_groups to control access to articles.

weight

The relative weighting value assigned to the article. This value affects where it appears in lists with siblings. Lower values appear towards the top

upvotes

Total of thumbs-up or like votes that readers have assigned to the article, which contributes to the article's overall rating.

downvotes

Total of thumbs-down or dislike votes that readers have assigned to the article, which contributes to the article's overall rating.

 Language: json
{
	"article_id": 42,
	"title": "article title",
	"slug": "first-article",
	"article_text": "html content of article 1",
	"creation_date": 1588698334,
	"modified_date": 1588698334,
	"views": 4600,
	"rating": 2197,
	"published": true,
	"author": 42,
	"editor": 42,
	"featured": false,
	"category_id": 123,
	"weight": 27,
	"upvotes": 2200,
	"downvotes": 3
}



⯁


Retrieve an articleGET /article

Returns one or more articles matching the specified category_id, article_id or slug

Required parameters

At least one of the optional category_id, article_id or slug parameters must be specified


Optional parameters

category_id

Numeric identifier for the category of article(s) to be returned. Articles cannot be created in root categories (no article can be assigned a category_id value of 0)

Note that specifying a category_id without specifying article_id or slug will return all articles having a category_id matching the specified value, which may be useful when determining which articles are within a given category

article_id

Unique numeric identifier for the article.

slug

Unique alphanumeric string reference to the article.

This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted

limit

Optional limit on the number of article objects to be returned, between 1 and 100

If this parameter is not provided, a default limit of 100 will be applied, returning the maximum of 100 items.

fetch_offset

A cursor to use for pagination. Defines the numeric offset from where results should begin being fetched.

For example, if you were working with a large number of records, and wanted to fetch them in pages of 10 at a time, you might set the limit value to 10 (indicating only 10 records at a time should be returned) and for the first page, fetch_offset would be 0 to indicate no offset (returning records 1-10).

For the second page, fetch_offset would be set to 10, allowing records 11-20 to be returned.

If this parameter is not provided, a default fetch_offset of 0 will be applied, returning records from the start of the result set.

 Language: bash [ Line Numbers Enabled ]
curl -X GET https://api.gogoworx.com/article \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"category_id": 123, "limit": 2}'

Response (containing specified articles):

 Language: json
[{
	"article_id": 42,
	"title": "article title",
	"slug": "first-article",
	"article_text": "html content of article 1",
	"creation_date": 1588698334,
	"modified_date": 1588698334,
	"views": 4600,
	"rating": 2197,
	"published": true,
	"author": 42,
	"editor": 42,
	"featured": false,
	"category_id": 123,
	"weight": 27,
	"upvotes": 2200,
	"downvotes": 3
},
{
	"article_id": 43,
	"title": "second title",
	"slug": "second-article",
	"article_text": "html content of article 2",
	"creation_date": 1588698334,
	"modified_date": 1588698334,
	"views": 52,
	"rating": 15,
	"published": true,
	"author": 42,
	"editor": 42,
	"featured": false,
	"category_id": 123,
	"weight": 28,
	"upvotes": 15,
	"downvotes": 0
}]



⯁


Create an articlePOST /article

Creates a new article based on the specified criteria.

Note that the weight attribute for newly created articles will be automatically calculated to place the article at the bottom of the list of siblings (the highest numeric weight value). This can be changed after creation by making a PUT request as described below

Required parameters

title

A descriptive title that is associated with the article and will be shown at the top of the page when the article is displayed.

Using titles that are too long may cause them to become truncated or displayed incorrectly on certain devices (think of mobile displays, which have less usable area)

You should limit the length of this to be as short as practical and well within the maximum 55 character limit

slug

Unique alphanumeric string reference to the article.

This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted

article_text

The raw HTML content of the article body. Note that appropriate character escaping should be applied in order to preserve formatting.

The raw text contents from article_text will be extracted and indexed as part of the advanced lexical search mechanisms used within the GoGoWorx system.

There are no practical limits to the length of data that can be included in article_text, however you should consider your reader audience and decide whether it would be better to split up lengthy articles into several related articles.

author

Numeric reference to an the account user that is creating the article.

Note that a valid account user_id value must be specified here. Use the User API to obtain details of account users if needed.

This value will also be assigned to the editor parameter of the article object created.

category_id

Numeric identifier for the category the new article should be associated with. Articles cannot be created in root categories (no article can be assigned a category_id value of 0)


Optional parameters

views

A numeric value indicating the number of times readers have viewed the article.

published

A boolean value of true or false indicating whether the article is published or not.

Articles that are not published cannot be seen by readers. Only editors and other staff will be able to view and edit them.

featured

A boolean value of true or false indicating whether the article is marked as 'featured' or not.

Articles that are marked as 'featured' will be shown in a special 'featured' list (when enabled) on the knowledge base homepage.

upvotes

Total of thumbs-up or like votes that readers have assigned to the article, which contributes to the article's overall rating.

downvotes

Total of thumbs-down or dislike votes that readers have assigned to the article, which contributes to the article's overall rating.

 Language: bash [ Line Numbers Enabled ]
curl -X POST https://api.gogoworx.com/article \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"title": "New Article", "slug": "new-article", "article_text": "Here is my article", \
        "author": 42, "category_id": 123}'

Response (containing newly created article object):

 Language: json
[{
	"article_id": 97,
	"title": "New Article",
	"slug": "new-article",
	"article_text": "Here is my article",
	"creation_date": 1588698334,
	"modified_date": 1588698334,
	"views": 0,
	"rating": 0,
	"published": false,
	"author": 42,
	"editor": 42,
	"featured": false,
	"category_id": 123,
	"weight": 31,
	"upvotes": 0,
	"downvotes": 0
}]



⯁


Update an articlePUT /article

Updates a single, specified article based on the parameters provided

Note that the modified_date value will be automatically updated to reflect the current time of editing.

Also, the rating value is calculated and cannot be directly modified (see upvotes and downvotes parameters)

Required parameters

Either article_id or slug must be specified to uniquely identify the article to be updated.


Optional parameters

article_id

Unique numeric identifier for the article.

This value is immutable and cannot be changed.

slug

Unique alphanumeric string reference to the article. This must contain no spaces or special characters. Only alphanumeric characters and hyphens are permitted

Ideally, you should try to avoid changing the slug parameter whenever possible, since this will change any external URLs that reference the article.

Any internal references within GoGoWorx will automatically update whenever this value is changed (internal references use the immutable article_id value)

Note that in order to change the slug value, you must specify the article_id parameter

title

A descriptive title that is associated with the article and will be shown when the article is displayed. You should limit the length of this to be as short as practical.

Using titles that are too long may cause them to become truncated or displayed incorrectly on certain devices (think of mobile displays, which have less usable area)

There is a maximum length of 55 characters permitted for this value

article_text

The raw HTML content of the article body. Note that appropriate character escaping should be applied in order to preserve formatting.

The raw text contents from article_text will be extracted and indexed as part of the advanced lexical search mechanisms used within the GoGoWorx system.

There are no practical limits to the length of data that can be included in article_text, however you should consider your reader audience and decide whether it would be better to split up lengthy articles into several related articles.

views

A numeric value indicating the number of times readers have viewed the article.

published

A boolean value of true or false indicating whether the article is published or not.

Articles that are not published cannot be seen by readers. Only editors and other staff will be able to view and edit them.

author

Numeric reference to an the account user that created the article.

Note that a valid account user_id value must be specified here. Use the User API to obtain details of account users if needed.

editor

Numeric reference to an the account user that is updating the article.

Note that a valid account user_id value must be specified here. Use the User API to obtain details of account users if needed.

featured

A boolean value of true or false indicating whether the article is marked as 'featured' or not.

Articles that are marked as 'featured' will be shown in a special 'featured' list (when enabled) on the knowledge base homepage.

category_id

Numeric identifier for the category the article is associated with. Articles cannot be assigned to root categories (no article can be assigned a category_id value of 0)

weight

The relative weighting value assigned to the article. This value affects where it appears in lists with siblings. Lower values appear towards the top

upvotes

Total of thumbs-up or like votes that readers have assigned to the article, which contributes to the article's overall rating.

downvotes

Total of thumbs-down or dislike votes that readers have assigned to the article, which contributes to the article's overall rating.

 Language: bash [ Line Numbers Enabled ]
curl -X PUT https://api.gogoworx.com/article \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"article_id": 97, "title": "Modified Title"}'

Response (containing the updated article object):

 Language: json
[{
	"article_id": 97,
	"title": "Modified Title",
	"slug": "new-article",
	"article_text": "Here is my article",
	"creation_date": 1588698334,
	"modified_date": 1588698334,
	"views": 0,
	"rating": 0,
	"published": false,
	"author": 42,
	"editor": 42,
	"featured": false,
	"category_id": 123,
	"weight": 31,
	"upvotes": 0,
	"downvotes": 0
}]



⯁


Delete an articleDELETE /article

Deletes a single, specified article based on the specified article_id or slug.

Note that once deleted, an article can no longer be accessed. If you simply intend to remove the article from being visible to readers, update the published flag or modify category_group settings for the category the article belongs to.

Required parameters

Either of article_id or slug must be specified to uniquely identify the article to be deleted


Optional parameters

article_id

Unique numeric identifier for the article.

slug

Unique alphanumeric string reference to the article.

 Language: bash [ Line Numbers Enabled ]
curl -X DELETE https://api.gogoworx.com/article \
    -H "x-api-key: qI9CSNml2mwL7zPVpwLW4WBJPCmTcIkBKeCQL1t7" \
    -H "x-account-uuid: sitename/02fccd86-18e8-4816-a52c-bd3bf9f8446e" \
    -d '{"article_id": 97}'

Response (containing empty array):

 Language: json
[]