Akb

Edit a single document by replacing exact text. Scope is one document. old_string must be unique within the document (or use replace_all). If old_string is not found or appears multiple times, the call fails with a clear error. Use this for inserting, replacing, or removing an inline image without resending the complete document body. For find-and-replace across many documents, use akb_grep with replace instead.

Explain why a user holds the role they hold on a vault: every independent basis, and the effective role derived from them. A member list shows the result, never the reasons.

Export an entire vault as a portable knowledge bundle. Returns the bundle inline as a {path: content} map. The `format` parameter selects the on-disk format — currently 'okf' (Open Knowledge Format: markdown + YAML frontmatter, the only required field being `type`). Documents export 1:1; tables and files become OKF concept documents (schema / metadata + a `resource` pointer — the rows/bytes stay in AKB). Reader role required. For a downloadable zip, use the REST endpoint GET /api/v1/vaults/{vault}/export.

Retrieve a document by its URI. Returns full content with metadata. Use akb_browse or akb_search first to obtain the URI. Optionally pass a commit hash (from akb_history) to read a previous version.

Download a file from vault storage to a local path. Pass the file URI — `akb://{vault}[/coll/{coll_path}]/file/{uuid}` — from akb_browse or akb_put_file.

Grant vault access to a user. You must be owner or admin of the vault. A rule-driven grantor should name its own source_key so it can later withdraw its own reason without deleting anybody else's.

Get a same-vault knowledge graph — nodes (documents, tables, files) and edges (relations). Provide `uri` to get a subgraph centered on any resource with BFS traversal. Provide `vault` (without uri) to get the full vault graph.

Search for exact text or regex patterns across document content. On a native Document backend, optionally include admitted searchable text Files with `include_text_files=true`; binary Files remain excluded. Unlike akb_search (semantic/meaning-based), this finds exact string matches — use it for specific terms, URLs, code snippets, version numbers, etc. Native matching and replacement use per-line Python regex semantics; case-insensitive literals use the same Unicode rules as replacement. Native results include body-relative line numbers and searched revision identity. Returns matching document…

Get help on AKB tools and workflows. Call with no arguments for an overview. Drill down into categories or specific tools for details and examples. START HERE if you're new to AKB.

Get version history of a document — who changed it, when, and why. Each entry is a Git commit. Use the commit hash with akb_get to read a previous version.

Import a knowledge bundle into a vault. Pass `files` as a {path: content} map (the shape akb_export returns). `format` selects the bundle format — currently 'okf'. Concept documents are imported as AKB documents; a `type: table`/`file` concept doc (which carries only schema/metadata, not rows/bytes) imports as a regular document describing that asset. Existing paths are skipped, not overwritten. Records targeting the reserved 'overview' collection or carrying type='skill' are skipped per-record and reported in the response's 'reserved' list. Writer role required.

Description is built at runtime.

List accessible vaults as {name, description} pairs. Response is slim — no metadata (id/role/created_at) — to fit large tenants in agent context. Returns {vaults, total, returned, truncated?, hint?}. Optional args: - filter: substring match on name+description (case-insensitive). Use to narrow to a domain (e.g. filter='finance'). - limit / offset: pagination when there are many matches. - include_archived: include archived vaults (default false).

Move or rename a document — change its collection and/or slug while keeping its identity and full git history. The old akb:// URI keeps resolving (a redirect is recorded), and graph links/publications are rewritten. Provide collection and/or slug (at least one must change). The title is unchanged; use akb_update to change the displayed title.

Get provenance for a document — who created it, when, which entities were extracted, and its visible same-vault relations.

Freeze a table_query publication's current result to S3 and flip its mode to 'snapshot' (subsequent visits return the cached result). Identified by `slug` alone — the vault is resolved from the publication. Returns the updated publication dict.

List every publication in a vault. Each item is the canonical publication dict (same shape as `akb_publish` returns).

Create a public, no-auth share URL for a document, file, or table query. Document/file: pass the resource `uri`. Table query: pass `query_sql` plus `vault` (and `query_vault_names` if the query touches more than one). Returns the canonical publication dict — `slug` is the only identifier you need; `share_url` is always an absolute URL ready to paste.

