Canister API

Call Kinic Wiki from ICP CLI

Use icp canister call when you need the raw Candid API on the mainnet canister. Query methods include --query; write methods are update calls and omit it.

Mainnet canister6emaw-iyaaa-aaaay-aacka-cai

Public read meansanonymous principal has Reader role

Anonymous-readable DBUse a database ID returned by list_databases as anonymous.

Anonymous principal2vxsx-fae

Network flag-n ic for direct canister-principal calls

1. Smoke Check

Confirm that ICP CLI can reach the Kinic Wiki canister on mainnet.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai canister_health '()' --query -n ic -o candid

2. List Anonymous-Readable DBs

Use --identity anonymous to find DBs readable by principal 2vxsx-fae.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai list_databases '()' \
  --query -n ic --identity anonymous -o candid

3. Query Database SQL

Call a readable DB with the current ICP CLI identity. Private DBs require a member identity.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai query_database_sql_json \
  '("<database-id>", "SELECT json_object('\''path'\'', path, '\''updated_at'\'', updated_at) FROM fs_nodes ORDER BY updated_at DESC LIMIT 20", 20 : nat32)' \
  --query -n ic -o candid

4. Anonymous SQL Read

Read the example DB anonymously. This is not an auth bypass; the DB grants Reader to 2vxsx-fae.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai query_database_sql_json \
  '("<public-database-id>", "SELECT json_object('\''path'\'', path) FROM fs_nodes LIMIT 20", 20 : nat32)' \
  --query -n ic --identity anonymous -o candid

5. Anonymous Node Read

Use a path returned by SQL or search, then call read_node against the same anonymous-readable DB.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai read_node \
  '("<public-database-id>", "/Sources")' \
  --query -n ic --identity anonymous -o candid

6. Write Preflight

Check writer access and DB cycles before sending an update call. Anonymous identity is rejected.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai check_database_write_cycles \
  '("<database-id>")' \
  --query -n ic -o candid

7. Write Nodes

Call write_nodes as a database writer or owner. This is an update call, so it has no --query flag.

icp canister call 6emaw-iyaaa-aaaay-aacka-cai write_nodes \
  '(record {
    database_id = "<database-id>";
    nodes = vec {
      record {
        path = "/Knowledge/example.md";
        kind = variant { File };
        content = "# Example";
        metadata_json = "{}";
        expected_etag = null;
      };
    };
  })' \
  -n ic -o candid

Access Model

The mainnet canister ID is the endpoint target. Access is still enforced per database.
Anonymous read means calls use --identity anonymous and caller principal 2vxsx-fae.
Only DBs that granted Reader to 2vxsx-fae are readable anonymously.
Private DB calls use the current ICP CLI identity and require that identity to be a DB member.
This page documents raw Candid calls, not kinic-vfs CLI commands.

Parameters

database_id: text: Readable wiki database ID. Private DBs require a member identity; anonymous-readable DBs can use anonymous.
sql: text: Restricted JSON SELECT over fs_nodes or fs_links.
limit: nat32: Maximum rows returned by the canister response envelope.
path: text: Exact VFS path, for example /Knowledge/index.md or a path returned by query_database_sql_json.
nodes: vec WriteNodeItem: Batch of File, Source, or Folder writes. Each item has path, kind, content, metadata_json, and optional expected_etag.
expected_etag: opt text: Use null for create or unchecked replace; use opt "<etag>" to reject stale overwrites.

Query Endpoints

canister_health(): Smoke check for the target canister.
list_databases(): List databases readable by the caller identity.
check_database_write_cycles(database_id): Preflight write access and cycles state for writer or owner identities.
read_node(database_id, path): Read one file or folder node by exact path.
query_database_sql_json(database_id, sql, limit): Run a restricted JSON SELECT against one readable wiki database.
search_nodes(request): Search wiki content and paths with lightweight previews.
search_node_paths(request): Search paths only.
list_children(request): List direct children under one folder path.
read_node_context(request): Read a node with nearby link context.
query_context(request): Recall task-scoped memory from role pages, search, and linked nodes.
source_evidence(request): Resolve source evidence for a knowledge node.
memory_manifest(request): Inspect the workspace four-store layout and recall limits.

Write Endpoints

write_node(request): Write or replace one file/source node, or create one folder.
write_nodes(request): Write or replace multiple file/source nodes, or create folders, in one batch.
append_node(request): Append content to one node with an optional etag guard.
edit_node(request): Replace text inside one node with an optional etag guard.
delete_node(request): Delete one node. Use etag guards for destructive edits.
mkdir_node(request): Create a folder node.
move_node(request): Move or rename one node.

Write calls are update calls. Do not pass --query.
The caller must be a writer or owner of the target database.
The database must have enough cycles for writes.
check_database_write_cycles is a query preflight; it rejects anonymous callers and underfunded DBs.
Use expected_etag when replacing existing content to avoid overwriting concurrent edits.
Use expected_etag = null only for a create or intentionally unchecked replace.
write_node and write_nodes accept File, Source, and Folder items; folder writes are create-only and idempotent.
Anonymous identity can read only anonymous-readable DBs; it cannot write.

SQL Rules

SQL must be one SELECT, <=4096 bytes, from exactly fs_nodes or fs_links.
LIMIT 1..100 is required in SQL; pass the same upper bound as the nat32 argument.
Return exactly one non-null JSON object TEXT column, usually with json_object(...).
Each row is capped at 64 KiB; the total row payload is capped at 256 KiB.
Joins, subqueries, grouping, window functions, aggregate functions, comments, semicolons, OFFSET, and mutating/admin tokens are rejected.
Index DB tables, metrics, sessions, marketplace orders, and billing tables are not exposed.