> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand and Launch Your Hosted Help Center

> Turn on the hosted help center, brand it, organize categories, publish articles from your knowledge base, power visitor search, and capture unauthenticated support tickets from the public web.

# Brand and Launch Your Hosted Help Center

Devotel Orbit hosts a public help center for your workspace: the articles you
publish from your knowledge base, browsable categories, full-text search,
your logo and colors, and a visitor ticket form — all served from
`orbit.devotel.io/help` without you standing up a site. This guide walks the
portal from empty to launched: enable it, brand it, structure its taxonomy,
publish articles into it, and wire the ticket intake into your inbox.

The endpoint paths below are relative. Send them against
`https://api.orbit.devotel.io/api/v1`.

<Note>
  The public help center is distinct from the internal knowledge bases your
  agents ground on. The internal base keeps every document private; the help
  center only ever exposes documents you explicitly flag public and publish.
</Note>

## What the portal serves

Everything a visitor can reach lives under `/api/v1/public/help`, and
everything there is tenant-scoped by the `?org=<your-slug>` query parameter:

* **Articles** — published markdown documents from your knowledge base that
  you flagged public. This is the self-serve content layer.
* **Categories and sections** — a two-level taxonomy that groups articles
  for browsing ("Browse by topic").
* **Full-text search** — substring matching across title and body, title
  matches ranked first.
* **Branding** — your logo, primary and secondary colors, header links, and
  an opt-out "Powered by Orbit" credit.
* **Visitor ticket form** — an unauthenticated submission endpoint that
  lands in your inbox as a ticket, with a capability token the visitor uses
  to track their request without an account.

The hosted frontend at `orbit.devotel.io/help` renders these endpoints; you
can also embed the same calls in your own site if you want a fully custom
page. Source content lives in the internal knowledge base; the help center
is a projection of the subset you publish.

## 1. Set up the portal

The portal needs no explicit enablement step — it serves whatever you have
published. What you do before launch is branding and (optionally) a custom
domain.

**Brand it.** The public-safe branding subset is a small set of fields:
help-center logo, primary and secondary colors, header links, and whether
the "Powered by Orbit" credit shows. Set them on your organization's
branding settings (dashboard **Settings → Branding**, or the branding API).
Set only the `help_*` subset; the portal never exposes your dashboard logo,
support email, or custom domain on this unauthenticated surface. Unset
fields fall back to the platform default theme.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/public/help/branding?org=acme" \
  -H "X-API-Key: dv_live_sk_..."
```

The response carries `logo_url`, `primary_color`, `secondary_color`,
`header_links`, and `show_powered_by`. The hosted help page reads this once
on load. To hide the credit, explicitly set `show_powered_by` to `false` in
your branding settings — an unset value shows it.

**Put it on your domain.** To serve the help center from `help.acme.example`
instead of `orbit.devotel.io/help`, register a custom domain and let the
platform issue and maintain the certificate. Walk through
[Custom domains and managed SSL](/concepts/custom-domains-and-ssl): you
register the hostname, point a CNAME, and the TLS certificate provisions
automatically. The help center's `?org=` query parameter keeps the tenant
scope uniform across the platform domain and your custom domain.

## 2. Organize categories

Categories and their nested sections are a two-level taxonomy over the
knowledge documents you publish. The public taxonomy tree endpoint returns
every public category with its public sections and a rolled-up article
count:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/public/help/categories?org=acme" \
  -H "X-API-Key: dv_live_sk_..."
```

Each element carries `name`, `slug`, `description`, `position`, and
`article_count`, plus a `sections` array of the same shape. Only categories
and sections flagged `is_public` appear; a category with only draft articles
renders with `article_count: 0`.

Manage the taxonomy from the knowledge-base side of your workspace (the
dashboard **Agents → Knowledge base** page, or the knowledge API): create
the category, set its slug and position, and flip it public when it is
ready. A private category hides every article inside it from the public
surface, even when individual articles are flagged public — you keep a
single flip instead of unpublishing each article.

