Help Center

Help Center

The Help Center API manages the public-facing knowledge base portal where end-users can browse articles, search for solutions, and submit feedback. The Help Center is available at a dedicated subdomain (e.g., help.yourcompany.com).

All endpoints live under the /api/v1/help-center prefix.

The Help Center read endpoints are public and unauthenticated — they do not accept (or require) an API key. The tenant is resolved automatically from the request host when called via the tenant's Help Center domain, or you may pass a tenant_id query parameter explicitly when calling from another origin (see Resolving the tenant). The only authenticated surface is admin branding, which requires a dashboard session JWT (see Authentication).

Public Endpoints

These endpoints power the Help Center portal. They do not require API key authentication.

ℹ️ Tenant resolution

When you call these endpoints from outside the tenant's Help Center domain (for example, a raw curl against apps.aurionai.net), include a tenant_id query parameter. Without it — and without a Help Center Host header that the tenant-context middleware can resolve — the request returns 400 {"detail": "Missing tenant_id"}.

Resolve Tenant

Resolve a hostname to a tenant. Used by the Help Center frontend to determine which tenant's content to display. Supports subdomain patterns ({slug}.help.aurionai.net), custom domains, and the default bare domain.

curl "https://apps.aurionai.net/api/v1/help-center/resolve-tenant?hostname=acme.help.aurionai.net"

Response:

{
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_slug": "acme",
  "tenant_name": "Acme Corp",
  "redirect_slug": null
}

Landing Page

Fetch landing page data including top-level collections and popular articles:

curl "https://apps.aurionai.net/api/v1/help-center/landing?tenant_id=TENANT_UUID&locale=en"

List Collections

Retrieve the hierarchical collection (category) tree for the Help Center:

curl "https://apps.aurionai.net/api/v1/help-center/collections?tenant_id=TENANT_UUID&locale=en"

Collection Detail

Fetch a single collection with its breadcrumbs, sub-collections, and articles:

curl "https://apps.aurionai.net/api/v1/help-center/collections/COLLECTION_UUID/detail?tenant_id=TENANT_UUID&locale=en"

Response:

{
  "collection": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Network", "slug": "network" },
  "description": "VPN, Wi-Fi, and connectivity guides",
  "breadcrumbs": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Network", "slug": "network" }
  ],
  "sub_collections": [],
  "articles": []
}

An unknown collection returns 404 {"detail": "Collection not found"}.

Get Settings

Retrieve public Help Center settings:

curl "https://apps.aurionai.net/api/v1/help-center/settings?tenant_id=TENANT_UUID"

Response:

{
  "help_center_public_enabled": true,
  "help_center_domain": "acme.help.aurionai.net",
  "sitemap_enabled": true,
  "schema_type": "article",
  "noindex_unpublished": true
}

Browse Articles

List articles, optionally filtered. Supported query parameters: collection_id (UUID), search (keyword), tag (max 100 chars), locale (default en), limit (1–100, default 20), and offset (≥0, default 0). There is no category parameter — filter by collection_id or tag instead. Plain keyword search is done here via the search parameter (there is no separate /search endpoint).

curl "https://apps.aurionai.net/api/v1/help-center/articles?collection_id=COLLECTION_UUID&search=vpn+setup&limit=10&tenant_id=TENANT_UUID"

Response:

The list envelope key is items (not articles):

