# Conventions

This page collects, in one place, the HTTP conventions that apply to every request and response when you call the WEEGLOO API from code. They cover the response media type, partial updates (JSON Patch), and the `X-Weegloo-Version` header that prevents concurrent-edit conflicts. The endpoints of each individual resource are covered in that resource's reference, and those endpoints refer to this page for the conventions they share.

## Response media type {#response-media-type}

WEEGLOO API responses use the `application/vnd.com.weegloo.v1+json;charset=UTF-8` media type. It is not plain `application/json`.

Do not send `Accept: application/json` on your requests. Negotiating the media type against that value does not match WEEGLOO's vendor type and can cause failures such as `406 Not Acceptable`.

- Recommended: omit the `Accept` header on requests (for example, do not set `Accept` on `fetch`).
- If you must send it, use the same vendor type as the response, `application/vnd.com.weegloo.v1+json;charset=UTF-8`, exactly.

When you build an `axios` instance or a shared `fetch` wrapper, make sure its defaults do not force `Accept: application/json`. (This rule applies to application code. AI agents do not call HTTP directly; they use MCP tools.)

## Partial updates (JSON Patch) {#partial-updates-json-patch}

Most resources, such as *Content*, *Media*, and *Content Type*, can be updated in part using `PATCH`. The body is an array in the [RFC 6902 JSON Patch](https://www.rfc-editor.org/rfc/rfc6902) format. Each entry has an `op` (the operation), a `path` (a JSON Pointer to the target location), and, depending on the operation, a `value` or a `from`.

The `Content-Type` header of a `PATCH` request must be `application/json-patch+json`. It is not plain `application/json`.

The following example changes only one field's value.

```json
[
  { "op": "replace", "path": "/fields/price/en-US", "value": 16500 }
]
```

To replace the entire body, use `PUT`. `PUT` replaces the resource with the full body (or, where the endpoint contract allows it, with a partial body containing only the parts you intend to change). Which endpoints support `PATCH`, and whether a given `PUT` is a full or partial replacement, is documented in the endpoint block on each resource page.

## Concurrency control (X-Weegloo-Version) {#concurrency-control-x-weegloo-version}

If the same resource is edited in two places at once, one change can overwrite the other. To prevent this, WEEGLOO uses optimistic concurrency control. When you update, delete, or change the state of a resource, you send the current `sys.version` in the `X-Weegloo-Version` header.

The server accepts the change only when this value matches the current stored version. If the header is missing or the value does not match (for example, when someone else edited it first and the version went up in the meantime), the request is rejected with a conflict error. When this happens, read the resource again to get the latest `sys.version`, then retry the change. The error response format is covered in [Errors](/api/reference/common/errors.md).

The following table shows which requests need it.

| Operation | `X-Weegloo-Version` |
|---|---|
| Update (`PUT`) and partial update (`PATCH`) | Required |
| State transitions (publish, unpublish, archive, unarchive) | Required |
| Create (`POST`) | Not used |
| Delete (`DELETE`) | Required for some |

Resources that have no `version` (*ServiceUser*) do not accept this header. To find out exactly which endpoints require this header, check the `requestHeaderSchema` in the endpoint block on each resource page. The meaning of `sys.version` itself is covered in [System properties (sys)](/api/reference/common/system-properties.md).

## Related documents {#related-documents}

- [System properties (sys)](/api/reference/common/system-properties.md): The `sys.version` carried in `X-Weegloo-Version`.
- [Common query parameters](/api/reference/common/query-parameters.md): List reads and pagination.
- [Errors](/api/reference/common/errors.md): Error codes such as `WGL409005`.