AimableDocs
DocsAPI Reference

Knowledge

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.

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

Response (201 Created):

{
  "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.

curl -X POST 'https://api.aimable.com/api-proxy/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):

{
  "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

curl -X POST 'https://api.aimable.com/api-proxy/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):

{
  "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.

curl -X POST 'https://api.aimable.com/api-proxy/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.

curl -X GET 'https://api.aimable.com/api-proxy/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).

Authentication & Errors

All endpoints require authentication via the Authorization: Bearer <token> header. API keys (X-API-Key) are optional and legacy.

Common Errors

| Status | Meaning | |-------|--------| | 401 | Missing or invalid access token | | 403 | User lacks permission for the resource | | 422 | Invalid parameters or request body |

Example validation error:

{
  "detail": [
    {
      "loc": ["query", "question"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

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