The Places API provides read-only access to places (workspaces/canvases) in a project. Use it to list all places or filter by project.

Capability required: places:read

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// List places in a specific project
const places = await rp.places.list("project-id-123");
// -> [{ id: "p1", title: "Homepage", slug: "homepage", projectId: "project-id-123", ... }]

// List all places across all projects
const allPlaces = await rp.places.list();

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    getPlaces: async (_params, { rp }) => {
      return await rp.places.list("project-id");
    },
  },
});

server.start();

MCP

Every rp.places.* method is exposed via the CallRegistry hook with the rightplace_places_ prefix. Reads require places:read; writes require places:write.

Tool	Purpose	Permission
rightplace_places_listTabs	All tabs in a place	places:read
rightplace_places_listPanes	All panes in a layout	places:read
rightplace_places_loadLayout	Persisted layout tree	places:read
rightplace_places_getActive	Active place + project	places:read
rightplace_places_getFocusedPane	Focused pane + tab	places:read
rightplace_places_listOpenTabs	Tabs in the currently-active place	places:read
rightplace_places_openTab	Open a new tab	places:write
rightplace_places_openResource	Open a user resource as a tab	places:write
rightplace_places_openTool	Open a project-level tool (terminal / browser / etc.)	places:write
rightplace_places_selectTab	Focus an existing tab	places:write
rightplace_places_closeTab	Close a tab	places:write

RobinPath Bridge

# What is the user looking at right now?
rightplace.places_getActive into $active
rightplace.places_listOpenTabs into $tabs
log "active place:" $active.placeId "tabs:" $tabs.length

# Focus a specific tab
rightplace.places_selectTab {tabId: $tabs[0].id}

# Open a resource in a new tab (current pane, current place)
rightplace.places_openResource {resourceId: "res_docs_readme"} into $opened
log "opened tab:" $opened.tabId

# Open a project tool
rightplace.places_openTool {tool: "terminal"}

# Or use the generic hook dispatcher - identical behavior, different entrypoint
rightplace.hook "res_docs_readme" "places.openResource" {resourceId: "res_docs_readme"}

API Reference

rp.places.list(projectId?)

Returns places, optionally filtered by project.

Parameter	Type	Description
projectId	string	Optional project filter
Returns	Promise<PlaceInfo[]>	List of places

PlaceInfo

Field	Type	Description
id	string	Place ID
title	string	Place title
slug	string	URL-safe slug
projectId	string	Owning project ID
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)

Manifest Configuration

{
  "capabilities": [
    "places:read"
  ]
}

Notes

• This API is read-only. Resources cannot create, update, or delete places.
• The canvas data is not exposed through this API for security and performance reasons.

Listing tabs and panes

All read methods require places:read.

rp.places.listTabs({ placeId, windowNum? })

Returns every tab in the place’s persisted layout. windowNum defaults to "1".

const { tabs } = await rp.places.listTabs({ placeId: "place-123" });
// tabs: [{ id, type, path, title, pinned, paneId, placeId, projectId }, ...]

rp.places.listPanes({ placeId, windowNum? })

Returns { id, tabIds, activeTabId } for every pane.

rp.places.loadLayout({ placeId, windowNum? })

Returns the full layout tree (typed), or null if no layout is saved.

Active state

All require places:read.

rp.places.getActive({ windowLabel? })

“What place is the user on?” - returns { placeId, projectId }. Defaults to the current window.

rp.places.getFocusedPane({ windowLabel? })

Returns { placeId, paneId, activeTabId } for the focused pane.

rp.places.listOpenTabs({ windowLabel? })

Convenience: tabs in the currently-active place. Equivalent to getActive + listTabs.

Navigation

All require places:write.

rp.places.openTab({ placeId?, paneId?, type, resourceId?, path? })

Open a new tab. Defaults: active place, focused pane. If a tab with the same path already exists, it’s focused instead of duplicating. Returns { tabId, paneId }.

rp.places.openResource({ resourceId, path?, placeId?, paneId? })

Open a user resource (docs, WordPress site, spreadsheet, etc.) as a tab. Returns { tabId, paneId }.

rp.places.openTool({ tool, projectId?, placeId?, paneId? })

Open a project-level tool. tool is one of:

Tool	Description
terminal	Shell/terminal
browser	In-app web browser
git	Git status / diff view
files	File & media explorer
editor	Code editor
imageeditor	Image editor
html_playground	HTML scratch pad
relay_test	Relay Test dev tool (dev mode only)
hooks_test	Hooks Test dev tool (dev mode only)

rp.places.selectTab({ tabId, placeId?, windowLabel? })

Focus an already-open tab. Returns { tabId, paneId }.

rp.places.closeTab({ tabId, placeId?, windowLabel? })

Close a tab. Refuses to close pinned tabs. Returns { closed, reason? }.

Error cases

Error	When
place not found	placeId doesn’t exist
tab not found: <id>	tabId isn’t in the resolved place’s layout
navigate timeout after 5s	Frontend didn’t acknowledge within 5s (no window mounted?)
no active place	Navigation needs an active place; the user isn’t on one yet
tab is pinned	closeTab called on a pinned tab

Manifest (full)

{
  "capabilities": ["places:read", "places:write"]
}