Skip to main content

Training Sources

Programmatically manage custom file uploads - add, list, retrieve, and delete sources via API.

Overview​

  • Upload files (PDFs, Word docs, spreadsheets, etc.)
  • List and filter your custom sources
  • Retrieve source details
  • Delete sources individually or in bulk
API Key Permissions Required

Enable Manage Sources Permission for your API key in Settings → Custom APIs.

Authentication​

Authorization: YOUR_API_KEY

See Getting Started - Authentication.

Endpoints​

1. List Custom Sources​

GET /external/sources/custom

Retrieve paginated list with optional filtering.

Query Parameters​

ParameterTypeDescription
namestringFilter by name (partial, case-insensitive)
statusstringFilter by status (active, error, processing)
typestringFilter by file type
teamIdstringFilter by team ID
pagenumberPage number (default: 1)
pageSizenumberItems per page (default: 100, max: 1000)

Example​

curl "https://api.chataid.com/external/sources/custom?teamId=team123&status=active" \
  -H "Authorization: YOUR_API_KEY"

Response​

{
  "ok": true,
  "data": [
    {
      "id": "65e1c08202791119fbe1d476",
      "name": "Product Documentation.pdf",
      "status": "active",
      "type": "pdf",
      "url": "https://storage.chataid.com/...",
      "wordCount": 15420,
      "usageCounts": 87,
      "createdAt": "2024-03-01T10:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "total": 42,
  "totalPages": 5
}

2. Get Custom Source by ID​

GET /external/sources/custom/:id

Retrieve single source details.

Example​

curl "https://api.chataid.com/external/sources/custom/65e1c08202791119fbe1d476" \
  -H "Authorization: YOUR_API_KEY"

Response​

{
  "ok": true,
  "data": {
    "id": "65e1c08202791119fbe1d476",
    "name": "Product Documentation.pdf",
    "status": "active",
    "type": "pdf",
    "wordCount": 15420,
    "createdAt": "2024-03-01T10:30:00Z"
  }
}

3. Add Custom Sources (Upload)​

POST /external/sources/custom

Upload one or more files.

Implementation
  • Use multipart/form-data encoding
  • For Node.js 18+, use built-in FormData
  • Append files as Blob with proper MIME types

Query Parameters​

ParameterTypeDescription
teamIdstringTeam ID (optional, defaults to org-wide)

Request Body​

Content-Type: multipart/form-data

FieldTypeDescription
filesFile[]One or more files to upload

Supported Formats​

CategoryFormats
DocumentsPDF, Word (.doc, .docx), Text (.txt), Markdown (.md), HTML
SpreadsheetsExcel (.xls, .xlsx), CSV
PresentationsPowerPoint (.ppt, .pptx)
ImagesPNG, JPEG, GIF

See Data Sources - Supported File Types.

Example​

cURL File Upload
curl -X POST "https://api.chataid.com/external/sources/custom?teamId=team123" \
  -H "Authorization: YOUR_API_KEY" \
  -F "files=@/path/to/file1.pdf" \
  -F "files=@/path/to/file2.docx"

Response​

{
  "ok": true,
  "message": "Started training on 2 sources successfully."
}
Asynchronous Processing

Files process asynchronously. Use List Custom Sources to check status.

Common Errors​

  • Unsupported file type: <filename> - Use supported formats
  • File already exists: <filename> - Rename or delete existing
  • File size exceeds limit - Max 100 MB per file
  • API Key does not have permission to manage sources - Enable permissions

4. Delete Multiple Sources​

DELETE /external/sources/custom

Delete by IDs or filters.

Permanent Deletion

This operation is irreversible. Deleted sources cannot be recovered.

Request Body​

Content-Type: application/json

Specify either ids or filters:

FieldTypeDescription
idsstring[]Array of source IDs to delete
filtersobjectFilter criteria to delete all matches
warning

If neither is provided, all custom sources will be deleted.

Filter Options​

FieldDescription
nameFilter by source name
statusFilter by status (e.g., error)
typeFilter by file type
teamIdFilter by team ID

Examples​

Delete by IDs:

curl -X DELETE "https://api.chataid.com/external/sources/custom" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["id1", "id2"]}'

Delete by filter:

curl -X DELETE "https://api.chataid.com/external/sources/custom" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"status": "error"}}'

Response​

{
  "ok": true,
  "deletedCount": 25
}

5. Delete Source by ID​

DELETE /external/sources/custom/:id

Delete single source.

Permanent Deletion

Cannot be undone.

Example​

curl -X DELETE "https://api.chataid.com/external/sources/custom/65e1c08202791119fbe1d476" \
  -H "Authorization: YOUR_API_KEY"

Response​

{
  "ok": true
}

Error Responses​

StatusErrorSolution
401Unauthorized: No Authorization Token ProvidedAdd Authorization header
401Unauthorized: Invalid Access TokenGenerate new API key
403API Key does not have permission to manage sourcesEnable "Manage Sources Permission"
404Custom source not foundVerify source ID
400Unsupported file typeUse supported formats

See Getting Started - Error Handling.

Best Practices​

  1. Check Permissions - Ensure API key has "Manage Sources Permission"
  2. Validate Files - Check formats before uploading
  3. Monitor Status - Poll source status after upload
  4. Use Filters - Reduce response size when listing
  5. Handle Errors - Implement proper error handling
  6. Organize by Teams - Assign sources appropriately
  7. Cleanup Regularly - Remove old or error sources

Need Help?

Our support team is here to help you get the most out of Chat Aid.