App Search | Captain

App Search is in beta with design partners. Endpoints roll out per tenant.

Captain App Search powers the search box inside an application or website: product search on a store, listing search on a marketplace, article search on a help center, or record search inside a SaaS product.

Captain File Search is a separate product for files and their contents. It uses collections, documents and chunks. App Search uses indexes and records.

Vocabulary

Term	Meaning
Tenant	One customer’s dedicated App Search deployment, with its own endpoint.
Index	A searchable set of records, such as `products`, `stores` or `articles`.
Record	One product, article, listing or other entity in an index.
Query, filter, facet	The usual search terms: the text searched, the conditions every result must meet, and the counts per field value.

How a request finds its data

Each customer gets a dedicated deployment and a dedicated hostname, for example https://acme.captain.dev.

The hostname selects the tenant.
The path selects the index: /v1/indexes/products/search.
The key grants access to that tenant’s indexes and operations.

Requests carry no tenant id, and there is no /tenants/... path. Two tenants may each have an index called products. A key issued for one tenant does not work against another tenant’s endpoint.

What Captain manages

Captain creates each tenant and its keys, and tunes ranking and index settings with the customer. The customer’s application creates indexes, keeps their records up to date, searches, and sends click and conversion events. Keys lists which key calls which operation.

Endpoint

Onboarding provides two things: the tenant endpoint, for example https://acme.captain.dev, and the keys for this tenant. The Quickstart creates a first index from there.

Every App Search route sits under that endpoint:

https://acme.captain.dev/v1/indexes/products/search
https://acme.captain.dev/v1/indexes/articles/search

Keys

Key	Use it for	Where it lives
Search key	Searching, reading records, sending events and reading analytics.	Safe in a browser or mobile app.
Scoped key	Searching on behalf of one end user, when an index has per-record access control. Minted from an issuer key and short lived.	Safe in a browser, once minted.
Write key	Creating, listing, copying and deleting indexes and aliases, changing settings, synonyms and rules, adding, updating and deleting records, importing, and reading and cancelling jobs. It cannot search.	Server side only.

Captain issues a search key, a write key and an issuer key at onboarding, each for every index, and keeps the admin key. Access-control and audit settings go through Captain. Index settings lists what you set and what Captain sets.

Which key calls which operation

Operation	Search key	Scoped key	Write key
Search, typeahead, browse, similar, multiple searches	Yes	Yes	No
Get records	Yes	Yes	No
List filters	Yes	Yes	No
Send events	Yes	Yes	No
Read analytics	Yes	No	No
Create an index	No	No	Yes
List indexes	No	No	Yes
Add, replace, update and delete records	No	No	Yes
Delete records by filter, empty an index	No	No	Yes
Get an index’s status and update status	No	No	Yes
Import from Algolia	No	No	Yes
List jobs, get a job, cancel a queued job	No	No	Yes
Change settings, synonyms and rules	No	No	Yes, except `acl`, `tenant_field` and `audit`
Copy an index, set and delete aliases	No	No	Yes
Create, list and revoke keys	No	No	Yes, with a write key for every index
Read usage	No	No	Yes
Delete an index	No	No	Yes. Keys limited to that index alone are revoked. See Delete an index.

A tenant’s keys work on every index in that tenant, including indexes created later. A key can also be limited to some indexes. A request for any other index returns 403, the same answer as for an index that does not exist.

Manage your keys

The write key you got at onboarding covers every index, and it manages keys too. Create Key mints a search, scoped, write or issuer key, for every index (["*"]) or for the indexes you name. The new key’s secret is in that reply only. Captain stores a hash and can’t show it again.

curl -X POST "https://acme.captain.dev/v1/keys" \
  -H "Authorization: Bearer $CAPTAIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "search", "indexes": ["products-staging"], "description": "staging storefront"}'

Example: (201 Created)

{
  "id": "key_8a1f3c0d9e2b4f67",
  "type": "search",
  "indexes": ["products-staging"],
  "prefix": "cap_k3Jd9x",
  "description": "staging storefront",
  "created_by": "key_2c7e90a1b4d35f18",
  "created_at": 1759433001,
  "key": "cap_k3Jd9x...",
  "note": "store this key now: it is shown once and kept only as a hash"
}

A key can also carry expires_at (unix seconds) and allowed_origins. List Keys (GET /v1/keys) returns every key without its secret, and marks the key making the call with current: true. Revoke Key (DELETE /v1/keys/{key_id}) stops a key at once.

Revoking a key also revokes every key it created, and every key those created. The reply’s revoked lists every id it revoked. To revoke only the one key, send ?cascade=none.

A key can’t revoke itself, so you can’t lock yourself out. To replace a leaked write key:

Get a new write key for every index that the old key didn’t create: ask Captain support for one, or mint it with another write key you trust. A key the old key minted would be revoked with it, so revoking the old key with such a key answers 409 CASCADE_INCLUDES_CALLER and revokes nothing.
With the new key, mint replacements for every key the old key minted that your apps still use, and deploy them. Revoking the old key in the next step revokes those keys too, so an app still on one of them stops working.
Revoke the old key with the new one. That also revokes every key the old key minted, including any an attacker minted with it. To revoke only the old key and keep the keys it minted, send ?cascade=none, but then any key an attacker minted keeps working until it’s revoked on its own.

