> ## 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.
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
The artifact's id.
## Body parameters
A new title. Cannot be null.
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.
The complete new BlockLayout, with camelCase keys. Replaces the whole layout and creates a new version. Requires `expected_version`.
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.
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.