Articles

Resource Fields

Name Type Read-only Description
uuid string
legacy_id string
titles Field Locales
slugs Field Locales
contents Field Locales
keywords string List of extra words and phrases which you think your customers may search for to find this article. It will increase the likelihood of this article appearing in searches that include these words and phrases.
section Section
creator User
author User
attachments Attachments
download_all string
status string PUBLISHED, DRAFT, PENDINGAPPROVAL

 Default:DRAFT
upvote_count integer
downvote_count integer
views integer
rank float
tags Tags
is_featured boolean Default: false
allow_comments boolean Default: true
total_comments integer
created_at timestamp ISO-8601 Format
published_at timestamp ISO-8601 Format
updated_at timestamp ISO-8601 Format
helpcenter_url string The helpcenter url of the article

Tags

RESOURCE FIELDS

Name Type Read-only Description
name string

Metadata




 
 




Actions

Retrieve all articles

GET /api/v1/articles.json

Information

Allowed for Public

Arguments

Name Type Mandatory Description
section_id integer
tags string Comma separated tags
filter string PINNED, PUBLISHED

OR

Name Type Mandatory Description
legacy_ids string The comma separated legacy ids

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,

    "legacy_id": null,
    "uuid": "44afa976-5041-57d2-820e-55ab43c4c6b9",
    "titles": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "slugs": [
        {
            "locale": "en-us",
            "translation": "1-v60-pour-over-brewing",
            "resource_type": "slug"
        }
    ],
    "contents": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "keywords": null,
    "section": {
    "id": 1,

    "resource_type": "section"

}
,
    "creator": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "author": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "attachments": [],
    "download_all": null,
    "status": "PUBLISHED",
    "upvote_count": 0,
    "downvote_count": 0,
    "views": 0,
    "rank": 0,
    "tags": [],
    "is_featured": true,
    "allow_comments": true,
    "total_comments": 0,
    "created_at": "2016-04-13T07:32:51+00:00",
    "published_at": "2016-04-13T07:32:51+00:00",
    "updated_at": "2016-04-13T07:32:51+00:00",
    "helpcenter_url": "https://brewfictus.kayako.com/article/1",

    "resource_type": "article"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1"

}

        ],
        "resource": "article",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Retrieve an article

GET /api/v1/articles/:id.json

Information

Allowed for Public

Response

    {
        "status": 200,
        "data": {
    "id": 1,

    "legacy_id": null,
    "uuid": "44afa976-5041-57d2-820e-55ab43c4c6b9",
    "titles": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "slugs": [
        {
            "locale": "en-us",
            "translation": "1-v60-pour-over-brewing",
            "resource_type": "slug"
        }
    ],
    "contents": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "keywords": null,
    "section": {
    "id": 1,

    "resource_type": "section"

}
,
    "creator": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "author": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "attachments": [],
    "download_all": null,
    "status": "PUBLISHED",
    "upvote_count": 0,
    "downvote_count": 0,
    "views": 0,
    "rank": 0,
    "tags": [],
    "is_featured": true,
    "allow_comments": true,
    "total_comments": 0,
    "created_at": "2016-04-13T07:32:51+00:00",
    "published_at": "2016-04-13T07:32:51+00:00",
    "updated_at": "2016-04-13T07:32:51+00:00",
    "helpcenter_url": "https://brewfictus.kayako.com/article/1",

    "resource_type": "article"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1"

}
,
        "resource": "article"
    }

Add an article

POST /api/v1/articles.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Collaborators can add an article only with DRAFT status

Parameters

Name Type Mandatory Description
titles string
contents string
legacy_id string
section_id integer
author_id integer
keywords string
status string PUBLISHED, DRAFT, PENDINGAPPROVAL

 Default: DRAFT
is_featured boolean Default: false
allow_comments boolean Default: true
tags string Comma separated value of tag names
files array File Upload multipart/form-data
attachment_file_ids CSV

Request

curl -X POST https://brewfictus.kayako.com/api/v1/articles.json \
    -d '{"titles":[{"locale":"en-us", "translation": "V60 pour over brewing"}], "contents":[{"locale":"en-us", "translation": "V60 pour over brewing..."}],"section_id":1,"author_id":1,"status":"PUBLISHED","allow_comments":true}' \
    -H "Content-Type: application/json" \
    -u "jordan.mitchell@brewfictus.com:jmit6#lsXo"