Only a write key for every index manages keys. A write key limited to some indexes gets 403.

List Keys also shows keys Captain issued on your tenant, such as a short-lived key support uses to look at your index with you. Those carry issued_by_captain: true, and revoking one with your key answers 403 KEY_ISSUED_BY_CAPTAIN. Ask support to revoke it.

Sending the key

Every endpoint takes its key the same way, as a bearer token in the Authorization header. Each endpoint’s reference page names the kind of key it needs.

curl

Python

TypeScript

curl -X POST "https://acme.captain.dev/v1/indexes/products/search" \
  -H "Authorization: Bearer $CAPTAIN_SEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "waterproof hiking boots",
  "k": 3
}'

A missing or unknown key returns 401. A key without access to the index or operation returns 403, and so does an index the key cannot see, whether or not that index exists.

Calling from a browser

A search key, and a scoped key once minted, can be used straight from a web page. Captain answers the browser’s preflight for any origin, without a key. A page may send these request headers:

Authorization (or X-Captain-Key)
Content-Type
X-Captain-Min-Seq

Answers to a search or scoped key allow the page’s origin and let page code read X-Captain-Seq, X-Captain-Applied-Seq and X-Request-Id.

A key can be limited to your own sites. Captain sets that list when it issues the key, and a request from any other origin then gets 403 ORIGIN_NOT_ALLOWED. The origin check stops other websites from using your key in their visitors’ browsers. It doesn’t stop a server that sends a fake origin. Limit what a leaked key can reach with its scope, and revoke it if it leaks.

Write keys stay on your server. Their answers carry no CORS headers, so a page can’t read them.

Errors

Every error reply has the same shape: a machine code in error and a readable message. That includes a path no endpoint answers (404 ROUTE_NOT_FOUND) and a method an endpoint doesn’t take (405 METHOD_NOT_ALLOWED).

{"error": "FILTER_INVALID", "message": "filter: unknown field colour", "position": 0, "expected": ["brand", "color", "price"]}

Status	Common codes	Meaning
400	`VALIDATION_ERROR`, `FILTER_INVALID`, `FACET_UNKNOWN`, `PAGE_TOO_DEEP`, `ID_CONFLICT`	The request is malformed or names something the index lacks. `ID_CONFLICT`: an Algolia object’s own id field differs from its `objectID`.
401	`UNAUTHORIZED`	The key is missing or unknown.
403	`FORBIDDEN`, `ACCESS_DENIED`, `KEY_ISSUED_BY_CAPTAIN`	The key may not use this index or operation. `KEY_ISSUED_BY_CAPTAIN`: the key to revoke was issued by Captain’s support or console, and only Captain revokes it.
404	`INDEX_NOT_FOUND`, `RECORD_NOT_FOUND`, `JOB_NOT_FOUND`, `ALIAS_NOT_FOUND`, `ROUTE_NOT_FOUND`	The index, record, job or alias does not exist, or no endpoint has that path. A `RECORD_NOT_FOUND` reply also carries `legacy_error: "DOCUMENT_NOT_FOUND"`, its former name.
405	`METHOD_NOT_ALLOWED`	The endpoint exists but doesn’t take this method.
409	`INDEX_EXISTS`, `JOB_RUNNING`, `INDEX_NOT_READY`, `IDEMPOTENCY_KEY_REUSED`, `JOB_NOT_CANCELLABLE`, `INDEX_HAS_ALIAS`, `ALIAS_NOT_INDEX`, `CASCADE_INCLUDES_CALLER`	An index or alias with that name already exists, an import is already running, the index has no records yet, an idempotency key was reused with a different body, the job has already started, an alias still points at the index, the name is an alias, not an index, or revoking the key would also revoke the key making the call.
413	`PAYLOAD_TOO_LARGE`	The request body is too large.
429	`RATE_LIMITED`	A request with no valid key, from an address sending many of them. Retry after the time in `Retry-After`. Requests with a valid key aren’t rate limited: use is fair use.
503	`UNAVAILABLE`	The service is briefly unavailable. Retry with backoff.

A request whose connection closes before any answer arrives never reached Captain. Connections and retries shows when to send it again.

Limits

Limit	Value
Records per add request	1,000 as a JSON array, 100,000 as NDJSON or CSV
Records per update or delete request	1,000
Records per get request	100
Events per request	1,000
Searches per multi-search request	10

Machine-readable guides

Each tenant publishes its own reference:

https://acme.captain.dev/v1/openapi.json
https://acme.captain.dev/llms.txt

openapi.json lists the endpoints in this reference, as deployed on that tenant. llms.txt is a short plain-text guide for coding assistants.

Request ids

Every reply carries an X-Request-Id header. Quote it when you contact Captain about a request. A request that sends its own X-Request-Id (8 to 128 letters, digits, ., _ or -) gets the same id back.