# Mavo API

Read and write household data with an API key. Authenticate every request with the `x-api-key` header. Keys are scoped to a single family.

## Authentication

Every request is authenticated with the `x-api-key` header. Each key is scoped to a single family, so the `familySlug` in the path must match the key family.

```http
x-api-key: $MAVO_API_KEY
```

## How to choose an endpoint

### Collections

Use these when your app needs to see or manage the family’s collection list: meals, chores, routines, and any custom collections. These endpoints are about the containers themselves.

### Entries

Use these when your app already knows which collection it is working with and needs the rows inside it. Each entry has a `title` display label plus `data` for the fields defined by that collection.

### Calendar

Use these for calendar events, linked external calendars, and calendar share links.

### Household operations

Use these for household people, notifications, webhook destinations, and other household settings that an integration may need to manage directly.

### Context and lookups

Use these when an integration needs Mavo’s household context search, weather lookup, or public web lookup without running a full agent conversation.

### MCP

Use the REST API for apps, scripts, and automations that can make normal HTTP requests with an API key. Use MCP when you are connecting Mavo to an assistant, so Mavo can appear inside that assistant as a set of available household actions.

## List collections

`GET /api/v1/families/{familySlug}/trackers`

Returns every collection in the family, built-in and custom.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/trackers \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "trackers": [
    {
      "key": "meals",
      "name": "Meals",
      "description": "What’s for dinner.",
      "fields": []
    }
  ]
}
```

## Create a collection

`POST /api/v1/families/{familySlug}/trackers`

Creates a custom collection with the given fields.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `category` string
- `color` string
- `description` string
- `fields` array
- `name` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/trackers \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"string"}'
```

### Example Response

```json
{
  "tracker": {
    "key": "chores",
    "name": "Chores",
    "fields": []
  }
}
```

## Update a collection

`PATCH /api/v1/families/{familySlug}/trackers/{trackerKey}`

Updates a custom collection. Send only the fields you want to change.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Request Body

- `color` string
- `description` value
- `fields` array
- `name` string

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/trackers/meals \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"color":"sage","description":"string","fields":[{"key":"string","label":"string"}],"name":"string"}'
```

### Example Response

```json
{
  "tracker": {
    "key": "chores",
    "name": "Weekly chores"
  }
}
```

## Delete a collection

`DELETE /api/v1/families/{familySlug}/trackers/{trackerKey}`

Deletes a custom collection and its entries. Built-in collections cannot be deleted.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/trackers/meals \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "tracker": {
    "key": "chores",
    "name": "Weekly chores"
  }
}
```

## List entries

`GET /api/v1/families/{familySlug}/trackers/{trackerKey}/entries`

Returns the entries in a collection.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/trackers/meals/entries \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "entries": [
    {
      "id": "ent_123",
      "title": "Taco night",
      "data": {
        "day": "2026-06-09",
        "status": "Planned"
      }
    }
  ]
}
```

## Create an entry

`POST /api/v1/families/{familySlug}/trackers/{trackerKey}/entries`

Adds an entry to a collection. `title` is the entry’s display label; collection-specific fields go in `data`.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Request Body

- `data` object: Collection-specific fields for this entry. Only fields defined by the collection are saved.
- `title` string required: Human-readable entry label. This is stored separately from collection-specific data fields and is returned in entry responses.

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/trackers/meals/entries \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"string"}'
```

### Example Response

```json
{
  "entry": {
    "id": "ent_123",
    "title": "Taco night",
    "data": {
      "day": "2026-06-09",
      "status": "Planned"
    }
  }
}
```

## Update an entry

`PATCH /api/v1/families/{familySlug}/trackers/{trackerKey}/entries/{entryId}`

Updates an entry. Send only the fields you want to change. `title` renames the entry; collection-specific fields go in `data`.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".
- `entryId` required: Identifier of the entry within the collection.

### Request Body

- `data` object: Collection-specific fields for this entry. Only fields defined by the collection are saved.
- `status` string
- `title` string: Human-readable entry label. This is stored separately from collection-specific data fields and is returned in entry responses.

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/trackers/meals/entries/ent_123 \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"data":{},"status":"active","title":"string"}'
```

### Example Response

```json
{
  "entry": {
    "id": "ent_123",
    "title": "Taco night",
    "status": "done"
  }
}
```

## Delete an entry

`DELETE /api/v1/families/{familySlug}/trackers/{trackerKey}/entries/{entryId}`

Removes an entry from a collection by id. No request body is needed; the deleted entry is returned for confirmation.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".
- `entryId` required: Identifier of the entry within the collection.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/trackers/meals/entries/ent_123 \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "entry": {
    "id": "ent_123",
    "title": "Taco night"
  }
}
```

