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.

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.

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.

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.