> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brelio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimistic concurrency (expectedVersion)

> Every record carries a version. Send it back as expectedVersion so two changes never overwrite each other.

A receptionist edits a patient in Brelio while your integration updates the same patient. Without a check, the last write silently wins. Brelio prevents that: every record has a `version`, and every change says which version it was based on.

## The rule

1. **Read** the record. Its `version` is in the response.
2. **Send** that value unchanged as `expectedVersion` in the change.
3. If someone changed the record in between, Brelio answers `409` and changes nothing. Read it again, decide again, retry.

```bash theme={null}
# 1. Read
curl https://api.brelio.app/v1/patients/$PATIENT_ID \
  -H "Authorization: Bearer $BRELIO_API_KEY"
# → { "id": "…", "phone": "+34 600 123 456", "version": "2026-11-09 17:59:58.817+00", … }

# 2. Change, based on that version
curl -X PATCH https://api.brelio.app/v1/patients/$PATIENT_ID \
  -H "Authorization: Bearer $BRELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expectedVersion": "2026-11-09 17:59:58.817+00", "phone": "+34 600 765 432"}'
# → 200, with the new "version"
```

Sending the old version again answers:

```json 409 VERSION_CONFLICT theme={null}
{
  "type": "https://api.brelio.app/problems/version-conflict",
  "title": "Request refused",
  "status": 409,
  "code": "VERSION_CONFLICT",
  "detail": "Patient changed since it was read: d4ddb883-ee85-46d1-9719-5e0f7e585392",
  "request_id": "31adfde0-8936-43e6-9330-4abc092d6d20",
  "params": { "id": "d4ddb883-ee85-46d1-9719-5e0f7e585392" }
}
```

## Treat the version as opaque

Copy `version` exactly as you read it. Do not build, parse, compare or increment it. Its form depends on the resource and may change:

| Resource | `version` looks like | `expectedVersion` type |
| - | - | - |
| Patient | `"2026-11-09 17:59:58.817+00"` | string |
| Appointment | `"2"` | string |
| Webhook | `2` | integer |
| Data area (`/v1/platform-policy`) | `0` | integer |

Send it with the type the resource gave it: a string where `version` is a string, a number where it is a number.

## Operations that need it

| Operation | Conflict code |
| - | - |
| `PATCH /v1/patients/{id}`, `POST /v1/patients/{id}/archive` | `VERSION_CONFLICT` |
| `POST /v1/appointments/{id}/reschedule`, `POST /v1/appointments/{id}/cancel` | `VERSION_CONFLICT` |
| `POST /v1/webhooks/{id}/rotate-secret`, `POST /v1/webhooks/{id}/delete` | `WEBHOOK_VERSION_CONFLICT` |
| `PATCH /v1/platform-policy/{id}` | `DATA_POLICY_VERSION_CONFLICT` |

Creates do not take one: there is nothing to overwrite.

## Handle a 409

Do not retry the same request: it will fail again. Read the record, check whether your change still makes sense with the new data (the appointment may already be cancelled), and send a new request with the new version and a new `Idempotency-Key`.

```javascript Node.js theme={null}
const BASE = 'https://api.brelio.app/v1'
const AUTH = { Authorization: `Bearer ${process.env.BRELIO_API_KEY}` }

async function updatePhone(patientId, phone) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const patient = await (await fetch(`${BASE}/patients/${patientId}`, { headers: AUTH })).json()
    const response = await fetch(`${BASE}/patients/${patientId}`, {
      method: 'PATCH',
      headers: { ...AUTH, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
      body: JSON.stringify({ expectedVersion: patient.version, phone }),
    })
    if (response.status !== 409) return response.json()
  }
  throw new Error('The patient keeps changing; try later')
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.