Catalog AI
Sign In

File uploads API

Upload reference documents that enrichment jobs can read alongside public web sources. Use this for spec sheets, supplier price lists, and datasheets that are not published anywhere the platform could find on its own.

Uploaded files are stored against the organization and referenced by ID when a job is created.

Upload files

Endpoint: POST /api/{organization}/enrichment-files/upload

This is the one endpoint in the API that takes multipart/form-data rather than JSON. Send each file under the field name files; repeat the field to send several in one request.

Limits

Limit Value
Maximum size per file 20 MB
Accepted types PDF, CSV, XLSX, XLS, PNG, JPEG, WebP

Type is checked against the MIME type the client sends, not the file extension.

Accepted MIME types

Type MIME type
PDF application/pdf
CSV text/csv
XLSX application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
XLS application/vnd.ms-excel
PNG image/png
JPEG image/jpeg
WebP image/webp

Example request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/enrichment-files/upload \
  -H "Authorization: Bearer your_api_key_here" \
  -F "files=@spec-sheet.pdf" \
  -F "files=@price-list.xlsx"

Response

{
  "success": true,
  "uploadedFileIds": ["file_abc123", "file_def456"]
}

The response is not wrapped in a data object, unlike the rest of the API. Read uploadedFileIds from the top level.

Partial failures

Files are ingested independently, so one bad file does not discard the rest. When any file fails, success is false and an errors array is included alongside the IDs that did succeed.

{
  "success": false,
  "uploadedFileIds": ["file_abc123"],
  "errors": [
    {
      "fileName": "price-list.xlsx",
      "error": "Could not read the workbook"
    }
  ]
}

Check uploadedFileIds rather than success when you want to proceed with whatever was accepted.

Errors

Status Meaning
400 No files in the request, an unsupported MIME type, or a file over 20 MB
401 No API key on the request
403 The key cannot reach this organization
500 Server error

Size and type are validated across the whole batch before anything is ingested, so one oversized file rejects the entire request with a 400. Partial failures in the response body are ingestion errors, which happen after that check passes.

Next steps