artifact_edit

Edit an artifact card in place. Pass the card’s message_id plus only the fields you want to change; everything else is preserved. The merged spec is validated before the edit is applied.

User guide / All capabilities

Contract

Effect: write. Evidence role: discovery_only.

Edit an artifact card.

Parameters

This is the current provider-facing JSON Schema, generated from the runtime definition.

{
  "type": "object",
  "properties": {
    "expected_revision": {
      "type": "number",
      "description": "Current revision returned by artifact_read. If supplied, reject an edit when the card has changed since it was read."
    },
    "message_id": {
      "type": "string",
      "description": "Message ID of the artifact card to edit, from the artifact_send result."
    },
    "title": {
      "type": "string",
      "description": "New card title. Omit to keep the current one."
    },
    "summary": {
      "type": "string",
      "description": "New summary. Omit to keep the current one."
    },
    "sections": {
      "type": "array",
      "description": "Replacement sections (1 to 50). Omit to keep the current ones. This replaces the whole list, not a partial patch.",
      "items": {
        "type": "object",
        "properties": {
          "heading": {
            "type": "string",
            "description": "Optional section heading, max 80 chars."
          },
          "body": {
            "type": "string",
            "description": "Section body, markdown allowed, max 3000 chars."
          },
          "thumbnail_url": {
            "type": "string",
            "description": "Optional direct https image URL rendered top-right of this section like an embed thumbnail."
          },
          "accessory_button": {
            "type": "object",
            "description": "Optional button accessory (right side). Provide either thumbnail_url or accessory_button, not both.",
            "properties": {
              "label": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "customId": {
                "type": "string"
              },
              "style": {
                "type": "number"
              },
              "emoji": {
                "type": "string"
              }
            },
            "required": [
              "label"
            ]
          }
        },
        "required": [
          "body"
        ]
      }
    },
    "gallery": {
      "type": "array",
      "description": "Replacement image grid below the content (max 10 direct https image URLs). Omit to keep the current one.",
      "items": {
        "type": "string"
      }
    },
    "files": {
      "type": "array",
      "description": "Replacement file cards (max 10 https file URLs). Omit to keep the current ones.",
      "items": {
        "type": "string"
      }
    },
    "accent_color": {
      "type": "number",
      "description": "New accent color as an integer (0 to 0xffffff). Omit to keep the current one."
    },
    "spoiler": {
      "type": "boolean",
      "description": "Gray out the whole card. Omit to keep the current value."
    },
    "navigation": {
      "type": "object",
      "description": "Replacement navigation config ({type:'select'} or {type:'pagination'}). Omit to keep the current one.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "select",
            "pagination"
          ],
          "description": "Navigation style."
        }
      },
      "required": [
        "type"
      ]
    },
    "action_rows": {
      "type": "array",
      "description": "Replacement custom interactive rows (max 5). Each row is buttons or a select (string/user/role/mentionable/channel). Omit to keep the current ones.",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "buttons",
              "stringSelect",
              "userSelect",
              "roleSelect",
              "mentionableSelect",
              "channelSelect"
            ]
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "style": {
                  "type": "number"
                },
                "customId": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "emoji": {
                  "type": "string"
                },
                "disabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "label"
              ]
            }
          },
          "customId": {
            "type": "string"
          },
          "placeholder": {
            "type": "string"
          },
          "minValues": {
            "type": "number"
          },
          "maxValues": {
            "type": "number"
          },
          "channelTypes": {
            "type": "array",
            "items": {
              "type": "number"
            }
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "emoji": {
                  "type": "string"
                },
                "default": {
                  "type": "boolean"
                }
              },
              "required": [
                "label",
                "value"
              ]
            }
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "game_state": {
      "type": "object",
      "description": "Replacement game state JSON (max ~4000 chars serialized). Persisted per card for minigames.",
      "properties": {},
      "required": []
    },
    "handlers": {
      "type": "object",
      "description": "Replacement sandboxed JS handlers keyed by customId. Omit to keep the current ones. Same VM contract as artifact_send.",
      "properties": {},
      "required": []
    },
    "link_buttons": {
      "type": "array",
      "description": "Replacement https link buttons (max 5). Omit to keep the current ones.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Button label, max 80 chars."
          },
          "url": {
            "type": "string",
            "description": "Absolute https URL the button opens."
          },
          "emoji": {
            "type": "string",
            "description": "Optional emoji shown before the label."
          }
        },
        "required": [
          "label",
          "url"
        ]
      }
    },
    "ttl_days": {
      "type": "number",
      "description": "New retention in days, counted from now. 0 removes the expiry."
    },
    "rearm": {
      "type": "boolean",
      "description": "No content change: re-render the card's controls with fresh, correctly-namespaced custom ids. Use when the user reports buttons not responding (legacy cards, bot restarts, or disabled controls). Needs no other fields."
    }
  },
  "required": [
    "message_id"
  ]
}

Execution requirements

• actor_grant
• the card was sent by this bot and exists in the artifacts store

Expected postconditions

• card re-rendered with the merged spec