Writes, versions, and retries

Read before changing a resource

Get the resource before changing it. When a route requires expected_version, send the version from that read without incrementing it yourself. Versions can be strings or integers; use the type shown for that endpoint.

A workflow can also require its current target version and Attio workflow version. A merge execution requires the exact plan revision, its returned digests, and current authorization versions. Copy these values from the relevant read response; do not manufacture them.

Request keys

For a write whose reference requires a request key, send it in the REST Idempotency-Key header. The same value is the request_key argument in MCP. Other writes, including lookup-row PATCH and DELETE, do not use this mechanism. Follow the operation’s reference.

Generate a new value for a new intended action. Keep the same value and request content when retrying an action after a lost response or timeout. Reusing a key for a different request can be refused. Creating a fresh key for every retry can repeat the effect.

Lookup-row writes and other API families can have different retry behavior. The operation's reference describes what is replayed. Retrying an accepted request is not a rollback, and work completed before a timeout can remain.

Follow accepted work

An HTTP 202 response means work was accepted. Follow its returned operation or status resource until it finishes. A successful operation can still contain unsuccessful items; inspect those outcomes before retrying them.

Use operation status for scans, merge work, and other requests that return an operation. Table configuration work can instead be followed through the table settings and pending_work; CSV imports have their own status resource.

Handle conflicts and partial results

If a resource changed, get it again and review the new state before repeating a write. Do not automatically replace the expected version with the latest one without checking what changed.

Inspect each item's outcome in a batch response. Stopping an import or canceling remaining work does not undo changes that completed. A request that reports an uncertain result needs inspection before a new attempt.

Rate limits and temporary failures

Use Retry-After when returned and back off between retries. Inspect the current state after a write whose response was lost. See rate limits and errors. Do not retry authentication, permission, or invalid-input errors unchanged.