## Create entries

`POST /api/v1/families/{familySlug}/trackers/{trackerKey}/entries/batch`

Adds multiple entries to a collection in one request.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Request Body

- `items` array required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/trackers/meals/entries/batch \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"items":[{"title":"string"}]}'
```

### Example Response

```json
{
  "count": 2,
  "entries": [
    {
      "id": "ent_123",
      "title": "Taco night"
    }
  ],
  "ok": true
}
```

## Update entries

`PATCH /api/v1/families/{familySlug}/trackers/{trackerKey}/entries/batch`

Updates multiple entries in a collection in one request.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Request Body

- `items` array required

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/trackers/meals/entries/batch \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"items":[{"entryId":"string"}]}'
```

### Example Response

```json
{
  "count": 2,
  "entries": [
    {
      "id": "ent_123",
      "title": "Taco night",
      "status": "done"
    }
  ],
  "ok": true
}
```

## Delete entries

`DELETE /api/v1/families/{familySlug}/trackers/{trackerKey}/entries/batch`

Deletes multiple entries from a collection in one request. Pass entry ids only; titles are returned in the response for confirmation.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `trackerKey` required: Key of the collection, e.g. "meals".

### Request Body

- `entryIds` array required

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/trackers/meals/entries/batch \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"entryIds":["string"]}'
```

### Example Response

```json
{
  "count": 2,
  "entries": [
    {
      "id": "ent_123",
      "title": "Taco night"
    }
  ],
  "ok": true
}
```

## List calendar events

`GET /api/v1/families/{familySlug}/calendar/events`

Returns family calendar events. Supports optional `query`, `status`, and `limit` query parameters.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/calendar/events \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "events": [
    {
      "id": "ent_123",
      "title": "Soccer practice",
      "data": {
        "date": "2026-07-01",
        "time": "17:00"
      }
    }
  ],
  "ok": true
}
```

## Create calendar event

`POST /api/v1/families/{familySlug}/calendar/events`

Adds an event to the family calendar.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `assignee` string
- `date` string: ISO date when known.
- `note` string
- `ownerPersonId` string
- `time` string
- `title` string required
- `where` string

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/calendar/events \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"string"}'
```

### Example Response

```json
{
  "entryId": "ent_123",
  "ok": true,
  "title": "Soccer practice"
}
```

## Update calendar event

`PATCH /api/v1/families/{familySlug}/calendar/events/{eventId}`

Updates one family calendar event.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `eventId` required: Identifier of the calendar event.

### Request Body

- `assignee` string
- `date` string: ISO date when known.
- `note` string
- `ownerPersonId` string
- `time` string
- `title` string
- `where` string
- `data` object
- `status` string

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/calendar/events/eventId \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"assignee":"string","date":"string","note":"string","ownerPersonId":"string","time":"string","title":"string","where":"string","data":{},"status":"active"}'
```

### Example Response

```json
{
  "event": {
    "id": "ent_123",
    "title": "Soccer practice",
    "data": {
      "date": "2026-07-01"
    }
  },
  "ok": true
}
```

## Delete calendar event

`DELETE /api/v1/families/{familySlug}/calendar/events/{eventId}`

Deletes one family calendar event.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `eventId` required: Identifier of the calendar event.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/calendar/events/eventId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "event": {
    "id": "ent_123",
    "title": "Soccer practice"
  },
  "ok": true
}
```

## Search household context

`GET /api/v1/families/{familySlug}/context`

Searches household collections, members, and upcoming calendar items. Use the optional `query` query parameter to narrow results.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/context \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "query": "soccer",
  "results": []
}
```

## List recent notifications

`GET /api/v1/families/{familySlug}/notifications`

Returns recent household notifications. Supports optional `sinceMinutes` and `triggerId` query parameters.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/notifications \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "notifications": [
    {
      "title": "Practice moved",
      "body": "Field changed."
    }
  ]
}
```

## Send notification

`POST /api/v1/families/{familySlug}/notifications`

Sends a household notification.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `body` string
- `channels` array
- `title` string required
- `triggerId` string

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/notifications \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"title":"string"}'
```

### Example Response

```json
{
  "delivered": 1,
  "ok": true,
  "suppressed": 0
}
```

## Schedule event check

`POST /api/v1/families/{familySlug}/checks`

