> ## Documentation Index > Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update Artifact > Rename an artifact or replace its layout. > [!NOTE] > > Artifacts are in preview. These endpoints are available only to organisations with the Visual Builder enabled; elsewhere they return `404` with an empty body. Only the fields you send are changed. An explicit `null` clears `description`; `name` and `layout` cannot be null. Sending `layout` replaces the whole layout and creates a new version. It requires `expected_version`, the version you last read. With `expected_version`, any concurrent edit to the artifact can refuse the update: nothing is written and the response is a `409`: ```json theme={null} { "error_code": "artifact_version_conflict", "ws_api_error_code": "artifact_version_conflict", "message": "This artifact changed since you read it. Fetch it again, reapply your change and retry.", "current_version": 3 } ``` The conflicting edit does not have to be a layout change. A rename or a description edit saved while your update ran also returns the `409`, and it leaves the version where it was. So `current_version` can equal the `expected_version` you sent. Either way, fetch the artifact again, reapply your change to what you fetched and retry. A name or description change does not create a version. Such a change does not need `expected_version`; if you send it, the update can return the `409` in the same way. Without `expected_version`, a name or description change that races another edit of the same field is retried once on the server. If it loses again, the response is the `409` above: send the change again. The response lists in `warnings` any problem that did not block the write, such as an `unknown_field` issue for a misspelt key the server dropped. It is empty when there are none or you sent no `layout`. An artifact you can view but not edit is a `404`, as is one you cannot open. The layout of an artifact with `has_data_sources` cannot be replaced here: sending `layout` for one is a `400` with `error_code` `artifact_layout_read_only`. Check `can_edit_layout` on the artifact before you send a layout; `can_edit` covers only the name, the description and deleting. Do not retry it with a different layout: only Wordsmith chat can change this artifact's layout. Its `name` and `description` can still be changed. A layout that fails validation is a `400` listing every problem by path: ```json theme={null} { "error_code": "artifact_layout_invalid", "ws_api_error_code": "artifact_layout_invalid", "message": "blocks[1].items[0].href: Only https, http and mailto URLs, or paths starting with /, are allowed here.", "errors": [ { "path": "blocks[1].items[0].href", "code": "unsafe_url", "message": "Only https, http and mailto URLs, or paths starting with /, are allowed here." } ], "warnings": [] } ``` A layout over 2 MB is a `400` with `error_code` `artifact_layout_too_large`. Check a layout first with [Validate Layout](/api-reference/artifacts/validate-layout). ## Path parameters **artifact\_id** `string (uuid)` *required* The artifact's id. ## Body parameters **name** `string` A new title. Cannot be null. **description** `string` A new summary. Send null to clear it. At most 2,000 characters; a longer one is a `400` with `error_code` `bad_request`. The stored description can be sent back unchanged even if it is longer, so an artifact you fetched can always be pushed back. **layout** `object` The complete new BlockLayout, with camelCase keys. Replaces the whole layout and creates a new version. Requires `expected_version`. **expected\_version** `integer` The version you last read. With it, any concurrent edit to the artifact can return a `409`, including a rename that does not change the version. On a `409`, fetch the artifact again and retry, even when `current_version` equals the version you sent. Required when `layout` is sent; optional otherwise. **change\_summary** `string` A short note for the version history, e.g. "Added the Globex renewal". Recorded only when the layout changes. ```bash cURL theme={null} curl --location --request PATCH 'https://api.wordsmith.ai/api/v1/artifacts/3f2c9a1e-7b4d-4e8a-9c6f-2d1b0a9e8f7c' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "layout": { "type": "document", "title": "Q3 contract review", "blocks": [ { "type": "header", "title": "Summary" }, { "type": "callout", "title": "Key finding", "body": "Three supplier agreements renew automatically before the notice window closes.", "variant": "warning" }, { "type": "table", "headers": [ "Agreement", "Renewal date" ], "rows": [ [ "Acme supply", "2026-11-01" ], [ "Globex services", "2026-12-15" ] ] } ] }, "expected_version": 1, "change_summary": "Added the Globex renewal" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.wordsmith.ai/api/v1/artifacts/3f2c9a1e-7b4d-4e8a-9c6f-2d1b0a9e8f7c", { method: "PATCH", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ "layout": { "type": "document", "title": "Q3 contract review", "blocks": [ { "type": "header", "title": "Summary" }, { "type": "callout", "title": "Key finding", "body": "Three supplier agreements renew automatically before the notice window closes.", "variant": "warning" }, { "type": "table", "headers": [ "Agreement", "Renewal date" ], "rows": [ [ "Acme supply", "2026-11-01" ], [ "Globex services", "2026-12-15" ] ] } ] }, "expected_version": 1, "change_summary": "Added the Globex renewal" }), }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = "https://api.wordsmith.ai/api/v1/artifacts/3f2c9a1e-7b4d-4e8a-9c6f-2d1b0a9e8f7c" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", } payload = { "layout": { "type": "document", "title": "Q3 contract review", "blocks": [ { "type": "header", "title": "Summary" }, { "type": "callout", "title": "Key finding", "body": "Three supplier agreements renew automatically before the notice window closes.", "variant": "warning" }, { "type": "table", "headers": [ "Agreement", "Renewal date" ], "rows": [ [ "Acme supply", "2026-11-01" ], [ "Globex services", "2026-12-15" ] ] } ] }, "expected_version": 1, "change_summary": "Added the Globex renewal" } response = requests.patch(url, headers=headers, json=payload) print(response.json()) ``` ```json Response theme={null} { "id": "3f2c9a1e-7b4d-4e8a-9c6f-2d1b0a9e8f7c", "name": "Q3 contract review", "description": "Renewal risks across supplier agreements.", "version": 2, "visibility": "private", "has_data_sources": false, "can_edit": true, "can_edit_layout": true, "created_by": { "id": "11111111-2222-3333-4444-555555555555", "name": "Jane Doe", "email": "jane@example.com" }, "last_edited_by": { "id": "11111111-2222-3333-4444-555555555555", "name": "Jane Doe", "email": "jane@example.com" }, "created_at": "2026-09-30T09:15:00Z", "updated_at": "2026-09-30T10:02:00Z", "web_url": "https://app.wordsmith.ai/artifacts/3f2c9a1e-7b4d-4e8a-9c6f-2d1b0a9e8f7c", "layout": { "type": "document", "title": "Q3 contract review", "blocks": [ { "type": "header", "title": "Summary" }, { "type": "callout", "title": "Key finding", "body": "Three supplier agreements renew automatically before the notice window closes.", "variant": "warning" }, { "type": "table", "headers": [ "Agreement", "Renewal date" ], "rows": [ [ "Acme supply", "2026-11-01" ], [ "Globex services", "2026-12-15" ] ] } ], "version": "1" }, "warnings": [] } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.