API keys
A Locus API key lets the Locus engine on your computer, and an AI app you connect, use Locus's hosted services with your account. Local mode needs no key and no account: with the local embedder, indexing and search run on your computer (see Connect). You need a key only for the hosted features below.
What a key unlocks
Every request sends the key as Authorization: Bearer. Keys have no scopes yet: any active key of yours works on all four endpoints, so treat each one like a password.
| Endpoint | What it is | Used by | Uses your allowance |
|---|---|---|---|
| GET /api/support/account-status | Account status | The locus_account_status tool, and the key check below. Answers even when your trial has ended or your plan is inactive. | No |
| POST /api/embed-relay | Managed embeddings | The engine with LOCUS_EMBEDDER=managed, for indexing and for each search query. | Yes |
| POST /api/mcp/relay | Remote connection: the connector URL (in testing) | A web AI app's custom connector. It forwards tool calls to your computer. | No |
| POST /api/relay/token | Remote connection: relay token (in testing) | The engine running locus serve --transport relay. You don't call it by hand. | No |
All four live under https://locusfiles.com.
Create a key
- Sign in. New accounts are closed until paid plans open; join the waitlist to hear when they do. An existing account signs in as usual.
- Open your dashboard and choose Create key under Your API keys.
- Copy the key right away. It starts with
locus_live_and is shown only once: Locus stores a hash of it, never the key itself, so nobody can show it to you again. If you lose it, revoke it and create a new one. - Use one key per computer. Your plan sets how many keys can be active at once (limits).
To use the key in a terminal without leaving it in your shell history, paste it into a variable instead of typing it into a command. Every example on this page reads the key from $LOCUS_API_KEY:
read -rs LOCUS_API_KEY # paste the key, press Enter (nothing is shown)
export LOCUS_API_KEYCheck your key
This call proves the key works. It reads your account status, uses none of your allowance and sends no file content:
curl -sS https://locusfiles.com/api/support/account-status \
-H "Authorization: Bearer $LOCUS_API_KEY"A working key returns HTTP 200 with a JSON object with these fields. A 401 means the key is wrong, incomplete or revoked.
| Field | Meaning |
|---|---|
| tier | Your plan: starter, personal or power. Older accounts may show pro or founding, which have Power's limits. |
| status | trialing, active, or another state such as canceled. |
| trial_end | For a trial: no_end_yet, ends, ended or unavailable. |
| trial_ends_at | When the trial ends, if it has an end date. |
| daily_quota | Texts your plan may embed per UTC day through managed embeddings. |
| used_today | Texts embedded so far today (null if it could not be read). |
| api_key_count | Your active (not revoked) keys. |
| canonical_url | The site's address. |
The locus_account_status tool in your AI assistant shows the same information once LOCUS_API_KEY is set for the engine.
Managed embeddings
With managed embeddings your engine sends chunk text to Locus's relay instead of needing a Voyage AI key of its own. On managed plans, chunk text and your search queries pass through Locus's relay to Voyage AI to be embedded. We don't store them; we keep only usage counts. Set these where the engine runs (a .env file in the folder you run locus from, or exported in your shell), then index:
LOCUS_EMBEDDER=managed
LOCUS_API_KEY=<the key you copied>locus doctor # confirms LOCUS_API_KEY is set for LOCUS_EMBEDDER=managed
locus index ~/Documents/notes --pruneLocus keeps one embedding model per index. If you already indexed with another embedder, locus refuses to mix the two: add a new LOCUS_COLLECTION name (for example LOCUS_COLLECTION=managed) and index again. You can also call the relay directly. This example embeds one search query:
curl -sS https://locusfiles.com/api/embed-relay \
-H "Authorization: Bearer $LOCUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"texts": ["what did I decide about pricing"], "purpose": "query", "input_type": "query"}'{
"model": "voyage-4",
"embeddings": [[0.0132, -0.0478, 0.0251, …]]
}texts: 1 to 128 strings, each at most 6,000 characters.purpose:"document"(the default, for indexing) or"query"(exactly one text of at most 2,000 characters).input_type(optional):"document"or"query", passed on to Voyage AI.model(optional): onlyvoyage-4.
Each call counts against your plan's managed-embedding daily limit. Your dashboard shows today's usage.
Remote connection (in testing)
Remote connection lets a web AI app reach the Locus engine on your computer through Locus's relay. Your engine runs locus serve --transport relay with your key and exchanges it for a short-lived relay token (/api/relay/token, lasting up to ten minutes and renewed automatically). The AI app's connector calls https://locusfiles.com/api/mcp/relay with your key. Which apps have setup steps, and the steps themselves, are on Connect. Only one computer per account serves remote requests at a time; starting Locus relay on another computer takes over. The computer must be on, awake and running Locus. Remote connection needs an active subscription or trial. Through the relay, your AI app can read a whole file piece by piece (up to 40,000 characters per read), list the paths of your indexed files, and, when it asks, see your account status (plan, trial end, usage, number of API keys) and setup details (operating system, Python and Locus versions, embedder, number of indexed chunks).
The /api/relay/token answer also carries realtime_public_key: Locus's public key for the relay connection. It is not a secret (it is the same public value this website sends to every browser) and it is present only when it is configured. Locus 0.1.3 and later take it from this answer, so a fresh install needs no setting; older versions need it in LOCUS_MCP_RELAY_SUPABASE_ANON_KEY, shown on Connect. When that variable is set it is used instead of the answer's value.
Some web AI apps connect by signing in (OAuth) instead of with a pasted key. Where Locus supports that, you approve the app on a Locus consent screen and it sends its own sign-in token, not your key. To cut such an app off, choose Disconnect for it under Connected assistants (/oauth/consent/grants); revoking API keys does not disconnect it.
You can check the connector endpoint and your key without your computer being online. The initialize handshake is answered by the relay itself:
curl -sS https://locusfiles.com/api/mcp/relay \
-H "Authorization: Bearer $LOCUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}'{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-06-18",
"capabilities": { "tools": {} },
"serverInfo": { "name": "locus_mcp", "version": "0.1.0" },
"instructions": "Locus searches the user's own files on their computer: documents, notes, PDFs, …"
}
}tools/list and tools/call are forwarded to your computer and need it on, awake and running locus serve --transport relay; otherwise the relay answers that your computer did not respond, after up to 25 seconds.
Keys and limits per plan
| Plan | Active keys (computers) |
|---|---|
| Starter | 1 |
| Personal | 3 |
| Power | 10 |
A new free trial has Starter's limit. Paid plans are not open yet. Revoked keys don't count. When you are at your limit, revoke a key before creating another.
- Managed embeddings: 128 texts per request and a daily allowance that depends on your plan. Your dashboard and the
daily_quota/used_todayfields of the account-status check show yours. - Remote connection: 60 requests per minute and 5,000 per day per account, request bodies up to 65,536 bytes.
- Account status: no allowance used.
These limits can change; when you hit one, the error says which one and, where waiting helps, how long to wait.
Errors
/api/embed-relay and /api/relay/token answer errors as {"error": "...", "code": "...", "reason": "...", "retry_after": 30}. error is safe to show as-is, code is the stable value to act on, and retry_after (seconds, also sent as the Retry-After header) is present on every 429 and 503.
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 401 | auth_failed | The Authorization header is missing or malformed, or the key is unknown or revoked. | Send Authorization: Bearer with the full key. If it was revoked, create a new one. |
| 400 | input_rejected | The request itself is wrong: texts, batch size, text length, model, purpose or input_type. | Fix the request. Sending the same body again gives the same answer. |
| 402 | subscription_inactive | The account has no active plan or trial, or the trial has ended. | Check your plan on the dashboard. |
| 402 or 429 | budget_exhausted | An allowance is used up. 429: a daily one, which resets at 00:00 UTC. 402: the trial's total, which does not reset. | On 429, wait retry_after seconds. Search queries (purpose "query") fall back to a separate daily allowance. |
| 429 or 503 | rate_limited | Too many requests, from your account or across the service. | Wait retry_after seconds, then retry. |
| 503 | paused | An operator has paused this feature for a while. | Retry after retry_after seconds. Search queries are not paused with indexing. |
| 502 | provider_unavailable | The embedding provider failed or could not be reached. | Retry later. |
| 426 | client_outdated | Only while Locus requires a minimum engine version: the X-Locus-Version header is missing or older than that minimum. | Update Locus (uv tool upgrade locusfiles, or pipx upgrade locusfiles) and restart it. A direct call must send an X-Locus-Version header at or above the minimum. |
| 500 | internal_error | Something failed on our side. | Retry later. If it persists, send us the x-request-id header value. |
/api/mcp/relay speaks JSON-RPC 2.0, so its errors arrive as {"jsonrpc": "2.0", "id": 1, "error": {"code": -32029, "message": "..."}}:
| HTTP | JSON-RPC code | Meaning | What to do |
|---|---|---|---|
| 401 | (none) | Plain {"error": ...}: missing, invalid or revoked key. | Check the key the connector sends; create a new one if it was revoked. |
| 401 | (none) | Plain {"error": "Invalid or expired OAuth token"}: an app that signed in with OAuth sent a sign-in token that has expired or was disconnected. Where OAuth sign-in is on, every 401 also carries a WWW-Authenticate header that points the app to Locus sign-in. | Reconnect the app so it signs in again. |
| 400 | -32700 | The body is not JSON. | Send a JSON-RPC 2.0 request. |
| 400 or 413 | -32600 | Not a valid JSON-RPC request, or a body over 65,536 bytes. | Fix the request. |
| 402 | -32002 | The account has no active plan or trial, or the trial has ended. | Check your plan on the dashboard. |
| 429 | -32029 | The per-minute or per-day request limit is reached. | Wait for the Retry-After header's seconds. |
| 503 | -32053 | Remote connection is paused, or the rate limiter is unavailable. | Wait for the Retry-After header's seconds. |
| 200 | -32000 | The relay got no usable answer from your computer. error.data.reason is computer_offline, engine_outdated, relay_unavailable or engine_error. | computer_offline: start locus serve --transport relay on a computer that is on and awake. engine_outdated: update Locus. On tools/call these two come back as a tool result with isError: true instead. |
| 200 | -32601 | Unknown method. | Use initialize, tools/list or tools/call. |
| 200 | -32602 | tools/call without a tool name. | Send params.name. |
| 500 | -32603 | Something failed on our side. | Retry later; send us the x-request-id. |
/api/support/account-status answers 401 for a missing or revoked key, 404 if the account has no plan record, and 500 for a failure on our side, each as {"error": "..."}.
Responses from the embedding relay, the relay token and the connector carry an x-request-id header. Include it when you contact support; it lets us find your request in our logs, which hold no file content.
Rotate and revoke
- Create the new key on the dashboard. If you are at your plan's limit, revoke the old key first; on a one-key plan that means a short gap until step 2 is done.
- Put the new key in
LOCUS_API_KEYwherever the engine runs, and in the connector settings of each AI app you connected with the old key (an app that signed in with OAuth holds no key and needs no change). Restartlocus serve. - Run the check with the new key.
- Revoke the old key on the dashboard.
A revoked key is refused on its next request: every endpoint looks the key up each time, with no caching. A relay token already made from it stays valid for up to ten minutes, so after revoking a key you think leaked, check your key list again ten minutes later and revoke any key you did not create. There is no way to show an existing key again; a lost key is revoked and replaced.
Anyone who holds your Locus API key can search and read your indexed files through the relay while your computer is serving, take over as your relay computer, spend your managed-embedding budget, and act as your account for up to ten minutes with each relay token they get from it. Keep it secret. If it leaks, revoke it from the dashboard, then check your key list again after ten minutes and revoke any key you did not create.
If you join an organization, its members can see your email, your role, when you joined, whether you are still a member, when you last used Locus's hosted features and which Locus version you ran. Its admins can also see its invites and audit log, and can revoke your Locus API keys. Nobody in the organization can see your files or searches, because Locus doesn't store them.
What passes through Locus
- Managed embeddings: On managed plans, chunk text and your search queries pass through Locus's relay to Voyage AI to be embedded. We don't store them; we keep only usage counts.
- Remote connection: When you reach your computer from another device or a web AI app, your question and the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your computer. They are encrypted in transit and we don't store them. Through the relay, your AI app can read a whole file piece by piece (up to 40,000 characters per read), list the paths of your indexed files, and, when it asks, see your account status (plan, trial end, usage, number of API keys) and setup details (operating system, Python and Locus versions, embedder, number of indexed chunks).
- Account status: returns your plan, trial end, daily allowance, today's usage and number of active keys to whoever calls it with your key. It carries no file content.
- Your key: stored as a hash. Your account details are stored with Supabase. Your files are not.
Your raw files are never uploaded to Locus. The full breakdown by mode is on Privacy, and what protects keys today is on Security.