Bring your own agent

1Getting a key

API keys are created in the iPhone app under Settings → Account → Developer API. You can hold up to ten active keys, each with a name and a scope:

• Read & write (default) — everything the Concierge can do.
• Read-only — listing and lookups only. Any call that would change data is refused with 403.

The full key is displayed exactly once. We store only a hash, so if you lose it, revoke it and create another.

2Endpoints

Base URL: https://kinrows.com. Every request needs Authorization: Bearer <your key>.

3The tool catalog

Tools are grouped by area of the app, and each takes an action:

Don't memorise this — fetch /v1/tools and hand the result to your model as its tools. Every parameter and its description is in the schema, and the catalog is generated from the same source our own Concierge runs on, so it never drifts.

4Connect via MCP

If your agent host speaks MCP (Claude Desktop, Claude Code, Cursor, ChatGPT connectors and many others), this is the one-line setup:

{
  "mcpServers": {
    "kinrows": {
      "url": "https://kinrows.com/v1/mcp",
      "headers": { "Authorization": "Bearer kr_live_…" }
    }
  }
}

The server is stateless — no session IDs to manage — and your model will see every Kinrows tool immediately.

5Connect via REST

Any language, any model. Sanity-check the key:

curl https://kinrows.com/v1/me \
  -H "Authorization: Bearer $KINROWS_KEY"

Add a task and log an expense:

curl https://kinrows.com/v1/tools/tasks \
  -H "Authorization: Bearer $KINROWS_KEY" -H "Content-Type: application/json" \
  -d '{"action":"add","title":"Book dentist","due_date":"2026-09-02"}'

curl https://kinrows.com/v1/tools/budget \
  -H "Authorization: Bearer $KINROWS_KEY" -H "Content-Type: application/json" \
  -d '{"action":"log_expense","amount":42.10,"merchant":"Costco","category":"Groceries"}'

A minimal agent loop with the Anthropic SDK — fetch the catalog, let the model pick tools, execute them against /v1/tools, repeat:

const BASE = 'https://kinrows.com';
const H = { Authorization: `Bearer ${process.env.KINROWS_KEY}`, 'Content-Type': 'application/json' };
const { tools } = await (await fetch(`${BASE}/v1/tools`, { headers: H })).json();

let messages = [{ role: 'user', content: 'Move the dentist task to Friday and add milk to Groceries.' }];
for (;;) {
  const r = await anthropic.messages.create({ model: 'claude-sonnet-5', max_tokens: 1024, tools, messages });
  messages.push({ role: 'assistant', content: r.content });
  if (r.stop_reason !== 'tool_use') break;
  const results = [];
  for (const b of r.content.filter(c => c.type === 'tool_use')) {
    const out = await (await fetch(`${BASE}/v1/tools/${b.name}`, { method: 'POST', headers: H, body: JSON.stringify(b.input) })).json();
    results.push({ type: 'tool_result', tool_use_id: b.id, content: JSON.stringify(out) });
  }
  messages.push({ role: 'user', content: results });
}

6Limits & errors

• 120 requests per minute per key. Over that you get 429.
• 10 active keys per user.
• 401 — missing, malformed, or revoked key. 402 — the household's Concierge subscription is not active. 403 — a read-only key tried to write. 400 — bad action or missing fields (the message tells you which).
• Tool-level problems ("no list named Costco") come back as 400 {"error": "…"} so your model can recover and try again.

7Security & privacy

• A key is bound to one person and one household. It cannot see or touch any other household — the same database-level isolation that protects every Kinrows family applies to every API call.
• Keys are 256-bit random values, stored only as a hash. Revoke from the app at any time; it takes effect immediately.
• A key can never log in, change your password or email, or delete your account. Those stay behind sign-in and two-factor in the app.
• Whatever your agent does with your data happens on your model and your provider under your terms. Kinrows still never sells data or uses it to train AI.
• Treat the key like a password. Anyone holding it can act as you inside your household.

Questions or ideas for the API? kinrows@atlasatlantic.co.