# Uskeep REST API for agents

Uskeep is a shared household workspace for projects, errands, recipes, weekly meal plans,
shopping lists and Activity. People use the app; their AI agents use the same data through
MCP or this REST API. This guide is public; no sign-in is required to read it.

There are three ways for an agent to reach a household:

- **MCP** at `https://uskeep.app/mcp` (Streamable HTTP, OAuth sign-in). Prefer it when the
  client speaks MCP. Setup: https://uskeep.app/docs/mcp
- **REST API** at `https://uskeep.app/v1` with a bearer credential: an OAuth access token
  from the user's Uskeep sign-in, or a manual API key. This guide.
- **The app's own API** at `https://uskeep.app/api`, for an agent that operates inside the
  user's signed-in browser. Same routes and JSON as `/v1`, authenticated by the browser
  session. See "Inside the user's browser session" below.

Human guide: https://uskeep.app/docs/api

## Base URL and discovery

- Base URL: **https://uskeep.app/v1**. Every path below is relative to it.
- `GET https://uskeep.app/v1` (public, no credential): a JSON index with the documentation,
  OpenAPI and authentication links.
- OpenAPI 3.1 description: https://uskeep.app/docs/openapi.json (also redirected from
  `/openapi.json`). It lists every operation with its scopes (`security` and `x-scopes`),
  request schemas and response schemas.
- API catalog (RFC 9727): https://uskeep.app/.well-known/api-catalog
- Agent index: https://uskeep.app/llms.txt
- This guide in Markdown: https://uskeep.app/docs/api.md. `GET /docs/api` with
  `Accept: text/markdown` returns the same Markdown.

## Authentication

Every `/v1` request except `GET /v1` needs `Authorization: Bearer <credential>`. Choose one
of the three options below. Never ask the user for a Google or Apple token, a browser
cookie or a password, and never copy cookies out of a browser.

### Option 1: sign in with the user's Uskeep account (OAuth, preferred)

Use this when the agent can open a browser page for the user. The user signs in to Uskeep,
checks the household and return address, chooses permissions and selects
**Allow connection**. The agent gets a short-lived access token and a refresh token.

Protocol summary:

- Protected-resource metadata: https://uskeep.app/.well-known/oauth-protected-resource/v1
  (an unauthenticated `/v1` request also returns it in
  `WWW-Authenticate: Bearer resource_metadata="…"`).
- Authorization-server metadata: https://uskeep.app/.well-known/oauth-authorization-server
- Dynamic client registration: `POST https://uskeep.app/oauth/register` with JSON
  `redirect_uris` (required), optional `client_name` and `token_endpoint_auth_method`
  (`none` (default), `client_secret_post` or `client_secret_basic`). Redirect URIs use HTTPS
  or loopback HTTP (`localhost`, `127.0.0.1`, `[::1]`), without fragments or wildcards, and
  must later match exactly, including the port.
- Authorization code flow with **S256 PKCE** at `https://uskeep.app/oauth/authorize`.
  Authorization and token requests must include **`resource=https://uskeep.app/v1`**.
- Token, refresh and revocation requests are form-encoded
  (`application/x-www-form-urlencoded`) at `https://uskeep.app/oauth/token` and
  `https://uskeep.app/oauth/revoke`.
- Access tokens (`uk_at_…`) last at most one hour. Refresh tokens (`uk_rt_…`) rotate on each
  use; reusing a spent refresh token disconnects the connection. The connection expires
  after 30 days, even with refresh; then the user connects again.
- Tokens are bound to the resource they were issued for: a `/v1` token does not work at
  `/mcp` or `/api`, and an MCP token does not work at `/v1`.
- If `scope` is omitted, Uskeep requests all six permissions; the user can narrow them on
  the consent page. A requested write scope needs the matching read scope.

Worked example (replace the placeholder values; the redirect URI is a local callback that
the agent listens on):

```sh
# 1. Register a client (once). Keep the client_id from the 201 response.
curl -X POST https://uskeep.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Example household agent","redirect_uris":["http://127.0.0.1:8765/callback"],"token_endpoint_auth_method":"none"}'
# → {"client_id":"CLIENT_ID","client_name":"Example household agent","redirect_uris":[…],…}

# 2. Create a PKCE verifier and challenge, and a random state.
CODE_VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)
```

3. Open this URL in the user's browser (one line; values URL-encoded):

```text
https://uskeep.app/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&resource=https%3A%2F%2Fuskeep.app%2Fv1&scope=errands%3Aread%20errands%3Awrite%20meals%3Aread%20meals%3Awrite&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&state=STATE
```

