Connect to a workspace API

Moltaro’s public website and a customer’s Moltaro workspace are different systems. Before making an API request, identify which URL the request belongs to. A path that starts with /api/workspace/ is always served by the API host of a configured Moltaro workspace. It is never served by moltaro.com.

Do not send workspace requests to the public website

https://moltaro.com/docs/... is documentation. It is not a workspace API base URL. Do not append /api/workspace/... to https://moltaro.com.

The URLs have different roles

URL	Example	Purpose
Public website, portal, and documentation	https://moltaro.com/docs/	Product documentation, public reference copies, account and deployment entry points. It has no access to a customer’s workspace data.
Workspace Web Application	https://acme.apps.example.com/	The signed-in product UI. The workspace owner completes administrative setup and prepares Agent integration through the Portal or administrative interface.
Workspace API base URL	https://acme.api.example.com	The origin for /api/workspace/... and the installation-local /openapi/... documents. Use this URL for development and integration requests.

Depending on the deployment, the Web Application and API may share an origin or use different origins. Never derive one by changing the hostname yourself. The workspace-specific guide prepared by the administrator provides the authoritative workspace API base URL.

The documentation uses WORKSPACE_API_BASE_URL for that value. For example:

GET ${WORKSPACE_API_BASE_URL}/api/workspace/context
GET ${WORKSPACE_API_BASE_URL}/openapi/moltaro-public-v1.json
GET ${WORKSPACE_API_BASE_URL}/openapi/moltaro-config-v1.json

In command examples, https://ops.example.com is a placeholder for the same WORKSPACE_API_BASE_URL; replace the whole origin, not only part of the path.

Complete Workspace API reference

The two installation-local documents together describe all controller operations under /api/workspace/..., including the API used by the Web Application:

• moltaro-public-v1: runtime reads and commands, user preferences, Work Inbox, Tasks, Workflow, Work Schedule, reporting, files and other operational modules.
• moltaro-config-v1: module lifecycle and security, schemas and UI design, module configuration, administrative operations and developer tooling.

Module enablement does not remove its installed routes from the reference. Execution still requires the module’s readiness and the caller’s current rights. HTTP publication does not make an administrative operation anonymous. Ordinary Workspace API calls use a bearer token or service API key; password, token and key administration retain their own administrator checks.

Special protocols describe their own credentials. File Protection Agent routes under /api/workspace/file-protection/agent/v1 use TLS and the X-Moltaro-File-Protection-Agent device-token header, with a one-time enrollment code for enrollment. Inbound function routes use the authentication policy of the published endpoint and return that function’s response shape. A Workspace bearer is not a substitute for a required device credential.

Public website copies can be newer than an installed release. Older releases had incomplete public API publication; a missing route in those documents is not proof that enabling a module will add it. Check the installed product/build identity and upgrade to a release containing the complete reference.

Administrative handoff before API development

Web Application installation or registration and access provisioning happen in the Moltaro Portal or administrative Web Application interface. They are workspace-owner responsibilities, not steps for a coding agent to automate. This developer documentation intentionally starts after that setup.

Under Administration > Agent integration, the administrator selects Create service user for agent and confirms the high-privilege handoff. Moltaro creates a distinct Service user with the Admin and Configurator roles, issues a 90-day API key, and downloads a ZIP containing:

• AGENTS.md and CLAUDE.md with workspace-specific instructions;
• .moltaro/credentials.env with the exact API URL, service-user identity, key expiration, and one-time API key;
• .moltaro/.gitignore, which excludes credentials.env from version control.

Extract the kit into the intended project and delete the downloaded ZIP. Keep .moltaro/credentials.env local: never commit, upload, paste, echo, or print it. The API key is not shown again after the download.

If any of these inputs is missing, an agent must stop and ask the user to complete Agent integration in the Portal or administrative interface. It must not try to install or register the Web Application, create a service account, rotate credentials, or grant itself permissions through an API.

The developer or agent loads .moltaro/credentials.env and sends MOLTARO_API_KEY as Authorization: Bearer <api-key>. Do not put the key in the guide, source code, a prompt, logs, or version control.

The two Markdown files contain the same workspace-specific guide under conventional filenames. They describe the particular installation that generated them; they are not generic copies of the public documentation.

What the Agent integration endpoints are for

The following are authenticated endpoints on the workspace API host:

GET ${WORKSPACE_API_BASE_URL}/api/workspace/admin/agent-integration
GET ${WORKSPACE_API_BASE_URL}/api/workspace/admin/agent-integration/agents-md
POST ${WORKSPACE_API_BASE_URL}/api/workspace/admin/agent-integration/access-kit

These are administrative endpoints of the configured Moltaro Application, not endpoints of the public Portal. An administrator, provisioning tool, or coding agent may call them after it knows the workspace API base URL and has suitable credentials. They remain part of the published Configuration API.

They are not global discovery endpoints. The access-kit operation is the administrator-owned UI action that performs the one-time handoff; an agent must not call it to create or elevate its own access. After receiving the kit, the agent may use the two read endpoints to re-read the manifest or guide.

Installed product version

The read-only GET /api/workspace/admin/agent-integration requires the same administrative access as the generated guide. It returns these fields inside the normal Data response object, alongside the existing API and documentation URLs:

Field	Meaning
ProductVersion	Moltaro product release embedded in the running API runtime during packaging. This is not the OpenAPI document version or a C# assembly version.
BuildId	Opaque build identity from the same package, distinguishing hotfix builds of one release. Compare for equality; do not parse it or use it to order releases.
ReleaseNotesVersionUrl	Release-note page for that installed release, or null if no note was supplied.

ProductVersion and BuildId are both null for source builds made without package identity. Older installations can omit these fields entirely. Treat either case as an unknown installed release and ask the administrator for its package metadata when a version decision is required; never substitute the public site’s version. DocsUrl, LlmsFullUrl, and ReleaseNotesUrl remain links to current documentation and the release-note index, not archived full documentation for the installed version.

The endpoint reads embedded metadata locally, without contacting the public site, changing workspace state, or creating credentials. Its response disables caching. It identifies the API runtime answering the request; it is not an inventory of independently deployed Worker or WebApp components. For split deployments, an operator must also verify component alignment.

Before starting or resuming work, record the installed version/build pair and read the returned release-note link when available. Compare the installed release with ProductVersion in the public documentation manifest. If they differ, use the installed release notes and installation-local OpenAPI and developer surface to check the intended tools; newer documentation alone does not establish compatibility.

Public and installation-local contracts

The public documentation hosts reference copies of the Runtime and Configuration OpenAPI documents. They are useful before a workspace is available and for browsing supported concepts. For actual development, use the OpenAPI documents served by the target installation:

${WORKSPACE_API_BASE_URL}/openapi/moltaro-public-v1.json
${WORKSPACE_API_BASE_URL}/openapi/moltaro-config-v1.json

Those documents match the installed release. The downloaded guide also links to the installation-local developer surface for supported C# assemblies and injectable services. Public documentation explains the model; the target workspace remains authoritative for its URL, schema, modules, permissions, OpenAPI contract, and C# developer surface.

Continue with the Integration quickstart for record operations, the Configuration quickstart for schema authoring, or the AI agent development quickstart for the complete API-first C# and Workspace UI workflow. Apply the concurrency, retry, recovery, and audit rules in Reliable API automation to both human and agent-driven integrations.