AimableDocs
DocsAPI ReferenceRelease Notes

Knowledge

Updated 9 July 2026

Knowledge Domain

The Knowledge domain in the Aimable Platform API enables applications to manage, enrich, and retrieve structured and unstructured information from document collections. It powers intelligent search, context-aware AI assistants, and knowledge base features by combining document storage, vector indexing, and access control.

Collections are central to this domain — they group related documents (PDFs, text files, etc.) that can be indexed for semantic search. Each collection supports granular permissions, allowing fine-grained access control across users and spaces.

Legacy Note: The /v1/knowledge/ endpoints are being phased out in favor of space-scoped equivalents under /v1/spaces/{space_id}/collections. New integrations should use the space-scoped versions for better context and access management.

Key Concepts

  • Collection: A container for documents, with its own vector index. Can be linked to a space and shared with members.
  • Document: A file (e.g., PDF, TXT) uploaded to a collection. Automatically processed into searchable chunks.
  • Space: A collaborative environment. Collections can be linked to spaces for visibility and access.
  • Member: A user or service principal with a role (viewer, editor, owner) on a collection.

How to Use: Common Workflows

1. Create a Collection in a Space

Use the space-scoped endpoint to create a new collection.

bash
curl -X POST 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/collections' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json'

Response (201 Created):

json
{
  "collection_id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "space_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2024-05-01T10:00:00Z"
}

2. Upload Documents to a Collection

Upload one or more files for background indexing.

bash
curl -X POST 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/collections/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8/documents' \
  -H 'Authorization: Bearer <your-access-token>' \
  -F 'file=@/path/to/manual.pdf'

Response (202 Accepted):

json
{
  "document_id": "doc-9087-6543-2109",
  "filename": "manual.pdf",
  "status": "processing"
}

3. Search Knowledge with Context

Enhance AI prompts by retrieving relevant context chunks.

🔁 Legacy Endpoint — prefer using the tool execution endpoint: POST /v1/spaces/{space_id}/tools/knowledge_search/execute

bash
curl -X POST 'https://api.aimable.com/api/v1/knowledge/calculate_context?question=How+do+I+reset+the+device&collection_ids=a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

json
{
  "question": "How do I reset the device?",
  "context": [
    {
      "text": "To reset the device, hold the power button for 10 seconds...",
      "source": "manual.pdf",
      "score": 0.87
    }
  ],
  "sources": [
    {
      "file_path": "a1b2c3d4/manual.pdf",
      "title": "User Manual"
    }
  ]
}

4. Manage Collection Access

Add a user to a collection with viewer role.

bash
curl -X POST 'https://api.aimable.com/api/v1/knowledge/collections/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8/members' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_id": "usr-1122-3344-5566",
    "role": "viewer"
  }'

5. Generate a Thumbnail

Preview a document page.

bash
curl -X GET 'https://api.aimable.com/api/v1/knowledge/thumbnail?file_path=a1b2c3d4/manual.pdf&page=1&width=200' \
  -H 'Authorization: Bearer <your-access-token>' \
  --output thumbnail.png

Returns an image file (PNG/JPG).

See Authentication & errors for request authentication and the standard error responses.

Best Practices

  • Use space-scoped collection endpoints for new integrations.
  • After uploading documents, allow time for indexing before searching.
  • Use POST /v1/knowledge/prerender-thumbnails to pre-generate thumbnails in bulk.
  • Always URL-encode query parameters like file_path.

This domain powers intelligent, context-aware applications — from chatbots to documentation hubs — with secure, scalable knowledge retrieval.

Related Endpoints

See also