Usable Platform public overview

Usable is a collaborative, AI-enhanced knowledge platform. It helps teams capture durable information as memory fragments, organize it in workspaces, and make the same knowledge available through a dashboard, REST API, and MCP server.

This document explains public concepts and workflows. It does not describe internal infrastructure, private deployment details, secrets, or unreleased features.

What Usable is for

Use Usable when a team needs a durable knowledge base that can be read and maintained by both humans and AI assistants.

Common use cases include:

• Public or internal documentation fragments.
• Engineering standards, runbooks, recipes, and troubleshooting notes.
• AI assistant memory that persists beyond a single chat.
• Workspace-scoped knowledge retrieval for MCP clients.
• Knowledge imports from scripts or services.
• Public workspace discovery and subscription where enabled.
• Files and attachments associated with a fragment or workspace.
• Marketplace/application integrations where available to the user's account.

Main objects

Workspace

A workspace is the top-level collaboration boundary. It contains fragments, fragment types, members, collections, files, webhooks, and settings. Access checks are generally evaluated against the workspace.

Typical workspace actions:

1. Create or join a workspace.
2. Invite members or accept an invitation.
3. Configure workspace settings.
4. Manage fragment types and webhooks.
5. Create fragments and collections.
6. Upload files.
7. Use the workspace through REST or MCP.

Memory fragment

A memory fragment is the main knowledge record. It is designed to be small enough to retrieve and reason about, but durable enough to serve as an authoritative note.

A fragment commonly includes:

• id: UUID identifier.
• workspaceId: workspace it belongs to.
• fragmentTypeId: category/type identifier.
• title: short searchable title.
• content: markdown body.
• summary: short summary, user-provided or AI-generated.
• tags: array of labels for retrieval and filtering.
• status: draft, published, or archived where exposed.
• key: optional human-readable workspace-scoped lookup key.
• createdAt / updatedAt: timestamps.
• Optional files, collections, and symlink relationships.

Good fragments are specific, sourceable, and easy to retrieve. Avoid storing secrets or volatile chat-style notes unless they are intentionally being preserved.

Fragment type

Fragment types categorize fragments. New workspaces are initialized with Knowledge and Skill. Workspaces may define additional types such as Recipe, Solution, Template, Research, Plan, PRD, or organization-specific types.

Use the most precise type available:

• Knowledge: reference material or background.
• Recipe: step-by-step how-to.
• Solution: troubleshooting or fix details.
• Template: reusable pattern.
• Skill: AI-agent skill definition or instruction set.
• Plan/PRD/Research: project planning and discovery material.

Collection

A collection is a curated group of fragments within a workspace. Use collections for documentation sets, project packets, release notes, onboarding guides, customer-safe bundles, or topic pages.

Collections do not replace good fragment metadata. A fragment should still have a useful title, summary, type, and tags outside the collection.

File and attachment

Files are workspace assets. A file can be uploaded, searched by metadata, downloaded, and attached to a fragment. Attach a file when the file is evidence, source material, a screenshot, a PDF, a spreadsheet, or another asset that gives context to a fragment.

Personal access token

A personal access token (PAT) is a bearer credential for REST and MCP integrations. Tokens should be scoped to the smallest set of workspace permissions required. Revoke tokens when an integration is retired.

Access and permission model

Usable combines user identity, workspace membership, public workspace subscriptions, and token permissions.

Workspace roles

Token permissions

Tokens are not the same as full user sessions. Common permission families:

• fragments.read: search/list/read fragments and related workspace knowledge.
• fragments.create: create fragments.
• Fragment write/update/delete permissions where exposed by the token configuration.
• Workspace-scoped permissions for workspace and collection/file operations.

When an action fails, distinguish auth failure from permissions failure:

• 401: no valid authentication.
• 403: authenticated but not authorized.
• 404: object absent or hidden because the caller cannot access it.

Authentication surfaces

