Optimistic concurrency (expectedVersion)

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

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

# 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:

409 VERSION_CONFLICT

{
  "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.

Node.js

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')
}

Get started

Concepts

Guides

MCP reference

Reference

Optimistic concurrency (expectedVersion)

The rule

Treat the version as opaque

Operations that need it

Handle a 409

​The rule

​Treat the version as opaque

​Operations that need it

​Handle a 409

The rule

Treat the version as opaque

Operations that need it

Handle a 409