# Bitwarden `bw serve` — endpoint cheat sheet

Base URL: `http://127.0.0.1:8087` (puerto en `BW_PORT`).
Todos los endpoints devuelven `{ success: true|false, data?: ..., message?: ... }`.

## Lectura (GET) — siempre permitida

### Estado y metadata
| Endpoint | Devuelve |
|---|---|
| `GET /status` | `{ object, status: locked\|unlocked, serverUrl, userEmail, userId, lastSync }` |
| `GET /sync` | Fuerza sync con el server. `{ object: "message", title: "Syncing complete." }` |
| `GET /object/fingerprint/me` | Fingerprint phrase de la cuenta |

### Listas
| Endpoint | Filtros (querystring) |
|---|---|
| `GET /list/object/items` | `search`, `url`, `folderid`, `collectionid`, `organizationid`, `trash` |
| `GET /list/object/folders` | `search` |
| `GET /list/object/collections` | `search`, `organizationid` |
| `GET /list/object/org-collections` | `organizationid` (requerido) |
| `GET /list/object/org-members` | `organizationid` (requerido) |
| `GET /list/object/organizations` | `search` |
| `GET /list/object/sends` | `search` |

### Objeto específico (por id o por search exact-match en name)
| Endpoint | Notas |
|---|---|
| `GET /object/item/<id\|name>` | Item completo (login/note/card/identity) |
| `GET /object/folder/<id\|name>` | Folder |
| `GET /object/collection/<id>` | Collection (personal o org) |
| `GET /object/org-collection/<id>?organizationid=X` | Collection del org con detalles de members |
| `GET /object/send/<id\|name>` | Send |
| `GET /object/password/<item-id>` | **Sólo el password en plaintext** |
| `GET /object/username/<item-id>` | Sólo el username |
| `GET /object/uri/<item-id>` | Primera URI del item |
| `GET /object/totp/<item-id>` | Código TOTP actual (si el item tiene `login.totp` configurado) |
| `GET /object/notes/<item-id>` | Texto de la nota |
| `GET /object/exposed/<item-id>` | Cuántas veces el password apareció en HIBP |
| `GET /object/attachment/<attachment-id>?itemid=X&output=path` | Descarga el attachment |
| `GET /object/template/<type>` | Template JSON para crear (`item`, `item.login`, `item.card`, `item.identity`, `item.securenote`, `folder`, `collection`, `send.text`, `send.file`, `org-collection`) |

### Generador
| Endpoint | Querystring |
|---|---|
| `GET /generate` | `length=20`, `uppercase`, `lowercase`, `numbers`, `special`, `passphrase=true`, `words=3`, `separator=-`, `capitalize`, `number` |

Ejemplo: `GET /generate?length=24&uppercase&lowercase&numbers&special`

## Creación (POST) — permitida en endpoints específicos

| Endpoint | Body | Devuelve |
|---|---|---|
| `POST /object/item` | item JSON (ver `GET /object/template/item`) | item creado con `id`, `revisionDate` |
| `POST /object/folder` | `{ "name": "..." }` | folder con `id` |
| `POST /object/send` | send JSON (`GET /object/template/send.text` o `send.file`) | send con `id`, `accessUrl` |
| `POST /object/org-collection?organizationid=X` | collection JSON | requiere permisos en el org (claudecode0 = "Can view" → 403) |

### Auth/utility (también POST permitido)
| Endpoint | Body | Notas |
|---|---|---|
| `POST /sync` | (vacío) | Equivalente a GET /sync |
| `POST /unlock` | `{ "password": "..." }` o vía `BW_SESSION` env | Devuelve nueva session |
| `POST /lock` | (vacío) | Lockea el vault. Requiere unlock para volver a usar |
| `POST /generate` | `{ length, uppercase, ... }` | Equivalente a GET /generate |

### Schema mínimo de item (type 1 = login)
```json
{
  "organizationId": null,
  "folderId": null,
  "type": 1,
  "name": "GitHub",
  "notes": "personal account",
  "favorite": false,
  "fields": [
    { "name": "Custom Field", "value": "x", "type": 0 }
  ],
  "login": {
    "uris": [{ "uri": "https://github.com", "match": null }],
    "username": "user",
    "password": "***",
    "totp": "otpauth://totp/..."
  }
}
```

Tipos: `1`=Login, `2`=SecureNote, `3`=Card, `4`=Identity.

Para SecureNote usar `"type": 2` + `"secureNote": { "type": 0 }` en lugar de `login`.

Pedí `GET /object/template/item.login` (o `.card`, `.identity`, `.securenote`) para el schema exacto antes de POST.

## Bloqueado por la skill (read+create only)

| Verbo / endpoint | Por qué |
|---|---|
| `PUT /object/*` | Modifica items existentes |
| `DELETE /object/*` | Soft-delete (a Trash) |
| `POST /restore/item/<id>` | Restaura desde Trash |
| `POST /move/<ids>/<orgId>` | Comparte item al org |
| `POST /confirm/org-member/<id>` | Confirma member invite |
| `POST /object/attachment` (multipart) | Adjuntar archivos |
| `POST /object/share/*` | Si existe, comparte items |

Si **realmente** necesitás bypass-ear el guard (ej. cleanup), pidiéndoselo al usuario:
```bash
BITWARDENCLI_APPDATA_DIR=~/.claude/skills/bitwarden/.cache/bw \
  BW_SESSION=$(cat ~/.claude/skills/bitwarden/.cache/session) \
  bw <delete|edit|...>
```

## Códigos de error comunes

| HTTP | Causa | Qué hacer |
|---|---|---|
| 401 | Vault locked o session expirada | Re-correr `setup.sh` para re-unlock |
| 403 | Server side permission (rol "Can view" rechaza writes) | Esperado para acciones write en collections del org |
| 404 | Item/folder/collection no existe (o no tiene acceso) | Verificar id |
| 400 | Body JSON inválido | Pedí `GET /object/template/<type>` para el schema |
| 500 | bw serve crasheó | `serve-down.sh && serve-up.sh`, ver `.cache/serve.log` |

## Referencias
- Doc oficial CLI: https://bitwarden.com/help/cli/
- Vault Management API spec: https://bitwarden.com/help/vault-management-api/
- Vaultwarden compat: https://github.com/dani-garcia/vaultwarden