Pages
Pages in Allpage: its screens, what you can do there and its operations.
Availability. Every business has it.
What you can do
- Add a section to a page: the assistant can do it on its own
- Hide a section of a page: the assistant can do it on its own
- Move a section of a page: the assistant can do it on its own
- Star a page or record: the assistant can do it on its own
- Save a filter on a list: the assistant can do it on its own
- Make a page of your own: the assistant can do it on its own
- Reset a page’s arrangement: the assistant can do it on its own
- Undo a change to a page: the assistant can do it on its own
For apps
Tools
- screen_addView (Add a section to a page): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_hide (Hide a section of a page): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_move (Move a section of a page): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_pin (Star a page or record): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_saveFilter (Save a filter on a list): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_createPage (Make a page of your own): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_reset (Reset a page’s arrangement): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
- screen_undo (Undo a change to a page): a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Reads
- screen_catalog (See what you can add to a page)
- screen_page (See what’s on a page)
- screen_nav (See how your navigation is arranged)
- screen_summary (What’s going on)
Operations
Each one's input and output, as JSON Schema. Ids are typed (typed ids).
surface.addView
Add a section to a page
- Kind
- Change
- Tool
screen_addView- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"view": {
"description": "The view to add, from surface.catalog. Leave out only to show again a section already on the page.",
"type": "string",
"pattern": "^[a-z][a-z-]*\\.[a-zA-Z]+$"
},
"params": {
"description": "The view’s values, all strings, from surface.catalog.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"region": {
"description": "The board it goes on. Leave out for the page’s first board.",
"type": "string",
"maxLength": 120
},
"after": {
"description": "The section it goes after, or null for first. Leave out for last.",
"type": [
"string",
"null"
]
},
"instance": {
"description": "A section already on the page, to show it again or change its values. Leave out to add a new one.",
"type": "string",
"maxLength": 120
}
},
"required": [
"page"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.catalog
See what you can add to a page
- Kind
- Read
- Tool
screen_catalog- Scope
surface:read- Reached by
- API, MCP, ChatGPT
Read-only.
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"q": {
"default": "",
"description": "Words to look for in a view’s name and description: \"new customers\", \"owed\".",
"type": "string",
"maxLength": 200
},
"record": {
"description": "Only views about this kind of record, for its page. Leave out for any page.",
"type": "string",
"enum": [
"customer",
"session",
"order",
"booking",
"gallery",
"proposal"
]
}
},
"additionalProperties": false
}Output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"description": "The tool its views come from, by id."
},
"title": {
"type": "string",
"description": "The tool’s name, as the owner knows it."
},
"views": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The view’s id: what surface.addView takes, `<area>.<name>`."
},
"title": {
"type": "string",
"description": "Its heading on the page, in the owner’s words."
},
"description": {
"type": "string",
"description": "What it shows and when it helps."
},
"shape": {
"type": "string",
"enum": [
"person",
"day",
"answers",
"hero",
"rows",
"collection",
"timeline",
"table",
"chart",
"week",
"progress",
"stat",
"facts",
"composer",
"roster",
"stops",
"params",
"ask",
"custom"
],
"description": "How it shows."
},
"shapeDescription": {
"type": "string",
"description": "What that shape is for."
},
"record": {
"description": "The kind of record it’s about, when it sits on record pages only.",
"type": "string",
"enum": [
"customer",
"session",
"order",
"booking",
"gallery",
"proposal"
]
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "JSON Schema of the values it takes, all strings, with their defaults."
},
"firstTime": {
"description": "On a new business: what fills it, in one line.",
"type": "string"
}
},
"required": [
"id",
"title",
"description",
"shape",
"shapeDescription",
"params"
],
"additionalProperties": false
}
}
},
"required": [
"tool",
"title",
"views"
],
"additionalProperties": false
},
"description": "Views this person can add, grouped by tool."
},
"measures": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "What `analytics.measure` and the metric views take as `measure`."
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"by": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"count",
"sum",
"average",
"people"
]
},
"words": {
"type": "string"
}
},
"required": [
"id",
"words"
],
"additionalProperties": false
},
"description": "Ways to count it, the default first."
},
"groups": {
"type": "boolean",
"description": "Whether it splits by a group of customers (`segment`)."
}
},
"required": [
"id",
"title",
"description",
"by",
"groups"
],
"additionalProperties": false
},
"description": "Numbers this person may read, for the metric views: their role reads what each counts."
},
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
],
"additionalProperties": false
},
"description": "Groups of customers a measure about customers splits by."
}
},
"required": [
"groups",
"measures",
"segments"
],
"additionalProperties": false
}
},
"required": [
"status",
"title",
"change",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "refused"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
},
"required": [
"status",
"title",
"change",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs"
},
"kind": {
"type": "string",
"enum": [
"module",
"portal",
"business",
"limit",
"paused",
"reauth"
]
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"status",
"kind",
"title",
"change",
"message"
],
"additionalProperties": {}
}
]
}surface.createPage
Make a page of your own
- Kind
- Change
- Tool
screen_createPage- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Its name, as people see it: \"Studio numbers\"."
},
"views": {
"default": [],
"description": "Its sections, in order, from surface.catalog: at most 12. More can be added later with surface.addView.",
"maxItems": 12,
"type": "array",
"items": {
"type": "object",
"properties": {
"view": {
"type": "string",
"pattern": "^[a-z][a-z-]*\\.[a-zA-Z]+$",
"description": "The view’s id, from surface.catalog."
},
"params": {
"description": "The view’s values, all strings, from surface.catalog.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
},
"required": [
"view"
],
"additionalProperties": false
}
},
"pin": {
"default": false,
"description": "true also stars it, so it shows on the rail. Only when they ask for it there.",
"type": "boolean"
}
},
"required": [
"title"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.hide
Hide a section of a page
- Kind
- Change
- Tool
screen_hide- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "The section to hide, or on navigation the area or page. It can be added back. On navigation, hiding a page of your own (`custom:<id>`) deletes it; Undo brings it back."
}
},
"required": [
"page",
"instance"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.move
Move a section of a page
- Kind
- Change
- Tool
screen_move- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"instance": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "The section to move, or on navigation the area or page."
},
"region": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "The board it goes on. On navigation: `rail` for the rail itself, or the area it goes in."
},
"after": {
"description": "The section it goes after, or null for first. Leave out for the end of another board.",
"anyOf": [
{
"type": "string",
"maxLength": 120
},
{
"type": "null"
}
]
}
},
"required": [
"page",
"instance",
"region"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.page
See what’s on a page
- Kind
- Read
- Tool
screen_page- Scope
surface:read- Reached by
- API, MCP, ChatGPT
Read-only.
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
}
},
"required": [
"page"
],
"additionalProperties": false
}Output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {
"type": "object",
"properties": {
"page": {
"type": "string",
"description": "The page key, as the surface.* commands take it."
},
"title": {
"type": "string"
},
"custom": {
"type": "boolean",
"description": "A page someone made (`custom:<id>`)."
},
"boards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"key",
"label"
],
"additionalProperties": false
},
"description": "Where sections can be added and moved: surface.addView’s and surface.move’s `region`."
},
"sections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"instance": {
"type": "string",
"description": "The section, as surface.hide, surface.move and surface.addView take it."
},
"view": {
"type": "string",
"description": "Its view, from surface.catalog."
},
"title": {
"type": "string"
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"board": {
"description": "Its board, or null for a fixed place it can’t move from.",
"type": [
"string",
"null"
]
},
"hidden": {
"type": "boolean",
"description": "Hidden, or waiting to be added: surface.addView with its `instance` shows it."
}
},
"required": [
"instance",
"view",
"title",
"params",
"board",
"hidden"
],
"additionalProperties": false
},
"description": "Every section on the page this person may see, in order."
},
"showing": {
"type": "number",
"description": "Sections that read when the page loads."
},
"budget": {
"type": "number",
"description": "The most sections a page shows. Hide one to add past it."
},
"versions": {
"type": "object",
"properties": {
"business": {
"type": "number"
},
"person": {
"type": "number"
}
},
"required": [
"business",
"person"
],
"additionalProperties": false
}
},
"required": [
"page",
"title",
"custom",
"boards",
"sections",
"showing",
"budget",
"versions"
],
"additionalProperties": false
}
},
"required": [
"status",
"title",
"change",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "refused"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
},
"required": [
"status",
"title",
"change",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs"
},
"kind": {
"type": "string",
"enum": [
"module",
"portal",
"business",
"limit",
"paused",
"reauth"
]
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"status",
"kind",
"title",
"change",
"message"
],
"additionalProperties": {}
}
]
}surface.pin
Star a page or record
- Kind
- Change
- Tool
screen_pin- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"default": "nav",
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"target": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "page"
},
"page": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
}
},
"required": [
"type",
"page"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "record"
},
"kind": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"type",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "filter"
},
"page": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
},
"filter": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
}
},
"required": [
"type",
"page",
"filter"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "custom"
},
"id": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,79}$",
"description": "A page of your own, by its id."
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
}
],
"description": "What the star points at: a page, a record, a saved filter or a custom page."
},
"pinned": {
"default": true,
"description": "true stars it; false takes the star off.",
"type": "boolean"
}
},
"required": [
"target"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.reset
Reset a page’s arrangement
- Kind
- Change
- Tool
screen_reset- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"page"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.saveFilter
Save a filter on a list
- Kind
- Change
- Tool
screen_saveFilter- Scope
surface:write- Reached by
- API, MCP
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"collection": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "The list on the page it filters, by its section id."
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60,
"description": "Its name, as people see it: \"Owes money\"."
},
"query": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
{
"type": "null"
}
],
"description": "The list’s values to keep (`q`, `filter`, `sort`), or null to delete the saved filter."
},
"instance": {
"description": "A saved filter to change or delete. Leave out to save a new one.",
"type": "string",
"maxLength": 120
}
},
"required": [
"page",
"collection",
"label",
"query"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}surface.summary
What’s going on
- Kind
- Read
- Tool
screen_summary- Scope
surface:read- Reached by
- API, MCP
Read-only.
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}Output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"facts": {
"type": "array",
"items": {
"type": "string"
},
"description": "One-line facts, e.g. \"3 bookings today\"."
},
"attention": {
"description": "Things that need the owner, each with a plain reason.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"href": {
"type": "string"
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
}
},
"happening": {
"description": "What’s on today, each at its time.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"at": {
"type": "number",
"description": "Epoch milliseconds."
},
"text": {
"type": "string"
},
"href": {
"type": "string"
}
},
"required": [
"id",
"at",
"text"
],
"additionalProperties": false
}
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"value": {
"type": "number"
},
"prior": {
"type": "number"
},
"unit": {
"type": "string",
"enum": [
"count",
"money"
]
},
"href": {
"type": "string"
}
},
"required": [
"id",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"title",
"facts"
],
"additionalProperties": false
}
},
"required": [
"status",
"title",
"change",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "refused"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
},
"required": [
"status",
"title",
"change",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs"
},
"kind": {
"type": "string",
"enum": [
"module",
"portal",
"business",
"limit",
"paused",
"reauth"
]
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
},
"required": [
"status",
"kind",
"title",
"change",
"message"
],
"additionalProperties": {}
}
]
}surface.undo
Undo a change to a page
- Kind
- Change
- Tool
screen_undo- Scope
surface:write- Reached by
- API, MCP, ChatGPT
a private change: runs now if the owner lets your app make private changes, otherwise waits for their approval
Input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"page": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "The page: its id (`today`, `customers`), a record kind (`customer`) for every record of that kind, or `nav` for navigation."
},
"layer": {
"default": "person",
"description": "`person`: only your own view of the page. `business`: the page everyone on the team starts from. Only the owner changes it, and the assistant asks them first.",
"type": "string",
"enum": [
"person",
"business"
]
},
"version": {
"description": "The version you last saw. A newer one never stops the change: it applies on top, and the answer says to load the page again.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"restore": {
"maxItems": 120,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "add"
},
"instance": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"view": {
"type": "string",
"pattern": "^[a-z][a-z-]*\\.[a-zA-Z]+$",
"description": "The view’s id, from surface.catalog."
},
"params": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "The view’s values, all strings: what surface.catalog lists."
},
"region": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"after": {
"description": "The section it goes after, or null for first. One that’s gone puts it back where it starts.",
"type": [
"string",
"null"
]
}
},
"required": [
"kind",
"instance"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "hide"
},
"instance": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
}
},
"required": [
"kind",
"instance"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "move"
},
"instance": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"region": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"after": {
"description": "The section it goes after, or null for first. One that’s gone puts it back where it starts.",
"type": [
"string",
"null"
]
}
},
"required": [
"kind",
"instance",
"region"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "pin"
},
"instance": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"target": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "page"
},
"page": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
}
},
"required": [
"type",
"page"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "record"
},
"kind": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"type",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "filter"
},
"page": {
"type": "string",
"pattern": "^[a-z][a-z-]*$"
},
"filter": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
}
},
"required": [
"type",
"page",
"filter"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "custom"
},
"id": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,79}$",
"description": "A page of your own, by its id."
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
}
],
"description": "What the star points at: a page, a record, a saved filter or a custom page."
},
"pinned": {
"type": "boolean"
}
},
"required": [
"kind",
"instance",
"target",
"pinned"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "saveFilter"
},
"instance": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"collection": {
"type": "string",
"pattern": "^[a-z0-9][\\w:.-]{0,119}$",
"description": "A section on the page (a default’s id, or the one surface.addView answered), or on navigation an area or a page id."
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"query": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
{
"type": "null"
}
]
}
},
"required": [
"kind",
"instance",
"collection",
"label",
"query"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "page"
},
"instance": {
"type": "string",
"pattern": "^custom:[a-z0-9][a-z0-9-]{0,79}$"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 60
}
},
"required": [
"kind",
"instance",
"title"
],
"additionalProperties": false
}
]
},
"description": "The changes to put back, from a change’s `previous`."
},
"drop": {
"maxItems": 120,
"type": "array",
"items": {
"type": "string",
"maxLength": 160
},
"description": "The changes to take away, from a change’s `previous`."
}
},
"required": [
"page",
"restore",
"drop"
],
"additionalProperties": false
}Output
{
"oneOf": [
{
"type": "object",
"required": [
"status",
"title",
"change"
],
"properties": {
"status": {
"const": "done"
},
"title": {
"type": "string"
},
"change": {
"type": "boolean"
},
"result": {},
"undo": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"input": {}
}
}
}
},
{
"type": "object",
"required": [
"status",
"proposalId"
],
"properties": {
"status": {
"const": "proposed"
},
"proposalId": {
"type": "string"
},
"preview": {},
"approveAt": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"status",
"check"
],
"properties": {
"status": {
"const": "pending"
},
"message": {
"type": "string"
},
"check": {
"type": "string"
},
"checkInput": {
"type": "object"
}
}
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"const": "refused"
},
"message": {
"type": "string"
},
"field": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"status",
"kind",
"message"
],
"properties": {
"status": {
"const": "needs"
},
"kind": {
"type": "string"
},
"message": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
]
}