Agent API

← Reference

Every operation agents and your own programs can call, with sign-in, request body, and response codes. The agent API is in beta and may change.

All addresses are relative to https://api.monomer.cc. REST requests and responses use JSON; the OAuth token and revoke endpoints take form bodies. For the sign-in flow and token lifetimes, follow Connect a REST client; for MCP clients, follow Connect an agent. What each error status means is in Errors.

Download the contract

REST and MCP verify Bearer credentials before decoding request bodies. Invalid credentials return 401; a missing target or membership returns 404; insufficient roles return 403 ROLE_REQUIRED. Agent input-value errors return 400, concurrency conflicts 409, and execution backpressure 503 EXECUTION_BACKPRESSURED. UUID target IDs and UUID resource-path segments use canonical lowercase hyphenated UUIDs. See Errors for codes and safe recovery.

Retryable 503 responses carry Retry-After: 2; non-retryable 503 responses omit it. If a Dashboard create, Explore start, or Semantic create returns OWNER_UNAVAILABLE with retryable:false, read or list the target before resending because the change may already exist. Unexpected owner failures use OWNER_UNAVAILABLE; invalid owner response contracts use AGENT_OWNER_RESPONSE_INVALID; unexpected owner execution argument errors use 500 INTERNAL_ERROR. Response contract violations after those creates or starts also set retryable:false and require reading or listing the target before resending.

Agent OpenAPI: the operations on this page as OpenAPI 3.1.
Agent schema: request and response bodies for the resource operations, including each resource path and action.
Problem Details schema: the error body.

Discovery & Organization

Start here. POST /v2/agent/list with {"path":"workspaces"} or {"path":"organizations"} returns what you can access. Each Workspace has workspaceId, organizationId, organizationDisplayName, displayName, and sample. sample is {"dataset":"acme-cloud@3"} (or an earlier acme-cloud@ version) for a Workspace with Monomer’s read-only sample data and null for a Workspace with your own data; identify a sample by this field rather than its display name. A sample that is still being prepared is not listed. Organization operations take the Organization ID in the URL and support list, read, create, and invoke.

`POST /v2/agent/list`

List the Organizations or Workspaces you can access.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, fields path
Responses: 200, 400, 401, 500, 503

`POST /v2/agent/organizations/{organizationId}/list`

List Organization resources.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentOrganizationListRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/agent/organizations/{organizationId}/read`

Read an Organization resource.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentOrganizationReadRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/agent/organizations/{organizationId}/create`

Create an Organization resource.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentOrganizationCreateRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/agent/organizations/{organizationId}/invoke`

Invoke an Organization action.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentOrganizationInvokeRequest
Responses: 200, 202, 400, 401, 403, 404, 409, 429, 500, 503

Workspace

Workspace operations take the Workspace ID in the URL; omit it from the body. list and read take a resource path, search finds resources by name and description or Pages by display title, create and edit change resources, and invoke runs an action that a resource advertises, such as running a query or applying a dashboard draft. Your Workspace role decides which of these succeed.

To find Pages, send {"path":"workspace/pages","queries":["weekly revenue"],"limitPerQuery":20} to POST /v2/workspaces/{workspaceId}/agent/search.

Page search allows Viewer or higher and uses the same Page access rules as the app. Viewer sees only currently placed Pages; Explorer or higher can also find unplaced Pages. Deleted Pages are excluded. Every whitespace-separated query word must occur in the display title, ignoring case. Page descriptions and Document content are not searched. Results use the same Page listing items as list; Viewer receives reader metadata without internal Dashboard or version references, timestamps, or provenance.

You can also use "path":"workspace" with "kinds":["PAGE"] for Page-only search. Other searches require Explorer or higher. Omitting kinds at workspace searches all eight supported kinds; omitting it at workspace/pages searches Pages only. A mixed search returns ranked metadata matches first, then Page matches, within one limitPerQuery for each query. See MCP tools for the equivalent tool call.

`GET /v2/workspaces/{workspaceId}/agent/explore/runs/{runId}/result`

Download an Explore result with Agent REST OAuth authorization.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Query parameters: format
Responses: 200, 400, 401, 403, 404, 409, 410, 503

`POST /v2/workspaces/{workspaceId}/agent/list`

List Workspace resources.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentListRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/workspaces/{workspaceId}/agent/search`

Search Workspace resources.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentSearchRequest
Responses: 200, 400, 401, 403, 404, 500, 503

`POST /v2/workspaces/{workspaceId}/agent/read`

