Skip to content

File Uploads & Downloads

Ag2Trust supports file uploads via the Customer API and provides signed download URLs for agent-generated files and knowledge document citations.

Overview

Flow Description URL Lifetime
Knowledge documents Upload files to the knowledge base for agent context Permanent (until deleted)
Citation downloads Download knowledge documents referenced in agent responses 24 hours (signed token)
Agent file downloads Download files generated by agents during conversations 1 hour (signed token)

Uploading Knowledge Documents

Upload documents to your knowledge base for agents to reference. See the Knowledge Base guide for full details.

Via Customer API

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"

Response:

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

Supported Formats

Format Extension Max Size
PDF .pdf 10MB
Word .docx 10MB
Excel .xlsx 10MB
CSV .csv 10MB
Plain Text .txt 10MB
Markdown .md 10MB
HTML .html 10MB

Checking Document Status

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

Documents progress through: pending → processing → ready (or failed).

Citation Downloads

When an agent cites a knowledge document in its response, the pool endpoint includes a citations array with signed download URLs:

{
  "content": "According to the product manual [source:1], the feature supports...",
  "citations": [
    {
      "source_id": "source:1",
      "document_name": "Product Manual",
      "download_url": "https://api.ag2trust.com/api/v1/knowledge/documents/123/download?thread_id=thread_abc&token=eyJ..."
    }
  ]
}

Downloading a Cited Document

The download_url is self-contained — no API key required:

curl -o product-manual.pdf \
  "https://api.ag2trust.com/api/v1/knowledge/documents/123/download?thread_id=thread_abc&token=eyJ..."

Token Expiration

Citation download tokens expire after 24 hours. Generate a new response to get fresh download URLs.

Agent File Downloads

When an agent generates a file (e.g., a report, export, or analysis), the pool endpoint includes a files array:

{
  "content": "I've generated the report [file:1]. You can download it below.",
  "files": [
    {
      "ref_id": "file:1",
      "filename": "quarterly-report.pdf",
      "link_text": "Download Report",
      "download_url": "https://api.ag2trust.com/api/v1/uploads/456/download?thread_id=thread_abc&token=eyJ..."
    }
  ]
}

Downloading an Agent File

curl -o quarterly-report.pdf \
  "https://api.ag2trust.com/api/v1/uploads/456/download?thread_id=thread_abc&token=eyJ..."

Short-Lived URLs

Agent file download tokens expire after 1 hour. Files themselves are deleted from storage after 24 hours (S3 lifecycle policy).

Security Model

Both download endpoints use signed tokens instead of API key authentication:

  • Tokens are HMAC-signed with a server secret
  • thread_id is embedded in and enforced by the token
  • Tokens cannot be reused across threads
  • No API key is needed — the signed URL is self-authenticating

This allows you to safely pass download URLs to end users without exposing your API key.

API Reference

Knowledge Documents

Method Endpoint Description
POST /api/v1/knowledge/documents Upload document (multipart)
GET /api/v1/knowledge/documents List documents
GET /api/v1/knowledge/documents/{id} Get document details
DELETE /api/v1/knowledge/documents/{id} Delete document
GET /api/v1/knowledge/documents/{id}/download Download document (signed token)

Agent File Downloads

Method Endpoint Description
GET /api/v1/uploads/{id}/download Download agent file (signed token)

Account Usage

Method Endpoint Description
GET /api/v1/account/usage Knowledge token/doc usage vs limits
GET /api/v1/account/limits Tier limits

Best Practices

  1. Check document status after upload — Documents need processing before they're available to agents
  2. Cache download URLs sparingly — Tokens have limited lifetimes; generate fresh responses for new downloads
  3. Monitor account usage — Knowledge documents consume tokens against your tier limit
  4. Use end_user_id — Pass ?end_user_id= query parameter on document operations to scope visibility

Next Steps