{
  "items": [
    {
      "id": "101",
      "collection_id": "550e8400-e29b-41d4-a716-446655440000",
      "collection_name": "Network",
      "title": "VPN Setup Guide",
      "slug": "vpn-setup",
      "locale": "en",
      "status": "published",
      "view_count": 1203,
      "helpful_count": 88,
      "not_helpful_count": 4,
      "published_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-05-02T14:30:00Z",
      "tags": ["vpn", "network"],
      "snippet": "To set up VPN access, install the company VPN client and..."
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Search with AI Summary

Search articles and return an AI-generated summary of the top results. Rate-limited to 10 requests per minute. The search parameter (aliased to q) is required (min length 1); limit is capped at 10 (default 5).

curl "https://apps.aurionai.net/api/v1/help-center/search-summary?search=vpn+setup&tenant_id=TENANT_UUID&locale=en&limit=5"

Response:

{
  "summary": "To set up VPN access, install the company VPN client and...",
  "citations": [
    {
      "article_id": "101",
      "title": "VPN Setup Guide",
      "slug": "vpn-setup",
      "collection_name": "Network",
      "snippet": "Install the company VPN client, then sign in with your SSO credentials."
    }
  ],
  "source_count": 3,
  "mode": "ai",
  "provider": "anthropic"
}

Get Article

Fetch a single article by reference. The {article_ref} path segment may be a numeric article id or a slug.

curl "https://apps.aurionai.net/api/v1/help-center/articles/vpn-setup?tenant_id=TENANT_UUID"

Response:

The article is returned nested alongside its collection and breadcrumb trail:

{
  "article": {
    "id": "101",
    "collection_id": "550e8400-e29b-41d4-a716-446655440000",
    "collection_name": "Network",
    "collection_slug": "network",
    "title": "VPN Setup Guide",
    "slug": "vpn-setup",
    "body_html": "<p>To set up VPN access...</p>",
    "body_text": "To set up VPN access...",
    "locale": "en",
    "status": "published",
    "version": 3,
    "published_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-05-02T14:30:00Z",
    "view_count": 1203,
    "helpful_count": 88,
    "not_helpful_count": 4,
    "tags": ["vpn", "network"],
    "author_name": "AurionAI Team"
  },
  "collection": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Network", "slug": "network" },
  "breadcrumbs": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Network", "slug": "network" }
  ]
}

An unknown reference returns 404 {"detail": "Article not found"}.

Related Articles

Return articles related to a given article. Rate-limited to 60 requests per minute. Supported query parameters: locale (default en) and limit (1–10, default 5).

curl "https://apps.aurionai.net/api/v1/help-center/articles/101/related?tenant_id=TENANT_UUID&limit=5"

Submit Feedback

Record whether an article was helpful. The body accepts only helpful (boolean, required) and request_chat_handoff (boolean, default false). There is no comment field.

curl -X POST "https://apps.aurionai.net/api/v1/help-center/articles/101/feedback?tenant_id=TENANT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "helpful": true,
    "request_chat_handoff": false
  }'

Contact Form Schema

Retrieve the dynamic form schema for the contact form, based on custom field definitions configured by the tenant:

curl "https://apps.aurionai.net/api/v1/help-center/contact-form/schema?tenant_id=TENANT_UUID"

Contact Form

curl -X POST "https://apps.aurionai.net/api/v1/help-center/contact?tenant_id=TENANT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "subject": "Cannot find VPN article",
    "message": "I need help setting up VPN but cannot find the right article."
  }'

Ticket Form Schema

Retrieve the portal form schema for conversation/ticket creation. Returns JSON Schema and UI Schema for rendering the form, including branding, authentication, and file-upload settings:

curl "https://apps.aurionai.net/api/v1/help-center/ticket-form/schema?tenant_id=TENANT_UUID&locale=en"

Response:

{
  "schema": { "type": "object", "properties": { "subject": { "type": "string" } } },
  "ui_schema": {},
  "form_id": "form_abc123",
  "form_version": 2,
  "branding": { "primary_color": "#6366F1" },
  "requires_auth": false,
  "file_upload_enabled": true,
  "max_file_size_mb": 10,
  "rich_text_enabled": true,
  "allowed_file_types": ["image/*", ".pdf", ".docx", ".txt", ".csv", ".xlsx"]
}

Submit Conversation

Submit the portal form rendered from the Ticket Form Schema. This creates an AurionAI conversation (channel portal_form) — no ITSM provider ticket is created automatically. The endpoint accepts both anonymous and authenticated submissions: when an end-user JWT is supplied via Authorization: Bearer <token>, identity is taken from the token and name/email are ignored; otherwise name and email are required.

