Working with Help sites

Help sites are the public guides your customers read. Use the API to answer customers from your published help, add articles, and see what readers look for.

How it fits together

Answer a customer from your help

Search articles takes the customer’s own words and returns matching articles with a snippet and their public address, so a support tool can suggest the right one.

curl -G "https://api.olamma.sh/v1/w/your-workspace/help-articles" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  --data-urlencode 'query=how do I top up by bank transfer' \
  --data-urlencode 'limit=3'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/help-articles?${new URLSearchParams({"query":"how do I top up by bank transfer","limit":"3"})}`, {
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
  },
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.get(
    "https://api.olamma.sh/v1/w/your-workspace/help-articles",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}"},
    params={"query":"how do I top up by bank transfer","limit":"3"},
    timeout=30,
)
data = response.json()
response.raise_for_status()

Read the full article as Markdown with Get article. upToDate says whether readers see the latest version of its page.

Put a page on a site

1. Find your sites and topics. Each site lists its topics and their articles, draft or published.
   cURLJavaScriptPython

   curl "https://api.olamma.sh/v1/w/your-workspace/help-sites" \
     -H "Authorization: Bearer $OLAMMA_KEY"

   const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/help-sites`, {
     headers: {
       Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
     },
   });
   const data = await response.json();
   if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

   import os
   import requests
   
   response = requests.get(
       "https://api.olamma.sh/v1/w/your-workspace/help-sites",
       headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}"},
       timeout=30,
   )
   data = response.json()
   response.raise_for_status()

2. Write the article as a page with Create page. Articles are pages, so you edit them the same way.
   cURLJavaScriptPython

   curl -X POST "https://api.olamma.sh/v1/w/your-workspace/pages" \
     -H "Authorization: Bearer $OLAMMA_KEY" \
     -H "Idempotency-Key: help-fees-page" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Pay school fees",
       "markdown": "# Pay school fees\n\nOpen **Fees**, choose the term and pay by card or transfer."
     }'

   const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
       "Idempotency-Key": "help-fees-page",
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       "title": "Pay school fees",
       "markdown": "# Pay school fees\n\nOpen **Fees**, choose the term and pay by card or transfer."
     }),
   });
   const data = await response.json();
   if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

   import os
   import requests
   
   response = requests.post(
       "https://api.olamma.sh/v1/w/your-workspace/pages",
       headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "help-fees-page"},
       json={
           "title": "Pay school fees",
           "markdown": "# Pay school fees\n\nOpen **Fees**, choose the term and pay by card or transfer."
       },
       timeout=30,
   )
   data = response.json()
   response.raise_for_status()

3. Place it in a topic. It starts as a draft that readers can’t see.
   cURLJavaScriptPython

   curl -X POST "https://api.olamma.sh/v1/w/your-workspace/help-articles" \
     -H "Authorization: Bearer $OLAMMA_KEY" \
     -H "Idempotency-Key: help-fees-article" \
     -H "Content-Type: application/json" \
     -d '{
       "topicId": "kc_…",
       "pageId": "pg_…"
     }'

   const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/help-articles`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
       "Idempotency-Key": "help-fees-article",
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       "topicId": "kc_…",
       "pageId": "pg_…"
     }),
   });
   const data = await response.json();
   if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

   import os
   import requests
   
   response = requests.post(
       "https://api.olamma.sh/v1/w/your-workspace/help-articles",
       headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "help-fees-article"},
       json={
           "topicId": "kc_…",
           "pageId": "pg_…"
       },
       timeout=30,
   )
   data = response.json()
   response.raise_for_status()

4. Propose publishing it. A person approves it in Olamma; until then readers see nothing new.
   cURLJavaScriptPython

   curl -X POST "https://api.olamma.sh/v1/w/your-workspace/help-articles/ka_…/publish" \
     -H "Authorization: Bearer $OLAMMA_KEY" \
     -H "Idempotency-Key: help-fees-publish"

   const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/help-articles/ka_…/publish`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
       "Idempotency-Key": "help-fees-publish",
     },
   });
   const data = await response.json();
   if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

   import os
   import requests
   
   response = requests.post(
       "https://api.olamma.sh/v1/w/your-workspace/help-articles/ka_…/publish",
       headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "help-fees-publish"},
       timeout=30,
   )
   data = response.json()
   response.raise_for_status()

See what readers need

Get insights shows each article’s views and votes, what readers searched for, and searches that found nothing. Those gaps are the articles to write next.