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

# Writes and concurrency

> Retry mutations safely and protect against stale updates.

Send JSON with `Content-Type: application/json` when an operation accepts a request body. Unknown fields are rejected. Omitted update fields stay unchanged; `null` is accepted only for fields declared nullable.

## Idempotency

Every POST request requires an `Idempotency-Key` of at most 128 bytes. Generate a unique key for each logical mutation. If you retry that mutation, reuse the same key and body. Other mutation methods accept an optional key.

```http theme={null}
Idempotency-Key: 2f51b5e4-6d66-49e7-9f59-2ac2bd124e0a
```

The value above is illustrative. Generate a fresh value for your own operation. Reusing a key with a different request can produce a conflict.

## Conditional updates

For operations that require `If-Match`, read the resource first and preserve its `ETag` response header. Send that exact value with your mutation:

```http theme={null}
If-Match: "<etag-from-read-response>"
```

If the server returns `412`, fetch the latest resource and reconcile your changes before retrying. A `428` response indicates that a required precondition was missing.

Some nested resources use their parent's version: automation triggers use the automation ETag, and Marketplace items use the release ETag. The endpoint reference identifies these cases.

Knowledge content writes additionally require `expected_version` from the document's version field.

## Asynchronous work

A `202 Accepted` response confirms that work was admitted, not that it completed successfully. Follow the returned operation or run to observe its result. Handle failure and any state that requires attention before treating the work as complete.

## Payload limits

The default request-body limit is 2 MiB, including bodies sent with read requests. Some artwork operations have a different limit; use the limit documented on the specific endpoint.


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