Start with a small, browsing-oriented set — two to six categories that match
how a visitor asks for help, not your internal org chart. Common shapes:
"Getting started", "Billing and account", "Troubleshooting". Reorder via the
`position` field; rename freely — the slug is the stable key.

## 3. Author and publish articles

Articles come from your knowledge base. The full source-editing lifecycle —
draft, review, approve — is in
[Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle);
the help center is where a document goes after you flag it public and
publish-ready.

The lifecycle the portal sees:

1. **Draft** in the knowledge base. Drafts and unapproved versions never
   reach the public surface.
2. **Flag the document public** (`is_public = true`) on the document —
   this is the explicit opt-in. (`kd-publication` flow on the dashboard
   knowledge-page.)
3. **Publish** — the document status moves to `ready`, which is the gate
   the portal queries. An article whose category is private stays hidden
   even when the article itself is public.

Each article is browseable by a `slug` (lowercase letters, digits, hyphens),
carries a `summary` in its metadata, and is rendered from its raw markdown
body by the hosted page. Unpublish by clearing the public flag or moving
the status off `ready`; a slug miss on the portal returns an empty list
rather than an error, so visitors re-render gracefully.

## 4. Wire full-text search

The portal's search endpoint matches substring patterns across the title and
body of your published, public articles:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/public/help/search?org=acme&q=refund&limit=10" \
  -H "X-API-Key: dv_live_sk_..."
```

Title matches rank ahead of body matches, then by recency. The response is
`data.results` (slug, title, summary, view count) plus the echoed query.
Search is intentionally substring-based — the vector-similarity search your
internal knowledge bases use is not exposed on the public surface, so a
visitor can't probe it for nearby private content.

**Analytics.** Every article detail view increments a `view_count` you can
read back in the list and detail responses, and the visitor ticket form
captures which article slugs the visitor read before filing. Together those
tell you which topics drive traffic and which gaps turn into tickets. Use
`sort=most-viewed` on the article list to surface your most-read content.

## 5. Branding and theming

The branding subset the portal exposes is deliberately narrow — proof that
an unauthenticated surface doesn't leak your wider white-label config:

* `logo_url` — the help-center logo. Stored as a signed link; the portal
  re-mints a fresh signed URL on each branding read so the link never
  expires in front of a visitor.
* `primary_color` / `secondary_color` — accent colors the hosted page
  applies to header and links.
* `header_links` — up to your own nav items (label + URL), rendered in the
  portal header.
* `show_powered_by` — the "Powered by Orbit" credit. Explicitly set `false`
  to hide it; unset means shown.

For custom-domain serving, the help page renders on the same registered
hostname you walked through in
[Custom domains and managed SSL](/concepts/custom-domains-and-ssl) — one
CNAME, one managed certificate, no upload.

## 6. Capture visitor tickets

The ticket endpoint is unauthenticated by design — a visitor who cannot
self-serve needs a path to support before signing in:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/public/help/tickets" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "org": "acme",
    "subject": "Refund not received after 30 days",
    "body": "Order #12345 was returned two weeks ago and the refund has not landed.",
    "email": "visitor@example.com",
    "name": "Alex Visitor",
    "articleSlugs": ["refund-policy", "returns-window"]
  }'
```

Body fields: `org` (required), `subject` (3–200 chars), `body` (10–16,384
chars), `email` (format-checked at the edge), optional `name`, `locale`, and
`articleSlugs` — the slugs of articles the visitor read before filing, so
your agent sees which self-serve paths were tried without re-asking.

The 201 response returns the ticket receipt and a `status_token`. The
visitor uses that token plus the ticket id to track the request without an
account:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/public/help/tickets/<ticket-id>?org=acme&token=<status_token>" \
  -H "X-API-Key: dv_live_sk_..."
