Update Artifact

Rename an artifact or replace its layout.

PATCH /api/v1/artifacts/{artifact_id}

cURL

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"
}'

Response

{
  "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": "[e-mail]"
  },
  "last_edited_by": {
    "id": "11111111-2222-3333-4444-555555555555",
    "name": "Jane Doe",
    "email": "[e-mail]"
  },
  "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": []
}

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:

{
  "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:

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

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.

cURL

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"
}'

Response

{
  "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": "[e-mail]"
  },
  "last_edited_by": {
    "id": "11111111-2222-3333-4444-555555555555",
    "name": "Jane Doe",
    "email": "[e-mail]"
  },
  "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": []
}