Knowledge Base

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

The Knowledge Base API lets you manage KB articles that power the AI agent's knowledge. Articles are synced with your ITSM provider and used for automated resolution and guided walkthroughs.

The KB routers are mounted at /api/kb (article creation + categories) and /api/v2/kb (full management + search). None of these paths fall under the public API-key allowlist (/api/v1/*), so they are reached today through a dashboard JWT (Authorization: Bearer …), not an API key. The X-API-Key: itsm_sk_live_… headers shown below reflect the intended future public-API auth.

Search Articles

Full-text search over your KB articles, ranked with relevance scores and snippets.

cURL

curl "https://apps.aurionai.net/api/v2/kb/search?q=vpn+setup&limit=5" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Python

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v2/kb/search",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    params={"q": "vpn setup", "limit": 5},
)
results = response.json()

Response:

{
  "items": [
    {
      "id": "8f1c2d3e-4b5a-6789-0abc-def123456789",
      "title": "How to Set Up VPN on Windows",
      "slug": "how-to-set-up-vpn-on-windows",
      "collection_id": "7a6b5c4d-3e2f-1908-7654-321fedcba098",
      "collection_name": "Network",
      "status": "published",
      "snippet": "Before you begin, ensure you have your <mark>VPN</mark> credentials...",
      "relevance_score": 0.82,
      "updated_at": "2026-02-15T09:00:00Z",
      "view_count": 342,
      "helpful_count": 28,
      "not_helpful_count": 2
    }
  ],
  "total": 3,
  "query": "vpn setup",
  "language": "english"
}

Query Parameters:

Parameter	Type	Description
`q`	string	Required. Search query (2–500 chars), matched against title and content
`language`	string	Full-text search configuration (default: `english`)
`status`	string	Filter by a single status value
`collection_id`	string	Filter to one collection
`limit`	integer	Results per page (default: 20, min: 1, max: 100)
`offset`	integer	Number of results to skip (default: 0)

GET /api/v2/kb/search is a /api/v2 path and is not reachable with an API key (returns 403). Call it with a dashboard JWT.

Get Article

Fetch a single article by ID. The real endpoint lives under /api/v2/kb.

curl "https://apps.aurionai.net/api/v2/kb/articles/{article_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response (KBArticleV2):

{
  "id": "8f1c2d3e-4b5a-6789-0abc-def123456789",
  "collection_id": "7a6b5c4d-3e2f-1908-7654-321fedcba098",
  "collection_name": "Network",
  "title": "How to Set Up VPN on Windows",
  "body_html": "<h2>Prerequisites</h2><p>Before you begin...</p>",
  "body_json": null,
  "body_text": "Prerequisites Before you begin...",
  "slug": "how-to-set-up-vpn-on-windows",
  "locale": "en",
  "status": "published",
  "version": 4,
  "published_version_id": "1b2c3d4e-5f6a-7890-1bcd-ef2345678901",
  "author_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "reviewer_id": "a1b2c3d4-0000-0000-0000-000000000002",
  "reviewed_at": "2026-02-14T18:00:00Z",
  "published_at": "2026-02-15T09:00:00Z",
  "view_count": 342,
  "helpful_count": 28,
  "not_helpful_count": 2,
  "tags": ["vpn", "windows", "network"],
  "scheduled_publish_at": null,
  "expires_at": null,
  "created_at": "2026-01-10T14:00:00Z",
  "updated_at": "2026-02-15T09:00:00Z"
}

GET /api/v2/kb/articles/{article_id} is a /api/v2 path and is not reachable with an API key (returns 403). Call it with a dashboard JWT.

Create Article (v2)

The v2 document-ingestion endpoint accepts document uploads (PDF, DOCX, MD, TXT, HTML) and uses LLM processing to structure the content into a polished KB article.

curl -X POST "https://apps.aurionai.net/api/kb/create-v2" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -F "file=@vpn-guide.pdf" \
  -F "custom_title=VPN Setup Guide" \
  -F "category_id=42" \
  -F "status=published"

Python

import requests

response = requests.post(
    "https://apps.aurionai.net/api/kb/create-v2",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
    files={"file": open("vpn-guide.pdf", "rb")},
    data={"custom_title": "VPN Setup Guide", "category_id": "42", "status": "published"},
)
article = response.json()

Form Fields (all optional unless noted):

Field	Type	Description
`file`	file	Source document to ingest (or supply `preview_id` from a prior preview)
`preview_id`	string	Reuse a cached preview instead of re-parsing a file
`destination_id`	string	Target publish destination
`folder_id`	string	Target folder within the destination
`category_id`	string	Target category within the destination
`status`	string	Initial status (default: `published`)
`custom_title`	string	Override the LLM-inferred title
`custom_tags`	string	Comma-separated tags to apply
`llm_provider`	string	Override the LLM provider used for structuring
`llm_model`	string	Override the LLM model used for structuring
`destinations`	string	JSON array for multi-destination publishing; when set, the single-destination fields above are ignored

Response (CreateResponseV2):

{
  "success": true,
  "article_id": "102",
  "article_url": "https://example.freshservice.com/solution/articles/102",
  "title": "VPN Setup Guide",
  "attachment_count": 3,
  "tags": ["vpn", "windows", "network"],
  "processing_time_ms": 2450,
  "error": null,
  "destination_results": [],
  "warnings": []
}

The LLM pipeline processes the document through: Parser → LLM Structuring (primary → failover → fallback) → Verifier → HTML Builder.

Rate Limits:

Endpoint	Limit
Preview article (`/api/kb/preview-v2`)	10/minute
Create article (`/api/kb/create-v2`)	5/minute

POST /api/kb/create-v2 requires the kb:write admin permission and is not reachable with an API key (the /api/kb prefix is outside the API-key allowlist, so it returns 403). Call it with a dashboard JWT.

Preview Before Creating

Preview how a document will be structured before committing. Returns a PreviewResponseV2 (including a preview_id you can pass to create-v2).

curl -X POST "https://apps.aurionai.net/api/kb/preview-v2" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -F "file=@vpn-guide.pdf"

Form Fields:

Field	Type	Description
`file`	file	Required. Source document to parse and structure
`llm_provider`	string	Override the LLM provider used for structuring
`llm_model`	string	Override the LLM model used for structuring

Like create-v2, this endpoint requires the kb:write admin permission and is not reachable with an API key (403).

KB Categories

curl "https://apps.aurionai.net/api/kb/categories" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a bare list of categories (not a paginated envelope):

[
  { "id": "42", "name": "Network", "description": "Network and connectivity guides" }
]

Query Parameters:

Parameter	Type	Description
`destination`	string	KB destination key: `itsm`, `aurion`, or empty for default resolution

Requires the kb:write admin permission and is not reachable with an API key (403).

KB Destinations & Folders

Two additional admin-only helpers under /api/kb (both require kb:write, both return 403 for API keys):

List publish destinations

curl "https://apps.aurionai.net/api/kb/destinations" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a list of destinations — each { key, name, provider_type, supports_categories, supports_folders, destination_type }.

List folders within a category

curl "https://apps.aurionai.net/api/kb/folders/{category_id}?destination=itsm" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a list of folders — each { id, name, description, category_id, category_name }. Accepts an optional destination query (itsm, aurion, or empty).

Supported Upload Formats

Format	Extension
PDF	`.pdf`
Word	`.docx`
Markdown	`.md`
Plain text	`.txt`
HTML	`.html`

Uploads are subject to a single configurable size cap (KB_MAX_FILE_SIZE_MB, default 50 MB), applied uniformly across all formats. All uploads are scanned for malware before processing; files exceeding the size limit or containing detected threats are rejected.

KB Management API (v2)

Every endpoint in this section is mounted under /api/v2/kb and is gated by a dashboard role check. The /api/v2/* surface is not in the public API-key allowlist, so a request authenticated with X-API-Key returns 403. Call these endpoints with a dashboard JWT (Authorization: Bearer …). The reference below documents the intended contract.

The v2 KB management endpoints provide full CRUD operations for articles and collections.

List Collections

curl "https://apps.aurionai.net/api/v2/kb/collections" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a list of KBCollectionV2 objects — each { id, parent_id, name, slug, description, icon, locale, sort_order, article_count, total_article_count, depth, visibility, approval_type, created_at, updated_at }.

Collection Tree

Get the hierarchical collection tree (each node adds a children array):

curl "https://apps.aurionai.net/api/v2/kb/collections/tree" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Create Collection

curl -X POST "https://apps.aurionai.net/api/v2/kb/collections" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Network", "description": "Network guides", "parent_id": null, "visibility": "all_visitors"}'

Body fields: name (required, 1–200 chars), parent_id, slug, description, icon, locale (default en), sort_order, visibility (all_visitors, logged_in_users_only, or agents_only).

Update Collection

curl -X PATCH "https://apps.aurionai.net/api/v2/kb/collections/{collection_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Networking"}'

All KBCollectionPatchRequestV2 fields are optional: parent_id, name, slug, description, icon, locale, sort_order, visibility.

Delete Collection

curl -X DELETE "https://apps.aurionai.net/api/v2/kb/collections/{collection_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content.

Reorder Collections

curl -X POST "https://apps.aurionai.net/api/v2/kb/collections/reorder" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"id": "col_1", "sort_order": 0, "parent_id": null}, {"id": "col_2", "sort_order": 1, "parent_id": null}]}'

Body is { "items": [ { "id", "sort_order", "parent_id"? } ] } (1–200 items).

List Articles (v2)

curl "https://apps.aurionai.net/api/v2/kb/articles?collection_id=col_1&limit=50" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Parameter	Type	Description
`locale`	string	Filter by locale (2–10 chars)
`status`	string	Filter by status (see status values below)
`collection_id`	string	Filter to one collection
`tag`	string	Filter by tag
`search`	string	Title/content substring match
`limit`	integer	Results per page (default: 50, min: 1, max: 100)
`offset`	integer	Number of results to skip (default: 0)

Returns { "items": [KBArticleV2, …], "total": N, "limit": L, "offset": O }.

Get Article (v2)

curl "https://apps.aurionai.net/api/v2/kb/articles/{article_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Create Article (v2, JSON)

Create an article directly from structured HTML (distinct from the document-ingestion POST /api/kb/create-v2):

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "VPN Setup", "body_html": "<p>...</p>", "collection_id": "col_1", "status": "draft"}'

Body fields: title (required), body_html (required), collection_id, body_json, body_text, slug, locale (default en), status (default draft), tags, change_summary.

Update Article

curl -X PATCH "https://apps.aurionai.net/api/v2/kb/articles/{article_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "body_html": "<p>Updated content</p>"}'

All KBArticlePatchRequestV2 fields are optional: collection_id, title, body_html, body_json, body_text, slug, locale, status, tags, scheduled_publish_at, expires_at, change_summary, expected_updated_at (optimistic-concurrency guard).

Delete Article

curl -X DELETE "https://apps.aurionai.net/api/v2/kb/articles/{article_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content. Soft-deletes the article.

Restore Article

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles/{article_id}/restore" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Publish Article

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles/{article_id}/publish" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Archive Article

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles/{article_id}/archive" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Unpublish Article

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles/{article_id}/unpublish" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Moves a published article back to draft.

Rollback Article

Restore a previous version of an article:

curl -X POST "https://apps.aurionai.net/api/v2/kb/articles/{article_id}/rollback" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"version_id": "1b2c3d4e-5f6a-7890-1bcd-ef2345678901"}'

Body: version_id (required) plus an optional change_summary.

Article Status Values

The status field on KBArticleV2 (and the status filter / transition payloads) uses one of:

draft, in_review, approved, published, archived, changes_requested, rejected.

Import Articles

Import articles from an external provider's knowledge base.

Preview import

curl -X POST "https://apps.aurionai.net/api/v2/kb/import/preview" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"provider": "freshservice", "limit": 10}'

Execute import

curl -X POST "https://apps.aurionai.net/api/v2/kb/import/execute" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"provider": "freshservice", "limit": 10, "target_collection_id": "col_1", "target_status": "draft"}'

Check import status

curl "https://apps.aurionai.net/api/v2/kb/import/status/{job_id}" \
  -H "X-API-Key: itsm_sk_live_xxxx"

import/preview body: provider (required, 3–50 chars), limit (1–50, default 10). import/execute body: provider (required), query, limit (1–50, default 10), target_collection_id, target_status (default draft).

Deleted Articles

View soft-deleted articles:

curl "https://apps.aurionai.net/api/v2/kb/articles/deleted" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Help Center — Public self-service portal powered by your KB articles
Analytics — Track KB deflection and article performance

Required Scopes

The scope pairs below are the intended future public-API scopes. They are not yet enforceable, because no KB router is mounted under the API-key allowlist today — every KB endpoint returns 403 to an X-API-Key request and must be called with a dashboard JWT.

Scope	Endpoints
`kb:read`	`GET /api/v2/kb/search`, `GET /api/v2/kb/articles[/…]`, `GET /api/v2/kb/collections[/…]`
`kb:write`	`POST /api/kb/create-v2`, `POST /api/kb/preview-v2`, `GET /api/kb/categories`, `GET /api/kb/destinations`, `GET /api/kb/folders/{category_id}`, all v2 collection/article writes + import

Knowledge Base

On this page