Knowledge search API

Add documents to collections and search them by meaning.

The Knowledge Base lets you search by meaning across your documents and records. This API manages collections and documents and runs searches. If you can ask a question in your own words, search returns the passages that answer it, even when they do not share the same words.

If the Knowledge Base app is switched off in Settings › Apps, these routes answer 404 NOT_FOUND. If knowledge search is not available for your workspace, calls answer 503 KNOWLEDGE_DISABLED.

Where knowledge comes from

Scope What it holds Who can search it
org Your documents, grouped into collections, plus record types you chose to include Anyone with knowledge:query on the collection
user A person's own personal documents That person only
platform AxisIQ's own product help Every member

Documents are indexed in the background after upload. A document is searchable once its status is ready.

Endpoints

Method Path Permission What it does
GET /orgs/{orgId}/knowledge/collections knowledge:read List collections
POST /orgs/{orgId}/knowledge/collections knowledge:manage Create a collection
DELETE /orgs/{orgId}/knowledge/collections/{key} knowledge:manage Delete a collection
GET /orgs/{orgId}/knowledge/sources knowledge:read List documents
POST /orgs/{orgId}/knowledge/sources knowledge:write Add a document
DELETE /orgs/{orgId}/knowledge/sources/{sourceId} knowledge:write Remove a document
POST /orgs/{orgId}/knowledge/search knowledge:query Search
GET /orgs/{orgId}/knowledge/types knowledge:read Which record types are indexed
PUT /orgs/{orgId}/knowledge/types/{typeKey} knowledge:manage Include or exclude a record type

Permissions are checked against the collection (its key is the resource), so a role can be limited to particular collections. knowledge:query is separate from knowledge:read because searching returns document text, while reading only lists what exists.

Collections

{ "key": "policies", "name": "HR policies", "description": "Leave, expenses, travel", "created_at": "2026-10-01T08:00:00Z" }

POST takes key (lowercase letters, digits and hyphens, up to 64 characters, starting with a letter or digit), name and description. Response 201; 409 DUPLICATE_VALUE when the key exists. DELETE answers 204.

POST …/knowledge/sources

Field Type Required Notes
scope string No org (default) or user
collection string For org The collection key. You need knowledge:write on it
title string No Shown with search results. Give it one
body string Yes The text, up to 4 MB 
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/knowledge/sources \
  -H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
  -d '{"collection": "policies", "title": "Travel policy", "body": "Employees may book economy fares…"}'

Response 201:

{ "data": { "id": "0190f800-…", "scope": "org", "collection_key": "policies", "kind": "document", "title": "Travel policy", "status": "pending", "created_at": "2026-10-04T09:30:00Z" } }

status becomes ready when indexing finishes or failed (with error_msg) if it could not be indexed.

GET …/sources accepts scope (org by default, or user) and collection. For org scope collection is required (400 VALIDATION_ERROR without it). It returns { "sources": [ … ] }. Record sources appear with kind: "record", record_type and record_id.

POST …/knowledge/search

Field Type Required Notes
query string Yes Your question or topic
scopes array No Any of platform, org, user. Default is all three
collections array No Limit organization documents to these collection keys
top_k number No How many passages. Default 8, maximum 50 
{
  "data": {
    "results": [
      {
        "scope": "org",
        "score": 0.83,
        "content": "Employees may book economy fares for flights under six hours…",
        "source_id": "0190f800-…",
        "source_title": "Travel policy",
        "collection_key": "policies",
        "created_at": "2026-10-04T09:30:00Z"
      }
    ]
  }
}

Higher score is a closer match. Results are filtered to what you may read: a passage from a record is dropped if any field it contains is hidden from your role.

Record types

GET …/knowledge/types (knowledge:read) lists record types with { "type_key", "enabled", "text_fields", "updated_at" }. PUT …/types/{typeKey} (knowledge:manage) with { "enabled": true, "text_fields": ["notes", "description"] } includes that type's records, using those fields' text, in search. Records created or changed after you include the type are indexed, and re-indexed when they change; excluding the type removes them from search.

Errors

Status Code When
400 VALIDATION_ERROR Empty query or body, body over 4 MB, bad key
403 FORBIDDEN The permission is missing on that collection
404 NOT_FOUND No such collection or document
409 DUPLICATE_VALUE Collection key already used
503 KNOWLEDGE_DISABLED Knowledge search is not available