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

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)

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 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.

[
  { "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)

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 the conflict error WGL409005. 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.

The following table shows which requests need it.

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).

Related documents

• System properties (sys): The sys.version carried in X-Weegloo-Version.
• Common query parameters: List reads and pagination.
• Errors: Error codes such as WGL409005.