```

The token is a read-only capability over the ticket id — no session is
created, and a wrong token returns the same generic 404 as a missing ticket
so the surface never enumerates ids.

**Abuse posture.** The endpoint is rate-limited more tightly than reads
because every submission lands in your operator queue. Visitor IP addresses
are hashed before persistence — never stored raw — and we deliberately do
not auto-resolve the submitted email to a contact, because the address is
unverified; an operator links it after review. The ticket lands in your
inbox ticket queue as a `public_form`-source ticket. Run the same routing
you'd run for any web-form intake — auto-assignment, SLA, queue routing —
per [Inbox tickets workflow](/guides/inbox-tickets-workflow).

If you also accept inbound email, the from-address and routing rules follow
the pattern in
[Audience senders hub](/guides/audience-senders-hub); the help-center form
is the no-account complement to that mailbox intake.

## 7. API walkthrough

The six public help-center calls you wire against — full endpoint shapes in
the [Help Center API reference](/api-reference/endpoints/help-center):

| Operation       | Endpoint                                       | Purpose                                                                 |                         |
| --------------- | ---------------------------------------------- | ----------------------------------------------------------------------- | ----------------------- |
| List articles   | `GET /public/help/articles?org=<slug>`         | Render the article index. Optional `category`, `section`, \`sort=recent | most-viewed`, `limit\`. |
| Get one article | `GET /public/help/articles/:slug?org=<slug>`   | Render the article page; increments `view_count`.                       |                         |
| List categories | `GET /public/help/categories?org=<slug>`       | Render the "browse by topic" tree with per-category article counts.     |                         |
| Search          | `GET /public/help/search?org=<slug>&q=<terms>` | Power the search box; title matches rank first.                         |                         |
| Submit feedback | `POST /public/help/feedback`                   | "Was this helpful?" votes + optional comment per article.               |                         |
| Open a ticket   | `POST /public/help/tickets`                    | Unauthenticated visitor submission. Returns a tracking `status_token`.  |                         |

Two more complete the surface: `GET /public/help/branding` reads the
public-safe branding, and `GET /public/help/tickets/:id` lets the visitor
track their ticket with the capability token — both are covered above,
and the API reference lists every call.

List articles:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/public/help/articles?org=acme&category=getting-started&sort=most-viewed&limit=20" \
  -H "X-API-Key: dv_live_sk_..."
```

Submit article feedback:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/public/help/feedback" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "org": "acme",
    "articleId": "kd_doc_123",
    "helpful": true,
    "comment": "The returns-window section answered it."
  }'
```

Feedback is the only write other than tickets; the article existence is
verified before the vote is recorded so junk `articleId` values don't
inflate your metrics.

## 8. Where the nav lands

The help center is wired into the workspace alongside the other inbox and
knowledge surfaces. Use the dashboard **Agents → Knowledge base** page to
author and flag documents public, the dashboard **Settings → Branding** page
to theme, and the hosted `/help` page to preview exactly what a visitor
sees. Keep the launched URL handy: `https://orbit.devotel.io/help?org=<your-slug>`, or your
custom domain if you registered one.

## Troubleshooting

| Symptom                                | Fix                                                                                                                                            |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Portal returns an empty article list   | Confirm the document is flagged `is_public` and moved to `ready` status, and that its category is also public. Both gates apply.               |
| Category tree renders with count 0     | The category only contains draft or unpublished articles; publish at least one and the count rolls up.                                         |
| Search misses an article you published | Substring match needs the term in the title or body; check for a private category or non-`ready` status on the document.                       |
| Logo missing / default Orbit branding  | The stored help logo link expired; the portal re-mints signed links on each branding read, and unset fields fall back to the platform default. |
| `ORG_NOT_FOUND` on every call          | The `?org=` slug doesn't match an active organization; pass the workspace slug, not the display name.                                          |
| Visitor ticket 400                     | One of the subject/body/email constraints failed — subject 3–200 chars, body 10–16,384 chars, email must carry an `@` and a dot.               |

## See also

* [Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle) — author and lifecycle-manage the source documents.
* [Inbox tickets workflow](/guides/inbox-tickets-workflow) — route and work the visitor tickets the portal captures.
* [Custom domains and managed SSL](/concepts/custom-domains-and-ssl) — serve the portal on your own hostname.
* [Help Center API reference](/api-reference/endpoints/help-center) — endpoint shapes for every public call.
* [Audience senders hub](/guides/audience-senders-hub) — the from-address rules your email intake uses alongside the form.