Upload and process files

Upload places a durable file asset inside a Usable workspace. Choose the interface based on who controls the workflow: dashboard for a person, REST for deterministic transfer, and MCP when an AI client should mediate the operation.

The released public upload route documents a 50 MB limit. A released Usable Chat embed byte bridge independently enforces a 50 MiB cap. Treat the current interface response as authoritative when limits differ by environment or path.

Before uploading

Confirm:

• the target workspace and audience;
• that your role or token can upload files;
• the file is necessary and safe to retain;
• its size and format are accepted;
• its filename and metadata reveal no secrets;
• the workspace is Cloud-backed, because Hosted Zone V1 does not support file payload workflows.

Scan or sanitize untrusted files according to your organization's policy before broad distribution.

Upload from the dashboard

1. Open the workspace.
2. Select the Files tab.
3. Choose the upload action.
4. Select the file.
5. Add useful tags where exposed.
6. Start the upload.
7. Wait for upload and processing to complete.
8. Review the resulting file metadata.
9. Attach it to a fragment only when the relationship is useful.

Do not navigate away assuming the file is ready merely because transfer started. Reopen or refresh the Files view and inspect status.

Asynchronous states

A successful upload request can return an identifier while processing continues. Depending on the interface, you may see states such as uploading, processing, ready, failed, or canceled.

While processing:

• preserve the returned file ID;
• poll or refresh with bounded backoff;
• do not create duplicate uploads because search has not indexed the file yet;
• do not attach or distribute a download link until readiness is confirmed.

If processing fails, record the visible error and retry only after correcting its cause.

Upload through REST

For deterministic scripts and services, use the released multipart upload route:

curl https://usable.dev/api/files/upload \
  -H "Authorization: Bearer <personal-access-token>" \
  -F "workspaceId=<workspace-id>" \
  -F 'tags=["docs","source"]' \
  -F "file=@./source.pdf"

Store the returned file ID and poll the file-status route before the next operation. Use REST when the application already knows exactly which file to transfer.

Never log the bearer token or an authorized download URL.

Upload through MCP

An MCP client can use request-upload-url to begin the supported client-assisted upload flow. The client must then perform the returned transfer step and confirm the file with search-files or get-file.

MCP does not remove the need for byte transfer, file validation, or permission checks. Some clients cannot complete upload flows cleanly; use multipart REST in that case.

Cancellation and retries

Where the interface exposes cancellation, cancel an upload that is no longer needed or cannot complete. Then verify its current state before starting over.

For safe retries:

1. Search by returned ID, stable filename, and relevant metadata.
2. Confirm the prior operation did not complete.
3. Retry once with corrected input or network conditions.
4. Avoid appending copy filenames that hide duplicates.
5. Clean up failed or redundant assets after review.

A timeout does not prove that the server discarded the upload.

Common failures

File is too large

Reduce or split it, or store an approved external source link in a fragment. Do not bypass limits by changing only the filename extension.

Upload is stuck

Check network connectivity, refresh the Files view, inspect status, and try a smaller safe test file. Avoid repeated parallel retries.

Upload returns 403

The credential can authenticate but lacks the required workspace/file write access. Confirm the target and minimum needed role.

The file is ready but not on a fragment

Upload and attachment are separate. Follow Attach files to fragments.

Related pages

• Integrate file workflows
• Search, download, and maintain files
• Personal access tokens