Skip to content

Knowledge Base API

Manage knowledge documents and monitor account usage via the Customer API.

Upload Document

POST /api/v1/knowledge/documents
Content-Type: multipart/form-data

Request

curl -X POST https://api.ag2trust.com/api/v1/knowledge/documents \
  -H "X-API-Key: cust_your_api_key" \
  -F "file=@product-manual.pdf" \
  -F "name=Product Manual"
Field Type Required Description
file binary Yes The document file (max 10MB)
name string No Display name (defaults to filename)

Optional query parameter: ?end_user_id= to scope the document to a specific end user.

Response (201 Created)

{
  "id": 123,
  "name": "Product Manual",
  "original_filename": "product-manual.pdf",
  "mime_type": "application/pdf",
  "file_size_bytes": 2048576,
  "token_count": null,
  "status": "pending",
  "error_message": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

Supported Formats

PDF, DOCX, XLSX, CSV, TXT, MD, HTML — max 10MB per file.

List Documents

GET /api/v1/knowledge/documents

Query Parameters

Parameter Type Description
status string Filter by status: pending, processing, ready, failed
end_user_id string Filter by end user

Request

curl "https://api.ag2trust.com/api/v1/knowledge/documents?status=ready" \
  -H "X-API-Key: cust_your_api_key"

Get Document

GET /api/v1/knowledge/documents/{id}

curl https://api.ag2trust.com/api/v1/knowledge/documents/123 \
  -H "X-API-Key: cust_your_api_key"

Delete Document

Deletes the document, its S3 object, chunked embeddings, and scope attachments.

DELETE /api/v1/knowledge/documents/{id}

curl -X DELETE https://api.ag2trust.com/api/v1/knowledge/documents/123 \
  -H "X-API-Key: cust_your_api_key"

Download Document (Signed Token)

Download a knowledge document using a signed token from a citation URL. No API key required.

GET /api/v1/knowledge/documents/{id}/download?thread_id={thread_id}&token={token}

The download_url in the pool endpoint's citations array is pre-signed and ready to use.

Document Processing States

Status Description
pending Queued for text extraction
processing Extraction in progress
ready Complete — available to agents
failed Extraction failed (check error_message)

Account Usage

Check your knowledge base usage against tier limits.

Get Usage

GET /api/v1/account/usage

curl https://api.ag2trust.com/api/v1/account/usage \
  -H "X-API-Key: cust_your_api_key"

Returns current document count, token usage, and daily consumption.

Get Limits

GET /api/v1/account/limits

curl https://api.ag2trust.com/api/v1/account/limits \
  -H "X-API-Key: cust_your_api_key"

Returns tier name, document limit, token limit, and other tier-specific constraints.

API Reference Summary

Method Endpoint Description
POST /api/v1/knowledge/documents Upload document
GET /api/v1/knowledge/documents List documents
GET /api/v1/knowledge/documents/{id} Get document
DELETE /api/v1/knowledge/documents/{id} Delete document
GET /api/v1/knowledge/documents/{id}/download Download (signed token)
GET /api/v1/account/usage Account usage stats
GET /api/v1/account/limits Tier limits

Next Steps