kms

KMS Agent Tools

Talk to a TailorMind KMS instance over its REST API using small bash scripts. No SDK, no Node — just curl + jq.

Quick start

1. Set three environment variables (no defaults — scripts fail loudly if unset):

   • KMS_API_KEY — a project-scoped API key (kms_...). Mint one in the KMS dashboard (Project → Settings → API Keys). Read-only by default; grant Write only if the key must upload or delete.
   • KMS_PROJECT_ID — the project UUID the key is bound to.
   • KMS_BASE_URL — the KMS API base, e.g. https://kms-api.tailormind.io.

   Prefer exporting these from a non-echoed source (e.g. a chmod 600 file you source), not inline on the command line — an inline KMS_API_KEY=... lands in shell history and ps.

2. Run whoami.sh first. It validates the credentials and prints the tenant, scopes, and bound project. If anything is wrong, fix it before doing real work.

scripts/whoami.sh

Operations

Run scripts from this skill's scripts/ directory. Each prints JSON.

Goal	Command
Confirm credentials / identity	whoami.sh
Projects (list/get/create/update/archive/restore/delete)	projects.sh {list [--status]|get <id>|create <name>|update <id> <json>|archive <id>|restore <id>|delete <id> [--hard]}
Ask a question (RAG, with citations)	query.sh "your question" [--mode …] [--rerank] [--collection <id>] [--document <id>] [--min-score F]
Semantic search (raw passages, no synthesis)	search.sh "query" [top_k] [collection_id] [--rerank] [--min-score F]
List documents (filter/paginate)	docs.sh list [--status S] [--collection <id>] [--tags a,b] [--page N]
Get a document / its text	docs.sh get <doc_id> · docs.sh content <doc_id>
Update document metadata (move, tags)	docs.sh update <doc_id> '<json>'
Upload a document (async)	upload.sh <file> [collection_id] [metadata] [--tags a,b] [--version-of <id>]
Recover a stuck/failed doc	reprocess.sh {doc <id>|all|texts <id>|confirm-version <id>}
Poll an upload/processing job	job-status.sh <job_id> [--wait]
Delete a document	delete-doc.sh <doc_id> [--hard] [--force]
Collections	collections.sh {list|create <name>|update <id> <json>|delete <id>}
Structured entities (extracted values)	entities.sh {search "<text>" [--type T]|get <id>|types}
Usage & cost	usage.sh {summary|project|costs}
Graph search / neighbors	graph.sh search "<text>" · graph.sh neighbors <node_id>
Anything else (long tail)	api.sh METHOD PATH [JSON] — see reference.md

reference.md documents the full API surface (bookmarks, exports, webhooks, retention, ontology, audit, citations, query history, every graph op, …) — reach any of it with api.sh. Admin-only domains (api-keys, provider keys, roles, users, platform) are intentionally out of scope for self-serve keys.

Writes (upload.sh, delete-doc.sh, docs.sh update, collections.sh create/update/delete, reprocess.sh, projects.sh create/update/...) need a key with the write scope. Read-only keys get a clear 403 insufficient scope naming write.

Search strategies

There are two distinct operations, then four strategies within a query:

• query.sh — RAG: retrieves context and returns a synthesized answer with citations. Use when the user wants an answer.
• search.sh — semantic search: returns the raw matching passages, no LLM synthesis. Faster; use when you want the source text to reason over yourself.

query.sh --mode picks the retrieval strategy:

Mode	What it does	Use when
semantic (default)	Vector similarity only. Fast.	General "what does the doc say about X".
graph	Knowledge-graph traversal only.	Relationship/entity questions — "how is A connected to B", "who works at X".
hybrid	Semantic + graph combined. Best recall.	When unsure, or the question mixes facts and relationships.
agentic	Iterative tool-calling loop. Deepest, slower, costlier.	Hard multi-hop questions a single retrieval won't answer.

Scope a query with --collection <uuid> (repeatable) or hard-scope to one document with --document <uuid> (resolves cross-document noise in multi-doc projects). Standalone graph exploration (by entity id) is graph.sh.

Uploads are asynchronous — don't claim success early

upload.sh returns immediately with a document id and a job id (HTTP 202). The document is NOT searchable until its job reaches the terminal completed state. Always poll:

upload.sh ./report.pdf <collection_id>      # note the job id it prints
job-status.sh <job_id> --wait               # blocks until completed / *_failed

Job states include intermediate ones (processing, chunking, embedding, …). Terminal states are completed (success) or anything containing failed. Only treat the document as ready on completed.

Errors

Scripts map HTTP status to a one-line message on stderr and exit non-zero:

• 401 — key invalid or revoked. Re-check KMS_API_KEY; run whoami.sh.
• 403 insufficient scope — names the missing scope. Mint a key with it (write covers upload and delete).
• 403 project access denied / 404 — KMS_PROJECT_ID is likely not this key's project. Run whoami.sh.
• 409 — resource busy (often a document still processing). Poll the job, then retry.
• 413 — file over the ~30MB effective cloud upload limit.
• 422 — validation error; check inputs.

Notes & limits

• Graph is tenant-scoped. graph.sh results can span multiple projects in your tenant, unlike query.sh/search.sh which are project-scoped.
• Upload size: the cloud edge (Cloud Run, HTTP/1) caps requests at 32 MiB, so the effective document limit is ~30 MB. Supported types: PDF, DOCX, TXT, MD. Larger files are rejected before the API sees them.
• The full endpoint list lives in reference.md; reach any of it with api.sh METHOD PATH [JSON].