Agent API

The Agent API exposes the same high-level methods as the Coview MCP server over HTTP. Agents should use this API instead of writing directly to document sync endpoints.

Base URL:

https://coview.dev/api/agents

Call a method with:

POST https://coview.dev/api/agents/{method}
Content-Type: application/json

The live machine-readable catalog is available at:

GET https://coview.dev/api/agents

A generic presentation example is available at:

GET https://coview.dev/api/agents/examples/presentation

Document id

Use the document id from the Coview document URL. In https://coview.dev/d/my-document-id, the documentId is my-document-id.

write_html also accepts documentUrl, so an agent can pass the canvas link directly.

Use create_document only when you need a fresh document.

Fast flow

1. Call get_basic_info.
2. Use get_tree_summary to choose targets.
3. Inspect specific nodes with get_node.
4. Create or replace larger sections with write_html.
5. Refine with update_styles, set_text_content, rename_nodes, duplicate_nodes, move_nodes, or delete_nodes.
6. Use get_screenshot to check layout, clipping, contrast, and spacing.

For creating or replacing a presentation, use write_html with full HTML frames. Send multiple 1280x720 <section> elements and pass targetNodeId:"root" when replacing the canvas directly. Use mode:"insert-children" to append top-level objects to root or append inside an existing frame/flex-frame.

Do not send raw operation batches through the Agent API. The document changes API under /api/v1/documents/... is for the Coview app runtime, not agent editing.

Methods

Method	Endpoint	Purpose
get_guide	/get_guide	Return fast workflow and layout guidance.
get_basic_info	/get_basic_info	Return document metadata, canvas summary, endpoint URLs, fonts, and guidance.
create_document	/create_document	Create a blank document and return its documentId, path, and URL.
request_access_token	/request_access_token	Create a short-lived bearer token for one private document from an authenticated context.
request_user_validation	/request_user_validation	Create a consent URL and pending API key for private documents owned by the approving user.
update_document_metadata	/update_document_metadata	Update document-level metadata such as the title.
get_selection	/get_selection	Return the current selected node, if any.
get_node	/get_node	Return focused geometry, style, text, parent, and child ids for one node or root.
get_children	/get_children	List direct children for the root canvas or one node.
get_tree_summary	/get_tree_summary	Return a compact hierarchy for choosing edit targets.
get_screenshot	/get_screenshot	Return a visual verification image. It defaults to fast SVG rendering; use renderer:"browser" only for final PNG browser fidelity.
get_jsx	/get_jsx	Return inline-style JSX for a node.
get_computed_styles	/get_computed_styles	Return inline style objects for one or more nodes.
get_font_family_info	/get_font_family_info	Check available font families and weights before styling text.
create_artboard	/create_artboard	Create a top-level frame or flex-frame.
write_html	/write_html	Parse HTML and replace a target node, or insert children when requested.
insert_nodes	/insert_nodes	Insert structured Coview nodes into a parent or as top-level canvas nodes.
update_styles	/update_styles	Merge style properties into nodes.
set_text_content	/set_text_content	Set text content for text nodes and convert targets to text when needed.
rename_nodes	/rename_nodes	Rename nodes for clearer layer inspection.
duplicate_nodes	/duplicate_nodes	Duplicate nodes with fresh ids.
move_nodes	/move_nodes	Move, reparent, or reorder nodes without resizing them.
delete_nodes	/delete_nodes	Delete nodes by id.

Examples

Create an artboard:

curl -s https://coview.dev/api/agents/create_artboard \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","name":"Poster","styles":{"width":390,"height":844,"background":"#ffffff"}}'

Replace an artboard with HTML:

curl -s https://coview.dev/api/agents/write_html \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","targetNodeId":"frame-id","mode":"replace","html":"<section style=\"position:relative;width:100%;height:100%\"><p id=\"headline\" style=\"position:absolute;left:56px;top:236px;width:590px;font-size:72px;line-height:78px\">Build Coview with agents</p></section>"}'

Create or replace a presentation from HTML:

curl -s https://coview.dev/api/agents/write_html \
  -H "content-type: application/json" \
  -d '{"documentUrl":"https://coview.dev/d/my-document-id","targetNodeId":"root","html":"<section id=\"slide-one\" style=\"width:1280px;height:720px;background:#f8fafc;color:#0f172a;font-family:Inter,Arial,sans-serif;position:relative\"><h1 style=\"position:absolute;left:72px;top:180px;font-size:64px;line-height:1.05\">Project plan</h1><p style=\"position:absolute;left:76px;top:320px;width:640px;font-size:24px;line-height:1.35\">A clear opening frame.</p></section><section id=\"slide-two\" style=\"width:1280px;height:720px;background:#ffffff;color:#111827;font-family:Inter,Arial,sans-serif;display:flex;flex-direction:column;gap:28px;padding:72px\"><h2 style=\"font-size:52px;line-height:1.08;margin:0\">Agenda</h2><p style=\"font-size:24px;line-height:1.4;margin:0;color:#4b5563\">Context, approach, and next steps.</p></section>"}'

Inspect the root:

curl -s https://coview.dev/api/agents/get_node \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","nodeId":"root"}'

Request user approval for private document access:

curl -s https://coview.dev/api/agents/request_user_validation \
  -H "content-type: application/json" \
  -d '{"documentId":"my-document-id","role":"editor"}'

HTML authoring

write_html accepts normal HTML fragments or full HTML documents. By default it replaces the selected node or root canvas content when no targetNodeId is passed. Pass targetNodeId to replace a specific node, or pass targetNodeId:"root" to force root canvas replacement even when another node is selected. Replace mode accepts one or more root HTML elements. Use mode:"insert-children" to append top-level objects to root or add nodes inside an existing frame/flex-frame.

Coview preserves normalized CSS intent: property names become camelCase, authored CSS values stay CSS strings, mixed direct text is preserved in flow order, and data-coview-name sets the Coview layer name.

Return shapes

Method	Return shape
create_document	{ documentId, path, url }
get_screenshot	{ documentId, nodeId, format, mimeType, renderer, width, height, scale, data }
Edit methods	{ version, ...specificResult }
update_document_metadata	{ documentId, metadata, version }

Direct edit calls return the persisted version plus method-specific ids or geometry. They do not repeat the request documentId, current selection, or low-level operation summary.

write_html also returns recommendedNextCall for get_screenshot so agents can verify the rendered result before continuing.