# Avelle assistant setup

Avelle works alongside your AI assistant. There is no implied partnership with an assistant provider. Your assistant uses your plan with its provider; Avelle does not call an LLM for these requests.

## Connect

Open Account → Team → Add your assistant. Name it, choose permissions, and copy the invitation token. Tokens are shown once, stored only as a hash, and expire after 90 days. Removing the assistant revokes access immediately. Never share an account password.

Base URL: `https://losrzqznguccrpufxgqf.supabase.co/functions/v1/assistant-api`

Send `Authorization: Bearer avelle_YOUR_TOKEN` on every request. Send `Content-Type: application/json` for additions. Each addition also requires a unique `Idempotency-Key` header, 8–80 characters. Retry an interrupted addition with the same key to avoid creating it twice. Use a new key for a new item.

## Endpoints

| Endpoint | Permission | Request |
| --- | --- | --- |
| GET /tasks | tasks:read | Returns Brain Dump tasks |
| POST /tasks | tasks:add | `{"name":"Bring the library book","timeZone":"America/New_York"}` |
| GET /notes | notes:read | Returns notes added by assistants |
| POST /notes | notes:add | `{"name":"A thought worth keeping"}` |
| GET /dates | dates:read | Returns dates manually added to Datebook |
| POST /dates | dates:add | `{"title":"Dinner with Jill","date":"2026-10-10","annual":false}` |

Dates use local `YYYY-MM-DD` values. `remindAt` is optional. Names may contain up to 500 characters. Responses to additions include the new item ID. Read responses use `{"items":[...]}` and return at most 200 items. Notes land in Brain Dump; this creates no new list. Calendar-provider events, private journals, finances, account settings, billing, and deletion are unavailable through these endpoints. Added dates do not enable notifications automatically.

## Timed capture and parking

Tasks use the same deterministic parser as in-app capture. Include an IANA `timeZone` (or open the app once to save the account timezone). “Pick up Eamon at 3” becomes a calendar event; “call the dentist” stays in the parking lot, with a nullable `todayDate`. Unsuffixed 1–7 means afternoon; an already-passed time without an explicit day means tomorrow. Always repeat the saved date/time back to the person. Use explicit am/pm and a YYYY-MM-DD date when precision matters. Invalid or unrecognized times remain parked.

Scheduling through POST /tasks requires both tasks:add and dates:add. The returned task includes `scheduledEventId`, `event`, and `saved:true`. With dates:read permission, it also includes `conflicts` for events starting within 15 minutes, or overlapping the new start. The item is already saved. Mention the nearby event once, kindly; never imply saving was blocked. Retry with the same Idempotency-Key to retrieve the same result without a second event or notice.

Conflict checks cover Avelle events and the most recently synced Google snapshot. Device-only Apple Calendar events are checked inside the app, never sent to this API. The response names these limits in `conflictCheckSources`. Add-only tokens receive no existing calendar names or times. No AI service is called by Avelle.

Timed captures get the standard wrap-up nudge in the app once notification permission is granted. Leave nudges require an address and a confirmed leave time. All-day dates retain their existing optional reminder settings.

## Conventions

Suggest; never rearrange someone's day automatically. Ask before adding a plan on the person's behalf. Use short, warm, shame-free language. No streaks, scores, completion percentages, or guilt. Avoid “overdue,” “behind,” “missed,” “crush,” “grind,” and “optimize.” Avelle is a lifestyle planner, not medical treatment.

An assistant token can only read or add the categories its owner chose. There are no update, delete, billing, or account-management endpoints for assistants. Account JWTs manage invitations through `/team`; assistant tokens cannot do so.

## Errors

- 400: Check the item name, date, JSON, or Idempotency-Key.
- 401: Token is invalid, expired, or revoked. Ask the owner to reconnect.
- 403: The owner has not shared that permission. Do not bypass it.
- 429: Wait a minute before retrying. Limit: 60 requests per minute per token.
- 500: Temporary service problem. Retry additions with the same Idempotency-Key.

Never put tokens in URLs, screenshots, shared documents, or logs. The assistant provider can see information you choose to send it; its privacy policy applies.