The user signs in if needed, chooses permissions and selects **Allow connection**. The
browser then goes to
`http://127.0.0.1:8765/callback?code=CODE&state=STATE&iss=https%3A%2F%2Fuskeep.app`.
Check that `state` matches. If the user cancels, the callback has `error=access_denied`.
The code expires after five minutes and works once.

```sh
# 4. Exchange the code for tokens.
curl -X POST https://uskeep.app/oauth/token \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode code="CODE" \
  --data-urlencode redirect_uri=http://127.0.0.1:8765/callback \
  --data-urlencode code_verifier="$CODE_VERIFIER" \
  --data-urlencode client_id="CLIENT_ID" \
  --data-urlencode resource=https://uskeep.app/v1
# → {"access_token":"uk_at_…","token_type":"Bearer","expires_in":3600,"refresh_token":"uk_rt_…","scope":"errands:read errands:write meals:read meals:write"}

# 5. First call.
export UK_TOKEN=uk_at_…
curl -H "Authorization: Bearer $UK_TOKEN" https://uskeep.app/v1/me

# Later: refresh before or after the access token expires. Store the new refresh token.
curl -X POST https://uskeep.app/oauth/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode refresh_token="uk_rt_…" \
  --data-urlencode client_id="CLIENT_ID" \
  --data-urlencode resource=https://uskeep.app/v1

# To disconnect from the agent side:
curl -X POST https://uskeep.app/oauth/revoke \
  --data-urlencode token="uk_rt_…" --data-urlencode client_id="CLIENT_ID"
```

Confidential clients (`client_secret_post` or `client_secret_basic`) receive a
`client_secret` at registration and send it on token and revocation requests. The user can
also disconnect the agent in Settings → AI Agents at https://uskeep.app/settings/agents.

### Option 2: manual API key

Use this for scripts and clients that need a fixed token. The person creates the key in
**Settings → AI Agents → Create an agent key** at https://uskeep.app/settings/agents,
chooses permissions and an expiry, and copies the secret once (it is not shown again).

- Send `Authorization: Bearer uk_live_…`.
- Keys expire after 1–90 days (30 by default).
- New keys default to all six permissions; the person can reduce them before creating the
  key. Existing keys keep their permissions; create a replacement key to change access.
- The same key works at `/v1` and at `/mcp`.

Keep the key in the client's secret storage. Do not paste it into chat transcripts or logs.

### Option 3: inside the user's browser session

If the agent controls the user's own signed-in browser (for example a browser-automation
agent working in a tab where the user has opened https://uskeep.app), it can call the app's
API directly. No key or OAuth connection is needed.

- Use the same paths under `https://uskeep.app/api` instead of `/v1`, for example
  `/api/errands` or `/api/meals/weeks/this`. Bodies, responses and errors are the same.
- Send the requests from a page on `https://uskeep.app`, for example with
  `fetch("/api/errands", { credentials: "same-origin" })`. `/api` has no CORS, so other
  sites cannot read its responses.
- On writes with a body, send `Content-Type: application/json`. The browser adds the
  `Origin` and `Sec-Fetch-Site` headers that the CSRF check needs; bodyless writes such as
  `POST /api/errands/{id}/complete` also pass from the app's own origin.
- The session acts as the person: changes are attributed to the person as if they made them
  in the app (not to an agent), and the scopes below do not apply.
- `/api` also has routes that are intentionally not on `/v1`: household name and members
  (`/api/household…`), invitations (`/api/household/invites…`), agent keys (`/api/me/keys`),
  browser sessions (`/api/me/sessions`), notification preferences (`PATCH /api/me/prefs`),
  marking notifications read, dismissing Activity and the profile photo (`/api/me/avatar`).
  Use them only when the person explicitly asks. Some (creating keys, removing a member)
  require a recent sign-in.
- Never copy the session cookie out of the browser or use it from another program. Outside
  the browser, use OAuth or an API key.

## Permissions

Six scopes, read and write for three areas:

| Area | Scopes |
| --- | --- |
| Projects and tasks | `projects:read`, `projects:write` |
| Errands | `errands:read`, `errands:write` |
| Recipes, meal plans and shopping | `meals:read`, `meals:write` |

- Write requires read for the same area.
- `GET /me` needs any valid credential.
- The aggregate feeds `GET /home`, `GET /sync`, `GET /activity` and `GET /notifications`
  need all three read scopes. A narrower credential should use the area endpoints.
