Typesense
Typesense: search collections, index documents, and manage collections, aliases and scoped API keys.
About
Typesense ships in the w6w first-party pack. It declares 16 actions, 3 health checks, and the host runs its code in a sandbox that never sees the credential.
- App id
io.w6w.typesense- Version
- 0.1.1
- Author
- w6w
- Licence
- MIT
- Categories
- Search · Databases
Overview
Typesense is an open-source, typo-tolerant search engine, and this app searches and indexes documents in it, and manages the collections, aliases, and API keys around them: writing and searching documents, running several searches in one request, and reading a collection’s schema to see what it can actually search on. It is built for workflows that need to keep a search index up to date or query it directly, whether self-hosted or on Typesense Cloud.
A few actions handle failure modes that are easy to miss: a bulk document import checks each document’s own result rather than trusting the overall success response, since a partial import otherwise looks identical to a complete one, and a filtered delete previews how many documents it will remove before running. Collections can be created, retired, and swapped behind an alias for a zero-downtime reindex, and scoped API keys can be minted, listed, and revoked for narrower access than a full admin key.
Build with Typesense
Three routes to the same 16 actions. The Workflow tab is generated from Typesense's own manifest and carries its real ids, so it is copy-pasteable; the Code and CLI examples are the same call for any action on any app, so every app-specific value in them is a blank you fill in.
List aliases
alias-list The aliases on this node and what they point at — the indirection that makes zero-downtime reindexing work. Flags aliases pointing at a collection that no longer exists, which is a 404 on every search through that name.
Point an alias at a collection
alias-upsert The swap in a zero-downtime reindex: build a versioned collection, import into it, then move the alias. Refuses to point at an EMPTY collection unless told to — searches keep working, return nothing, and look like a search problem.
Create a collection
collection-create Define a collection. Typesense has NO create-or-update — an existing name is a 409 — and an existing field's type cannot be changed, so reshaping means building a new collection and swapping an ALIAS over to it.
Delete a collection
collection-delete Drop a collection and every document in it. No soft delete, no snapshot. An ALIAS naming it survives the deletion and resolves to nothing, so this reports which aliases are about to start returning 404.
Get a collection's schema
collection-get The schema every search and write has to satisfy. Reports which fields are SEARCHABLE, which are facetable, whether the schema has a `.*` catch-all — its absence is why an import breaks when somebody adds a column upstream — and whether ties have a tiebreaker.
List collections
collection-list The collections on this node, with their document counts and field shapes. Typesense holds its index IN MEMORY, so a document count is also roughly the RAM bill — the thing that eventually returns OUT_OF_MEMORY.
Delete documents
document-delete Delete one document by id, or every document matching a FILTER. Typesense offers no dry run, so this one searches with the same filter first and refuses past a threshold — a filter that matches everything empties the collection and reports success.
Get a document
document-get Fetch one document by id — the only EXACT read Typesense offers, with no ranking, no typo tolerance and none of the widening a search does. The right call when the id is already known.
Import documents
document-import Bulk write, and the one to be careful with: Typesense answers 200 with a per-document JSONL result, so a check on the HTTP status reports success when every record failed. This fails on a partial write unless told otherwise.
Search a collection
document-search Search documents. Typesense QUIETLY WIDENS a thin result — dropping query words below 10 hits and allowing more typos below 100 — which is right for a search box and a correctness problem for a workflow that acts on the answer. `strict` turns both off.
Write a document
document-upsert Write one document. SAFER than `document-import`, which answers 200 with per-line failures — here a rejection is an HTTP error. Note `upsert` REPLACES, so a partial document deletes the fields it does not carry; `emplace` merges.
Create an API key
key-create Mint a scoped key. The VALUE IS RETURNED ONCE and never again, so whatever receives it must store it there and then. Defaults to search-only on the named collections — too narrow fails immediately, too wide fails silently.
Revoke an API key
key-delete Revoke a key, immediately and with no grace period — a search key in a deployed front end stops working for every visitor at once, so create and deploy the replacement first. Note the server's bootstrap `--api-key` cannot be revoked here at all.
List API keys
key-list The keys this node accepts and what each may do. Only a PREFIX of each key comes back — the value is shown once at creation and never again. Flags unrestricted keys, which look identical from outside to a search-only one.
Run several searches at once
multi-search Federated search across collections, or the same query with different parameters compared side by side. Note multi_search answers 200 while an individual search inside it FAILED, so this reports per-search errors rather than burying them in the results array.
Get node stats
node-stats Request rates, latencies and — the number that matters — MEMORY headroom, because Typesense serves from RAM and the failure when it runs out is writes stopping while searches carry on. Note stats.json is a live 10-SECOND window, not a counter.
A workflow step names the app and the action, and the editor fills in the
connection when you pick one. This is the Step shape from the
workflow spec, carrying Typesense's real ids.
{
"manifestVersion": "2",
"name": "typesense-example",
"steps": [
{
"id": "alias-upsert",
"uses": {
"app": "io.w6w.typesense",
"action": "alias-upsert",
"connection": "conn_YOUR_CONNECTION_ID"
},
"with": {
"alias": "<alias>",
"collection": "<collection>"
}
}
]
}Here are some of the things you can do
-
Point an alias at a collection
performalias-upsert -
List aliases
readalias-list -
Create a collection
performcollection-create -
Get a collection's schema
readcollection-get -
List collections
searchcollection-list
+11 more actions available
Every app-specific value here is a blank you have to fill in. An
app action is reached through the connection that authenticates it, so the
address is a connection id, not the app id — and connections belong to your account,
so a public page cannot know yours. Create one for Typesense, then fill in
the three blanks: conn_YOUR_CONNECTION_ID, the action key, and the
parameters that action declares. The call itself is real — the shape is transcribed
from the studio's own snippet builder, which prints the same kind of blanks — but
nothing in it is specific to Typesense. The Workflow tab is where this app's
real ids are.
npm install @w6w/sdkyarn add @w6w/sdkpnpm add @w6w/sdkdeno add npm:@w6w/sdkimport { W6wClient, isActionRun } from "@w6w/sdk";
// Reads W6W_BASE_URL and W6W_TOKEN from the environment when omitted.
const client = new W6wClient();
const envelope = await client.run({
urn: "conn_YOUR_CONNECTION_ID",
action: "alias-upsert",
payload: {
alias: "<value>",
collection: "<value>",
// allowEmpty: "<value>",
},
});
if (isActionRun(envelope)) console.log(envelope.value);npm install -g @w6w/cliw6w run conn_YOUR_CONNECTION_ID --action alias-upsert --payload '{"alias":"<value>","collection":"<value>"}'Give an AI agent Typesense — without giving it Typesense's credentials. One MCP endpoint exposes every app, function and workflow the caller is entitled to, as tools it can discover and run. Access is granted per team while we onboard.
One tool call{
"name": "w6w_invoke",
"arguments": {
"ref": "app:io.w6w.typesense#alias-upsert",
"input": {
"alias": "<alias>",
"collection": "<collection>"
}
}
}
Every tool names its target with a single ref. The
app: form above doesn't name a connection at all — the
host resolves which of the caller's Typesense connections to sign
with, and refuses rather than guesses when the answer is ambiguous.
What the agent gets
Credentials it can't read
The token is attached host-side, at the moment of the call. It is never a tool argument, never in the model's context, and never in a transcript — so a prompt injection has nothing to exfiltrate.
A tool surface scoped to the caller
Tools are derived per end user from what that person has actually connected and is entitled to — not one shared bot identity carrying the union of everyone's access.
A durable workflow in one call
Multi-step work runs on the workflow engine and returns a run handle the agent can poll — retries, branching and state survive the conversation that started them.
Health-aware discovery
Typesense's declared health checks are on the surface too, so an agent can tell "the vendor is down" from "your credential expired" before it burns a retry on either.
The MCP surface is part of the hosted platform. Typesense itself is MIT, and the runtime that executes it is source-available (FSL).
Health checks
Typesense declares its own checks, so its health is a property of the app rather than something the host guesses at.
Typesense Cloud status
Typesense Cloud's status feed — INFORMATIONAL, because Typesense is mostly self-hosted and this says nothing about a node in somebody's own cluster. The `node` check reads the connection's own server and is what decides.
Typesense node healthy
Reads this connection's own node through `/health`, which needs NO KEY — so an outage cannot be confused with a revoked credential. Reports Typesense's `resource_error`, which names OUT_OF_DISK and OUT_OF_MEMORY explicitly.
Memory and disk headroom
Typesense serves its index from RAM, so its quota is MEMORY rather than a request rate — and unusually, the real figure is readable. Warns before `/health` reports OUT_OF_MEMORY, because by then writes have already stopped and the index is going stale.