Read a Workspace resource.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentReadRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/workspaces/{workspaceId}/agent/create`

Create a Workspace resource.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentCreateRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/workspaces/{workspaceId}/agent/edit`

Edit a Workspace resource.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentEditRequest
Responses: 200, 400, 401, 403, 404, 409, 500, 503

`POST /v2/workspaces/{workspaceId}/agent/invoke`

Invoke a Workspace action.

Sign-in: OAuth access token for https://api.monomer.cc/v2/workspaces, scope agent.workspace
Request body: application/json, AgentInvokeRequest
Responses: 200, 202, 400, 401, 403, 404, 409, 429, 500, 503

Workspace access and Reporting time zone

READ workspace/access is available to Viewer or higher. It returns your role, the organizationId, the authorizationRevision, and the Workspace’s reportingTimeZone, an IANA name such as UTC or Asia/Seoul. Metric queries group and filter times in that zone. Agents cannot change it; Owners and Organization Admins change it in the web app. Explore and Dashboard result reads of a metric query include the reportingTimeZone the result used, which is null for SQL results. See Time zones and dates.

Metric source Connector candidates

LIST workspace/metrics returns a required sourceConnectors: [{connectorId, displayName}] on each METRIC item. READ workspace/metrics/{name} returns the same field on the envelope, alongside body; it is not part of the editable definition. An empty candidate list is []. These operations require Explorer or higher.

Candidates are current Connectors in the requested Workspace with a source definition for every model in the metric’s dependencies, including stored metric and input filters. Missing references, deleted Connectors, and other-Workspace Connectors cannot supply candidates. For a query with several metrics, intersect their connectorId values and choose one shared by all of them. See Analyze a metric for the workflow.

sourceConnectors does not validate Catalog, MetricFlow, calendar tables, or warehouse execution. The existing metric check action’s check.runsOn reports Connector IDs that passed current Catalog and MetricFlow validation and representative query rendering; it still does not run a warehouse query. In MCP, describe the advertised check entry and call monomer_check; REST uses the existing invoke route. REST and MCP return the same candidate fields and enforce the same Workspace access.

MCP

MCP clients send JSON-RPC messages to one endpoint. Every MCP request, including initialization, notifications and listing tools, requires an OAuth access token for https://api.monomer.cc/mcp. The tools are described in MCP tools.

The MCP tool surface follows resource discovery: list Workspaces, read workspace, follow availableOperations, and pass entire operation entries to monomer_describe before constructing inputs. Describe is MCP-only and takes no target ID; REST clients use the downloadable schemas above. After a write, confirm result.path with a read for a resource or a list for a collection. Resolve names referenced inside definitions with monomer_search.

`GET /mcp`

Open an event stream (not supported).

Sign-in: OAuth access token for https://api.monomer.cc/mcp, scope agent.workspace
Responses: 401, 405, 503

`POST /mcp`

Send an MCP JSON-RPC message.

Sign-in: OAuth access token for https://api.monomer.cc/mcp, scope agent.workspace
Request body: application/json, a JSON object
Responses: 200, 202, 400, 401, 403, 429, 503

`DELETE /mcp`

Delete a session (not supported).

Sign-in: OAuth access token for https://api.monomer.cc/mcp, scope agent.workspace
Responses: 401, 405, 503

OAuth & metadata

Clients discover the OAuth endpoints from the metadata documents, then sign in through the browser and exchange the code for tokens. The REST API and the MCP server each have their own protected resource metadata and token audience.

`GET /.well-known/oauth-authorization-server`

Get the OAuth authorization server metadata.

Sign-in: none
Responses: 200, 400, 401, 403, 429, 503

`GET /.well-known/oauth-protected-resource/mcp`

Get the protected resource metadata for MCP.

Sign-in: none
Responses: 200, 400, 401, 403, 429, 503

`GET /.well-known/oauth-protected-resource/v2/workspaces`

Get the protected resource metadata for the REST API.

Sign-in: none
Responses: 200, 400, 401, 403, 429, 503

`GET /oauth/authorize`

Start OAuth authorization in the browser.

Sign-in: none
Query parameters: response_type, client_id, redirect_uri, resource, scope, code_challenge, code_challenge_method, state
Responses: 302, 400, 401, 403, 429, 503

`POST /oauth/token`

Exchange an authorization code or refresh token for tokens.

Sign-in: none
Request body: application/x-www-form-urlencoded, fields grant_type, client_id, resource, code, code_verifier, redirect_uri, refresh_token, scope
Responses: 200, 400, 401, 403, 429, 503

