endpoints.md

Endpoints by Application

The Monolith WAR hosts several Jakarta REST applications. Each application has its own servlet mapping in web.xml. The default web context is /Monolith; replace it and add any deployment prefix when constructing URLs.

Application	Base URL	Responsibility
MonolithApplication	/Monolith/api	Pixel, engines, projects, sessions, permissions, and integration APIs
GitHubApplication	/Monolith/github	GitHub App setup, project links, callbacks, and push webhooks
MicrosoftGraphApplication	/Monolith/msgraph	Microsoft mailbox/calendar subscriptions and notifications
HealthApplication	/Monolith/health	Liveness, readiness, and resource status
TrustedTokenApplication	/Monolith/token	Trusted integration token service
AdminApplication	/Monolith/adminconfig	Initial administrator setup

Paths below include the application base. {...} denotes an ID or other path parameter to replace; * denotes a route family for navigation, not a literal request URL. Engine IDs follow a hyphen in these routes: for example, /Monolith/api/storage-<storage-id>/list.

The tables describe registered routes and their main inputs. Resource implementations define the full contract, and operations still enforce the configured authentication, CSRF, and resource permissions. Dedicated applications apply their own checks and provider-verification rules.

MonolithApplication

Base: /Monolith/api. MonolithApplication registers the core resources below.

Pixel execution and sessions