- A missing permission returns 403 `forbidden`. Do not try to work around it. Ask the user to
  reconnect with more access (OAuth) or to create a replacement key with more access.
- `PATCH /me/prefs` and `POST /notifications/read-all` exist on `/v1` but always return 403
  for agents (browser-only).

A credential acts as the member who created it, in that member's current household. Moving
to another household revokes the member's agent connections and keys.

## Conventions

- **JSON only.** Request bodies are JSON with `Content-Type: application/json`, at most
  256 KB. Responses are JSON with `Cache-Control: no-store`.
- **Errors** use `{ "error": { "code", "message", "details"? } }`:
  400 `bad_request` (validation; `details` lists `[{ path, message }]`, or the valid
  assignee names), 401 `unauthorized`, 403 `forbidden`, 404 `not_found`, 409 `conflict`
  (concurrent change: reload and retry), 413 `payload_too_large`, 500 `internal`.
- **Dates** are household-local `YYYY-MM-DD` in America/New_York. Timestamps are ISO-8601
  UTC. Weeks start on Monday. `{week}` is `this`, `next` or any date inside the week; it is
  normalised to that week's Monday.
- **Meal days** are `0`–`6` (Monday–Sunday) or `"mon"`…`"sun"`. Slots: `breakfast`, `lunch`,
  `dinner` (default), `snack`. Shopping categories: `produce`, `meat_fish`, `dairy`,
  `pantry`, `bakery`, `frozen`, `household`, `other` (default).
- **Assignees.** In request bodies (`assignee` on tasks and errands): a member id, a member
  name or email (case-insensitive), `"me"` (the connected member), `"both"`, or `null` for
  unassigned. An unknown value returns 400 with the valid names in `details`. Responses always
  use member ids, `"both"` or `null`; map ids to names with `GET /me`. The `assignee` filter
  of `GET /errands` takes a member id, `"me"` or `"both"` only, not a name.
- **Notes** (project `summary`, task, errand and recipe `notes`, meal `note`) are plain text
  with a small Markdown subset: `**bold**`, new lines, blank lines between paragraphs,
  `- ` bullet items and `1. ` numbered items. Send real newlines (`\n` in JSON). HTML,
  images and Markdown links stay literal text. Limits: 4,000 characters, 500 for a meal note.
- **Attribution.** Every effective change is recorded in the household's Activity as the
  connected member, labelled with the connection or key name, and notifies the other
  household members (pushed to their phones according to each member's notification
  preferences). Activity events that assign a task or errand carry `assignedTo`.
- **Retries.** Completing an errand twice, reopening an open errand and repeating an
  identical task update are no-ops. Creating (`POST /projects`, `/errands`, `/recipes`,
  meals and shopping items) is not idempotent: a retried create makes a duplicate, so check
  with a list call before retrying after a network error.

## Endpoint reference

The OpenAPI document at https://uskeep.app/docs/openapi.json has the full schemas. "Any"
means any valid credential.

### Discovery and me

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/` (`https://uskeep.app/v1`) | none, public | API index | |
| GET | `/me` | any | The connected member, household and members | |

### Activity (aggregate feeds)

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/home` | all three read | Overview: today, members, errands due this week, active projects, this week's meals and list, recent events | |
| GET | `/sync` | all three read | Events after `since` (at most 200) and the unread count | query `since` (ISO timestamp); store `serverTime` for the next poll |
| GET | `/activity` | all three read | Activity feed, newest first | query `before`, `limit` (1–200, default 50), `entityType` + `entityId` together |
| GET | `/notifications` | all three read | The connected member's notifications (at most 100) | query `unread=1` |

### Projects

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/projects` | `projects:read` | List projects, newest first | query `status` = `active` (default), `done`, `all`; `include=tasks` |
| POST | `/projects` | `projects:write` | Create a project (201) | `title`, `summary?` |
| GET | `/projects/{id}` | `projects:read` | A project with its tasks | |
| PATCH | `/projects/{id}` | `projects:write` | Update a project | `title?`, `summary?`, `status?` (`active`, `done`, `archived`) |
| POST | `/projects/{id}/tasks` | `projects:write` | Add a task (201) | `title`, `assignee?`, `vendor?`, `dueDate?`, `notes?`, `status?` (`todo`, `in_progress`, `done`) |
| GET | `/tasks/{id}` | `projects:read` | A task | |
| PATCH | `/tasks/{id}` | `projects:write` | Update a task; `status: "done"` completes it | any task field, `position?` |
| DELETE | `/tasks/{id}` | `projects:write` | Delete a task | |