Body fields: subject (1–255, required), description (1–5000, required), name (≤200), email (≤254), description_html (≤50000), custom_attrs (object), form_id, form_version, attachment_ids (≤10 pre-uploaded ids — see Attachments), and locale (≤10, defaults to en). Rate-limited to 5 submissions per IP per minute.

curl -X POST "https://apps.aurionai.net/api/v1/help-center/conversations?tenant_id=TENANT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "subject": "VPN keeps disconnecting",
    "description": "My VPN drops every few minutes after the latest client update.",
    "form_id": "form_abc123",
    "form_version": 2,
    "attachment_ids": [],
    "locale": "en"
  }'

Response: (201 Created)

{
  "id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
  "display_id": "CONV-1042",
  "status": "open",
  "created_at": "2026-06-09T10:15:00Z",
  "form_version_warning": null
}

Attachments

When file uploads are enabled on the portal form, attach files by pre-uploading them and then passing the returned ids in attachment_ids on the conversation submit. First request a presigned upload URL (rate-limited to 20 requests per IP per minute):

curl -X POST "https://apps.aurionai.net/api/v1/help-center/attachments/presign?tenant_id=TENANT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "screenshot.png",
    "content_type": "image/png",
    "file_size": 204800
  }'

Response: (201 Created)

{
  "upload_url": "https://...presigned-s3-url...",
  "attachment_id": "att_5f6g7h8i9j0k",
  "expires_in_seconds": 300
}

Then upload the file bytes. In production the upload_url is a presigned S3 PUT; in development the upload is served by the API:

curl -X PUT "https://apps.aurionai.net/api/v1/help-center/attachments/TENANT_UUID/att_5f6g7h8i9j0k/upload" \
  --data-binary @screenshot.png

Pass the attachment_id values (max 10) in the attachment_ids array when calling Submit Conversation.

Admin Branding Endpoints

These endpoints manage Help Center branding (logo, favicon, colors, custom CSS). They require a dashboard session JWT with an admin role (super_admin, tenant_owner, or tenant_admin) passed as a Bearer token. API keys cannot reach these endpoints — the entire /api/v1/help-center prefix returns 403 for X-API-Key requests (see Authentication).

Get Branding

curl "https://apps.aurionai.net/api/v1/help-center/admin/branding" \
  -H "Authorization: Bearer <dashboard-JWT>"

Update Branding

curl -X PATCH "https://apps.aurionai.net/api/v1/help-center/admin/branding" \
  -H "Authorization: Bearer <dashboard-JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#4F46E5",
    "footer_show_powered_by": false
  }'

Upload Branding Assets

Upload logo and/or favicon files (max 2 MB each, PNG/JPG/SVG/ICO/WebP):

curl -X POST "https://apps.aurionai.net/api/v1/help-center/admin/branding/upload" \
  -H "Authorization: Bearer <dashboard-JWT>" \
  -F "logo=@logo.png" \
  -F "favicon=@favicon.ico"

Categories

The Help Center organizes articles into categories and subcategories. Categories are managed through the admin dashboard or KB API.

Deflection Analytics

Track how effectively the Help Center deflects support tickets. View metrics in the Analytics dashboard or via the analytics API.

Related Guides

• Knowledge Base — Manage KB articles powering the Help Center
• Analytics — Help Center deflection metrics

Authentication

The Help Center surface is not API-key accessible. The /api/v1/help-center prefix is not in the public API-key allowlist, so any request authenticated with X-API-Key returns 403 {"detail": "API keys are not permitted for this endpoint"}. There is no config:read / config:write (or any other) scope that grants an API key access here.

• Public read endpoints (resolve-tenant, landing, collections, collection detail, settings, articles, related articles, search-summary, article detail, feedback, contact-form schema, contact, ticket-form schema, conversation submit, attachment presign/upload) require no authentication. The tenant is resolved from the request host when called via the tenant's Help Center domain, or you pass a tenant_id query parameter explicitly.
• Admin branding endpoints (/api/v1/help-center/admin/branding, /admin/branding/upload) require a dashboard session JWT with an admin role (super_admin, tenant_owner, or tenant_admin), passed as Authorization: Bearer <dashboard-JWT> — never an API key.