Integrate file workflows

Usable exposes file workflows through the dashboard, REST, and MCP. Use REST when your application already knows the exact transfer steps. Use MCP when an AI client should discover or choose a file operation within a permission boundary.

Neither interface replaces application-level authorization, validation, idempotency, or secret handling.

REST workflow

A practical deterministic sequence is:

multipart upload
→ store file ID
→ poll status
→ fetch metadata
→ attach or download
→ verify

The released public surface includes routes for upload, search, metadata update/delete, download, status, cancellation, bulk deletion, attachment add/remove, and listing a fragment's files. Use the current OpenAPI document at:

https://usable.dev/api/docs

for exact schemas and environment-specific behavior.

Upload example

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"

The released public route documents a 50 MB limit and asynchronous processing. Treat the returned file ID as the operation handle, not proof of readiness.

Poll with bounded backoff. Stop on ready, terminal failure, or timeout, and report the unresolved state.

MCP workflow

The MCP file sequence is:

request-upload-url
→ perform returned upload step
→ search-files or get-file
→ attach-file-to-fragment
→ verify

Use search-files for workspace-scoped metadata discovery and get-file for the selected file's current authorized metadata/download information.

A model-supplied file or fragment ID is untrusted input. The service must verify both objects and their workspace boundary before attachment.

Choose the right interface

Prefer REST for:

• known imports and synchronization jobs;
• multipart transfer;
• bulk deterministic cleanup;
• scheduled processing;
• strict idempotency and service-owned state.

Prefer MCP for:

• assistant-mediated file discovery;
• choosing evidence to attach after research;
• client-native tool workflows;
• operations that need model judgment within explicit limits.

If an MCP client cannot complete byte transfer, use REST for upload and MCP only for later discovery or attachment.

Authentication and permissions

Use OAuth for compatible interactive MCP clients and a dedicated least-privilege PAT for server automation. The credential must permit both the target workspace and each file/fragment action.

Keep bearer credentials and signed URLs in secret or transient server state. Never send them to the model, browser logs, fragment content, or public error reports.

Idempotency and retries

Store file IDs and operation state in the calling system. Before retrying an ambiguous upload or attachment:

1. Fetch by returned ID if available.
2. Search by stable metadata.
3. Check whether the relationship already exists.
4. Retry only the incomplete step.
5. Avoid duplicate binaries and duplicate attachments.

Do not infer failure solely from a client timeout.

Signed downloads

Treat a signed download URL as an expiring bearer-like capability:

• return it only to an authorized caller;
• do not persist it as the file's canonical identity;
• do not log or publish it;
• request a fresh authorized URL when needed;
• validate destination handling before following redirects.

The durable identity is the file ID inside its workspace boundary.

Hosted Zone limitation

Hosted Zone V1 does not support file upload, search, retrieval, or attachment on Leaf-backed workspaces. Do not route file payloads to Cloud as a fallback for private Leaf data.

Handle typed boundary errors and use a Cloud workspace for file workflows until support is released.

Error handling

Separate:

• HTTP transport/authentication errors;
• permission failures;
• validation or size failures;
• accepted operations still processing;
• missing/deleted objects;
• MCP tool-level errors.

Retry only transient conditions. Correct invalid input and review permissions deliberately.

Related pages

• MCP tools and permissions
• Upload and process files
• Attach files to fragments
• Personal access tokens