Files, attachments, and collections

This guide explains how files, attachments, and collections work across the dashboard, REST API, and MCP.

Files

A Usable file is a workspace-level asset. It can exist independently of a fragment and can be attached to one or more fragments when relevant.

When to use files

Use files for:

• PDFs, screenshots, diagrams, spreadsheets, exported reports, and reference assets.
• Evidence attached to a troubleshooting or solution fragment.
• Source material for public documentation.
• Assets that should be searchable by filename/tags.

Do not use files for secrets or credential exports, unreviewed customer data in public workspaces, or material that should be summarized as a fragment instead.

REST file endpoints

Upload example

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

The upload is asynchronous. Poll status before attaching or downloading. The public API documents a 50 MB file limit.

MCP file tools

Collections

Collections curate fragments into a named set. They are best for groups that humans or AI clients should treat as related.

Good collection names

• Public platform docs v1.195.0
• Customer onboarding guide
• API integration recipes
• Release notes and upgrade guidance

REST collection endpoints

MCP collection tools

Fragment collection membership is commonly managed by collectionIds on MCP create-memory-fragment and update-memory-fragment, or by the REST collection endpoints for deterministic batch scripts.

Fragment symlinks and auto-link rules

Usable supports fragment symlink/relationship operations through MCP tools and workspace-overview auto-link rules.

Manual MCP symlink tools

• create-fragment-symlink
• remove-fragment-symlink

Auto-link rules

Auto-link rules are workspace-level rules managed by owners/collaborators from the workspace overview page. They match source-workspace fragment tags and create symlinked fragments in a target workspace.

Rule fields:

Since v1.195.0, symlink child fragments are marked with createdVia: "symlink" and include an optional symlinkParentId. Reports that should count only original authoring should exclude or separately group createdVia: "symlink".

Webhooks

Webhooks are workspace-level integration hooks for external automation.

Public REST endpoints:

• GET /api/workspaces/{id}/webhooks
• POST /api/workspaces/{id}/webhooks
• PATCH /api/workspaces/{id}/webhooks/{webhookId}
• DELETE /api/workspaces/{id}/webhooks/{webhookId}
• POST /api/workspaces/{id}/webhooks/trigger

Recommended workflow:

1. Create a webhook receiver in your service.
2. Configure the webhook in workspace settings.
3. Select only the event types needed.
4. Use the manual trigger/test flow before production.
5. Rotate secrets or disable the webhook if exposed.

Permissions

Troubleshooting