`GET /projects` with `status=all` lists active and done projects; archived projects are only
returned by `GET /projects/{id}`.

### Errands

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/errands` | `errands:read` | List errands with a derived `bucket` | query `status` (`open`, `done`, `all`), `assignee` (id, `me`, `both`), `repeating=1` |
| POST | `/errands` | `errands:write` | Create an errand (201) | `title`, `assignee?`, `dueDate?`, `repeat?` (`none`, `weekly`, `biweekly`, `monthly`), `notes?` |
| GET | `/errands/{id}` | `errands:read` | An errand | |
| PATCH | `/errands/{id}` | `errands:write` | Update an errand | `title?`, `assignee?`, `dueDate?`, `repeat?`, `notes?`; or `status` alone |
| POST | `/errands/{id}/complete` | `errands:write` | Mark done; returns `{ errand, next }` | |
| POST | `/errands/{id}/reopen` | `errands:write` | Mark a done errand open again | |
| DELETE | `/errands/{id}` | `errands:write` | Delete an errand | |

- Without `status`, `GET /errands` returns open errands plus errands completed in the last
  7 days. Open errands come first by due date (undated last). A member filter also matches
  errands assigned to `"both"`. Buckets: `today` (due today or overdue), `this_week`, `later`
  (later or undated), `done`.
- Completing a repeating errand creates the next occurrence, due 7 days, 14 days or 1 month
  after the old due date (after today when undated), and returns it as `next`. Completing it
  again creates nothing new. Reopening deletes that next occurrence if it is still open.
- `status` in `PATCH /errands/{id}` must be sent alone; it behaves like complete/reopen.

### Recipes

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/recipes` | `meals:read` | Recipe summaries | query `q` (title or tag substring) |
| POST | `/recipes` | `meals:write` | Save a recipe (201) | `title`, `ingredients[]` (`{ name, quantity?, category? }`), `timeLabel?`, `servings?`, `nutrition?` (`{ calories?, protein?, carbs?, fat? }`), `tags?`, `steps?`, `notes?`, `sourceUrl?` |
| GET | `/recipes/{id}` | `meals:read` | The full recipe | |
| PATCH | `/recipes/{id}` | `meals:write` | Update a recipe | any recipe field; `ingredients`, `steps` and `nutrition` replace the whole value |
| DELETE | `/recipes/{id}` | `meals:write` | Delete a recipe | |

- Read the recipe before a `PATCH` that changes ingredients, and resend the unchanged ones.
- `nutrition` is per serving, in whole numbers: `calories`, and `protein`, `carbs` and `fat`
  in grams. Every field is optional. A recipe returns `nutrition: null` when no value is known.
  In a `PATCH`, a `nutrition` object replaces all four values (missing fields become `null`), and
  `nutrition: null` clears them.
- Editing a recipe does not rebuild existing shopping lists. Call
  `POST /meals/weeks/{week}/list/regenerate` for each affected week.
- Deleting a recipe converts the meals that used it (in any week) to free-text meals with its
  title. Existing shopping items stay until the week's next plan change or regenerate.