Response

    {
        "status": 200,
        "data": {
    "id": 1,

    "legacy_id": null,
    "uuid": "44afa976-5041-57d2-820e-55ab43c4c6b9",
    "titles": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "slugs": [
        {
            "locale": "en-us",
            "translation": "1-v60-pour-over-brewing",
            "resource_type": "slug"
        }
    ],
    "contents": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "keywords": null,
    "section": {
    "id": 1,

    "resource_type": "section"

}
,
    "creator": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "author": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "attachments": [],
    "download_all": null,
    "status": "PUBLISHED",
    "upvote_count": 0,
    "downvote_count": 0,
    "views": 0,
    "rank": 0,
    "tags": [],
    "is_featured": true,
    "allow_comments": true,
    "total_comments": 0,
    "created_at": "2016-04-13T07:32:51+00:00",
    "published_at": "2016-04-13T07:32:51+00:00",
    "updated_at": "2016-04-13T07:32:51+00:00",
    "helpcenter_url": "https://brewfictus.kayako.com/article/1",

    "resource_type": "article"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1"

}
,
        "resource": "article"
    }

Bulk add articles

POST /api/v1/bulk/articles.json

Information

Allowed for Agents, Admins & Owners

You can insert a maximum of 200 articles at a time

Parameters

Name Type Mandatory Description
articles array
Array of articles to be inserted

Arguments

Name Type Mandatory Description
partial_import boolean By default, even if a single record is invalid, the entire batch is dropped. However, if this parameter is set to true, all the records with no validation errors will be inserted while the invalid records will be returned back.

Request

curl -X POST https://brewfictus.kayako.com/api/v1/bulk/articles \
    -d '{"articles": [{"titles": [{"locale": "en-us", "translation": "Sample Article"}], "section_id": 1, "author_id": 1, "contents": [{"locale": "en-us", "translation": "Sample Contents"}],"legacy_id":"article_1"}]}' \
    -H "Content-Type: application/json"

Response

    {
        "status": 202,
        "data": {
    "id": 1,
    "status": "PENDING",
    "created_at": "2015-07-30T06:45:25+05:00",
    "updated_at": "2015-07-30T06:45:25+05:00",
    "resource_type": "bulk_job",
    "resource_url": "https://brewfictus.kayako.com/api/v1/jobs/1"
}
,
        "resource": "job"
    }

Update an article

PUT /api/v1/articles/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Collaborators can update an article only with DRAFT status

Parameters

Name Type Mandatory Description
titles string
contents string
keywords string
section_id integer
author_id integer
status string PUBLISHED, DRAFT, PENDINGAPPROVAL
is_featured boolean
allow_comments boolean
files array File Upload multipart/form-data
tags string Comma separated value of tag names

Request

curl -X PUT https://brewfictus.kayako.com/api/v1/articles/1.json \
    -d '{"titles":[{"locale":"en-us", "translation": "V60 pour over brewing"}], "contents":[{"locale":"en-us", "translation": "V60 pour over brewing..."}],"section_id":1,"author_id":1,"status":"PUBLISHED","allow_comments":true}' \
    -H "Content-Type: application/json" \
    -u "jordan.mitchell@brewfictus.com:jmit6#lsXo"

Response

    {
        "status": 200,
        "data": {
    "id": 1,

    "legacy_id": null,
    "uuid": "44afa976-5041-57d2-820e-55ab43c4c6b9",
    "titles": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "slugs": [
        {
            "locale": "en-us",
            "translation": "1-v60-pour-over-brewing",
            "resource_type": "slug"
        }
    ],
    "contents": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "keywords": null,
    "section": {
    "id": 1,

    "resource_type": "section"

}
,
    "creator": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "author": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "attachments": [],
    "download_all": null,
    "status": "PUBLISHED",
    "upvote_count": 0,
    "downvote_count": 0,
    "views": 0,
    "rank": 0,
    "tags": [],
    "is_featured": true,
    "allow_comments": true,
    "total_comments": 0,
    "created_at": "2016-04-13T07:32:51+00:00",
    "published_at": "2016-04-13T07:32:51+00:00",
    "updated_at": "2016-04-13T07:32:51+00:00",
    "helpcenter_url": "https://brewfictus.kayako.com/article/1",

    "resource_type": "article"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1"

}
,
        "resource": "article"
    }