`POST /oauth/revoke`

Revoke a token.

Sign-in: none
Request body: application/x-www-form-urlencoded, fields client_id, token, token_type_hint
Responses: 200, 400, 401, 403, 429, 503

Dashboard history, deletion, and restore

Dashboard READ advertises input-less delete to Explorer or higher. Invoke {"path":"workspace/dashboards/{dashboardId}","action":"delete"} with the returned dashboard ID. Success returns COMPLETED and workspace/dashboards. Missing, repeated, and other-Workspace deletes return 404; Viewer receives 403. Deletion removes the dashboard, its draft, sessions, query runs, schedules, and all linked dashboard Pages, and cancels running queries. Result files are cleaned up by the existing result cleanup process. Definition change records remain available.

LIST workspace/dashboards/{dashboardId}/history with required limit (1–100), then continue with nextCursor. Cursors belong to the same Workspace and dashboard ID. Each item gives a version READ path, changeId, action (CREATED, APPLIED, or DELETED), occurredAt, actor, credentialSurface, agentApp, the current deleted state, and restorable. READ workspace/dashboards/{dashboardId}/history/{changeId} for the complete recorded definition. History reads require Explorer or higher and remain available for deleted IDs. Unrecorded attribution is null. That covers older records and the starting dashboards Monomer creates in a sample Workspace; dashboard reads omit updatedBy, credentialSurface, and agentApp for them.

A restorable version of a deleted dashboard advertises input-less restore. Invoke the version’s returned path with "action":"restore". Success returns the original dashboard ID’s current resource and records one creation. Its schedules resume for future occurrences; linked Pages, past sessions, and results do not return. A living dashboard’s history is read-only, and earlier versions cannot be opened as a draft. Restoring a living dashboard or a version that is not restorable returns 409 DASHBOARD_NOT_RESTORABLE with the reason in detail. A recorded definition that no longer passes validation returns 400 INVALID_DASHBOARD_DEFINITION with the failing path.

The Human REST equivalents are DELETE /v2/workspaces/{workspaceId}/dashboards/{dashboardId} (204, no body or Idempotency-Key), GET .../{dashboardId}/history?limit=20&cursor=..., GET .../history/{changeId}, and POST .../history/{changeId}/restore with Idempotency-Key. Restore returns the normal Dashboard GET response, 409 DASHBOARD_NOT_RESTORABLE, or 422 INVALID_DASHBOARD_DEFINITION. Reuse the same key only when retrying the same restore after losing its response; replay returns the same result without another change record.

Semantic definition history and deletion

Model and Metric resources advertise input-less delete only to Editor or higher. For example, {"path":"workspace/metrics/revenue","action":"delete"} passed to monomer_invoke returns COMPLETED and workspace/metrics. Missing, repeated, and other-Workspace deletes return 404; Explorer receives 403 ROLE_REQUIRED. Deletion removes the current definition and search entry, retains its change records, and leaves dependent references in place.

Read a definition’s advertised History LIST path: workspace/metrics/revenue/history/{definitionId} or workspace/semantic-models/orders/history/{definitionId}. Supply limit (1–100) and continue with nextCursor. Items include action, occurrence time, actor, credential surface, agent app, and current deleted state. READ .../{changeId} for the complete recorded DSL. These ID-based paths remain readable after deletion and after a new definition reuses the name. The recorded name must match the path. Unrecorded attribution is null. That covers older records and the starting models and metrics Monomer creates in a sample Workspace; their reads omit updatedBy, credentialSurface, and agentApp.

A version advertises input-less restore to Editor or higher. INVOKE that version path with "action":"restore" to save it through the normal Semantic owner path. Success returns the current Model or Metric resource; a deleted definition retains its original ID. A name held by another definition returns 409 SEMANTIC_NAME_CONFLICT. Every create, edit, delete, and restore save is recorded; an idempotent replay adds no record.

The Human REST equivalents are DELETE /v2/workspaces/{workspaceId}/semantic/metrics/{metricId} and .../semantic-models/{semanticModelId} (204), GET .../{id}/history?limit=20&cursor=..., and POST .../{id}/history/{changeId}/restore with Idempotency-Key. History reads require Explorer or higher; deletion and restore require Editor or higher.

Lineage READ returns missing Semantic references in body.missingDefinitions, with missing: true. Their placeholder IDs identify nodes in that graph only. Healthy resources and their cone remain readable when a dependency is missing.