> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidecars.ai/llms.txt > Use this file to discover all available pages before exploring further. # Artifact URLs, IDs and Copy for agent > How an artifact's URL, document_id and sidecars:// URI relate, the artifact kinds and versions, and the Copy for agent handoff format. Documents, HTML pages and tables are all **artifacts**. One artifact has one id, and that id appears in three places. | Where | Form | Example (fictional) | | ----------------- | ------------------------------------------- | --------------------------------------------------------------- | | Web app URL | `https://sidecars.ai/artifacts/` | `https://sidecars.ai/artifacts/k97fq2example000000000000000000` | | MCP tool argument | `document_id` (or `page_id` for page tools) | `"document_id": "k97fq2example000000000000000000"` | | MCP resource URI | `sidecars://document/` | `sidecars://document/k97fq2example000000000000000000` | The id is an opaque string. Treat it as a token you copy, never something you parse or construct. ## Getting an id * **From the app:** the address bar of an open artifact, or [Copy for agent](/reference/artifacts#copy-for-agent) in the artifact header, which includes both the URL and the bare id. * **From MCP:** [`list_documents`](/reference/documents#list_documents) returns `document_id` for every row, and every create tool returns the id of what it created. * **From knowledge search:** `search_knowledge` and `ask_knowledge` return a `document_id` too, but that is the knowledge base's identifier for an ingested source. It is **not** guaranteed to be an artifact id and cannot be passed to the document tools unless the source is itself a Sidecars document. ## Ids for other things | Argument | What it names | Where you get it | | ----------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `conversation_id` | A room in a pod | [`list_conversations`](/reference/conversations) by pod or title, the conversation's URL in the app, or `parent.conversation_id` on `read_document` | | `pod_id` | A pod | [`list_conversations`](/reference/conversations) by name or slug, the pod's URL in the app, or `pod_id` on a `list_documents` row | | `thread_id` | A comment thread | `read_comments`, or the `thread_id` returned by `add_comment` | | `version_id` | A checkpoint or named version | `get_document_versions` (informational; no tool takes it as input) | ## Kinds of artifact `read_document` and `list_documents` report a `type`: | `type` | What it is | Read with | Write with | | ---------- | --------------------------------------------- | --------------------------------------------------------------- | --------------------- | | `document` | A collaborative markdown document | `read_document` | `edit_document` | | `html_app` | An HTML page | `read_page` (or `read_document`, which returns the HTML source) | `write_page` | | `table` | A grid filled in by the agent that created it | `read_document` | Not editable over MCP | Using the wrong write tool for a kind is refused with a message that names the right one. ## Versions Every read of a document or page returns a `version` number, and every successful write returns `new_version`. Versions move on every saved change, including human keystrokes. How each write tool treats `expected_version` is described on its reference page; the short version: * `write_page` and `edit_document` with `replace_all` **require** it and refuse on mismatch. * `edit_document` with `replace_section` uses the quoted excerpt as the freshness check and only **reports** drift. * `edit_document` with `append` treats it as informational. ## Copy for agent Every open document in the app has a **Copy** split button in its header, left of Share. It reads the live editor, so what you copy is exactly what is on screen, saved or not. | Action | What you get | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Copy** (main click) | The document as markdown, with the title as an `# H1` over the body | | **Copy as Markdown** | The same markdown | | **Copy for agent** | A self-contained handoff: an instruction line, the document's metadata, a pointer to the MCP tools, and the markdown snapshot | | **Download .md** | The markdown as a file named after the title slug (for example `q3-launch-plan.md`) | Copying never changes sharing or access. The URL in the handoff is the same one in the address bar and is gated by the same roles. ### The handoff format **Copy for agent** produces text shaped like this (fictional example): ```text theme={null} This is a snapshot of the document identified below. If you have access through the source URL or a connected artifact tool, retrieve the latest version before making changes. Otherwise, work from the included content. Do not claim to have updated the original unless you successfully save changes through an authorized integration. Title: Q3 launch plan Source URL: https://sidecars.ai/artifacts/k97fq2example000000000000000000 Artifact ID: k97fq2example000000000000000000 Last saved: 2026-09-06T14:12:09.000Z Connected artifact tool: the Sidecars MCP server's `read_document` (document_id: k97fq2example000000000000000000) returns the latest saved version; `edit_document` saves changes with permission checks. --- # Q3 launch plan ### Goals - Ship the Acme integration by 15 October ... ``` When the editor holds edits the server has not confirmed yet, an extra block appears before the divider: ```text theme={null} UNSAVED CHANGES: this snapshot includes edits that were not yet saved when it was copied. The linked version may differ from the content below. Preserve these edits — do not discard them in favour of the linked version. ``` `Last saved` is included in every handoff. ### How an agent should treat it If the Sidecars MCP server is connected, call [`read_document`](/reference/documents#read_document) with the `Artifact ID` to get the latest saved content and its `version`. If the handoff carries the `UNSAVED CHANGES` block, the snapshot holds edits the server never saw, and the server copy may have moved on since the copy was taken (`Last saved` tells you when). Neither side is simply newer. Read the live version, carry the snapshot's edits into it, and write the merged result with `expected_version` from that read; on `version_conflict`, read again and merge again. Save changes with [`edit_document`](/reference/documents#edit_document). Without MCP access, work from the snapshot and tell the person the original was not updated.