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 supports MCP OAuth, give it just the URL. Kinrows will open a secure browser consent screen:

{
  "mcpServers": {
    "kinrows": { "url": "https://kinrows.com/v1/mcp" }
  }
}

For hosts that need a manual bearer header, create a key in Settings and use:

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

OAuth clients can request kinrows:read or kinrows:read kinrows:write. Kinrows uses authorization code flow with S256 PKCE, short-lived access tokens, rotating refresh tokens, and standard protected-resource discovery. Manual keys use the read-only or read/write scope selected when the key is created.

What the MCP server exposes

The server supports the current MCP protocol and older stateless clients. Household resources are private and should not be cached across users. Every call rechecks the credential, household boundary, scope, and active Concierge entitlement; the private activity audit stores operation metadata and outcomes, never household inputs or results.

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"}'

# Kids' chores: set up, tick, read the week, pay
curl https://kinrows.com/v1/tools/routines \
  -H "Authorization: Bearer $KINROWS_KEY" -H "Content-Type: application/json" \
  -d '{"action":"setup_chores","child":"Jude","chores":[{"title":"Feed the dog","slots":["morning","evening"]}],"weekly_allowance":2,"bonuses":[{"title":"Good bedtime","amount":1}]}'

curl https://kinrows.com/v1/tools/routines \
  -H "Authorization: Bearer $KINROWS_KEY" -H "Content-Type: application/json" \
  -d '{"action":"log_chore","child":"Jude","chore_id":"feed the dog","slot":"evening"}'

curl https://kinrows.com/v1/tools/routines \
  -H "Authorization: Bearer $KINROWS_KEY" -H "Content-Type: application/json" \
  -d '{"action":"chores","child":"Jude"}'   # week grid, streak, earnings, owed, age guidance

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.
• OAuth clients use authorization code + S256 PKCE. Access and rotating refresh tokens are opaque, hashed at rest, and revocable.
• The agent audit records which tool/action ran and its outcome, never a copy of the household input or result.
• 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.