---
audience: developer
summary: Your profile, presence, preferences.
title: Profiles and preferences API
path: reference/api/profiles
status: published
---

# Profiles and preferences API

5 endpoints under `/v1/me/` and `/v1/profiles/`.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/me` | Your profile + tenant context. |
| `PUT` | `/v1/me` | Update display name, avatar, bio. |
| `GET` | `/v1/me/preferences` | Your preferences. |
| `PUT` | `/v1/me/preferences` | Update preferences (merge-update). |
| `PUT` | `/v1/me/presence` | Set presence state manually. |

## GET /v1/me

```json
{
  "data": {
    "participant_id": "5e4d…",
    "local_id": "alice",
    "fqid": "@alice:scaiwave.example.com",
    "display_name": "Alice Anderson",
    "email": "alice@example.com",
    "avatar_url": "...",
    "bio": "...",
    "personal_workspace_id": "ws-…",
    "roles": ["docs_developer"],
    "groups": ["group-eng"],
    "presence": "online",
    "tenant": {
      "id": "abc-…",
      "slug": "acme",
      "name": "Acme Corp",
      "features": { "prompt_studio": { "enabled": true } }
    }
  }
}
```

## Preferences

```jsonc
{
  "data": {
    "locale": "en",                          // ui language: en | nl | de
    "timezone": "Europe/Amsterdam",          // IANA tz
    "time_format": "24h",                    // "12h" | "24h"
    "ai_response_mode": "conversational",    // "streaming" | "conversational"; updated by room-wide flips
    "ai_engagement_mode": "always",          // "always" | "mention" | "keyword" | "autonomous"
                                             //   — applied when this user invites an AI into a new group room
    "default_mode": "all",                   // notification floor: "all" | "mentions" | "none"
    "quiet_hours": {
      "enabled": false,
      "start": null, "end": null,
      "weekdays_only": false, "weekends_only": false
    },
    "keyword_alerts": [],
    "read_marker_mode": "leave",             // "leave" | "scroll"
    "push": true,
    "email": false,
    "email_address": null
  }
}
```

`PUT /v1/me/preferences` is **merge-update** — only the keys you
send are touched; everything else is preserved.

## Presence

```bash
curl -X PUT "$BASE/v1/me/presence" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"state": "busy"}'
```

States: `online`, `idle`, `busy`, `appear_offline`. Setting any of
these is sticky — the auto-detect rule stops applying until you
explicitly reset:

```bash
curl -X PUT "$BASE/v1/me/presence" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"auto": true}'
```