# ConnectCloud API

The ConnectCloud API gives your software the same access to a ConnectCloud tenant that people have
in the portal: create and work on desk tickets, read employees and absences, record working time,
send notifications through your own mail and webhook channels, and react to events.

This is the documentation for **developers and integrators**. If you are looking for how to *use*
ConnectCloud, see the [user documentation](https://docs.mbcom.cloud).

## How the API is organised

ConnectCloud is a set of modules. Every module has its own versioned REST API under the API host
`https://api.mbcom.cloud` (see [Environments](/guides/environments)):

| Module | Base path | What it covers |
|---|---|---|
| [HR](/reference/hr) | `/api/hr/v1` | Employees, roles and groups, absences, working time, organisation. **Also issues the access tokens for every API.** |
| [Desk](/reference/desk) | `/api/desk/v1` | Tickets, issues and tasks with configurable spaces, types, workflows and fields; comments, mail, SLAs, automation, projects and payment plans (work is booked in HR). |
| [Forge](/reference/forge) | `/api/forge/v1` | Software development: projects with repositories, items (`APP-12`), milestones, iterations, views, automations, ownerships and teams (code ownership); [handoff and conversion](/guides/handoffs) with desk. |
| [Work entries](/guides/work-entries) | `/api/hr/v1/work-entries` | Book work (Leistungen) with start/end or a stopwatch, approvals, rates and billing batches (HR). |
| [Comms](/reference/comms) | `/api/comms/v1` | Mail and webhook channels, delivery log, inbound webhooks (notifications about events are [flows](/guides/flows)). |
| [Trade](/reference/trade) | `/api/trade/v1` | Offers, orders, invoices, credit notes, contracts, purchase orders, inbound invoices. |
| [DMS](/reference/dms) | `/api/dms/v1` | Documents with versions, folders, links to records, text extraction, containers, compliance, exports. |
| [Master data](/reference/masterdata) | `/api/masterdata` | Addresses (customers, suppliers) with contacts, articles, product groups, lookup tables, number ranges. |
| [CRM](/reference/crm) | `/api/crm/v1` | Leads, campaigns, opportunities, customer satisfaction, address quality checks. |
| [Workflow](/reference/workflow) | `/api/workflow/v1` | Approval workflows: blueprints, a person's tasks, running instances. |
| [Flows](/reference/flows) | `/api/flows/v1` | Automation: [flows](/guides/flows) as YAML (triggers, module actions, conditions, human tasks, mail, AI), test runs, publishing, runs, the task inbox and inbound webhooks. |
| [Search](/reference/search) | `/api/search/v1` | Full-text search over desk, CRM, master data, trade, knowledge, HR and comms records and DMS documents. |
| [Status](/reference/status) | `/api/status/v1` | Whether the modules of the environment are working (no token needed). |

All APIs share the basics: JSON over HTTPS, the same bearer tokens and an
[error object](/guides/errors) with an `error` message. HR, Desk, Comms and Forge also share stable error
codes, [optimistic locking](/guides/idempotency-and-concurrency) and
[rate limits](/guides/rate-limits); where another module differs, its reference page says so in its
*Conventions* section.

## Start here

1. [Quickstart](/guides/quickstart): from an API key to your first call in five minutes.
2. [Authentication](/guides/authentication): API keys, service accounts, access tokens and permissions.
3. [Sandbox](/guides/sandbox): try every endpoint against example data, no account needed.
4. The **API reference** per module (for example [Desk](/reference/desk) or
   [DMS](/reference/dms)): every endpoint with parameters, schemas, examples and a *Try it*
   console.

## Guides per module

| Module | Guides |
|---|---|
| HR | [Work entries](/guides/work-entries), [Careers API](/guides/careers) |
| Desk | [Tickets](/guides/desk-tickets), [Projects, plans and billing](/guides/projects), [Handoff and conversion](/guides/handoffs) |
| Forge | [Items](/guides/forge-items): project configuration, create, search, workflow by status category; [Handoff and conversion](/guides/handoffs) |
| Trade | [Sales documents and e-invoices](/guides/trade): offers, orders, invoices, XRechnung, inbound invoices, `423 workflow_locked` |
| Master data | [Addresses and articles](/guides/masterdata): codes, addresses, articles, sync with paging and change detection |
| CRM | [Leads and opportunities](/guides/crm): duplicates, conversion into a customer, pipeline stages |
| DMS | [Documents](/guides/dms): upload, folders, malware scan, versions, download |
| Flows | [Flows](/guides/flows) |
| Comms | [Mail, channels and the delivery log](/guides/comms), [Webhooks](/guides/webhooks) |

## Machine-readable descriptions

- OpenAPI 3.1 documents per module, e.g. [`/openapi/desk.yaml`](/openapi/desk.yaml) (also as
  `.json`; the [index](/openapi/index.json) lists all of them). Use them to generate clients or
  import them into Postman, Insomnia or Bruno.
- For AI agents: [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt), a Markdown version
  of every page and an MCP server at `https://developers.mbcom.cloud/mcp`. See [AI agents](/guides/ai-agents).

## Scope

The reference lists the endpoints API clients may use. Routes that only the portal itself or other
ConnectCloud services call (sign-in flows, internal service APIs, the customer portal) are not
part of the public API and may change without notice.