Method and endpoint / route family	Purpose
POST /Monolith/api/engine/runPixel	Execute Pixel expressions in an Insight
POST /Monolith/api/engine/runPixelAsync	Submit asynchronous Pixel execution
POST /Monolith/api/engine/pixelJobStreaming	Poll Pixel job output
POST /Monolith/api/engine/agentRunStreaming	Drain live agent events and return a durable run snapshot
/Monolith/api/session/*	Session activity, cleanup, invalidation, and insights
/Monolith/api/auth/*	Login, logout, user identity, and provider callbacks

Sources: NameServer, SessionResource, and UserResource. RunAgent is a Pixel operation submitted through the execution API; see agent runs.

Database engines

DatabaseEngineResource serves /Monolith/api/database-{databaseId}.

Method and endpoint	Inputs / purpose
GET /Monolith/api/database-{databaseId}/type	Return database type and catalog subtype
POST /Monolith/api/database-{databaseId}/reload	Reload the configured database through ReloadDatabase
POST /Monolith/api/database-{databaseId}/query	Required query; execute a query through the database engine

Storage engines

StorageEngineResource serves /Monolith/api/storage-{storageId}.

Method and endpoint	Inputs / purpose
POST /Monolith/api/storage-{storageId}/list	Required storagePath; list a storage path
POST /Monolith/api/storage-{storageId}/listDetails	Required storagePath; list entries with details
POST /Monolith/api/storage-{storageId}/delete	Required storagePath; delete the selected storage content

Vector engines

VectorEngineResource serves /Monolith/api/vector-{vectorId}.

Method and endpoint	Inputs / purpose
POST /Monolith/api/vector-{vectorId}/query	Required command; optional limit, paramValues; search the vector database
POST /Monolith/api/vector-{vectorId}/listDocuments	Optional paramValues; list indexed documents
POST /Monolith/api/vector-{vectorId}/removeDocument	Required fileNames; optional paramValues; remove indexed documents

Model engines

ModelEngineResource serves /Monolith/api/model-{modelId}.

Method and endpoint	Inputs / purpose
POST /Monolith/api/model-{modelId}/llm	Required command; optional context, useHistory, paramValues, roomId, image, url; invoke LLM
POST /Monolith/api/model-{modelId}/llmStreaming	Stream the LLM operation as server-sent events
POST /Monolith/api/model-{modelId}/embeddings	Required values; optional paramValues; generate embeddings
POST /Monolith/api/model-{modelId}/vision	Required command, image; optional paramValues; invoke vision

llmStreaming emits SEMOSS job payloads and ends with data: [DONE]. Use the compatibility endpoints below when a client expects a provider-specific response format. Supported generation, embeddings, media, and streaming capabilities depend on the selected model engine.

Function engines

FunctionEngineResource serves /Monolith/api/function-{functionId}.

Method and endpoint	Inputs / purpose
POST /Monolith/api/function-{functionId}/execute	Optional map or its alias inputs; execute the function using its configured input contract
GET /Monolith/api/function-{functionId}/definition	Return the function engine definition

Shared engine operations

EngineRouteResource serves /Monolith/api/e-{engineId} for operations shared across engine catalogs.

Method and endpoint	Purpose
GET /Monolith/api/e-{engineId}/type	Return engine type and subtype
POST /Monolith/api/e-{engineId}/updateSmssFile	Update engine configuration using the smss parameter
POST /Monolith/api/e-{engineId}/image/upload	Upload a catalog image using multipart field file
GET /Monolith/api/e-{engineId}/image/download	Download the engine catalog image

See catalog image uploads for supported images and permission requirements. Guardrail and virtual-environment engines have no dedicated operation resource registered alongside the database/model/storage/vector/function resources in this application; use their supported Pixel operations and shared catalog routes where applicable.

Projects, agents, and skills

ProjectResource serves /Monolith/api/project-{projectId}. Workspace agents and skills use their project IDs for these project operations.

Method and endpoint	Purpose
POST /Monolith/api/project-{projectId}/runReactor/{reactorName}	Execute a project reactor
POST /Monolith/api/project-{projectId}/updateSmssFile	Update project configuration
GET /Monolith/api/project-{projectId}/landing	Serve the project landing content
GET /Monolith/api/project-{projectId}/downloadProjectAsset/{relPath}	Download a project asset
POST /Monolith/api/project-{projectId}/image/upload	Upload a project catalog image
POST /Monolith/api/project-{projectId}/projectImage/upload	Alias for project catalog image upload
GET /Monolith/api/project-{projectId}/projectImage/download	Download the project catalog image

The same resource also defines embedded logos, insight images, and JDBC-format result routes. See its source for those request parameters and the project guide for project types and assets.

Engine request bodies and results

The database query, storage, vector, model, and function execution wrappers accept JSON or form-encoded bodies. Prefer JSON for nested maps and arrays. For example, send this JSON to POST /Monolith/api/vector-{vectorId}/query after replacing the vector ID:

{
  "command": "Find documents about agent configuration",
  "limit": 5,
  "paramValues": {}
}

These wrappers invoke the corresponding Pixel operations through ResourceUtility, with the authenticated user and a temporary Insight. Standard wrapper results use the SEMOSS Pixel response structure; Pixel errors or invalid syntax produce HTTP 400, and a missing session produces 401. Metadata, image, streaming, and compatibility routes have their own response contracts. Existing session state and permissions remain necessary when calling the typed routes directly.

Model compatibility APIs

These resources also belong to MonolithApplication and retain the /Monolith/api prefix.

Resource	Endpoints
OpenAIEndpoints	POST /Monolith/api/model/openai/v1/chat/completions, POST /Monolith/api/model/openai/v1/responses, POST /Monolith/api/model/openai/v1/images/generations, POST /Monolith/api/model/openai/v1/embeddings, GET /Monolith/api/model/openai/v1/models, GET /Monolith/api/model/openai/v1/models/{modelId}
AnthropicEndpoints	POST /Monolith/api/model/anthropic/v1/messages
OllamaEndpoints	POST /Monolith/api/model/ollama/api/chat, POST /Monolith/api/model/ollama/api/generate, POST /Monolith/api/model/ollama/embeddings

OpenAI also exposes the listed routes without /v1 and a legacy POST /Monolith/api/model/openai/completions route. Ollama exposes /chat and /generate aliases beneath /Monolith/api/model/ollama. The second /api in the Ollama chat/generate paths belongs to the compatibility route itself.

A call refused by a model usage limit answers with the error in the provider's shape and a code:

Refused by	Status	code	Retry-After
A minute or hour rule	429	rate_limit_exceeded	The seconds until the rule resets
A day or longer rule	429	usage_limit_reached	None, so clients do not keep retrying until it resets
Limits that cannot be checked right now, such as a cluster that cannot reach Redis	503	usage_limits_unavailable	None

OpenAI answers {"error": {"message", "type", "code"}, "errorMessage"}, Anthropic {"type": "error", "error": {"type", "message", "code"}} with the type rate_limit_error (api_error for a 503), and Ollama {"error", "code", "errorMessage"}. A streaming call is checked before its stream starts; a refusal after that is reported inside the stream. Every other error keeps its status and body.

Model usage limits

A model usage limit is JSON: Unlimited, or rules that must all have usage left.

{
  "unlimited": false,
  "rules": [
    { "metric": "TOKENS", "amount": 100000, "window": "MINUTE", "counts": "EACH_PERSON" },
    { "metric": "COST", "amount": 500000000, "window": "MONTH", "counts": "SHARED" }
  ]
}

metric is TOKENS, COST (millionths of a US dollar, on models with known prices) or COMPUTE_TIME (milliseconds). window is MINUTE, HOUR, DAY, WEEK, MONTH or YEAR, in UTC. windowLength is how long a MINUTE window (1 to 59 minutes) or an HOUR window (1 to 24 hours) is; it is left out for 1, and other windows are always 1 long. counts is SHARED (team limits, public use, model totals and team totals) or EACH_PERSON. A limit has one rule for each metric, window, window length and counts. An empty value means no limit defined, and so does an amount of 0. Responses leave out fields with no value, so a source with no limit defined has no usageLimit.

Only a model's owners, and admins in admin mode, set usage limits on it: a person's, a team's, public use and the model's total. Editors still add people and change the level of Read-Only and Editor people; their adds give no limit and their changes keep the current one. A change by an editor that leaves any other limit is refused with "Only owners can set usage limits".

These endpoints read and set limits that are not part of a grant. Anonymous sessions get 401 from each.

Method and endpoint	Inputs / purpose	Who may call
GET /Monolith/api/auth/permissionBatch/getUsageLimitPath	engineId, userId, userType (required, in any case); how limits apply to one person on a model: engineId, person, billedLimitType, the ceilings, then the steps in billing order, each with its state, rules, use and reset times. The person must have a grant on the model, their own or a custom team's; the model being public is not enough. Limits that count use on other models stay private: the ALL_MODELS and PLATFORM steps have no rules and say "rulesHidden": true, and TEAM steps have no teamTotal	The model's editors and owners
GET /Monolith/api/auth/admin/permissionBatch/getUsageLimitPath	The same, for any person on any model, with every step's rules and each team's teamTotal; userType is required	Admins
GET /Monolith/api/auth/permissionBatch/getMyUsageLimitPath	engineId; the same, for the signed in person, with every step's rules and each team's teamTotal	Anyone who can use the model
GET /Monolith/api/auth/permissionBatch/getMyUsageLimitPaths	{"models": [{"engineId", "name", "subtype", "path"}]}: the signed in person's path, as getMyUsageLimitPath gives it, on every model they can use	Anyone signed in
GET /Monolith/api/auth/admin/modelUsage/getPlatformDefault	{"usageLimit"}: the limit for everyone with no other limit, on any model	Admins
POST /Monolith/api/auth/admin/modelUsage/setPlatformDefault	Form usageLimit, empty to remove it; answers as the read	Admins
GET /Monolith/api/auth/admin/modelUsage/getTeamTotal	groupId, type; {"usageLimit"}: the team's total across all models	Admins
POST /Monolith/api/auth/admin/modelUsage/setTeamTotal	Form groupId, type, usageLimit, empty to remove it; answers as the read	Admins

Limits on grants are set through permission batches (usageLimit on a grant) and through these endpoints:

Endpoint	Limit fields
POST /Monolith/api/auth/engine/addEngineUserPermission, editEngineUserPermission, and the same under /Monolith/api/auth/admin/engine	Form usageLimit, empty for no limit defined. An add without it gives no limit, and an edit without it, such as a change of level only, keeps the limit as it is
POST .../addEngineUserPermissions, editEngineUserPermissions (user and admin)	Each userpermissions row's usageLimit. An added row without it gets no limit; an edited row without it keeps the person's limit, and an edited row whose usageLimit is null removes it
GET .../getEngineUsers (user and admin)	Each row's usage_limit
POST /Monolith/api/auth/project/propagateProjectDependencyPermission(s)	usageLimit (each row's, for the plural), for the models the project depends on. Without it, people added get no limit and people whose access changes keep theirs
POST /Monolith/api/auth/group/engine/addGroupEnginePermission, POST /Monolith/api/auth/admin/group/addGroupEnginePermission	Form usageLimit: the team limit on a model
POST /Monolith/api/auth/admin/user/registerUser	Form modelUsageLimit: the person's all-models default; without it, none is defined
POST /Monolith/api/auth/admin/user/editUser	model_usage_limit in the user JSON, null for no limit defined; without the key, the default is kept as it is
GET /Monolith/api/auth/admin/user/getAllUsers	Each row's model_usage_limit
POST /Monolith/api/auth/createUser	None: self-registration ignores limit fields, since only admins set all-models defaults

MCP, A2A, and other core resources

Endpoint / route family	Purpose / implementation
POST /Monolith/api/ext/mcp/{toolbox_id}/comms	MCPResource tool communication
GET /Monolith/api/ext/a2a/workspace/{workspaceId}/.well-known/agent-card.json	A2AResource agent card
POST /Monolith/api/ext/a2a/workspace/{workspaceId}/rpc	A2A JSON-RPC operations
/Monolith/api/browser-sessions/*	RemoteBrowserSessionController sessions, steps, and recordings
/Monolith/api/uploadFile/*, /Monolith/api/images/*	FileUploader and ImageUploader
/Monolith/api/authorization/*	AuthorizationResource
/Monolith/api/auth/engine/*, /Monolith/api/auth/project/*, /Monolith/api/auth/insight/*, /Monolith/api/auth/user/*	Resource authorization services
/Monolith/api/auth/group/*, /Monolith/api/auth/admin/*	Group permissions and administrator operations in the main API
/Monolith/api/exec/*, /Monolith/api/share/*	ExecuteInsightResource and ShareInsightResource
/Monolith/api/schedule/*	SchedulerResource
/Monolith/api/themes/*	AdminThemeResource
/Monolith/api/config/*	ServerConfigurationResource
/Monolith/api/form/*	FormResource legacy forms

NameServer also mounts legacy subresources at /Monolith/api/engine/i-{insightID}/* for frames and /Monolith/api/engine/e-{engine}/* for older engine operations. The shared engine catalog resource documented above is /Monolith/api/e-{engineId}/*.

Runtime endpoint discovery

GET /Monolith/api/config/endpoints lists HTTP methods, resource-relative paths, resource classes, operations, and declared content types for the main application's registered resources. The response includes contextPath, count, includesAdminResources, and endpoints.

Prefix each returned path with the deployment context and /api when building a URL. The current implementation omits resource classes whose names start with Admin unless the caller is an administrator. It inspects MonolithApplication's resources; use the separate application sections below for their routes. Subresource-locator children are not recursively enumerated.

GitHubApplication

Base: /Monolith/github. Registered resources: GitHubService and AdminGitHubService.

Endpoint / route family	Purpose
POST /Monolith/github/webhook	Signature-verified GitHub App events; pushes dispatch linked-project synchronization
GET /Monolith/github/available	App configuration preflight
/Monolith/github/manifest/*	Administrator app creation, callback, configuration, and project-link inventory
/Monolith/github/install/*	Installation callback and repository/branch selection
/Monolith/github/user/*	GitHub user authorization and callback
/Monolith/github/project/*	Read/disconnect project links and update tracked branches

See GitHub webhook and setup endpoints for every method, parameter, callback, and response. These paths start with /Monolith/github directly.

MicrosoftGraphApplication

Base: /Monolith/msgraph. Registered resources: MicrosoftGraphNotificationService and MicrosoftGraphSubscriptionService.

Method and endpoint	Purpose
POST /Monolith/msgraph/notifications/messages	Mailbox notifications and subscription validation
POST /Monolith/msgraph/notifications/events	Calendar notifications and subscription validation
GET /Monolith/msgraph/available	Microsoft identity, scope, and public-URL preflight
POST /Monolith/msgraph/subscribe	Create a mailbox/calendar subscription
GET /Monolith/msgraph/subscriptions	Compare recorded subscriptions with Microsoft's state
POST /Monolith/msgraph/renew	Renew an owned subscription
DELETE /Monolith/msgraph/subscription	Remove an owned subscription

See Microsoft Graph notification endpoints for parameters, validation, persistence, and renewal. Receivers currently fetch and log changes; they do not automatically submit agent runs.

HealthApplication

Base: /Monolith/health. Registered resource: HealthResource.

Method and endpoint	Purpose
GET /Monolith/health/	Liveness
GET /Monolith/health/ready	Startup readiness: 200 when ready, 503 otherwise
GET /Monolith/health/details	Required/enabled system-resource status

Health probes use this dedicated application and do not require a user session.

TrustedTokenApplication

Base: /Monolith/token. Registered resource: TrustedTokenService.

Method and endpoint	Purpose
POST /Monolith/token/getToken	Request a trusted integration token using the configured client-credential flow
GET /Monolith/token/getToken	Legacy variant; rejected when client/secret validation is enabled

The POST flow reads client_id and, when credential validation is enabled, secret_key. Configure trusted integrations through the deployment's token and filter settings. This application is separate from the login and resource-authorization APIs under /Monolith/api/auth.

AdminApplication

Base: /Monolith/adminconfig. Registered resource: AdminConfigService.

Method and endpoint	Purpose
POST /Monolith/adminconfig/setInitialAdmins	Initial administrator registration during deployment setup

The startup filter and service restrict this setup path once the security database contains users. Ongoing administrator operations are served by the main API's /Monolith/api/auth/admin/* resources.

Other web mappings

Direct servlet mappings, static assets, and WebSockets are outside these six REST applications. For example, SamlVerifierServlet is mapped at /Monolith/saml/config/fedletapplication. Consult web.xml and the relevant WebSocket implementation for those contracts.

When testing route changes in the local Docker image, verify the effective descriptor: the local build workflow preserves web.xml from the base image. See the core integration guide for request execution and agent boundaries.