curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"article": {
"title": "How to reset your password",
"content": "Open **Settings → Security** and click *Reset password*.",
"category_id": 12
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles"
payload = { "article": {
"title": "How to reset your password",
"content": "Open **Settings → Security** and click *Reset password*.",
"category_id": 12
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
article: {
title: 'How to reset your password',
content: 'Open **Settings → Security** and click *Reset password*.',
category_id: 12
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'article' => [
'title' => 'How to reset your password',
'content' => 'Open **Settings → Security** and click *Reset password*.',
'category_id' => 12
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles"
payload := strings.NewReader("{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 118,
"title": "How to reset your password",
"slug": "how-to-reset-your-password",
"content": "Open **Settings → Security** and click *Reset password*.",
"description": "Self-service password reset, step by step.",
"status": "draft",
"locale": "en",
"category_id": 12,
"associated_article_id": null,
"author_id": 7,
"portal_slug": "acme-help",
"public_url": "https://help.acme.com/hc/acme-help/articles/how-to-reset-your-password",
"created_at": "2026-08-10T14:32:05.123Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "category_id",
"code": "invalid",
"message": "The category does not belong to this portal."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Create an article
Create one article in the portal. It starts as draft — invisible on the public help center — unless the payload sends an explicit status; the usual flow is create as draft, review, then publish by updating the status.
Authorship is always the authenticated user behind the token. The article’s locale is inherited from its category, or from the portal default when no category_id is sent. Requires being an administrator of the account or a member of the portal.
curl --request POST \
--url https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'cloudchat-instance: <cloudchat-instance>' \
--data '
{
"article": {
"title": "How to reset your password",
"content": "Open **Settings → Security** and click *Reset password*.",
"category_id": 12
}
}
'import requests
url = "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles"
payload = { "article": {
"title": "How to reset your password",
"content": "Open **Settings → Security** and click *Reset password*.",
"category_id": 12
} }
headers = {
"cloudchat-instance": "<cloudchat-instance>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'cloudchat-instance': '<cloudchat-instance>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
article: {
title: 'How to reset your password',
content: 'Open **Settings → Security** and click *Reset password*.',
category_id: 12
}
})
};
fetch('https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'article' => [
'title' => 'How to reset your password',
'content' => 'Open **Settings → Security** and click *Reset password*.',
'category_id' => 12
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"cloudchat-instance: <cloudchat-instance>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles"
payload := strings.NewReader("{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cloudchat-instance", "<cloudchat-instance>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles")
.header("cloudchat-instance", "<cloudchat-instance>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cloudhumans.com/cloudchat/v1/accounts/{accountId}/portals/{portalSlug}/articles")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cloudchat-instance"] = '<cloudchat-instance>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"article\": {\n \"title\": \"How to reset your password\",\n \"content\": \"Open **Settings → Security** and click *Reset password*.\",\n \"category_id\": 12\n }\n}"
response = http.request(request)
puts response.read_body{
"id": 118,
"title": "How to reset your password",
"slug": "how-to-reset-your-password",
"content": "Open **Settings → Security** and click *Reset password*.",
"description": "Self-service password reset, step by step.",
"status": "draft",
"locale": "en",
"category_id": 12,
"associated_article_id": null,
"author_id": 7,
"portal_slug": "acme-help",
"public_url": "https://help.acme.com/hc/acme-help/articles/how-to-reset-your-password",
"created_at": "2026-08-10T14:32:05.123Z",
"updated_at": "2026-08-10T14:32:05.123Z"
}{
"error": {
"code": "bad_request",
"message": "The request is malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Authentication is required. Send a valid Bearer token in the Authorization header."
}
}{
"error": {
"code": "forbidden",
"message": "You are not allowed to perform this action."
}
}{
"error": {
"code": "not_found",
"message": "Resource could not be found."
}
}{
"error": {
"code": "validation_failed",
"message": "The request payload is invalid.",
"details": [
{
"field": "category_id",
"code": "invalid",
"message": "The category does not belong to this portal."
}
]
}
}{
"message": "API rate limit exceeded"
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Authorizations
Headers
Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.
1
Path Parameters
Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.
1
The portal's slug — the URL-safe handle you see in its public address (/hc/<slug>/...), not a numeric id. List portals returns every slug on the account. Note the asymmetry: portals are addressed by slug, articles by numeric id.
"acme-help"
Body
Response
The article as stored.
A help center article, drafts included.
The body, in Markdown. Images are ordinary Markdown image links — upload the file and embed the returned file_url.