# Prompt for your AI coding assistant

> A ready-made prompt that teaches Claude Code, Codex, Cursor, Copilot or Windsurf how to build with the LifeButler API.

Building an integration with Claude Code, OpenAI Codex, Cursor, GitHub Copilot or Windsurf? Paste this prompt first. It gives the assistant the essentials of the LifeButler API and tells it where to read the details, so it doesn't invent endpoints.

## The prompt

```text
You are helping me build an integration with the LifeButler API in this project.

ABOUT LIFEBUTLER
LifeButler (lifebutler.io) is a shared organiser for families, couples, flat shares, clubs and teams in Germany, Austria and Switzerland: calendar, tasks, shopping and to-do lists, documents with AI analysis, and an AI "butler". Data lives in workspaces: every user has a personal space, plus shared workspaces (groups). Hosted in Frankfurt; AI only in the EU.

API BASICS
- Base URL: https://api.lifebutler.io/v1 (keep it configurable). MCP server: https://api.lifebutler.io/mcp
- Auth: header "Authorization: Bearer lb_live_…" (alternative: "X-API-Key"). Keys are created by the user in the LifeButler app (Settings → API & MCP) and shown once. Never hard-code a key, never log it, never ship it in client-side code; read it from an environment variable or secret store.
- Access: a key reaches only the workspaces chosen for it, only where its user is owner or admin, only with Pro/Premium. Start with GET /workspaces to get workspace IDs; everything else is under /workspaces/{workspaceId}/…
- Scopes: calendar:read, calendar:write, tasks:read, tasks:write, lists:read, lists:write, documents:read, documents:write, search, butler. Missing scope → 403 insufficient_scope.
- Times: responses are ISO 8601 with the Europe/Berlin offset ("2026-11-20T19:30:00+01:00"). Requests accept ISO 8601; without offset = Berlin time. All-day appointments use dates (YYYY-MM-DD, end inclusive). GET …/events expands repeating appointments into occurrences.
- JSON in and out. POST → 201 with the created object. PATCH changes only sent fields. DELETE → {"id", "deleted": true}. Document upload: raw file bytes as body with its Content-Type, ?fileName=… in the query.
- Paging: {"data": […], "nextCursor": "…" | null}; pass cursor=<nextCursor>.
- Errors: {"error": {"code", "message", "requestId"}} with HTTP status. Branch on error.code, not on message. 404 workspace_not_found also means "not part of this key".
- Rate limit: 120 requests/minute per key; on 429 wait Retry-After seconds. Back off exponentially on 5xx.
- AI: POST …/butler and POST …/documents/{id}/analyze use the workspace owner's AI credits (402 no_credits); smart search and butler need AI turned on in the workspace (409 ai_disabled).

ENDPOINTS
- GET /me – Who am I [workspaces:read]
- GET /workspaces – List workspaces [workspaces:read]
- GET /workspaces/{workspaceId} – Get a workspace [workspaces:read]
- GET /workspaces/{workspaceId}/members – List members [workspaces:read]
- GET /workspaces/{workspaceId}/events – List appointments in a time range [calendar:read]
- POST /workspaces/{workspaceId}/events – Create an appointment [calendar:write]
- GET /workspaces/{workspaceId}/events/{eventId} – Get an appointment [calendar:read]
- PATCH /workspaces/{workspaceId}/events/{eventId} – Change an appointment [calendar:write]
- DELETE /workspaces/{workspaceId}/events/{eventId} – Delete an appointment [calendar:write]
- GET /workspaces/{workspaceId}/tasks – List tasks [tasks:read]
- POST /workspaces/{workspaceId}/tasks – Create a task [tasks:write]
- GET /workspaces/{workspaceId}/tasks/{taskId} – Get a task [tasks:read]
- PATCH /workspaces/{workspaceId}/tasks/{taskId} – Change a task [tasks:write]
- DELETE /workspaces/{workspaceId}/tasks/{taskId} – Delete a task [tasks:write]
- POST /workspaces/{workspaceId}/tasks/{taskId}/complete – Complete a task [tasks:write]
- POST /workspaces/{workspaceId}/tasks/{taskId}/reopen – Reopen a task [tasks:write]
- GET /workspaces/{workspaceId}/lists – List lists [lists:read]
- POST /workspaces/{workspaceId}/lists – Create a list [lists:write]
- PATCH /workspaces/{workspaceId}/lists/{listId} – Rename a list [lists:write]
- DELETE /workspaces/{workspaceId}/lists/{listId} – Delete a list [lists:write]
- GET /workspaces/{workspaceId}/lists/{listId}/items – List items [lists:read]
- POST /workspaces/{workspaceId}/lists/{listId}/items – Add items [lists:write]
- PATCH /workspaces/{workspaceId}/lists/{listId}/items/{itemId} – Change or tick off an item [lists:write]
- DELETE /workspaces/{workspaceId}/lists/{listId}/items/{itemId} – Remove an item [lists:write]
- GET /workspaces/{workspaceId}/documents – List and search documents [documents:read]
- POST /workspaces/{workspaceId}/documents – Upload a document [documents:write]
- GET /workspaces/{workspaceId}/documents/{documentId} – Get a document [documents:read]
- PATCH /workspaces/{workspaceId}/documents/{documentId} – Change a document [documents:write]
- DELETE /workspaces/{workspaceId}/documents/{documentId} – Delete a document [documents:write]
- GET /workspaces/{workspaceId}/documents/{documentId}/file – Download the file [documents:read]
- POST /workspaces/{workspaceId}/documents/{documentId}/analyze – Analyse a document with AI [documents:write]
- GET /workspaces/{workspaceId}/search – Smart search [search]
- POST /workspaces/{workspaceId}/butler – Ask the butler [butler]

DOCUMENTATION (Markdown – read before writing code)
- https://lifebutler.io/developers.md
- https://lifebutler.io/developers/authentication.md
- https://lifebutler.io/developers/access.md
- https://lifebutler.io/developers/conventions.md
- https://lifebutler.io/developers/mcp.md
- https://lifebutler.io/developers/recipes.md
- https://lifebutler.io/developers/reference/workspaces.md (Workspaces)
- https://lifebutler.io/developers/reference/calendar.md (Calendar)
- https://lifebutler.io/developers/reference/tasks.md (Tasks)
- https://lifebutler.io/developers/reference/lists.md (Lists)
- https://lifebutler.io/developers/reference/documents.md (Documents)
- https://lifebutler.io/developers/reference/search-and-butler.md (Search & Butler)
- OpenAPI 3.1: https://lifebutler.io/developers/openapi.json
- Index of all pages: https://lifebutler.io/developers/llms.txt

WORKING RULES
1. Read the relevant .md pages above (and the reference page of the endpoints you use) before writing code. Never invent endpoints, fields or error codes; if something isn't documented, say so.
2. Keep the API key out of source code, logs and client-side bundles.
3. Ask me for workspace and list IDs or look them up via the API (GET /workspaces, GET …/lists, GET …/members); don't guess them.
4. Write times with an explicit offset, or as Berlin wall-clock time without offset – never as a UTC time meant as local time.
5. Handle 401/403 (key, plan, scope, role), 404, 409, 429 (Retry-After) and 5xx explicitly.
6. POST requests are not deduplicated: after a timeout, check whether the item exists before retrying.
7. Confirm with me before code deletes data or spends AI credits in a loop.
8. Prefer small, typed helper functions per endpoint, and test against a workspace you can safely change.
```

## How to use it

- **Once:** paste it as the first message of the conversation, then describe what you want to build.
- **For a project:** save it where your assistant picks it up automatically – `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex and others), `.cursor/rules/lifebutler.mdc` (Cursor) or `.github/copilot-instructions.md` (Copilot).
- The assistant needs web access to read the linked `.md` pages. Without it, download them into your project – or give it the [OpenAPI spec](/developers/openapi.json).
- Want the assistant to *use* LifeButler rather than write code for it? Connect the [MCP server](/developers/mcp).

## Resources for AI tools

- [/developers/llms.txt](/developers/llms.txt) – index of all docs pages as Markdown
- Every page as Markdown: add `.md` to its address, e.g. [/developers/conventions.md](/developers/conventions.md)
- [/developers/openapi.json](/developers/openapi.json) – OpenAPI 3.1, also live at `https://api.lifebutler.io/v1/openapi.json`