Schedules a background check ahead of a calendar event.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `channels` array
- `eventId` string required
- `leadHours` number required
- `task` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/checks \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"eventId":"string","leadHours":0,"task":"string"}'
```

### Example Response

```json
{
  "eventId": "ent_123",
  "ok": true,
  "triggerId": "trg_123"
}
```

## List people

`GET /api/v1/families/{familySlug}/people`

Returns household people.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/people \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "people": [
    {
      "id": "person_123",
      "name": "Maya",
      "role": "child"
    }
  ]
}
```

## Create person

`POST /api/v1/families/{familySlug}/people`

Adds a household person profile.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `email` string
- `kind` string
- `name` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/people \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"string"}'
```

### Example Response

```json
{
  "ok": true,
  "person": {
    "id": "person_123",
    "displayName": "Maya"
  }
}
```

## Update person

`PATCH /api/v1/families/{familySlug}/people/{personId}`

Updates a household person profile.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `personId` required: Identifier of the household person.

### Request Body

- `email` value
- `kind` string
- `name` string

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/people/personId \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"email":"string","kind":"adult","name":"string"}'
```

### Example Response

```json
{
  "ok": true,
  "person": {
    "id": "person_123",
    "displayName": "Maya"
  }
}
```

## Delete person

`DELETE /api/v1/families/{familySlug}/people/{personId}`

Removes a household person profile from active household views.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `personId` required: Identifier of the household person.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/people/personId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "personId": "person_123"
}
```

## List webhook destinations

`GET /api/v1/families/{familySlug}/webhook-destinations`

Returns outbound webhook destinations, delivery history, available events, and usage.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/webhook-destinations \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "destinations": [],
  "events": [
    "tracker.entry.created"
  ],
  "ok": true
}
```

## Create webhook destination

`POST /api/v1/families/{familySlug}/webhook-destinations`

Creates an outbound webhook destination. The signing secret is returned once.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `enabled` boolean
- `eventTypes` array required
- `name` string required
- `url` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/webhook-destinations \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"eventTypes":["collection.created"],"name":"string","url":"string"}'
```

### Example Response

```json
{
  "destination": {
    "id": "whd_123",
    "name": "Zapier",
    "url": "https://example.com/webhook"
  },
  "ok": true,
  "signingSecret": "whsec_..."
}
```

## Update webhook destination

`PATCH /api/v1/families/{familySlug}/webhook-destinations/{destinationId}`

Updates an outbound webhook destination or rotates its signing secret.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `destinationId` required: Identifier of the webhook destination.

### Request Body

- `enabled` boolean
- `eventTypes` array
- `name` string
- `url` string
- `rotateSecret` boolean

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/webhook-destinations/destinationId \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"enabled":true,"eventTypes":["collection.created"],"name":"string","url":"string","rotateSecret":true}'
```

### Example Response

```json
{
  "destination": {
    "id": "whd_123",
    "name": "Zapier"
  },
  "ok": true
}
```

## Delete webhook destination

`DELETE /api/v1/families/{familySlug}/webhook-destinations/{destinationId}`

Deletes an outbound webhook destination.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `destinationId` required: Identifier of the webhook destination.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/webhook-destinations/destinationId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## Test webhook destination

`POST /api/v1/families/{familySlug}/webhook-destinations/{destinationId}/test`

Sends a test delivery to a webhook destination.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `destinationId` required: Identifier of the webhook destination.

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/webhook-destinations/destinationId/test \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## Get notification preferences

`GET /api/v1/families/{familySlug}/notification-preferences`

Returns household notification preferences.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/notification-preferences \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "preferences": {}
}
```

## Set notification preference

`POST /api/v1/families/{familySlug}/notification-preferences`

Updates one household notification preference.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `channel` string required
- `eventKind` string required
- `isEnabled` boolean required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/notification-preferences \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"channel":"email","eventKind":"reminder","isEnabled":true}'
```

### Example Response

```json
{
  "ok": true,
  "preferences": {}
}
```

## List notification routines

`GET /api/v1/families/{familySlug}/notification-routines`

Returns household notification routines.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/notification-routines \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "routines": []
}
```

## Create notification routine

`POST /api/v1/families/{familySlug}/notification-routines`

Creates a household notification routine.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `channels` array
- `cron` string
- `intent` string
- `isEnabled` boolean
- `mode` string
- `timezone` string

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/notification-routines \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"channels":["in_app"],"cron":"string","intent":"briefing","isEnabled":true,"mode":"plain","timezone":"string"}'
```

### Example Response

```json
{
  "ok": true,
  "routine": {
    "id": "trg_123"
  }
}
```

## Update notification routine