Browser session

The dashboard uses the browser session created by sign-in. Session helpers are exposed under /api/auth/*.

Bearer token

REST and MCP integrations generally use:

Authorization: Bearer <personal-access-token>

Token management endpoints:

• GET /api/tokens — list tokens.
• POST /api/tokens — create a token.
• GET /api/tokens/{id} — inspect token details.
• PUT /api/tokens/{id} — update a token.
• DELETE /api/tokens/{id} — revoke a token.

Treat returned token secret values as sensitive. Store them in your secret manager; do not put them in fragments, code comments, issue trackers, or public docs.

Main public interfaces

Dashboard

The dashboard is for human workflows:

• Create and browse workspaces.
• Create, view, edit, and search fragments.
• Upload and search files.
• Manage collections.
• Configure workspace settings, members, webhooks, and notifications where authorized.
• Manage organizations, billing, marketplace, installed apps, and applications where available.

Start at /dashboard after sign-in.

REST API

The REST API is for scripts, services, and integrations. Publicly documented endpoints are discoverable from GET /api/docs. Endpoint groups include auth/tokens, workspaces, members, webhooks, fragment types, memory fragments, search, files, collections, graph, AI helpers, subscriptions, profile/users, applications, health/version/docs, and MCP.

Use REST when you need deterministic programmatic behavior such as imports, exports, sync jobs, file upload flows, token management, webhook management, or service-to-service integrations.

MCP server

The MCP server is for AI clients. It exposes tools for searching, fetching, creating, updating, and organizing fragments, plus workspace discovery, collections, files, public workspace subscription, and application management.

Use MCP when an assistant should decide which fragments to search, fetch source material, create knowledge, or update documentation with workspace-aware context.

Recommended workflows

New workspace setup

1. Sign in and open /dashboard/workspaces.
2. Create a workspace with a clear name and description.
3. Confirm default fragment types; add custom types only when the default set is insufficient.
4. Invite collaborators or viewers.
5. Create initial fragments: workspace purpose, contribution rules, tagging conventions, and a public/private content policy.
6. Create collections for major documentation groups.
7. Configure webhooks or MCP only after core content exists.

Creating useful fragments

1. Pick the right workspace.
2. Pick the most precise fragment type.
3. Write a title that a human would search for.
4. Put the durable information in the content body, not only in the summary.
5. Add tags for repository, version, topic, audience, status, and ownership.
6. Use summary for quick scanning; if omitted, AI may generate one where supported.
7. Attach files only when they are relevant and safe to share with the workspace audience.
8. Add to one or more collections if the fragment belongs to a curated set.

Searching effectively

Use the interface best suited to the task:

• Dashboard search for human lookup.
• GET /api/search for structured workspace search.
• GET /api/search/global for accessible-workspace search.
• POST /api/fragments/agentic-search for richer agentic discovery.
• MCP agentic-search-fragments for AI assistant discovery.
• MCP list-memory-fragments for exact filtering and pagination.

Public workspace discovery

Public workspaces can be discoverable and subscribable where configured.

Relevant surfaces:

• Dashboard workspace discovery.
• GET /api/workspaces/discover.
• POST /api/workspaces/{id}/subscribe.
• MCP search-public-workspaces.
• MCP subscribe-to-workspace.

Troubleshooting

I can sign in but cannot edit a fragment

Check the workspace role. Viewers and public subscribers should expect read-only access. Ask a workspace owner for collaborator or owner access if editing is appropriate.

My token works for one workspace but not another

Tokens may be workspace-scoped. Create or update the token with the required workspace and permission set.

Search returns incomplete results

Try a broader query, remove overly strict tags, verify workspace scope, and fetch exact results with list-memory-fragments or REST filters.

A newly created fragment is not immediately enriched

Fragment creation and enrichment can involve asynchronous processing. If deterministic metadata matters, provide summary and tags explicitly instead of relying on AI generation.