For agents and scripts

Uskeep REST API

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. See the MCP setup guide.
• 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.

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):

# 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):

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.

# 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.

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, 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:

• 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 has the full schemas. “Any” means any valid credential.

Discovery and me

Activity (aggregate feeds)

Projects

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

Errands

• 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

• Read the recipe before a PATCH that changes ingredients, and resend the unchanged ones.
• 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

• 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

• 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.

Examples

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

# 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.

Need a hand?

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