Identify a business identifier or set of search parameters that uniquely identifies the resource (e.g., Patient?identifier=system|value)
Send PUT [base]/[ResourceType]?[search parameters] with the full resource body; do not include an id in the URL path — include the business identifier in the resource body
If the server finds exactly one matching resource it performs an update (200 or 204); if it finds zero matching resources it creates a new one and returns 201 Created
Inspect the response Location header on 201 to obtain the server-assigned logical id and record it for future direct access
If the server finds more than one matching resource it returns 412 Precondition Failed or 422; refine the search parameters to ensure uniqueness
Use the ETag from a prior read in If-Match for concurrent update safety if the resource may have been updated since last read
Known gotchas
The search parameters in the URL must resolve to at most one resource; ambiguous matches result in a server error, not a silent merge
Conditional update does not support partial updates — the entire resource body replaces the existing resource; ensure all fields including those not being modified are present in the body
Some servers require the resource id in the body to match the server-assigned id on update; for conditional update (no id in URL) leave the id out of the body or use a placeholder that the server will replace
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp