Connect tools
HTTP API reference
The Kept API lets scripts and apps on the Mac that runs Kept ask questions, search passages and list sources. It's read-only, JSON over HTTP, and answers only at 127.0.0.1.
Everything here is also available to AI agents through the MCP server, which uses the same keys and limits.
The API is off by default. Turn it on in Settings → Sharing → Let apps and AI tools on this Mac use Kept.
http://127.0.0.1:47822/v1
GET /v1/status
GET /v1/sources
POST /v1/search
POST /v1/ask
POST /mcp
Authentication
Every request needs an API key in the Authorization header, as a bearer token. Make keys in Settings → Sharing, one per tool or person, so you can revoke one without affecting the others.
- Keys start with
kept_and are 69 characters long. - A key is shown once, when you make it. Kept stores only its SHA-256 hash.
- Revoking a key stops it on the next request.
- Settings shows when each key was last used.
A missing or unknown key returns 401 with a WWW-Authenticate: Bearer header.
curl http://127.0.0.1:47822/v1/status \
-H "Authorization: Bearer kept_3f9a1c…"
const res = await fetch("http://127.0.0.1:47822/v1/status", {
headers: { Authorization: `Bearer ${process.env.KEPT_KEY}` },
});
import os, requests
res = requests.get(
"http://127.0.0.1:47822/v1/status",
headers={"Authorization": f"Bearer {os.environ['KEPT_KEY']}"},
)
Errors
In every response, fields with no value are left out rather than sent as null.
Kept uses ordinary HTTP status codes. Errors have a JSON body with one field, error, a sentence you can show to a person.
| Status | Meaning |
|---|---|
200 | OK. |
400 | Bad input: not JSON, a missing field, an empty or too-long question. |
401 | Missing or unknown API key. |
402 | The trial or subscription has ended. Search and ask stop; status and sources still work. |
403 | The API is turned off, the Host isn't a loopback name, or the request came from a website. |
404 | No such route. |
405 | Wrong method. The Allow header says which one to use. |
413 | The body is larger than 64 KB. |
429 | Rate limit reached for this key. |
500 | Something went wrong inside Kept. |
502 | The AI engine reported a problem. |
503 | Kept's AI isn't set up, its engine isn't running, or its model isn't installed. |
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": "Your free trial has ended. The owner can subscribe at kept.computer; the documents are all still there."
}
Rate limits
Each key can make 120 requests a minute, of which 20 can be questions (POST /v1/ask or the MCP ask tool), since each question runs the local model. Over the limit, Kept returns 429; wait a moment and retry.
Limits count per key, so give each tool its own.
Other limits
- Request bodies: 64 KB.
- Questions and queries: 2,000 characters.
- Search results: 20 passages.
{
"error": "Too many questions in the last minute. Wait a moment and try again."
}
Get status
GET/v1/status
What's running: Kept's version, the team, how many sources it has, the chat model, and whether it can answer questions right now. A cheap way to check that Kept is up and your key works.
Returns
- appstring
- Always
Kept. - versionstring
- Kept's version.
- businessstring
- The team's name from Settings → General. May be empty.
- sourcesinteger
- How many sources Kept has.
- chatModelstring, optional
- The model that writes answers.
- licensestring
- The trial or subscription, in words, for example
Subscribed · renews by Dec 9, 2026. - canAskboolean
- Whether search and ask will work.
falseafter the trial or subscription ends.
curl http://127.0.0.1:47822/v1/status \
-H "Authorization: Bearer $KEPT_KEY"
const res = await fetch("http://127.0.0.1:47822/v1/status", {
headers: { Authorization: `Bearer ${process.env.KEPT_KEY}` },
});
const status = await res.json();
status = requests.get(
"http://127.0.0.1:47822/v1/status",
headers={"Authorization": f"Bearer {KEPT_KEY}"},
).json()
{
"app": "Kept",
"version": "1.0.0",
"business": "Acme Platform",
"sources": 214,
"chatModel": "qwen3.5:9b",
"license": "Subscribed · renews by Dec 9, 2026",
"canAsk": true
}
The source object
A document Kept has read.
- idinteger
- Kept's ID for the source.
- namestring
- The display name, usually the file name.
- typestring
- The file type:
pdf,docx,rtf,txt,md,htmlorimage. - categorystring, optional
- Its category, if it has one.
- statusstring
ready(searchable),noText(nothing readable found) orerror(couldn't be read).- pagesinteger, optional
- Page count, for paged formats.
- addedAtstring
- When it was added, ISO 8601 in UTC.
{
"id": 42,
"name": "payments-runbook.md",
"type": "md",
"category": "Runbooks",
"status": "ready",
"addedAt": "2026-11-05T12:28:29Z"
}
List sources
GET/v1/sources
Every source Kept has. Works after the trial or subscription ends.
Returns
An object with sources, a list of source objects.
curl http://127.0.0.1:47822/v1/sources \
-H "Authorization: Bearer $KEPT_KEY"
const { sources } = await fetch("http://127.0.0.1:47822/v1/sources", {
headers: { Authorization: `Bearer ${process.env.KEPT_KEY}` },
}).then((r) => r.json());
sources = requests.get(
"http://127.0.0.1:47822/v1/sources",
headers={"Authorization": f"Bearer {KEPT_KEY}"},
).json()["sources"]
{
"sources": [
{
"id": 42,
"name": "payments-runbook.md",
"type": "md",
"category": "Runbooks",
"status": "ready",
"addedAt": "2026-11-05T12:28:29Z"
},
…
]
}
The passage object
A short piece of a source, a few paragraphs long, as Kept indexed it.
- sourcestring
- The source's name.
- categorystring, optional
- The source's category.
- pageStart, pageEndinteger, optional
- The pages the passage spans, for paged formats.
- headingstring, optional
- The nearest heading above the passage.
- textstring
- The passage, word for word.
- relevancenumber
- How close it is to the query in meaning, from 0 to 1. Useful for ranking, not as an absolute score.
{
"source": "payments-runbook.md",
"category": "Runbooks",
"heading": "Rolling back",
"text": "To roll back, run deploy rollback payments --to previous, then watch the error-rate dashboard for 10 minutes…",
"relevance": 0.812
}
Search passages
POST/v1/search
Finds the passages most relevant to a query, best first, without writing an answer. Fast, since no answer is written. Use it to give your own code or model the source text.
Body
- querystringrequired
- What to look for. Up to 2,000 characters.
- limitinteger
- How many passages, from 1 to 20. Default 6.
Returns
An object with passages, a list of passage objects. Returns 402 after the trial or subscription ends.
curl http://127.0.0.1:47822/v1/search \
-H "Authorization: Bearer $KEPT_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "payments rollback", "limit": 3}'
const { passages } = await fetch("http://127.0.0.1:47822/v1/search", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KEPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "payments rollback", limit: 3 }),
}).then((r) => r.json());
passages = requests.post(
"http://127.0.0.1:47822/v1/search",
headers={"Authorization": f"Bearer {KEPT_KEY}"},
json={"query": "payments rollback", "limit": 3},
).json()["passages"]
{
"passages": [
{
"source": "payments-runbook.md",
"category": "Runbooks",
"heading": "Rolling back",
"text": "To roll back, run deploy rollback payments --to previous…",
"relevance": 0.812
},
…
]
}
The answer object
An answer from your documents, with its citations.
- kindstring
groundedwhen the answer comes from your documents,notFoundwhen they don't cover the question.- answerstring
- The answer, with
[n]markers that matchcitations. FornotFound, a sentence saying so. - citationsarray
- The passages the answer relies on.
- numberinteger
- Matches an
[n]in the answer. - sourcestring
- The source's name.
- categorystring, optional
- The source's category.
- pageStart, pageEndinteger, optional
- Pages, for paged formats.
- quotestring
- The cited passage, or the part of it that matters.
- noticestring, optional
- A note to show with the answer, when Kept has one.
- pinnedboolean
- Only present, and
true, when this is an answer the owner pinned (approved), served without the model.
{
"kind": "grounded",
"answer": "Roll back with the deploy tool's previous release, then confirm the error rate drops within 10 minutes [1].",
"citations": [
{
"number": 1,
"source": "payments-runbook.md",
"category": "Runbooks",
"quote": "To roll back, run deploy rollback payments --to previous, then watch the error-rate dashboard for 10 minutes."
}
]
}
Ask a question
POST/v1/ask
Answers a question from your documents, the same way the app does. A local model writes the answer, so a request takes 5 to 60 seconds; set your client's timeout to match. Pinned answers come back at once.
Questions asked through the API aren't saved in Kept's history and don't appear on the Gaps page.
Body
- questionstringrequired
- The question, in plain language. Up to 2,000 characters.
Returns
An answer object. Counts toward the 20 questions a minute. Returns 402 after the trial or subscription ends, and 503 if the AI engine isn't running.
curl http://127.0.0.1:47822/v1/ask \
-H "Authorization: Bearer $KEPT_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "How do we roll back a payments deploy?"}'
const answer = await fetch("http://127.0.0.1:47822/v1/ask", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.KEPT_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ question: "How do we roll back a payments deploy?" }),
signal: AbortSignal.timeout(90_000),
}).then((r) => r.json());
answer = requests.post(
"http://127.0.0.1:47822/v1/ask",
headers={"Authorization": f"Bearer {KEPT_KEY}"},
json={"question": "How do we roll back a payments deploy?"},
timeout=90,
).json()
{
"kind": "grounded",
"answer": "Roll back with the deploy tool's previous release, then confirm the error rate drops within 10 minutes [1].",
"citations": [
{
"number": 1,
"source": "payments-runbook.md",
"category": "Runbooks",
"quote": "To roll back, run deploy rollback payments --to previous…"
}
]
}
Security
- This Mac only. Kept listens on
127.0.0.1. Other computers can't reach port 47822. - Not from websites.
Hostmust be127.0.0.1,localhostor[::1], which stops DNS rebinding. AnyOriginmust be a loopbackhttp://origin. Browsers can't sendAuthorizationcross-site without a CORS preflight, which Kept never approves. - Read-only. Nothing in the API can add, change or delete documents or settings.
- Untrusted text. Passages and answers contain your documents' words. If you pass them to an AI with tools, treat them as data, not instructions.
Updated November 9, 2026 · Something wrong or missing? Tell us.