Update Resource

Method: PUT /{api_prefix}/{collection_path}/{resource_key}/ Auth: Flux API Key — always required for writes, even on public APIs. The key's role must grant update on this API, and the target collection's connection must allow update (off by default).

Replaces a resource's document with a new revision and publishes it immediately. This is a full-document replace, not a partial patch — send the complete document. The REST twin of the MCP update_record tool.

URL Pattern

PUT https://{environment_key}.fxns.io/{api_prefix}/{collection_path}/{resource_key}/

There is no PATCH: partial updates would diverge from the revision model, where every revision is a complete, schema-valid document. PATCH returns 405 with a hint to use PUT.

Request Body

Name
data
Type
object
Required
required
Description
The full replacement document. Must match the collection schema — invalid documents return 422 with the standard content validation payload.

Conditional Updates

An update is unconditional by default: it replaces whatever is there now, which is the right behaviour when one writer owns the record. When two do — two agents, or an agent and a human — send the revision you read as an If-Match header and the write applies only if the record is still at that revision:

curl -sS -X PUT "https://7c9h4pwu.fxns.io/assistant/users/usr_8f2k1/memories/kDLT9jjrcAzh/" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "If-Match: 8f2b1c9d" \
  -H "Content-Type: application/json" \
  -d '{"data": {"content": "Prefers concise answers."}}'

The value is the revision field of the _sys block on the read that produced the record — see Get Resource. Quotes are accepted; weak validators (W/"...") and * are not.

Status	`error_code`	Meaning	What to do
412	`revision_precondition_failed`	The record moved on. `detail.current_revision` names the revision that is current now.	Re-read, recompute, then write.
409	`revision_number_conflict`	Two writers collided on the next revision number; nothing was lost.	Retry the same write.
422	`invalid_revision_precondition`	The header is malformed. Rejected at the edge, before the write is forwarded.	Fix the header.
501	`conditional_write_disabled`	The deployment does not have conditional writes enabled. The edge refuses rather than applying the write unconditionally.	Use a deployment that has them enabled, or contact support. Dropping the header lets the update proceed unconditionally, subject to the usual errors — the protection is gone, not degraded.

Full semantics: Conditional writes.

POST (create) does not accept If-Match. A precondition names a revision that must still be current, and a record being created has none.

Response

200 OK:

{
  "resource_key": "kDLT9jjrcAzh",
  "revision_key": "r_2xX0",
  "write_units": 1,
  "published": true
}

The previous revision is preserved in the revision history (Management API); the new revision becomes current and is re-vectorized, so search reflects the update once embedding completes.

Example

curl -sS -X PUT "https://7c9h4pwu.fxns.io/assistant/users/usr_8f2k1/memories/kDLT9jjrcAzh/" \
  -H "Authorization: Simple <public_key>:<private_key>" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "content": "Prefers concise answers; time zone changed to EET.",
          "kind": "preference",
          "source": "chat-2026-07-22"
        }
      }'

Errors

Same table as Create Resource, with these differences: 404 also covers an unknown resource_key; 409 external_id_conflict does not apply (no key field on update); and this route alone can return the conditional-write outcomes — 409 revision_number_conflict, 412, 422 invalid_revision_precondition and 501 — listed in Conditional Updates.

Create Resource — POST, create + publish.
MCP write tools — the same operations over MCP, where the precondition is the expected_revision argument.
Get Resource — verify a write's outcome after a 502.