{ "openapi": "3.1.0", "info": { "title": "Lessly REST API", "description": "Generated from the Lessly platform tool catalog — the same source as the MCP tools reference, so the two surfaces describe the same operations. Every endpoint names the MCP tool it is bound to in `x-mcp-tool`. Do not edit by hand: pipeline/run.mjs rewrites this file on every catalog change.", "version": "6707f56999a5cdea4a0a6e3de0be3ba0e5d053a2b12b88b7c30ece2821bd1b5a" }, "x-catalog-version": "6707f56999a5cdea4a0a6e3de0be3ba0e5d053a2b12b88b7c30ece2821bd1b5a", "servers": [ { "url": "https://api.lessly.com" } ], "tags": [ { "name": "Analytics", "description": "REST endpoints for the Analytics area of Lessly." }, { "name": "Brain", "description": "REST endpoints for the Brain area of Lessly." }, { "name": "Consent", "description": "REST endpoints for the Consent area of Lessly." }, { "name": "Content", "description": "REST endpoints for the Content area of Lessly." }, { "name": "Deployment", "description": "REST endpoints for the Deployment area of Lessly." }, { "name": "Mail", "description": "REST endpoints for the Mail area of Lessly." }, { "name": "Observe", "description": "REST endpoints for the Observe area of Lessly." }, { "name": "Organization", "description": "REST endpoints for the Organization area of Lessly." }, { "name": "Realtime", "description": "REST endpoints for the Realtime area of Lessly." }, { "name": "Support", "description": "REST endpoints for the Support area of Lessly." }, { "name": "Tracking", "description": "REST endpoints for the Tracking area of Lessly." }, { "name": "Users", "description": "REST endpoints for the Users area of Lessly." }, { "name": "Waitlist", "description": "REST endpoints for the Waitlist area of Lessly." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/analytics/catalog": { "get": { "operationId": "analytics_catalog_get", "summary": "Read the analytics semantic catalog: every entity this product may chart, with its declared metrics, dimensions and person-graph identity kinds.", "description": "Read the analytics semantic catalog: every entity this product may chart, with its declared metrics, dimensions and person-graph identity kinds. Call this FIRST to discover the exact `entity`, `metric` and `dimension` names analytics_metric_query and analytics_funnel_run accept — those names are resolved against this catalog and a name that is not in it is rejected.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_catalog_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "generated_at", "cycle", "entities" ], "properties": { "cycle": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string" }, "from": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "entities": { "type": "array", "items": { "type": "object", "required": [ "entity", "extensionSlug", "entityName", "description", "timeColumn", "dimensions", "metrics", "identityKinds", "propertiesColumn" ], "properties": { "entity": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "object", "required": [ "name", "type", "description" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "count", "sum", "avg", "ratio" ] }, "description": { "type": "string" } }, "additionalProperties": false } }, "dimensions": { "type": "array", "items": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": false } }, "entityName": { "type": "string" }, "timeColumn": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "extensionSlug": { "type": "string" }, "identityKinds": { "type": "array", "items": { "type": "string", "enum": [ "email", "phone", "users_id", "anonymous_id" ] } }, "propertiesColumn": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "product_id": { "type": "string" }, "generated_at": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dashboards": { "get": { "operationId": "analytics_dashboard_list", "summary": "List the saved dashboards of the current product, newest first.", "description": "List the saved dashboards of the current product, newest first. Narrow by an exact tag or by a case-insensitive substring of the name or slug. Returns definitions, not results.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_list", "parameters": [ { "name": "tag", "in": "query", "required": false, "description": "Exact tag the dashboard must carry", "schema": { "type": "string", "maxLength": 40 } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring of the name or slug", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dashboards" ], "properties": { "dashboards": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "tiles", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "analytics_dashboard_create", "summary": "Save a named dashboard for the current product: up to forty tiles, each either a reference to a saved insight by its uuid (from analytics_insight_list) or a block of markdown, each placed on a twelve-column grid.", "description": "Save a named dashboard for the current product: up to forty tiles, each either a reference to a saved insight by its uuid (from analytics_insight_list) or a block of markdown, each placed on a twelve-column grid. The slug is the address the dashboard is read by and cannot be changed later. Stores the arrangement only; it does not run it. Every insight a tile names must already exist in this product, so a stored dashboard always resolves.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } } }, "required": [ "slug", "name", "tiles" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "tiles", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dashboards/{id}": { "delete": { "operationId": "analytics_dashboard_delete", "summary": "Permanently delete one saved dashboard of the current product.", "description": "Permanently delete one saved dashboard of the current product. The insights its tiles referred to are not deleted.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The dashboard's uuid; slugs are not accepted here", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "analytics_dashboard_update", "summary": "Change fields of a saved dashboard of the current product.", "description": "Change fields of a saved dashboard of the current product. Only the fields supplied are changed; the rest keep their stored values. Supplying tiles replaces the whole arrangement, so send the tiles you want to keep along with the new ones. The slug cannot be changed — create a new dashboard instead.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_update", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The dashboard's uuid; slugs are not accepted here", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "tiles", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dashboards/{idOrSlug}": { "get": { "operationId": "analytics_dashboard_get", "summary": "Read one saved dashboard of the current product by its slug or its id.", "description": "Read one saved dashboard of the current product by its slug or its id. Returns the tiles and their layout, not results.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_get", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The dashboard's slug, or its uuid", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "tiles", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dashboards/{idOrSlug}/run": { "post": { "operationId": "analytics_dashboard_run", "summary": "Run every tile of a saved dashboard of the current product and return one entry per tile, in board order: the tile itself, and what it produced.", "description": "Run every tile of a saved dashboard of the current product and return one entry per tile, in board order: the tile itself, and what it produced. An insight tile carries exactly what analytics_insight_run answers for that insight; a text tile carries a null result, because its content is the tile. `from` and `to` override the window of every insight tile for this call only, changing nothing stored. A tile that fails carries an error with an HTTP status and does not stop the rest of the board, so check each tile's result before reading numbers.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_dashboard_run", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The dashboard's slug, or its uuid", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "description": "Inclusive window start; overrides the stored window", "type": "string", "format": "date-time" }, "to": { "description": "Inclusive window end; overrides the stored window", "type": "string", "format": "date-time" } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dashboard", "tiles" ], "properties": { "tiles": { "type": "array", "items": { "type": "object", "required": [ "tile", "result" ], "properties": { "tile": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "insight", "window", "series", "formula", "total", "target_status" ], "properties": { "extra": { "type": "object", "additionalProperties": { "type": "object", "required": [ "cohort_size", "retained" ], "properties": { "retained": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cohort_size": { "type": "integer" } }, "additionalProperties": false } }, "total": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } }, "series": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "bucket", "value" ], "properties": { "value": { "type": [ "number", "null" ] }, "bucket": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" } }, "additionalProperties": false } } }, "window": { "type": "object", "required": [ "from", "to", "grain" ], "properties": { "to": { "type": "string" }, "from": { "type": "string" }, "grain": { "type": "string", "enum": [ "day", "week", "month" ] } }, "additionalProperties": false }, "formula": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "bucket", "value" ], "properties": { "value": { "type": [ "number", "null" ] }, "bucket": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" } }, "additionalProperties": false } }, { "type": "null" } ] }, "insight": { "anyOf": [ { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)" }, "from": { "description": "Inclusive first day (UTC)" }, "grain": { "description": "Time bucket size" }, "entity": { "description": "Semantic view name from the catalog" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties" }, "metrics": { "description": "Declared metric names to compute" }, "group_by": { "description": "One declared dimension, or `props.`, to group by" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)" }, "from": { "description": "Inclusive first day (UTC)" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time" }, "steps": { "description": "Ordered funnel steps, 2 to 5" }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count" } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event" }, "from": { "description": "Inclusive first day of the cohort range (UTC)" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event" }, "cohort": { "description": "The starting event; empty filters mean any row of the entity" }, "entity": { "description": "Semantic view name from the catalog" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity" }, "subject": { "description": "Cohort key: \"identity\" or `props.`" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it" } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, { "type": "null" } ] }, "target_status": { "anyOf": [ { "type": "string", "enum": [ "met", "missed" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "dashboard": { "type": "object", "required": [ "slug", "name", "tiles", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "tiles": { "type": "array", "maxItems": 40, "items": { "anyOf": [ { "type": "object", "required": [ "id", "layout", "type", "insight_id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "insight" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "insight_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, { "type": "object", "required": [ "id", "layout", "type", "markdown" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "const": "text" }, "title": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "layout": { "type": "object", "required": [ "x", "y", "w", "h" ], "properties": { "h": { "type": "integer", "minimum": 1, "maximum": 12 }, "w": { "type": "integer", "minimum": 1, "maximum": 12 }, "x": { "type": "integer", "minimum": 0 }, "y": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "markdown": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } ] } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/funnels/run": { "post": { "operationId": "analytics_funnel_run", "summary": "Run an ordered conversion funnel over the analytics semantic layer for the current product.", "description": "Run an ordered conversion funnel over the analytics semantic layer for the current product. Each step names a semantic entity (optionally narrowed by declared-dimension filters) and is counted in resolved persons from the identity graph, so a person is counted once per step no matter how many rows or identifiers they produced. Deterministic: entity, dimension and metric names are resolved against the semantic catalog, never generated. A step whose entity has a `propertiesColumn` in the catalog may also filter on `props.`, compared as a string. Prefer this over analytics_query_run whenever the question is a conversion between ordered steps.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_funnel_run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] } }, "required": [ "steps", "from", "to" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "steps", "meta" ], "properties": { "meta": { "type": "object", "required": [ "from", "to", "window_days", "grain", "sql" ], "properties": { "to": { "type": "string" }, "sql": { "type": "string" }, "from": { "type": "string" }, "grain": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "month" ] }, { "type": "null" } ] }, "window_days": { "type": "integer" } }, "additionalProperties": false }, "steps": { "type": "array", "items": { "type": "object", "required": [ "step_index", "entity", "persons", "conversion_from_prev" ], "properties": { "entity": { "type": "string" }, "persons": { "type": "integer" }, "step_index": { "type": "integer" }, "conversion_from_prev": { "type": [ "number", "null" ] } }, "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "required": [ "ts", "step_index", "entity", "persons" ], "properties": { "ts": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" }, "entity": { "type": "string" }, "persons": { "type": "integer" }, "step_index": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/insights": { "get": { "operationId": "analytics_insight_list", "summary": "List the saved insights of the current product, newest first.", "description": "List the saved insights of the current product, newest first. Narrow by an exact tag or by a case-insensitive substring of the name or slug. Returns definitions, not results.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_list", "parameters": [ { "name": "tag", "in": "query", "required": false, "description": "Exact tag the insight must carry", "schema": { "type": "string", "maxLength": 40 } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring of the name or slug", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "insights" ], "properties": { "insights": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "analytics_insight_create", "summary": "Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it.", "description": "Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it. The slug is the address the insight is read by and cannot be changed later. Stores the definition only; it does not run it. Series requests are validated with the same schemas analytics_metric_query and analytics_funnel_run accept, so a stored insight always runs.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "slug", "name", "kind", "series", "window" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/insights/{id}": { "delete": { "operationId": "analytics_insight_delete", "summary": "Permanently delete one saved insight of the current product.", "description": "Permanently delete one saved insight of the current product. Dashboards referring to it will no longer resolve it.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The insight's uuid; slugs are not accepted here", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "analytics_insight_update", "summary": "Change fields of a saved insight of the current product.", "description": "Change fields of a saved insight of the current product. Only the fields supplied are changed; the rest keep their stored values. The slug cannot be changed — create a new insight instead.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_update", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The insight's uuid; slugs are not accepted here", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000 }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "formula": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "grain": { "type": "string", "enum": [ "day", "week", "month" ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ] }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "target": { "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/insights/{idOrSlug}": { "get": { "operationId": "analytics_insight_get", "summary": "Read one saved insight of the current product by its slug or its id.", "description": "Read one saved insight of the current product by its slug or its id. Returns the definition, not results.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_get", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The insight's slug, or its uuid", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/insights/{idOrSlug}/run": { "post": { "operationId": "analytics_insight_run", "summary": "Run a saved insight of the current product and return its numbers: every series executed over the resolved window and aligned onto the same buckets, the formula evaluated bucket by bucket, a total per series, and whether the target was met.", "description": "Run a saved insight of the current product and return its numbers: every series executed over the resolved window and aligned onto the same buckets, the formula evaluated bucket by bucket, a total per series, and whether the target was met. The window comes from the stored definition — relative windows and the current cycle are resolved at call time — and `from` and `to` override it for this call only, changing nothing stored. Use this rather than rebuilding the insight out of analytics_metric_query calls: the alignment and the formula are what make the numbers comparable.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_insight_run", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "description": "The insight's slug, or its uuid", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "description": "Inclusive window start; overrides the stored window", "type": "string", "format": "date-time" }, "to": { "description": "Inclusive window end; overrides the stored window", "type": "string", "format": "date-time" } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "insight", "window", "series", "formula", "total", "target_status" ], "properties": { "extra": { "type": "object", "additionalProperties": { "type": "object", "required": [ "cohort_size", "retained" ], "properties": { "retained": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cohort_size": { "type": "integer" } }, "additionalProperties": false } }, "total": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } }, "series": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "bucket", "value" ], "properties": { "value": { "type": [ "number", "null" ] }, "bucket": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" } }, "additionalProperties": false } } }, "window": { "type": "object", "required": [ "from", "to", "grain" ], "properties": { "to": { "type": "string" }, "from": { "type": "string" }, "grain": { "type": "string", "enum": [ "day", "week", "month" ] } }, "additionalProperties": false }, "formula": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "bucket", "value" ], "properties": { "value": { "type": [ "number", "null" ] }, "bucket": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" } }, "additionalProperties": false } }, { "type": "null" } ] }, "insight": { "anyOf": [ { "type": "object", "required": [ "slug", "name", "kind", "series", "window", "id", "product_id", "created_by", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "trend", "funnel", "number", "retention" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,63}$" }, "tags": { "type": "array", "default": [], "maxItems": 20, "items": { "type": "string", "maxLength": 40 } }, "grain": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" }, "series": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "request" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z]$" }, "request": { "anyOf": [ { "type": "object", "required": [ "entity", "metrics", "grain", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "steps", "from", "to" ], "properties": { "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "When set, also return per-step persons bucketed by step-entry time", "type": "string", "enum": [ "day", "week", "month" ] }, "steps": { "description": "Ordered funnel steps, 2 to 5", "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "entity" ], "properties": { "entity": { "description": "Semantic view name from the catalog; must declare identity columns", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "window_days": { "description": "Maximum days between two CONSECUTIVE steps for the later one to count", "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, "additionalProperties": false }, { "type": "object", "required": [ "entity", "subject", "day", "from", "to", "grain" ], "properties": { "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "target": { "default": null, "anyOf": [ { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ ">=", "<=", "=" ] }, "value": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "window": { "anyOf": [ { "type": "object", "required": [ "from", "to" ], "properties": { "to": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, { "type": "object", "required": [ "relative" ], "properties": { "relative": { "type": "string", "enum": [ "last_7d", "last_30d", "last_90d", "cycle" ] } }, "additionalProperties": false } ] }, "display": { "type": "string", "enum": [ "line", "bar", "bold_number", "table" ], "default": "line" }, "formula": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "product_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, { "type": "null" } ] }, "target_status": { "anyOf": [ { "type": "string", "enum": [ "met", "missed" ] }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/metrics/query": { "post": { "operationId": "analytics_metric_query", "summary": "Compute declared metrics from the analytics semantic layer for the current product, bucketed by time and optionally grouped by one declared dimension.", "description": "Compute declared metrics from the analytics semantic layer for the current product, bucketed by time and optionally grouped by one declared dimension. Deterministic: entity, metric and dimension names are resolved against the semantic catalog, never generated. Prefer this over analytics_query_run whenever the question is a metric over time — no LLM, no SQL generation. Where the catalog gives an entity a `propertiesColumn`, `group_by` and a filter dimension also accept `props.` to read one raw event property; property values always compare as strings.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_metric_query", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "metrics": { "description": "Declared metric names to compute", "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, "grain": { "description": "Time bucket size", "type": "string", "enum": [ "day", "week", "month" ] }, "from": { "description": "Inclusive first day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Inclusive last day (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "group_by": { "description": "One declared dimension, or `props.`, to group by", "type": "string" }, "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "description": "One declared dimension, or `props.`, to group by", "type": "string" } }, "additionalProperties": false } } }, "required": [ "entity", "metrics", "grain", "from", "to" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "series", "meta" ], "properties": { "meta": { "type": "object", "required": [ "entity", "grain", "sql", "source" ], "properties": { "sql": { "type": "string" }, "grain": { "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "type": "string" }, "source": { "type": "string", "enum": [ "rollup", "live", "mixed" ] } }, "additionalProperties": false }, "series": { "type": "array", "items": { "type": "object", "required": [ "ts", "metric", "value" ], "properties": { "ts": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" }, "group": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "metric": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/persons/timeline": { "post": { "operationId": "analytics_person_timeline", "summary": "Return one resolved person's profile and their chronological activity across every identity-bearing semantic entity of the current product.", "description": "Return one resolved person's profile and their chronological activity across every identity-bearing semantic entity of the current product. Address the person either by person_id or by any single identifier (email, phone, users_id, anonymous_id), which is normalised exactly as the identity graph normalised it. Deterministic: no LLM, and only catalog-declared columns are returned. Prefer this over analytics_query_run whenever the question is about one specific person.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_person_timeline", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "person_id": { "description": "Graph person id, when already known", "type": "string", "minLength": 1 }, "identifier": { "description": "Any single identifier belonging to the person", "type": "object", "required": [ "type", "value" ], "properties": { "type": { "description": "Which kind of identifier `value` is", "type": "string", "enum": [ "email", "phone", "users_id", "anonymous_id" ] }, "value": { "description": "Raw identifier; normalised server-side before lookup", "type": "string", "minLength": 1 } }, "additionalProperties": false }, "from": { "description": "Inclusive first day (UTC); unbounded when omitted", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Inclusive last day (UTC); unbounded when omitted", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "limit": { "description": "Maximum events to return, newest first", "type": "integer", "default": 200, "minimum": 1, "maximum": 1000 } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "person", "events", "truncated", "meta" ], "properties": { "meta": { "type": "object", "required": [ "entities", "limit", "sql" ], "properties": { "sql": { "type": "string" }, "limit": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "events": { "type": "array", "items": { "type": "object", "required": [ "ts", "entity", "fields" ], "properties": { "ts": { "description": "Event time, ISO-8601 (UTC)", "type": "string" }, "entity": { "description": "Semantic view the event came from", "type": "string" }, "fields": { "description": "Catalog-declared columns of that row", "type": "object", "additionalProperties": {} } }, "additionalProperties": false } }, "person": { "type": "object", "required": [ "person_id", "primary_email", "primary_phone", "users_id", "first_seen", "last_seen" ], "properties": { "users_id": { "type": [ "string", "null" ] }, "last_seen": { "type": [ "string", "null" ] }, "person_id": { "type": "string" }, "first_seen": { "type": [ "string", "null" ] }, "primary_email": { "type": [ "string", "null" ] }, "primary_phone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "truncated": { "type": "boolean" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/query": { "post": { "operationId": "analytics_query_run", "summary": "Answer a natural-language analytics question for the current product.", "description": "Answer a natural-language analytics question for the current product. Fallback surface: it routes the question to analytics_metric_query or analytics_funnel_run when it fits one of them and returns that tool's exact request and response in `structured`; it generates SQL only when neither fits. Call analytics_metric_query, analytics_funnel_run or analytics_person_timeline directly when you already know the shape of the question — those are deterministic and cheaper.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_query_run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "description": "Natural-language analytics question", "type": "string", "minLength": 1 } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "answer", "sql", "rows", "truncated", "explanation" ], "properties": { "sql": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "answer": { "type": "string" }, "truncated": { "type": "boolean" }, "structured": { "type": "object", "required": [ "kind", "request", "response" ], "properties": { "kind": { "description": "Which deterministic tool answered", "type": "string", "enum": [ "metric_query", "funnel" ] }, "request": { "description": "The exact tool input that was executed", "type": "object", "additionalProperties": {} }, "response": { "description": "The exact tool output", "type": "object", "additionalProperties": {} } }, "additionalProperties": false }, "explanation": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/retention/run": { "post": { "operationId": "analytics_retention_run", "summary": "Measure day-N retention over the analytics semantic layer for the current product: of the subjects whose FIRST matching cohort event falls in a bucket, how many produced a return event on day N (within `return_window_days` after it).", "description": "Measure day-N retention over the analytics semantic layer for the current product: of the subjects whose FIRST matching cohort event falls in a bucket, how many produced a return event on day N (within `return_window_days` after it). The cohort key is `subject` — an event property (`props.`, e.g. the customer product id) or `identity` for the entity's declared identity columns — and each subject is counted exactly once. Deterministic: entity and dimension names are resolved against the semantic catalog, never generated. A bucket whose day-N horizon has not elapsed yet is still returned, with `retained` and `rate` NULL rather than 0 — null means \"not measurable yet\", 0 means \"measured, nobody came back\", and a caller must not confuse them. `total` therefore covers the measurable buckets ONLY, so a half-elapsed cohort never drags the headline rate down; `meta.unmeasurable_buckets` says how many were left out.", "tags": [ "Analytics" ], "x-mcp-tool": "analytics_retention_run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "description": "Semantic view name from the catalog", "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "subject": { "description": "Cohort key: \"identity\" or `props.`", "type": "string" }, "cohort": { "description": "The starting event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "return": { "description": "The coming-back event; empty filters mean any row of the entity", "type": "object", "default": { "filters": [] }, "properties": { "filters": { "description": "Equality filters on declared dimensions, or on `props.` event properties", "type": "array", "default": [], "items": { "type": "object", "required": [ "dimension", "eq" ], "properties": { "eq": { "type": [ "string", "number", "boolean" ] }, "dimension": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "day": { "description": "N: a subject is retained if it has a return event at least N days after its cohort event", "type": "integer", "minimum": 1, "maximum": 365 }, "return_window_days": { "description": "Length of the window that opens on day N; a return event must fall inside it", "type": "integer", "default": 7, "minimum": 1, "maximum": 90 }, "from": { "description": "Inclusive first day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "description": "Inclusive last day of the cohort range (UTC)", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "grain": { "description": "Cohort bucket size, applied to each subject's FIRST cohort event", "type": "string", "enum": [ "day", "week", "month" ] } }, "required": [ "entity", "subject", "day", "from", "to", "grain" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "buckets", "total", "meta" ], "properties": { "meta": { "type": "object", "required": [ "entity", "subject", "from", "to", "grain", "day", "return_window_days", "unmeasurable_buckets", "sql", "source" ], "properties": { "to": { "type": "string" }, "day": { "type": "integer" }, "sql": { "type": "string" }, "from": { "type": "string" }, "grain": { "type": "string", "enum": [ "day", "week", "month" ] }, "entity": { "type": "string" }, "source": { "type": "string", "const": "live" }, "subject": { "type": "string" }, "return_window_days": { "type": "integer" }, "unmeasurable_buckets": { "type": "integer" } }, "additionalProperties": false }, "total": { "type": "object", "required": [ "cohort_size", "retained", "rate" ], "properties": { "rate": { "type": [ "number", "null" ] }, "retained": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cohort_size": { "type": "integer" } }, "additionalProperties": false }, "buckets": { "type": "array", "items": { "type": "object", "required": [ "bucket", "cohort_size", "retained", "rate" ], "properties": { "rate": { "description": "retained / cohort_size; null when not measurable yet or the cohort is empty", "type": [ "number", "null" ] }, "bucket": { "description": "Bucket start, YYYY-MM-DD (UTC)", "type": "string" }, "retained": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cohort_size": { "type": "integer" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/admin/shared-memory/reset": { "post": { "operationId": "brain_product_shared_memory_reset", "summary": "DESTRUCTIVE admin op: reset a product's SHARED Brain memory (vectors + knowledge graph) and clear its connector_state so a re-ingest re-writes.", "description": "DESTRUCTIVE admin op: reset a product's SHARED Brain memory (vectors + knowledge graph) and clear its connector_state so a re-ingest re-writes. Requires confirm:true AND confirmProductId echo; gated by an env arm flag, an env allowlist, and governance access.", "tags": [ "Brain" ], "x-mcp-tool": "brain_product_shared_memory_reset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "description": "Explicit product id whose SHARED memory will be wiped. Never inferred from ambient context.", "type": "string", "minLength": 1 }, "confirmProductId": { "description": "Must EXACTLY equal productId (double-entry confirmation).", "type": "string", "minLength": 1 }, "confirm": { "description": "Must be true to proceed. Guards against accidental invocation.", "type": "boolean" } }, "required": [ "productId", "confirmProductId", "confirm" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "productId", "scope", "vectorsDeleted", "graphDeleted", "connectorStateRowsCleared" ], "properties": { "scope": { "type": "string" }, "productId": { "type": "string" }, "graphDeleted": { "type": "number" }, "vectorsDeleted": { "type": "number" }, "connectorStateRowsCleared": { "type": "number" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/backups": { "get": { "operationId": "brain_backups_list", "summary": "List the current product's backups (most recent first).", "tags": [ "Brain" ], "x-mcp-tool": "brain_backups_list", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "productId", "snapshotId", "gcsPath", "status", "nodeCount", "edgeCount", "sizeBytes", "trigger", "engineVersion", "embeddingDims", "error", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "gcsPath": { "type": "string" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "pre-restore" ] }, "createdAt": { "type": "string", "format": "date-time" }, "edgeCount": { "type": [ "number", "null" ] }, "nodeCount": { "type": [ "number", "null" ] }, "productId": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "snapshotId": { "type": "string" }, "embeddingDims": { "type": [ "number", "null" ] }, "engineVersion": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "brain_backup_create", "summary": "Request an on-demand point-in-time backup of the current product's Brain memory.", "description": "Request an on-demand point-in-time backup of the current product's Brain memory. Async (202): records a running snapshot and runs the backup in the background — returns { accepted, snapshotId }; poll brain_backups_list / brain_backup_status for completion. Rejects (409) if a backup is already running for the product.", "tags": [ "Brain" ], "x-mcp-tool": "brain_backup_create", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted", "snapshotId" ], "properties": { "accepted": { "type": "boolean", "const": true }, "snapshotId": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/backups/{snapshotId}": { "get": { "operationId": "brain_backup_status", "summary": "Get a backup status by snapshot id, or the latest backup for the current product.", "tags": [ "Brain" ], "x-mcp-tool": "brain_backup_status", "parameters": [ { "name": "snapshotId", "in": "path", "required": true, "description": "Specific snapshot to look up; omit for the latest.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "id", "productId", "snapshotId", "gcsPath", "status", "nodeCount", "edgeCount", "sizeBytes", "trigger", "engineVersion", "embeddingDims", "error", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "gcsPath": { "type": "string" }, "trigger": { "type": "string", "enum": [ "scheduled", "manual", "pre-restore" ] }, "createdAt": { "type": "string", "format": "date-time" }, "edgeCount": { "type": [ "number", "null" ] }, "nodeCount": { "type": [ "number", "null" ] }, "productId": { "type": "string" }, "sizeBytes": { "type": [ "number", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "snapshotId": { "type": "string" }, "embeddingDims": { "type": [ "number", "null" ] }, "engineVersion": { "type": [ "string", "null" ] } }, "additionalProperties": false }, { "type": "null" } ] } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/clickup/channels": { "get": { "operationId": "brain_clickup_channels_list", "summary": "List the chat channels in a ClickUp workspace connection (for selecting channels to ingest)", "tags": [ "Brain" ], "x-mcp-tool": "brain_clickup_channels_list", "parameters": [ { "name": "connectorId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "channelId", "name" ], "properties": { "name": { "type": "string" }, "channelId": { "type": "string" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/clickup/connections": { "get": { "operationId": "brain_clickup_connections_list", "summary": "List the ClickUp workspace connections available to the current product", "tags": [ "Brain" ], "x-mcp-tool": "brain_clickup_connections_list", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "connectorId", "workspaceId", "workspaceName", "status" ], "properties": { "status": { "type": "string" }, "connectorId": { "type": "string" }, "workspaceId": { "type": "string" }, "workspaceName": { "type": "string" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/clickup/lists": { "get": { "operationId": "brain_clickup_lists_list", "summary": "List all lists in a ClickUp space (folderless and within folders, optionally filtered by search)", "tags": [ "Brain" ], "x-mcp-tool": "brain_clickup_lists_list", "parameters": [ { "name": "connectorId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "spaceId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "listId", "name", "folderId", "folderName", "archived" ], "properties": { "name": { "type": "string" }, "listId": { "type": "string" }, "archived": { "type": "boolean" }, "folderId": { "type": [ "string", "null" ] }, "folderName": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/clickup/spaces": { "get": { "operationId": "brain_clickup_spaces_list", "summary": "List the spaces in a ClickUp connection (optionally filtered by search)", "tags": [ "Brain" ], "x-mcp-tool": "brain_clickup_spaces_list", "parameters": [ { "name": "connectorId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "spaceId", "name", "archived" ], "properties": { "name": { "type": "string" }, "spaceId": { "type": "string" }, "archived": { "type": "boolean" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/cognition/digest": { "post": { "operationId": "brain_cognition_digest", "summary": "Queue a System-2 digest over the product shared pool (async); returns { accepted, run_id }.", "description": "Queue a System-2 digest over the product shared pool (async); returns { accepted, run_id }. Poll brain_cognition_status for the result.", "tags": [ "Brain" ], "x-mcp-tool": "brain_cognition_digest", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted", "run_id" ], "properties": { "run_id": { "type": "string" }, "accepted": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/cognition/status": { "get": { "operationId": "brain_cognition_status", "summary": "Read the engine-global System-2 queue gauge plus this product's last digest/sweep run (status, counts, timing).", "tags": [ "Brain" ], "x-mcp-tool": "brain_cognition_status", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "engine", "digest", "sweep" ], "properties": { "sweep": { "anyOf": [ { "type": "object", "required": [ "run_id", "kind", "status", "error", "started_at", "finished_at" ], "properties": { "kind": { "type": "string", "enum": [ "digest", "sweep" ] }, "error": { "type": [ "string", "null" ] }, "result": {}, "run_id": { "type": "string" }, "status": { "type": "string" }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "additionalProperties": false }, { "type": "null" } ] }, "digest": { "anyOf": [ { "type": "object", "required": [ "run_id", "kind", "status", "error", "started_at", "finished_at" ], "properties": { "kind": { "type": "string", "enum": [ "digest", "sweep" ] }, "error": { "type": [ "string", "null" ] }, "result": {}, "run_id": { "type": "string" }, "status": { "type": "string" }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "additionalProperties": false }, { "type": "null" } ] }, "engine": { "type": "object", "required": [ "running", "queue_size", "trigger_mode" ], "properties": { "running": { "type": "boolean" }, "queue_size": { "type": "number" }, "trigger_mode": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/cognition/sweep": { "post": { "operationId": "brain_cognition_sweep", "summary": "Queue a cross-domain sweep over the product shared pool (async); returns { accepted, run_id }.", "description": "Queue a cross-domain sweep over the product shared pool (async); returns { accepted, run_id }. Poll brain_cognition_status for the result.", "tags": [ "Brain" ], "x-mcp-tool": "brain_cognition_sweep", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted", "run_id" ], "properties": { "run_id": { "type": "string" }, "accepted": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons": { "get": { "operationId": "brain_daemons_list", "summary": "List configured ingestion daemons for this product", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemons_list", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "name", "owner", "repo", "branch", "connectorId", "enabled", "lastRunAt", "loadMode", "model", "sourceAuthority", "effectiveModel", "degradedCount", "unmeasuredCount" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "repo": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "owner": { "type": [ "string", "null" ] }, "branch": { "type": [ "string", "null" ] }, "config": {}, "enabled": { "type": "boolean" }, "loadMode": { "type": "string" }, "lastRunAt": { "type": [ "string", "null" ] }, "lastResult": {}, "connectorId": { "type": [ "string", "null" ] }, "clickupConfig": {}, "degradedCount": { "type": "number" }, "effectiveModel": { "type": [ "string", "null" ] }, "sourceAuthority": { "type": [ "string", "null" ] }, "unmeasuredCount": { "type": "number" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "brain_daemon_create", "summary": "Create a new ingestion daemon (github, clickup or gdrive)", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_create", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "github", "clickup", "gdrive" ], "default": "github" }, "name": { "type": "string" }, "connectorId": { "type": [ "string", "null" ] }, "owner": { "type": "string" }, "repo": { "type": "string" }, "branch": { "type": "string", "default": "main" }, "config": { "type": "string" }, "clickupConfig": { "type": "object", "required": [ "workspaceId", "workspaceName", "spaceId", "spaceName", "listId", "listName" ], "properties": { "listId": { "type": [ "string", "null" ] }, "content": { "type": "object", "default": {}, "properties": { "chat": { "type": "boolean", "default": false }, "docs": { "type": "boolean", "default": true }, "tasks": { "type": "boolean", "default": true }, "comments": { "type": "boolean", "default": true } }, "additionalProperties": false }, "spaceId": { "type": [ "string", "null" ] }, "listName": { "type": [ "string", "null" ] }, "spaceName": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "minLength": 1 }, "chatChannels": { "type": "array", "default": [], "items": { "type": "object", "required": [ "channelId", "name" ], "properties": { "name": { "type": "string" }, "channelId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "initialWindow": { "type": "string", "enum": [ "7d", "30d", "90d", "all" ] }, "workspaceName": { "type": "string" } }, "additionalProperties": false }, "loadMode": { "type": "string", "enum": [ "hot", "batch" ], "default": "hot" }, "model": { "type": [ "string", "null" ] }, "sourceAuthority": { "anyOf": [ { "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, { "type": "null" } ] } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "owner", "repo", "branch", "connectorId", "enabled", "lastRunAt", "loadMode", "model", "sourceAuthority", "effectiveModel", "degradedCount", "unmeasuredCount" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "repo": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "owner": { "type": [ "string", "null" ] }, "branch": { "type": [ "string", "null" ] }, "config": {}, "enabled": { "type": "boolean" }, "loadMode": { "type": "string" }, "lastRunAt": { "type": [ "string", "null" ] }, "lastResult": {}, "connectorId": { "type": [ "string", "null" ] }, "clickupConfig": {}, "degradedCount": { "type": "number" }, "effectiveModel": { "type": [ "string", "null" ] }, "sourceAuthority": { "type": [ "string", "null" ] }, "unmeasuredCount": { "type": "number" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}": { "delete": { "operationId": "brain_daemon_remove", "summary": "Remove an ingestion daemon and its connector state (leaves ingested memory)", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_remove", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "brain_daemon_get", "summary": "Get a specific ingestion daemon by id", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "name", "owner", "repo", "branch", "connectorId", "enabled", "lastRunAt", "loadMode", "model", "sourceAuthority", "effectiveModel", "degradedCount", "unmeasuredCount" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "repo": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "owner": { "type": [ "string", "null" ] }, "branch": { "type": [ "string", "null" ] }, "config": {}, "enabled": { "type": "boolean" }, "loadMode": { "type": "string" }, "lastRunAt": { "type": [ "string", "null" ] }, "lastResult": {}, "connectorId": { "type": [ "string", "null" ] }, "clickupConfig": {}, "degradedCount": { "type": "number" }, "effectiveModel": { "type": [ "string", "null" ] }, "sourceAuthority": { "type": [ "string", "null" ] }, "unmeasuredCount": { "type": "number" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "brain_daemon_update", "summary": "Update an ingestion daemon (config, enabled, name, branch)", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "config": { "type": "string" }, "clickupConfig": { "type": "object", "required": [ "workspaceId", "workspaceName", "spaceId", "spaceName", "listId", "listName" ], "properties": { "listId": { "type": [ "string", "null" ] }, "content": { "type": "object", "default": {}, "properties": { "chat": { "type": "boolean", "default": false }, "docs": { "type": "boolean", "default": true }, "tasks": { "type": "boolean", "default": true }, "comments": { "type": "boolean", "default": true } }, "additionalProperties": false }, "spaceId": { "type": [ "string", "null" ] }, "listName": { "type": [ "string", "null" ] }, "spaceName": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "minLength": 1 }, "chatChannels": { "type": "array", "default": [], "items": { "type": "object", "required": [ "channelId", "name" ], "properties": { "name": { "type": "string" }, "channelId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "initialWindow": { "type": "string", "enum": [ "7d", "30d", "90d", "all" ] }, "workspaceName": { "type": "string" } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "branch": { "type": "string" }, "loadMode": { "type": "string", "enum": [ "hot", "batch" ] }, "model": { "type": [ "string", "null" ] }, "sourceAuthority": { "anyOf": [ { "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, { "type": "null" } ] } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}/batch-status": { "get": { "operationId": "brain_daemon_batch_status", "summary": "Get batch ingestion status for a daemon (pending count, job, ETA, model, outcome)", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_batch_status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "daemonId", "loadMode", "supportsBatch", "model", "effectiveModel", "pendingCount", "run" ], "properties": { "run": { "anyOf": [ { "type": "object", "required": [ "runId", "status", "batchJobId", "submittedAt", "startedAt", "finishedAt", "model", "polls", "pollIntervalMs", "elapsedMs", "etaAt", "etaMs", "outcome", "counts", "errorMessage" ], "properties": { "etaAt": { "type": [ "string", "null" ] }, "etaMs": { "type": [ "number", "null" ] }, "model": { "type": [ "string", "null" ] }, "polls": { "type": "number" }, "runId": { "type": "string" }, "counts": { "type": "object", "properties": { "errored": { "type": "number" }, "finalized": { "type": "number" }, "submitted": { "type": "number" } }, "additionalProperties": false }, "status": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "finalized", "finalized-with-fallback", "below-min-files", "nothing-submitted", "timeout", "failed", "finalize-failed", "crash" ] }, { "type": "null" } ] }, "elapsedMs": { "type": [ "number", "null" ] }, "startedAt": { "type": "string" }, "batchJobId": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ] }, "submittedAt": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "pollIntervalMs": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "model": { "type": [ "string", "null" ] }, "daemonId": { "type": "string" }, "loadMode": { "type": "string" }, "pendingCount": { "type": "number" }, "supportsBatch": { "type": "boolean" }, "effectiveModel": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}/reingest": { "post": { "operationId": "brain_daemon_reingest", "summary": "Force re-ingest of specific document paths for a daemon: clears their stored content hash and triggers a realtime run, so degraded or never-measured documents are re-extracted instead of hash-skipped forever", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_reingest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paths": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1 } } }, "required": [ "paths" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cleared", "notFound", "skippedPending", "triggered" ], "properties": { "cleared": { "type": "array", "items": { "type": "string" } }, "notFound": { "type": "array", "items": { "type": "string" } }, "triggered": { "type": "boolean" }, "triggerError": { "type": "string" }, "skippedPending": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}/run": { "post": { "operationId": "brain_daemon_run", "summary": "Trigger an immediate run for a daemon and return its current status", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status", "done", "sources", "progress", "triggered", "routedTo" ], "properties": { "done": { "type": "boolean" }, "runId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed", "none" ] }, "sources": { "type": "array", "items": {} }, "progress": { "anyOf": [ { "type": "object", "required": [ "counts", "byCategory" ], "properties": { "counts": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false }, "byCategory": { "type": "object", "additionalProperties": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, { "type": "null" } ] }, "routedTo": { "type": "string", "enum": [ "realtime", "batch" ] }, "triggered": { "type": "boolean" }, "triggerError": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}/runs": { "get": { "operationId": "brain_daemon_runs", "summary": "Recent run history for a daemon with per-run ingest counts", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_runs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "daemonId", "runs" ], "properties": { "runs": { "type": "array", "items": { "type": "object", "required": [ "runId", "status", "lane", "outcome", "startedAt", "finishedAt", "counts", "deniedCount", "errorCount", "degradedCount" ], "properties": { "lane": { "type": "string", "enum": [ "realtime", "batch", "reclaimed" ] }, "runId": { "type": "string" }, "counts": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false }, "status": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "startedAt": { "type": "string" }, "errorCount": { "type": "number" }, "finishedAt": { "type": [ "string", "null" ] }, "deniedCount": { "type": "number" }, "degradedCount": { "type": [ "number", "null" ] } }, "additionalProperties": false } }, "daemonId": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/{id}/status": { "get": { "operationId": "brain_daemon_status", "summary": "Get the latest run status for a daemon", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status", "done", "sources", "progress" ], "properties": { "done": { "type": "boolean" }, "runId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed", "none" ] }, "sources": { "type": "array", "items": {} }, "progress": { "anyOf": [ { "type": "object", "required": [ "counts", "byCategory" ], "properties": { "counts": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false }, "byCategory": { "type": "object", "additionalProperties": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/gdrive/connections": { "get": { "operationId": "brain_gdrive_connections_list", "summary": "List Google Drive connections for this product with their picked files", "tags": [ "Brain" ], "x-mcp-tool": "brain_gdrive_connections_list", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "connectorId", "email", "displayName", "pickedFiles" ], "properties": { "email": { "type": "string" }, "connectorId": { "type": "string" }, "displayName": { "type": "string" }, "pickedFiles": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "mimeType" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mimeType": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/daemons/runs/{runId}/items": { "get": { "operationId": "brain_daemon_run_items", "summary": "List the per-item ingest ledger for a run (filter by outcome, esp.", "description": "List the per-item ingest ledger for a run (filter by outcome, esp. denied)", "tags": [ "Brain" ], "x-mcp-tool": "brain_daemon_run_items", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "discovered", "fetched", "ingested", "skipped_unchanged", "denied", "error" ] } }, { "name": "sourceKind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "counts", "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "sourceKind", "itemId", "outcome", "reason", "updatedAt" ], "properties": { "itemId": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "discovered", "fetched", "ingested", "skipped_unchanged", "denied", "error" ] }, "updatedAt": { "type": "string" }, "sourceKind": { "type": "string" } }, "additionalProperties": false } }, "runId": { "type": "string" }, "counts": { "type": "object", "required": [ "discovered", "fetched", "ingested", "skippedUnchanged", "denied", "error" ], "properties": { "error": { "type": "number" }, "denied": { "type": "number" }, "fetched": { "type": "number" }, "ingested": { "type": "number" }, "discovered": { "type": "number" }, "skippedUnchanged": { "type": "number" } }, "additionalProperties": false }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/knowledge/entities": { "get": { "operationId": "brain_knowledge_search", "summary": "Search product knowledge-graph entities (Feature, Decision, Risk, …) for the current product", "tags": [ "Brain" ], "x-mcp-tool": "brain_knowledge_search", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Filter by entity name / alias substring", "schema": { "type": "string", "minLength": 1 } }, { "name": "entity_type", "in": "query", "required": false, "description": "Filter by ontology entity type (e.g. Feature, Integration)", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max entities", "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entities", "total", "request_id", "elapsed_ms" ], "properties": { "total": { "type": "number" }, "entities": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "entity_type", "canonical_name", "display_name", "aliases", "description", "evidence_count" ], "properties": { "score": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "entity_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entity_type": { "type": "string" }, "display_name": { "type": "string" }, "canonical_name": { "type": "string" }, "evidence_count": { "type": "number" } }, "additionalProperties": false } }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/knowledge/entities/{entity_ref}/memories": { "get": { "operationId": "brain_knowledge_entity_memories", "summary": "List the memories a knowledge entity was extracted from (its DERIVED_FROM evidence)", "tags": [ "Brain" ], "x-mcp-tool": "brain_knowledge_entity_memories", "parameters": [ { "name": "entity_ref", "in": "path", "required": true, "description": "Entity id, name, or alias to fetch backing memories for", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max memories (default 50)", "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity", "memories", "total", "request_id", "elapsed_ms" ], "properties": { "total": { "type": "number" }, "entity": { "anyOf": [ { "type": "object", "required": [ "entity_id", "entity_type", "canonical_name", "display_name", "aliases", "description", "evidence_count" ], "properties": { "score": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "entity_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entity_type": { "type": "string" }, "display_name": { "type": "string" }, "canonical_name": { "type": "string" }, "evidence_count": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "memories": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "content", "layer", "status", "memory_at", "gmt_created", "user_id", "agent_id", "session_id", "speculate", "source_raw_memory_id", "tags", "custom", "source_authority", "kind" ], "properties": { "kind": { "description": "Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer", "type": "string", "enum": [ "schema", "intention", "identity", "basic", "fact", "summary", "knowledge", "raw", "unknown" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "custom": { "type": "object", "additionalProperties": {} }, "status": { "type": "string" }, "content": { "type": "string" }, "user_id": { "type": "string" }, "agent_id": { "type": "string" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "session_id": { "type": "string" }, "gmt_created": { "type": "number" }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/knowledge/entities/{entity_ref}/neighborhood": { "get": { "operationId": "brain_knowledge_neighborhood", "summary": "Expand the neighborhood (related entities + relations) around one knowledge entity", "tags": [ "Brain" ], "x-mcp-tool": "brain_knowledge_neighborhood", "parameters": [ { "name": "entity_ref", "in": "path", "required": true, "description": "Entity id or name to expand around", "schema": { "type": "string", "minLength": 1 } }, { "name": "depth", "in": "query", "required": false, "description": "Hops to expand (engine clamps to 3)", "schema": { "type": "integer", "maximum": 3, "exclusiveMinimum": 0 } }, { "name": "relation_type", "in": "query", "required": false, "description": "Only traverse this relation type", "schema": { "type": "string", "minLength": 1 } }, { "name": "entity_type", "in": "query", "required": false, "description": "Only include neighbors of this entity type", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max neighbors", "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "root", "entities", "relations", "request_id", "elapsed_ms" ], "properties": { "root": { "anyOf": [ { "type": "object", "required": [ "entity_id", "entity_type", "canonical_name", "display_name", "aliases", "description", "evidence_count" ], "properties": { "score": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "entity_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entity_type": { "type": "string" }, "display_name": { "type": "string" }, "canonical_name": { "type": "string" }, "evidence_count": { "type": "number" } }, "additionalProperties": false }, { "type": "null" } ] }, "entities": { "type": "array", "items": { "type": "object", "required": [ "entity_id", "entity_type", "canonical_name", "display_name", "aliases", "description", "evidence_count" ], "properties": { "score": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "entity_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entity_type": { "type": "string" }, "display_name": { "type": "string" }, "canonical_name": { "type": "string" }, "evidence_count": { "type": "number" } }, "additionalProperties": false } }, "relations": { "type": "array", "items": { "type": "object", "required": [ "source_id", "target_id", "relation_type", "symmetric", "reason", "source_display_name", "source_canonical_name", "target_display_name", "target_canonical_name" ], "properties": { "reason": { "type": [ "string", "null" ] }, "source_id": { "type": "string" }, "symmetric": { "type": "boolean" }, "target_id": { "type": "string" }, "relation_type": { "type": "string" }, "source_display_name": { "type": "string" }, "target_display_name": { "type": "string" }, "source_canonical_name": { "type": "string" }, "target_canonical_name": { "type": "string" } }, "additionalProperties": false } }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/knowledge/graph": { "get": { "operationId": "brain_knowledge_graph", "summary": "Export the product knowledge graph (entities + typed relations) as nodes and edges; truncation keeps the highest-degree nodes, so a small limit returns the hub concepts", "tags": [ "Brain" ], "x-mcp-tool": "brain_knowledge_graph", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max nodes (default 5000). When the cap applies the HIGHEST-DEGREE nodes are kept, so a small limit (e.g. 100) returns the hub concepts — that is usually what you want", "schema": { "type": "integer", "maximum": 5000, "exclusiveMinimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "nodes", "edges", "totals", "truncated", "request_id", "elapsed_ms" ], "properties": { "edges": { "type": "array", "items": { "type": "object", "required": [ "source", "target", "relation_type", "symmetric", "reason" ], "properties": { "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "target": { "type": "string" }, "symmetric": { "type": "boolean" }, "relation_type": { "type": "string" } }, "additionalProperties": false } }, "nodes": { "type": "array", "items": { "type": "object", "required": [ "id", "entity_type", "canonical_name", "display_name", "aliases", "description", "evidence_count", "degree" ], "properties": { "id": { "type": "string" }, "degree": { "type": "number" }, "aliases": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "entity_type": { "type": "string" }, "display_name": { "type": "string" }, "canonical_name": { "type": "string" }, "evidence_count": { "type": "number" } }, "additionalProperties": false } }, "totals": { "type": "object", "required": [ "nodeCount", "edgeCount" ], "properties": { "edgeCount": { "type": "number" }, "nodeCount": { "type": "number" } }, "additionalProperties": false }, "truncated": { "type": "boolean" }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/knowledge/relations": { "get": { "operationId": "brain_knowledge_relations", "summary": "List typed relations (depends_on, competes_with, …) in the product knowledge graph", "tags": [ "Brain" ], "x-mcp-tool": "brain_knowledge_relations", "parameters": [ { "name": "relation_type", "in": "query", "required": false, "description": "Filter by ontology relation type (e.g. depends_on)", "schema": { "type": "string", "minLength": 1 } }, { "name": "source_entity", "in": "query", "required": false, "description": "Filter by source entity id or name", "schema": { "type": "string", "minLength": 1 } }, { "name": "target_entity", "in": "query", "required": false, "description": "Filter by target entity id or name", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max relations", "schema": { "type": "integer", "maximum": 200, "exclusiveMinimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "relations", "request_id", "elapsed_ms" ], "properties": { "relations": { "type": "array", "items": { "type": "object", "required": [ "source_id", "target_id", "relation_type", "symmetric", "reason", "source_display_name", "source_canonical_name", "target_display_name", "target_canonical_name" ], "properties": { "reason": { "type": [ "string", "null" ] }, "source_id": { "type": "string" }, "symmetric": { "type": "boolean" }, "target_id": { "type": "string" }, "relation_type": { "type": "string" }, "source_display_name": { "type": "string" }, "target_display_name": { "type": "string" }, "source_canonical_name": { "type": "string" }, "target_canonical_name": { "type": "string" } }, "additionalProperties": false } }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/memory": { "get": { "operationId": "brain_memory_list", "summary": "List memories (shared + your private by default)", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_list", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "exclusiveMinimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "memories", "total" ], "properties": { "total": { "type": "number" }, "memories": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "content", "layer", "status", "memory_at", "gmt_created", "user_id", "agent_id", "session_id", "speculate", "source_raw_memory_id", "tags", "custom", "source_authority", "kind" ], "properties": { "kind": { "description": "Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer", "type": "string", "enum": [ "schema", "intention", "identity", "basic", "fact", "summary", "knowledge", "raw", "unknown" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "custom": { "type": "object", "additionalProperties": {} }, "status": { "type": "string" }, "content": { "type": "string" }, "user_id": { "type": "string" }, "agent_id": { "type": "string" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "session_id": { "type": "string" }, "gmt_created": { "type": "number" }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "brain_memory_add", "summary": "Store a memory for the current product", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_add", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "The memory text to store", "type": "string", "minLength": 1 }, "metadata": { "description": "Optional structured metadata", "type": "object", "additionalProperties": {} }, "scope": { "description": "'shared' = product-wide pool (default); 'private' = this agent only", "type": "string", "enum": [ "shared", "private" ], "default": "shared" }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal. Omit to default to official; an unrecognized value is rejected.", "type": "string", "enum": [ "policy", "official", "team", "informal" ] } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "memory_id", "request_id" ], "properties": { "success": { "type": "boolean" }, "memory_id": { "type": "string" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/memory/{memory_id}": { "delete": { "operationId": "brain_memory_delete", "summary": "Delete a memory you own (or a shared one)", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_delete", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "description": "Engine memory id", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "deleted_count", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "request_id": { "type": "string" }, "deleted_count": { "type": "number" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "brain_memory_get", "summary": "Get one memory by id (product+agent scoped)", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_get", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "description": "Engine memory id", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "memory_id", "content", "layer", "status", "is_latest", "supersedes", "superseded_by", "tags", "memory_at", "gmt_created", "speculate", "source_raw_memory_id", "user_id", "agent_id", "confidence", "custom", "source", "source_authority", "request_id", "elapsed_ms" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "custom": { "type": "object", "additionalProperties": {} }, "source": { "type": "string", "enum": [ "vdb", "graph" ] }, "status": { "type": "string" }, "content": { "type": "string" }, "user_id": { "type": "string" }, "agent_id": { "type": "string" }, "is_latest": { "type": "boolean" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "confidence": { "type": "number" }, "elapsed_ms": { "type": "number" }, "request_id": { "type": "string" }, "supersedes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "gmt_created": { "type": "number" }, "superseded_by": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "brain_memory_update", "summary": "Replace a memory you own (or a shared one)", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_update", "parameters": [ { "name": "memory_id", "in": "path", "required": true, "description": "Engine memory id", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "Replacement content", "type": "string", "minLength": 1 } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "memory_id", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "memory_id": { "type": "string" }, "request_id": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/memory/search": { "get": { "operationId": "brain_memory_search", "summary": "Search memories for the current product", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_search", "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Natural-language search query", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Max results per channel", "schema": { "type": "integer", "maximum": 100, "exclusiveMinimum": 0 } }, { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private. A person sees shared only (empty private namespace).", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "profile", "normal", "proactive" ], "properties": { "normal": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "content", "score", "layer", "speculate", "source_raw_memory_id", "tags", "memory_at", "gmt_created", "source_authority", "kind" ], "properties": { "kind": { "description": "Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer", "type": "string", "enum": [ "schema", "intention", "identity", "basic", "fact", "summary", "knowledge", "raw", "unknown" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "score": { "type": "number" }, "content": { "type": "string" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "gmt_created": { "type": "number" }, "schema_type": { "type": "string" }, "evolution_chain": { "type": "array", "items": { "type": "string" } }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "profile": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "content", "score", "layer", "speculate", "source_raw_memory_id", "tags", "memory_at", "gmt_created", "source_authority", "kind" ], "properties": { "kind": { "description": "Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer", "type": "string", "enum": [ "schema", "intention", "identity", "basic", "fact", "summary", "knowledge", "raw", "unknown" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "score": { "type": "number" }, "content": { "type": "string" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "gmt_created": { "type": "number" }, "schema_type": { "type": "string" }, "evolution_chain": { "type": "array", "items": { "type": "string" } }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "proactive": { "type": "array", "items": { "type": "object", "required": [ "memory_id", "content", "score", "layer", "speculate", "source_raw_memory_id", "tags", "memory_at", "gmt_created", "source_authority", "kind" ], "properties": { "kind": { "description": "Consumer-facing label derived from the layer; 'unknown' for an unrecognised layer", "type": "string", "enum": [ "schema", "intention", "identity", "basic", "fact", "summary", "knowledge", "raw", "unknown" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "layer": { "description": "Engine memory layer (l0_basic_info…l7_intention)", "type": "string", "enum": [ "l6_schema", "l7_intention", "l4_identity", "l0_basic_info", "l2_fact", "l3_summary", "l5_knowledge", "l1_raw" ] }, "score": { "type": "number" }, "content": { "type": "string" }, "memory_at": { "type": [ "number", "null" ] }, "memory_id": { "type": "string" }, "speculate": { "type": [ "string", "null" ] }, "gmt_created": { "type": "number" }, "schema_type": { "type": "string" }, "evolution_chain": { "type": "array", "items": { "type": "string" } }, "source_authority": { "description": "Source authority (highest→lowest): policy > official > team > informal", "type": "string", "enum": [ "policy", "official", "team", "informal" ] }, "source_raw_memory_id": { "type": [ "string", "null" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/memory/stats": { "get": { "operationId": "brain_memory_stats", "summary": "Summary counts for the current product (memories by layer, graph nodes/edges, entities)", "tags": [ "Brain" ], "x-mcp-tool": "brain_memory_stats", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Read scope; 'both' (default) unions shared + your private", "schema": { "type": "string", "enum": [ "shared", "private", "both" ], "default": "both" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "memories", "graph", "knowledge" ], "properties": { "graph": { "type": "object", "required": [ "nodeCount", "edgeCount" ], "properties": { "edgeCount": { "type": "number" }, "nodeCount": { "type": "number" } }, "additionalProperties": false }, "memories": { "type": "object", "required": [ "total", "byLayer" ], "properties": { "total": { "type": "number" }, "byLayer": { "type": "object", "required": [ "l2", "l3", "l4" ], "properties": { "l2": { "type": "number" }, "l3": { "type": "number" }, "l4": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false }, "knowledge": { "type": "object", "required": [ "entityCount" ], "properties": { "entityCount": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/restores": { "post": { "operationId": "brain_backup_restore", "summary": "DESTRUCTIVE: full-replace restore of the current product's Brain from a snapshot (wipe + load).", "description": "DESTRUCTIVE: full-replace restore of the current product's Brain from a snapshot (wipe + load). Takes an automatic pre-restore snapshot first (safety net). Requires confirm:true AND confirmProductId echo; refuses on product/snapshot mismatch or embedding-dims mismatch. Async — returns { accepted, restoreId }; poll brain_restore_status.", "tags": [ "Brain" ], "x-mcp-tool": "brain_backup_restore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshotId": { "description": "The snapshot id to restore for the current product.", "type": "string", "minLength": 1 }, "confirmProductId": { "description": "Must EXACTLY equal the current product id (double-entry confirmation).", "type": "string", "minLength": 1 }, "confirm": { "description": "Must be true. DESTRUCTIVE: the product's current Brain is wiped and replaced.", "type": "boolean" } }, "required": [ "snapshotId", "confirmProductId", "confirm" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted", "restoreId" ], "properties": { "accepted": { "type": "boolean", "const": true }, "restoreId": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/restores/{restoreId}": { "get": { "operationId": "brain_restore_status", "summary": "Read a restore run's status (pending|wiped|importing|completed|failed) with counts + timing, by restoreId (returned by brain_backup_restore).", "tags": [ "Brain" ], "x-mcp-tool": "brain_restore_status", "parameters": [ { "name": "restoreId", "in": "path", "required": true, "description": "The restore run id (returned by brain_backup_restore).", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "restoreId", "productId", "snapshotId", "preRestoreSnapshotId", "status", "nodeCount", "edgeCount", "error", "startedAt", "finishedAt" ], "properties": { "error": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "wiped", "importing", "completed", "failed" ] }, "edgeCount": { "type": [ "number", "null" ] }, "nodeCount": { "type": [ "number", "null" ] }, "productId": { "type": "string" }, "restoreId": { "type": "string" }, "startedAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "snapshotId": { "type": "string" }, "preRestoreSnapshotId": { "type": [ "string", "null" ] } }, "additionalProperties": false }, { "type": "null" } ] } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/usage/report": { "get": { "operationId": "brain_usage_report", "summary": "Reported LLM/embedding token usage for this product, next to the platform billing aggregate", "tags": [ "Brain" ], "x-mcp-tool": "brain_usage_report", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many UTC days of this product's ledger to return, ending today (default 30, max 90)", "schema": { "type": "integer", "default": 30, "maximum": 90, "exclusiveMinimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "platform", "platform_error", "note" ], "properties": { "note": { "type": "string" }, "product": { "description": "Brain's own ledger, for THIS product only", "type": "object", "required": [ "product_id", "days", "from", "to", "rows", "totals" ], "properties": { "to": { "description": "Inclusive UTC end of the window (today), YYYY-MM-DD", "type": "string" }, "days": { "description": "The window actually used, after clamping", "type": "number" }, "from": { "description": "Inclusive UTC start of the window, YYYY-MM-DD", "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "usage_date", "meter", "model", "mode", "purpose", "tokens", "events", "delivery_failed" ], "properties": { "mode": { "description": "'sync' | 'batch'; '' when the push carried none", "type": "string" }, "meter": { "description": "Manifest meter slug, e.g. llm-tokens", "type": "string" }, "model": { "description": "Model dimension; '' when the push carried none", "type": "string" }, "events": { "description": "How many record() calls landed in this slice", "type": "number" }, "tokens": { "description": "Tokens we metered for this slice, delivered or not", "type": "number" }, "purpose": { "description": "Purpose dimension; '' when the push carried none", "type": "string" }, "usage_date": { "description": "UTC calendar day, YYYY-MM-DD", "type": "string" }, "delivery_failed": { "description": "Of those events, how many billing did not accept", "type": "number" } }, "additionalProperties": false } }, "totals": { "description": "The rows rolled up per meter across the whole window", "type": "array", "items": { "type": "object", "required": [ "meter", "tokens", "events", "delivery_failed" ], "properties": { "meter": { "type": "string" }, "events": { "type": "number" }, "tokens": { "type": "number" }, "delivery_failed": { "type": "number" } }, "additionalProperties": false } }, "product_id": { "type": "string" } }, "additionalProperties": false }, "platform": { "description": "The platform billing aggregate for the whole ORG; null if it could not be read", "anyOf": [ { "type": "object", "required": [ "scope", "org_id", "plan", "meters" ], "properties": { "plan": { "type": "string" }, "scope": { "type": "string", "const": "org" }, "meters": { "type": "array", "items": { "type": "object", "required": [ "meter_slug" ], "properties": { "unit": { "type": "string" }, "used": { "type": "number" }, "limit": { "type": [ "number", "null" ] }, "remaining": { "type": [ "number", "null" ] }, "unlimited": { "type": "boolean" }, "meter_slug": { "type": "string" } }, "additionalProperties": false } }, "org_id": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "platform_error": { "description": "Why the platform aggregate is null; null when it was read successfully", "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/vcs/branches": { "get": { "operationId": "brain_connector_branches_list", "summary": "List branches for a repository on a GitHub connection", "tags": [ "Brain" ], "x-mcp-tool": "brain_connector_branches_list", "parameters": [ { "name": "connectorId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "repoFullName", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^[^/]+\\/[^/]+$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "name", "commitSha" ], "properties": { "name": { "type": "string" }, "commitSha": { "type": "string" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/vcs/connections": { "get": { "operationId": "brain_connector_connections_list", "summary": "List the GitHub connections available to the current product", "tags": [ "Brain" ], "x-mcp-tool": "brain_connector_connections_list", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "connectorId", "installationId", "accountLogin", "status" ], "properties": { "status": { "type": "string" }, "connectorId": { "type": "string" }, "accountLogin": { "type": "string" }, "installationId": { "type": "string" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brain/vcs/repos": { "get": { "operationId": "brain_connector_repos_list", "summary": "List repositories accessible to a GitHub connection (optionally filtered by search)", "tags": [ "Brain" ], "x-mcp-tool": "brain_connector_repos_list", "parameters": [ { "name": "connectorId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "fullName", "private", "defaultBranch" ], "properties": { "private": { "type": "boolean" }, "fullName": { "type": "string" }, "defaultBranch": { "type": "string" } }, "additionalProperties": false } } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/config": { "patch": { "operationId": "consent_config_floating_icon_upsert", "summary": "Configures the always-available \"Cookie settings\" entry point that lets a visitor reopen their consent preferences after they have made a choice.", "description": "Configures the always-available \"Cookie settings\" entry point that lets a visitor reopen their consent preferences after they have made a choice. By default Lessly renders a floating icon in a page corner; you can move it, or bind the entry point to an element the site already has (for example a \"Cookie settings\" link in the footer) instead of showing the icon. Fields (under `floatingIcon`): enabled — whether to render Lessly's built-in floating icon; position — which corner the icon sits in (\"bottom-right\" / \"bottom-left\" / \"top-right\" / \"top-left\"); customSelector — a CSS selector for an existing element on the page (e.g. \"#footer-cookie-link\") whose click opens consent settings, or null to rely on the built-in icon only. To hide the built-in icon (enabled: false) you must provide a customSelector, so the visitor always keeps a way to reopen settings.", "tags": [ "Consent" ], "x-mcp-tool": "consent_config_floating_icon_upsert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "floatingIcon": { "type": "object", "required": [ "enabled", "position", "customSelector" ], "properties": { "enabled": { "type": "boolean" }, "position": { "type": "string", "enum": [ "bottom-right", "bottom-left", "top-right", "top-left" ] }, "customSelector": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7E]+$" }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "floatingIcon" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "floatingIcon" ], "properties": { "floatingIcon": { "type": "object", "required": [ "enabled", "position", "customSelector" ], "properties": { "enabled": { "type": "boolean" }, "position": { "type": "string", "enum": [ "bottom-right", "bottom-left", "top-right", "top-left" ] }, "customSelector": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/config/cookie-domain": { "patch": { "operationId": "consent_config_cookie_domain_upsert", "summary": "Sets an explicit cookie Domain for the consent cookie (lessly_consent).", "description": "Sets an explicit cookie Domain for the consent cookie (lessly_consent). By default the banner derives the widest owned boundary automatically: the registrable domain (eTLD+1) on customer sites, or the deploy host on Lessly platform hosts — so consent given on site.com also covers docs.site.com. Set cookieDomain only to NARROW that perimeter, e.g. when several Lessly products live on subdomains of one domain and each must keep its own consent (cookieDomain: \"docs.site.com\" on the docs product). The value must be a suffix of the page hostname at runtime, otherwise the banner ignores it and falls back to auto-derivation. Platform deploy suffixes (lessly.dev / lessly.com / lessly.run / lessly.tech / v2.*) are rejected — a cookie on those would leak consent across tenants. Pass null or an empty string to remove the override.", "tags": [ "Consent" ], "x-mcp-tool": "consent_config_cookie_domain_upsert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cookieDomain": { "anyOf": [ { "type": "string", "const": "" }, { "type": "null" }, { "type": "string", "pattern": "^(?=.{1,253}$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$" } ] } }, "required": [ "cookieDomain" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cookieDomain" ], "properties": { "cookieDomain": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/config/customization": { "patch": { "operationId": "consent_config_customization_upsert", "summary": "Fine-tunes the banner beyond brand tokens, when the theme alone is not enough.", "description": "Fine-tunes the banner beyond brand tokens, when the theme alone is not enough. logoUrl / coverUrl — https URLs to images hosted on the client's side (we store nothing; an empty string removes the asset; an external URL exposes the visitor's IP to that host); coverUrl is a header strip across the top of the banner. position — where the banner sits on the page (\"bottom\" / \"top\" / \"bottom-left\" / \"bottom-right\" / \"center-modal\"); this is the banner's placement, distinct from the reopen-icon corner in consent_config_floating_icon_upsert. logoAlign — \"start\" / \"center\" / \"end\"; contentAlign — \"start\" / \"center\". All fields are optional and patch-merge onto the previous customization. This layer does not change button equality (\"Accept all\" / \"Reject all\") or the provider list.", "tags": [ "Consent" ], "x-mcp-tool": "consent_config_customization_upsert", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "logoUrl": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "string", "const": "" } ] }, "coverUrl": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "string", "const": "" } ] }, "position": { "type": "string", "enum": [ "bottom", "top", "bottom-left", "bottom-right", "center-modal" ] }, "logoAlign": { "type": "string", "enum": [ "start", "center", "end" ] }, "contentAlign": { "type": "string", "enum": [ "start", "center" ] } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "customization", "customizationInput" ], "properties": { "customization": { "type": "object", "additionalProperties": {} }, "customizationInput": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/config/theme": { "patch": { "operationId": "consent_config_theme_upsert", "summary": "Adapts the consent banner's appearance to the site's brand.", "description": "Adapts the consent banner's appearance to the site's brand. Pass what you observe on the client's site: brandColor — the site's primary brand color (any CSS color); surface — whether the site is \"light\" or \"dark\"; corners — button corner shape (\"sharp\" / \"rounded\" / \"pill\"); font — the site's font, given as a font name, a full CSS font stack, or \"inherit\" to adopt the host page's font. If the brand tokens are not enough, fine-tune `overrides`: backgroundColor, textColor, primaryTextColor, borderColor, focusColor, dangerColor, successColor, warningColor. primaryTextColor sets the text on the primary button; without it that text is derived from primaryColor. Fails when: primaryTextColor contrasts below 3.0:1 against the effective primaryColor — the patch is rejected, naming the computed ratio. All fields are optional and patch-merge onto the previous theme. To identify the site: use a URL from the request; otherwise the latest decision `pageUrl`; otherwise ask the user once. This layer is cosmetic only — after applying, \"Accept all\" and \"Reject all\" stay equally prominent and the provider list is unchanged.", "tags": [ "Consent" ], "x-mcp-tool": "consent_config_theme_upsert", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "brandColor": { "type": "string" }, "surface": { "type": "string", "enum": [ "light", "dark" ] }, "corners": { "type": "string", "enum": [ "sharp", "rounded", "pill" ] }, "font": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-zA-Z0-9 ,'\"_-]+$" }, "overrides": { "type": "object", "properties": { "textColor": { "type": "string" }, "focusColor": { "type": "string" }, "borderColor": { "type": "string" }, "dangerColor": { "type": "string" }, "successColor": { "type": "string" }, "warningColor": { "type": "string" }, "backgroundColor": { "type": "string" }, "primaryTextColor": { "type": "string" } }, "additionalProperties": false } }, "required": [] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "theme", "themeInput" ], "properties": { "theme": { "type": "object", "additionalProperties": {} }, "themeInput": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/consent/dashboard/config": { "get": { "operationId": "consent_dashboard_config_get", "summary": "Returns consent config for the current product: theme — the editable brand-theme intent previously set via consent_config_theme_upsert; customization — the editable escape-hatch intent (logo/cover URLs, position, alignment) set via consent_config_customization_upsert (empty object if none set yet) — and floatingIcon (trigger settings).", "description": "Returns consent config for the current product: theme — the editable brand-theme intent previously set via consent_config_theme_upsert; customization — the editable escape-hatch intent (logo/cover URLs, position, alignment) set via consent_config_customization_upsert (empty object if none set yet) — and floatingIcon (trigger settings). When no consent_config row exists, returns defaults; never 404s.", "tags": [ "Consent" ], "x-mcp-tool": "consent_dashboard_config_get", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "theme", "customization", "floatingIcon" ], "properties": { "theme": { "type": "object", "additionalProperties": {} }, "floatingIcon": { "type": "object", "required": [ "enabled", "position", "customSelector" ], "properties": { "enabled": { "type": "boolean" }, "position": { "type": "string", "enum": [ "bottom-right", "bottom-left", "top-right", "top-left" ] }, "customSelector": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "customization": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/consent/dashboard/decisions": { "get": { "operationId": "consent_dashboard_decisions_list", "summary": "Returns the latest consent decisions for the current product — each with its HMAC signature (`stamp`) and a computed accept/deny/custom/withdrawal label.", "description": "Returns the latest consent decisions for the current product — each with its HMAC signature (`stamp`) and a computed accept/deny/custom/withdrawal label. Read-only; useful to confirm decisions are still being signed.", "tags": [ "Consent" ], "x-mcp-tool": "consent_dashboard_decisions_list", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of records to return (1..10, default 10)", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset (>=0, default 0)", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "stamp", "utc", "label", "method", "flags", "region" ], "properties": { "id": { "type": "string" }, "utc": { "type": "number" }, "flags": { "type": "object", "required": [ "necessary", "preferences", "statistics", "marketing" ], "properties": { "marketing": { "type": "boolean" }, "necessary": { "type": "boolean" }, "statistics": { "type": "boolean" }, "preferences": { "type": "boolean" } }, "additionalProperties": false }, "label": { "type": "string", "enum": [ "accept", "deny", "custom", "withdrawal" ] }, "stamp": { "type": "string" }, "method": { "type": "string", "enum": [ "explicit", "implied", "withdrawal" ] }, "region": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "additionalProperties": false } } } }, "401": { "description": "Missing, malformed or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "The request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/consent/consent/dashboard/embed-snippet": { "get": { "operationId": "consent_dashboard_embed_snippet_get", "summary": "Returns the consent banner embed