Fragments and search API

Memory fragments are Usable's durable knowledge records. REST is appropriate for deterministic imports, synchronization, maintenance, and search when your application—not an AI model—controls the workflow.

Always scope operations to the intended workspace and use the deployed GET /api/docs contract for exact schemas.

Core fragment routes

List requests use query parameters, not an MCP-style request body:

curl "https://usable.dev/api/memory-fragments?workspaceId=<workspace-id>&status=published&tags=docs&limit=50&offset=0" \
  -H "Authorization: Bearer <personal-access-token>"

Released list filters include workspace ID, fragment ID, type ID, status, tags, limit, offset, and supported sort fields.

Create a fragment

Resolve a valid fragment type from the target workspace, then send deterministic content and metadata:

{
  "workspaceId": "<workspace-id>",
  "fragmentTypeId": "<fragment-type-id>",
  "title": "REST API authentication",
  "content": "# Authentication\n\nUse a least-privilege bearer token.",
  "summary": "How this integration authenticates to Usable.",
  "tags": ["docs", "api", "authentication"],
  "enhanceTags": false,
  "createdVia": "api",
  "key": "rest-api-authentication"
}

Required fields are workspace ID, fragment type ID, title, and content. Supplying summary and tags avoids relying on asynchronous AI generation when metadata must be exact.

A stable workspace-scoped key helps imports detect existing records. It is not a substitute for handling conflicts and storing the returned fragment ID.

Update safely

Before updating:

1. Fetch the current fragment.
2. Confirm its workspace and intended identity.
3. Preserve frontmatter and content you do not own.
4. Use only fields supported by PATCH.
5. Avoid sending both full content and mutually exclusive patch operations.
6. Refetch and verify the result.

Frontmatter can be embedded in the Markdown content; do not assume it is always returned as a separately parsed object by the raw REST endpoint.

Understand response shapes

The released list endpoint returns a fragment collection with count, total count, and pagination information. Single-fragment GET wraps its resource in a response containing fields such as success and fragment.

Do not reuse one parser for both without checking the endpoint schema.

Choose a search route

Exact list and filtering

Use GET /api/memory-fragments for known workspace, status, type, tags, sorting, and pagination.

Workspace search

Use GET /api/search for released workspace-scoped advanced search:

curl "https://usable.dev/api/search?workspaceId=<workspace-id>&q=authentication&limit=10" \
  -H "Authorization: Bearer <personal-access-token>"

Related released routes include global, simple, suggestions, saved-search, and analytics endpoints where authorized.

Structured listing

POST /api/fragments/list supports released exact, metadata-heavy listing with selection, ordering, and pagination. Treat query expressions as untrusted input; use only controlled templates and the deployed schema.

Agentic search

POST /api/fragments/agentic-search supports richer AI-oriented discovery when keyword and metadata filters are insufficient.

Agentic results are leads. Fetch the selected fragments in full and verify source, date, workspace, and status before relying on them.

REST and MCP are not interchangeable

MCP tool names and REST paths differ. Common mistakes include:

• posting an MCP search shape to /api/memory-fragments;
• expecting MCP's normalized content/frontmatter output from raw REST;
• expecting a file downloadUrl in REST metadata;
• assuming every MCP tool has a same-named REST endpoint.

A 405 often indicates the wrong method or a guessed path. Inspect /api/docs instead of translating tool names mechanically.

Processing and imports

Create or update can trigger enrichment, embedding, and graph processing. A successful response may represent accepted work rather than completed indexing.

For imports:

• preserve returned IDs;
• provide deterministic metadata;
• poll or refetch with bounded backoff;
• detect existing stable keys before retry;
• verify search only after processing;
• quarantine failed records instead of retrying forever.

Destructive operations

DELETE can archive or soft-delete depending on the endpoint and current contract. Before deletion, inspect collection membership, file attachments, symlink relationships, and downstream references. Refetch or list afterward to confirm effective state.

Related pages

• Memory fragments
• Search and retrieval
• Search and ground agent answers
• Requests, responses, pagination, and errors