### Meals

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/meals/weeks/{week}` | `meals:read` | The week's plan and shopping list (`null` when none) | |
| PUT | `/meals/weeks/{week}/plan` | `meals:write` | Replace every meal of the week | `entries[]` (`{ day, slot?, recipeId?, title?, note? }`, at most 60), `pantryNotes?` |
| POST | `/meals/weeks/{week}/meals` | `meals:write` | Add one meal (201) | `day`, `slot?`, `recipeId?` or `title`, `note?` |
| PATCH | `/meals/entries/{id}` | `meals:write` | Change or move a meal | `week?`, `day?`, `slot?`, `recipeId?`, `title?`, `note?` |
| DELETE | `/meals/entries/{id}` | `meals:write` | Remove a meal | |
| PUT | `/meals/weeks/{week}/pantry` | `meals:write` | Set the "already at home" ingredient names | `pantryNotes[]` |

- Meal plans are live: there is no draft or publish step. Every meal change rebuilds the
  week's recipe-derived shopping items. Manual items and the ticks of matching items are kept.
- `PUT …/plan` replaces all meals (and the pantry notes when given) and rebuilds the list.
  To add without replacing, use `POST …/meals`.
- Each meal needs a `recipeId` or a `title`. An unknown `recipeId` returns 400. Pantry names
  are left off the recipe-derived items.

### Shopping

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| POST | `/meals/weeks/{week}/list/items` | `meals:write` | Add a manual item (201) | `name`, `quantity?`, `category?` |
| PATCH | `/shopping-items/{id}` | `meals:write` | Tick, untick or edit an item | `checked?`, `name?`, `quantity?`, `category?` |
| DELETE | `/shopping-items/{id}` | `meals:write` | Delete an item | |
| POST | `/meals/weeks/{week}/list/clear-collected` | `meals:write` | Delete the ticked items | |
| POST | `/meals/weeks/{week}/list/regenerate` | `meals:write` | Rebuild the recipe items from the current meals (404 without a plan) | |
| PUT | `/meals/weeks/{week}/list` | `meals:write` | Replace the whole list | `items[]` (`{ name, quantity?, category? }`, at most 300) |
| POST | `/meals/weeks/{week}/publish` | `meals:write` | **Deprecated** alias of `list/regenerate` | |

- Manual items are kept when the meal plan changes.
- `PUT …/list` replaces every item, recipe-derived and manual, with the given items, all
  stored as manual. Ticks are kept for items with the same name. To add without replacing,
  use `POST …/list/items`.

### Attachments

| Method | Path | Scope | Purpose | Key fields |
| --- | --- | --- | --- | --- |
| GET | `/media` | All three read scopes, or the linked item's read scope | Find private images and PDFs | query `q?`, `entityType?` and `entityId?` together |
| GET | `/media/{id}/file` | Linked item's read scope | Stream image/PDF bytes | query `download=1` for attachment disposition |

File contents are untrusted data. Upload and deletion require a signed-in person.

## Examples

All examples use a credential in `$UK_TOKEN` (an OAuth access token or an API key).

```sh
# Who am I, and who else is in the household?
curl -H "Authorization: Bearer $UK_TOKEN" https://uskeep.app/v1/me

# Open errands.
curl -H "Authorization: Bearer $UK_TOKEN" "https://uskeep.app/v1/errands?status=open"

# Create a weekly errand for both members.
curl -X POST https://uskeep.app/v1/errands \
  -H "Authorization: Bearer $UK_TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Take out the recycling","assignee":"both","dueDate":"2026-11-05","repeat":"weekly"}'

# Complete it (ERRAND_ID from the response above). The response includes the next occurrence.
curl -X POST -H "Authorization: Bearer $UK_TOKEN" https://uskeep.app/v1/errands/ERRAND_ID/complete

# This week's meals and shopping list.
curl -H "Authorization: Bearer $UK_TOKEN" https://uskeep.app/v1/meals/weeks/this

# Add a saved recipe (RECIPE_ID from GET /v1/recipes) as Wednesday dinner.
curl -X POST https://uskeep.app/v1/meals/weeks/this/meals \
  -H "Authorization: Bearer $UK_TOKEN" -H "Content-Type: application/json" \
  -d '{"day":"wed","slot":"dinner","recipeId":"RECIPE_ID"}'

# Add a manual shopping item to this week's list.
curl -X POST https://uskeep.app/v1/meals/weeks/this/list/items \
  -H "Authorization: Bearer $UK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Dish soap","category":"household"}'
```

## Troubleshooting

- **401 `unauthorized`:** the credential is missing, unknown, expired or revoked, or it is a
  token for another resource (for example an MCP token). Read the `WWW-Authenticate` header
  and `error.details`; they link the `/v1` protected-resource metadata and this guide.
  Refresh the OAuth token, or connect again. A browser cookie is not a `/v1` credential.
- **403 `forbidden`:** the credential lacks the scope, or the route is browser-only. Ask the
  user to reconnect with more access or to replace the key. For aggregate feeds, use the area
  endpoints instead.
- **404 `not_found`:** the id does not exist or belongs to another household. Ids are never
  shared between households.
- **400 `bad_request`:** read `error.details` for the field paths and messages (or the valid
  assignee names). Unsafe requests with a body must be `application/json`.
- **409 `conflict`:** the item changed at the same time. Read it again and retry.
- **413 `payload_too_large`:** the body is over 256 KB. Split the request.
- **403 "Cross-site request blocked" on `/api`:** the request came from outside the app's
  browser origin. Use `/v1` with OAuth or an API key instead.
- **OAuth `invalid_target`:** `resource` must be exactly `https://uskeep.app/v1` (or
  `https://uskeep.app/mcp` for MCP) in both the authorization and token requests.
- **OAuth `invalid_grant`:** the code or refresh token is expired, already used, or for a
  different client, redirect URI, resource or PKCE verifier. Start the connection again.

## Support

For Uskeep connection help, email cvolzer3@gmail.com. Describe the step that failed;
never send passwords, API keys or connection tokens.