Reference and troubleshooting
Bergur DavidsenUpdated 2026-07-15
Use this page as a compact map when you know the task or symptom but not the correct Usable surface. Detailed procedures remain in the linked guides.
Dashboard map
| Area | Primary task |
|---|---|
/dashboard | Start authenticated workflows and open recent resources. |
/dashboard/workspaces | Create, list, discover, and select workspaces. |
| Workspace fragments | Browse, search, create, read, and edit fragments. |
| Workspace Files tab | Upload, process, search, download, and attach files. |
| Workspace settings | Manage details, access, types, notifications, and webhooks. |
/dashboard/organizations | View and administer organization context where authorized. |
| Organization billing | Review effective tier, usage, invoices, and plan changes. |
| Organization Hosted Zones | Register and operate Leaf data planes for eligible organizations. |
| Marketplace / Installed apps | Discover, connect, and review managed integrations. |
| Applications | Register and manage OAuth/Device Code applications. |
| Notifications | Review workspace and organization invitations. |
/account | Profile and account settings. |
Routes and labels can evolve. Start at the dashboard when a deep link no longer matches the current UI.
Authoritative developer references
- Raw deployed OpenAPI:
https://usable.dev/api/docs - Interactive API reference:
https://usable.dev/docs/api-reference - MCP endpoint:
https://usable.dev/api/mcp - MCP source of truth: call
tools/listafter authentication - Current deployed release: check
https://usable.dev/api/versionwhere available - Terms:
https://usable.dev/terms - Privacy:
https://usable.dev/privacy
The OpenAPI document version is not necessarily the same as the product release version.
Core glossary
- Workspace: collaboration, access, and knowledge boundary.
- Memory fragment: durable unit of knowledge.
- Fragment type: classification such as Knowledge, Recipe, Solution, or Skill.
- Tag: cross-cutting retrieval/filter label.
- Summary: short scan-friendly description, not the full source of truth.
- Collection: curated group of workspace fragments.
- File: workspace asset that can exist independently.
- Attachment: relationship between a file and fragment.
- Symlink: maintained cross-fragment/workspace relationship.
- Subscriber: read-style user of a public workspace.
- PAT: personal access token used as a bearer credential where supported.
- MCP: assistant-oriented protocol exposing Usable tools.
- Application: registered integration with OAuth/token configuration.
- Webhook: outbound workspace event delivery to an HTTPS receiver.
- Hosted Zone: organization-registered self-hosted Leaf data plane.
- Leaf workspace: workspace whose private data operations route to Leaf.
Common lifecycle/status terms
Fragment
Use the status exposed by the current surface, commonly draft, published, archived, or active/deleted lifecycle state. Publication status does not override workspace access.
File
Upload can be asynchronous. Treat uploading/processing as incomplete; poll until a terminal ready/succeeded or failed/cancelled state before attaching or depending on the asset.
Webhook
Enabled controls whether matching events are delivered. Manual test delivery is not proof that downstream asynchronous processing completed.
Hosted Zone
registration_requested, provisioned, online, degraded, config_mismatch, offline, and provisioning_failed are operational states documented in the released Hosted Zone contract.
Troubleshoot by symptom
Authentication: 401 or sign-in loop
Confirm account, session expiry, OAuth completion, token validity, client redirect support, and browser cookies. Reauthenticate rather than exposing credentials for diagnosis.
Authorization: 403 or missing control
Check workspace role, organization role, token scope, app administrator status, and plan gate. A listed MCP tool can still fail for a particular workspace/action.
Not found: 404
The object may be absent, archived, in another workspace, or intentionally hidden by access control. Verify identity and scope before recreating it.
Processing is delayed
Wait for asynchronous fragment enrichment, file processing, workspace projection, or Leaf sync. Provide explicit metadata and use smaller inputs when deterministic completion matters.
Search misses content
Verify workspace and status, remove strict filters, search exact title and synonyms, inspect collections, rerun agentic search, and fetch full candidates.
File workflow fails
Check size, status, permissions, and workspace placement. Hosted Zone V1 does not support Leaf file payload workflows.
Webhook fails
Check HTTPS reachability, receiver authentication, selected event, enabled state, response time, payload validation, and duplicate-safe processing.
Billing looks wrong
Refresh effective subscription, organization context, period, invoices, usage unit, and member quantity. Use current UI/API values instead of old examples.
Hosted Zone route fails
Inspect typed codes. Route private data to Leaf for HOSTED_ZONE_REQUIRED; wait for PENDING_LEAF_SYNC; do not retry unsupported files on Leaf.
Support evidence checklist
Provide only non-sensitive evidence:
- affected surface and route;
- approximate timestamp and timezone;
- workspace/fragment/application/webhook/zone ID when safe for the support channel;
- expected and actual behavior;
- HTTP status or typed error code;
- client and authentication method without credential values;
- effective role and plan;
- reproducible steps;
- whether the action succeeds in the dashboard, REST, or MCP;
- redacted logs or screenshots.
Never share tokens, cookies, one-time Leaf keys, payment data, private content, or full webhook authorization headers.
Release and documentation checks
When behavior differs from a guide:
- check the target environment's version;
- inspect deployed OpenAPI or MCP
tools/list; - review current public changelog material;
- confirm whether the feature is plan-, role-, or beta-gated;
- report the verified difference rather than editing docs from memory.