`PATCH /api/v1/families/{familySlug}/notification-routines/{triggerId}`

Updates a household notification routine.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `triggerId` required: Identifier of the notification routine.

### Request Body

- `channels` array
- `cron` string
- `intent` string
- `isEnabled` boolean
- `mode` string
- `timezone` string

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/notification-routines/triggerId \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"channels":["in_app"],"cron":"string","intent":"briefing","isEnabled":true,"mode":"plain","timezone":"string"}'
```

### Example Response

```json
{
  "ok": true,
  "routine": {
    "id": "trg_123"
  }
}
```

## Delete notification routine

`DELETE /api/v1/families/{familySlug}/notification-routines/{triggerId}`

Deletes a household notification routine.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `triggerId` required: Identifier of the notification routine.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/notification-routines/triggerId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## Check weather

`GET /api/v1/families/{familySlug}/weather`

Looks up weather for a location. Send `location`, and optionally `date` and `time`, as query parameters.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/weather \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## Search web

`GET /api/v1/families/{familySlug}/web/search`

Searches the public web. Send `query`, and optionally `numResults`, as query parameters.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/web/search \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "results": [
    {
      "title": "Example",
      "url": "https://example.com"
    }
  ]
}
```

## Read web page

`GET /api/v1/families/{familySlug}/web/page`

Reads the main text of a public web page. Send `url` as a query parameter.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/web/page \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "text": "Readable page content...",
  "url": "https://example.com"
}
```

## List external calendars

`GET /api/v1/families/{familySlug}/calendar/external`

Returns linked external calendar feeds.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/calendar/external \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "feeds": [],
  "ok": true
}
```

## Create external calendar

`POST /api/v1/families/{familySlug}/calendar/external`

Links an external ICS calendar feed and syncs its events.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `color` string
- `hint` string
- `name` string required
- `url` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/calendar/external \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"string","url":"string"}'
```

### Example Response

```json
{
  "eventCount": 12,
  "ok": true
}
```

## Probe external calendar

`POST /api/v1/families/{familySlug}/calendar/external/probe`

Checks whether an external ICS calendar URL can be read.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `url` string required

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/calendar/external/probe \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"string"}'
```

### Example Response

```json
{
  "ok": true
}
```

## Update external calendar

`PATCH /api/v1/families/{familySlug}/calendar/external/{sourceId}`

Updates notes about a linked external calendar feed.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `sourceId` required: Identifier of the external calendar feed.

### Request Body

- `hint` string

### Example Request

```bash
curl -X PATCH https://mavolife.com/api/v1/families/your-family/calendar/external/sourceId \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hint":"string"}'
```

### Example Response

```json
{
  "ok": true
}
```

## Delete external calendar

`DELETE /api/v1/families/{familySlug}/calendar/external/{sourceId}`

Removes a linked external calendar feed and its synced calendar.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `sourceId` required: Identifier of the external calendar feed.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/calendar/external/sourceId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## Refresh external calendar

`POST /api/v1/families/{familySlug}/calendar/external/{sourceId}/refresh`

Requests a refresh for a linked external calendar feed.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `sourceId` required: Identifier of the external calendar feed.

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/calendar/external/sourceId/refresh \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```

## List calendar shares

`GET /api/v1/families/{familySlug}/calendar/shares`

Returns household calendar share links.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Example Request

```bash
curl -X GET https://mavolife.com/api/v1/families/your-family/calendar/shares \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true,
  "shares": []
}
```

## Create calendar share

`POST /api/v1/families/{familySlug}/calendar/shares`

Creates a calendar share link. The plaintext share token is returned once.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.

### Request Body

- `categories` array
- `name` string required
- `personIds` array
- `sourceIds` array

### Example Request

```bash
curl -X POST https://mavolife.com/api/v1/families/your-family/calendar/shares \
  -H "x-api-key: $MAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"string"}'
```

### Example Response

```json
{
  "ok": true,
  "share": {
    "id": "share_123",
    "name": "Soccer calendar"
  },
  "token": "share-token"
}
```

## Revoke calendar share

`DELETE /api/v1/families/{familySlug}/calendar/shares/{shareId}`

Revokes a calendar share link.

### Path Parameters

- `familySlug` required: Slug of the family (household) to act on.
- `shareId` required: Identifier of the calendar share link.

### Example Request

```bash
curl -X DELETE https://mavolife.com/api/v1/families/your-family/calendar/shares/shareId \
  -H "x-api-key: $MAVO_API_KEY"
```

### Example Response

```json
{
  "ok": true
}
```