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.

StatusMeaning
200OK.
400Bad input: not JSON, a missing field, an empty or too-long question.
401Missing or unknown API key.
402The trial or subscription has ended. Search and ask stop; status and sources still work.
403The API is turned off, the Host isn't a loopback name, or the request came from a website.
404No such route.
405Wrong method. The Allow header says which one to use.
413The body is larger than 64 KB.
429Rate limit reached for this key.
500Something went wrong inside Kept.
502The AI engine reported a problem.
503Kept'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. false after 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, html or image.
categorystring, optional
Its category, if it has one.
statusstring
ready (searchable), noText (nothing readable found) or error (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
}

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
grounded when the answer comes from your documents, notFound when they don't cover the question.
answerstring
The answer, with [n] markers that match citations. For notFound, 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. Host must be 127.0.0.1, localhost or [::1], which stops DNS rebinding. Any Origin must be a loopback http:// origin. Browsers can't send Authorization cross-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.