Store a new document. The response carries the canonical `uri` — `akb://{vault}/coll/{collection}/doc/{filename}` when stored under a collection, or `akb://{vault}/doc/{filename}` at the vault root. Use that URI to address the document from every other tool. Automatically chunked and indexed for semantic search.

Upload a local file to a vault's file storage (S3-backed). Use for PDFs, images, datasets, or any binary content too large for akb_put. Response includes the canonical `uri` — `akb://{vault}/coll/{collection}/file/{uuid}` when stored under a collection, or `akb://{vault}/file/{uuid}` at the vault root — pass that to akb_get_file / akb_update_file / akb_delete_file. MIME type is auto-detected from the filename extension unless overridden.

Upload a local PNG, JPEG, GIF, or WebP (maximum 10 MiB) for inline use in an AKB Markdown document. Returns a stable `/api/assets/{uuid}` URL and a ready-to-paste `markdown` image expression. For a new document, place it with akb_put. For an existing document, prefer a targeted akb_edit; akb_update(content=...) replaces the entire body and must never receive only an image fragment. Images are immutable: upload a replacement and edit the Markdown reference. This creates a hidden document attachment, not a standalone File; use akb_put_file when the binary should appear in browse/search. If the d…

Get relations for any resource (document, table, or file). Shows same-vault cross-type connections: doc→table, doc→file, table→file, etc. Each row identifies whether it is an explicit link or implicit document-derived edge.

Revoke a user's vault access. You must be owner or admin. Omit source_key and the person is out of the vault entirely; name one and only that basis is withdrawn, which may downgrade rather than remove.

Search documents with hybrid retrieval — dense vector (semantic) fused with BM25 sparse (keyword) via Reciprocal Rank Fusion. Handles both natural-language questions and short keyword queries well. For exact string / regex matches (code, URLs, version numbers) prefer akb_grep. Returns each hit's `uri`; `collection_summary` and `vault_description` describe the hit's parent context but do not affect matching or ranking. Use akb_drill_down or akb_get with that URI for full content. Response reports `returned` (in `results`) and `total_matches` (size of the deduped prefetch pool — NOT a corpus-wid…

Search for users by username, display name, or email. Use this to find users before granting vault access.

Set vault public access level. Owner only. 'none'=private, 'reader'=public read, 'writer'=public read+write.

Execute SQL on vault tables. Tables are real PostgreSQL tables. Use table names directly (e.g. 'pipeline', 'partners') — they are auto-resolved to the vault's tables. For cross-vault queries, list all vaults in the vaults parameter. Prefix table names with vault name for cross-vault: sales__pipeline, external_projects__partners. SELECT requires reader role. INSERT/UPDATE/DELETE requires writer role. Add a LIMIT to SELECTs unless you truly need every row — the full result set is returned (nothing is silently truncated), so an unbounded SELECT on a large table can send back a very large response…

Transfer vault ownership to another user. The current owner or a system admin can do this.

Remove an explicit same-vault relation between two resources. Implicit relations are removed by editing their source document. If relation type is omitted, removes all explicit relations between the two resources.

Remove publication(s). Pass `slug` to remove one specific publication, OR `uri` to remove every publication of that document/file resource (handy when re-publishing). table_query publications have no resource URI, so remove them by slug. Returns {deleted: N}.

Update an existing document. Only provide fields you want to change. The `content` field replaces the complete Markdown body; never pass a partial fragment such as a newly uploaded image. Use a targeted akb_edit for inline insertion or replacement.

Replace the bytes of an existing vault file while preserving its URI. The local file is hashed before transfer; identical content is skipped. Pass expected_content_hash and/or expected_version from akb_get_file to reject stale writes with HTTP 409 instead of overwriting a concurrent change.

Get detailed vault information: owner, member count, document/table/file/edge counts, last activity.

List all members of a vault with their roles (owner, admin, writer, reader).

Get your current profile — username, email, display name, role. Use this to check who you are authenticated as.