Artifact URLs, IDs and Copy for agent

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/<id>`	`https://sidecars.ai/artifacts/k97fq2example000000000000000000`
MCP tool argument	`document_id` (or `page_id` for page tools)	`"document_id": "k97fq2example000000000000000000"`
MCP resource URI	`sidecars://document/<id>`	`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 in the artifact header, which includes both the URL and the bare id.
From MCP: 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` by pod or title, the conversation’s URL in the app, or `parent.conversation_id` on `read_document`
`pod_id`	A pod	`list_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):

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:

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

Prefer the live version when connected

If the Sidecars MCP server is connected, call read_document with the Artifact ID to get the latest saved content and its version.

Merge unsaved edits, do not overwrite

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.

Write back through MCP, or say you did not

Save changes with edit_document. Without MCP access, work from the snapshot and tell the person the original was not updated.

Get started

Use it

Reference

Artifact URLs, IDs and Copy for agent

Getting an id

Ids for other things

Kinds of artifact

Versions

Copy for agent

The handoff format

How an agent should treat it

​Getting an id

​Ids for other things

​Kinds of artifact

​Versions

​Copy for agent

​The handoff format

​How an agent should treat it

Getting an id

Ids for other things

Kinds of artifact

Versions

Copy for agent

The handoff format

How an agent should treat it