Update articles

PUT /api/v1/articles.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Collaborators can update an article only with DRAFT status

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Parameters

Name Type Mandatory Description
section_id integer
author_id integer
status string PUBLISHED, DRAFT, PENDINGAPPROVAL
is_featured boolean
allow_comments boolean
files array File Upload multipart/form-data

Response

{
    "status": 200,
    "total_count": 2
}

Votes

RESOURCE FIELDS

Name Type Read-only Description
type string
HELPFUL, NOT_HELPFUL
user User
created_at timestamp
ISO-8601 Format
updated_at timestamp
ISO-8601 Format

Retrieve all votes

GET /api/v1/articles/:id/votes.json

Information

Allowed for Customers, Collaborators, Agents, Admins & Owners
Ordered by id (descending)

Customer can retrieve own votes only

Arguments

Name Type Mandatory Description
filter string HELPFUL, NOT_HELPFUL

Response

    {
        "status": 200,
        "data": [




{
    "id": 1,

    "type": "HELPFUL",
    "user": 




{
    "id": 2,

    "resource_type": "user_minimal"

}
,
    "created_at": "2015-08-04T11:28:03+05:00",
    "updated_at": "2015-08-04T11:28:03+05:00",

    "resource_type": "vote"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/votes/1"

}
        ],
        "resource": "vote",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Retrieve a vote

GET /api/v1/articles/:id/votes/:id.json

Information

Allowed for Customers, Collaborators, Agents, Admins & Owners

Customer can retrieve own vote only

Response

    {
        "status": 200,
        "data": 



{
    "id": 1,

    "type": "HELPFUL",
    "user": 




{
    "id": 2,

    "resource_type": "user_minimal"

}
,
    "created_at": "2015-08-04T11:28:03+05:00",
    "updated_at": "2015-08-04T11:28:03+05:00",

    "resource_type": "vote"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/votes/1"

},
        "resource": "vote"
    }

Retrieve vote status

GET /api/v1/articles/:id/hasvoted.json

Information

Allowed for Public

Arguments

Name Type Mandatory Description
user_id integer

Response, if voted

    {
        "status": 200,
        "data": 



{
    "id": 1,

    "type": "HELPFUL",
    "user": 




{
    "id": 2,

    "resource_type": "user_minimal"

}
,
    "created_at": "2015-08-04T11:28:03+05:00",
    "updated_at": "2015-08-04T11:28:03+05:00",

    "resource_type": "vote"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/votes/1"

},
        "resource": "vote"
    }

Response, if not voted

{
    "status": 404,
    "errors": [
        {
            "code": "RESOURCE_NOT_FOUND",
            "message": "Resource does not exist or has been removed",
            "more_info": "https://developer.kayako.com/api/v1/reference/errors/RESOURCE_NOT_FOUND"
        }
    ]
}

Vote as helpful

POST /api/v1/articles/:id/votes/helpful.json

Information

Allowed for Customers, Collaborators, Agents, Admins & Owners

Response

    {
        "status": 201,
        "data": 



{
    "id": 1,

    "type": "HELPFUL",
    "user": 




{
    "id": 2,

    "resource_type": "user_minimal"

}
,
    "created_at": "2015-08-04T11:28:03+05:00",
    "updated_at": "2015-08-04T11:28:03+05:00",

    "resource_type": "vote"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/votes/1"

},
        "resource": "vote"
    }

Vote as not helpful

POST /api/v1/articles/:id/votes/nothelpful.json

Information

Allowed for Customers, Collaborators, Agents, Admins & Owners

Response

    {
        "status": 201,
        "data": 





{
    "id": 1,

    "type": "NOT_HELPFUL",
    "user": 




{
    "id": 2,

    "resource_type": "user_minimal"

}
,
    "created_at": "2015-08-04T11:28:03+05:00",
    "updated_at": "2015-08-04T11:28:03+05:00",

    "resource_type": "vote"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/votes/1"

},
        "resource": "vote"
    }

Delete a vote

DELETE /api/v1/articles/:id/votes/:id.json

Information

Allowed for Customers, Collaborators, Agents, Admins & Owners

Customer can delete own vote only

Response

{
    "status": 200
}

Delete votes

DELETE /api/v1/articles/:id/votes.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

{
    "status": 200,
    "total_count": 2
}

Reorder Articles

PUT /api/v1/articles/reorder.json

Information

Allowed for Agents, Admins & Owners

Parameters

Name Type Mandatory Description
article_ids string
Pass the section ids in order you want to set
section_id integer

Response

{
    "status": 200
}

Attachments

RESOURCE FIELDS

Name Type Read-only Description
name string
size integer
width integer
Only if the attachment is image
height integer
Only if the attachment is image
type string
Mime-type of the file
content_id string
Content ID used for inline attachment
alt string
url string
The URL to view the attachment
url_download string
The URL to download the attachment
thumbnails Thumbnails
created_at timestamp
ISO-8601 Format

Thumbnails

RESOURCE FIELDS

Name Type Read-only Description
name string
size integer
width integer
height integer
type string
Mime-type of the file
url string
The URL to view the thumbnail
created_at timestamp
ISO-8601 Format

Retrieve all article's attachments

GET /api/v1/articles/:id/attachments.json

Information

Allowed for Public

Response

    {
        "status": 200,
        "data": [




{
    "id": 1,

    "name": "test.jpg",
    "size": 240711,
    "width": 1280,
    "height": 800,
    "type": "image/jpeg",
    "content_id": null,
    "alt": null,
    "url": "https://brewfictus.kayako.com/api/v1/articles/1/attachments/2/url",
    "url_download": "https://brewfictus.kayako.com/api/v1/articles/1/attachments/2/download",
    "thumbnails": [
        {
            "name": "test.jpg",
            "size": 4391,
            "width": 64,
            "height": 40,
            "type": "image/jpeg",
            "url": "https://brewfictus.kayako.com/api/v1/articles/1/attachments/2/url&size=64",
            "created_at": "2015-07-07T18:03:04+05:00"
        }
    ],
    "created_at": "2015-07-07T18:03:04+05:00",

    "resource_type": "attachment"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1/attachments/1"

}
        ],
        "resource": "attachment",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }

Delete an attachment

DELETE /api/v1/articles/:id/attachments/:id.json

Information

Allowed for Collaborators, Agents, Admins & Owners

Response

{
    "status": 200
}

Delete an article

DELETE /api/v1/articles/:id.json

Information

Allowed for Agents, Admins & Owners

Response

{
    "status": 200
}

Delete articles

DELETE /api/v1/articles.json

Information

Allowed for Agents, Admins & Owners

Arguments

Name Type Mandatory Description
ids string
The comma separated ids

Response

{
    "status": 200,
    "total_count": 2
}

Search articles

POST /api/v1/helpcenter/search/articles.json

Information

Allowed for Public

Parameters

Name Type Mandatory Description
query string
Character limit should be more than 3 chars
locale string
brand_id integer

Response

    {
        "status": 200,
        "data": [
            {
    "id": 1,

    "legacy_id": null,
    "uuid": "44afa976-5041-57d2-820e-55ab43c4c6b9",
    "titles": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "slugs": [
        {
            "locale": "en-us",
            "translation": "1-v60-pour-over-brewing",
            "resource_type": "slug"
        }
    ],
    "contents": [






{
    "id": 1,

    "resource_type": "locale_field"

}
    ],
    "keywords": null,
    "section": {
    "id": 1,

    "resource_type": "section"

}
,
    "creator": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "author": 




{
    "id": 1,

    "resource_type": "user_minimal"

}
,
    "attachments": [],
    "download_all": null,
    "status": "PUBLISHED",
    "upvote_count": 0,
    "downvote_count": 0,
    "views": 0,
    "rank": 0,
    "tags": [],
    "is_featured": true,
    "allow_comments": true,
    "total_comments": 0,
    "created_at": "2016-04-13T07:32:51+00:00",
    "published_at": "2016-04-13T07:32:51+00:00",
    "updated_at": "2016-04-13T07:32:51+00:00",
    "helpcenter_url": "https://brewfictus.kayako.com/article/1",

    "resource_type": "article"

    ,"resource_url": "https://brewfictus.kayako.com/api/v1/articles/1"

}

        ],
        "resource": "article",
        "offset": 0,
        "limit": 10,
        "total_count": 1
    }