> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Companies

> A company is a campus compiled from documents you saved as workflows: one kind: campus document, its kind: building documents and their offices. plungeai_companies is the MCP door to it, action for action the One API's /v1/companies: the same company-service, called as you, with the same bodies …


Source: `orchestration/mcp-gateway/tools-companies.ts` (`CompaniesSchema`, `plungeaiCompanies`), `orchestration/mcp-gateway/ops/companies.ts` (`decideGate`), `orchestration/mcp-gateway/shared.ts` (`refusalResult`, `valueResult`), `orchestration/company-service/contract.ts` (`CompanyServiceApi`, the request and response types), `orchestration/api-gateway/routes/companies.ts` (the REST twin).

A **company** is a campus compiled from documents you saved as workflows: one `kind: campus` document, its `kind: building` documents and their offices. `plungeai_companies` is the MCP door to it, action for action the One API's `/v1/companies`: the same company-service, called as you, with the same bodies and the same refusals. Full parameter table: [14.21](/mcp/tool-reference#1421-plungeai_companies).

## 16.1 Tenancy

The key's user is the tenant. Every action but `list` takes `campus` (the slug of a campus you saved), and company-service only finds campuses you own: a campus another account owns is the same `not_found` as one that does not exist, so the answer never tells you that a slug is taken. A slug that cannot be a campus slug (lowercase letters, digits and dashes, 1–63 characters) is `not_found` without a call.

## 16.2 Actions

| `action` | Needs | REST twin | Does |
|---|---|---|---|
| `list` | nothing | `GET /v1/companies` | your campuses: slug, name, mode, status, buildings, pending gates |
| `apply` | `campus` | `POST /v1/companies/{campus}/apply` | compiles the saved documents and stores the plan; idempotent by name |
| `layout` | `campus` | `GET …/layout` | the compiled campus, buildings and offices |
| `snapshot` | `campus` | `GET …/snapshot` | live state: offices, items, the queue of pending gates, spend today |
| `events` | `campus`; optional `since` (default 0), `limit` (default 200, max 1,000) | `GET …/events` (JSON page) | the event log after `since`, oldest first. The server-sent stream is REST only |
| `ingest` | `campus`, `events` (1–200) | `POST …/events` | a local building reports its events up |
| `slice` | `campus`, `building` | `GET …/buildings/{building}/slice` | the part of the plan one building runs |
| `item_create` | `campus`, `building`, `title`; optional `body`, `kind`, `priority`, `tier` | `POST …/items` | puts an item through the building |
| `item_pause`, `item_resume`, `item_retry`, `item_cancel` | `campus`, `item_id` | `POST …/items/{id}/{verb}` | moves one item |
| `item_steer` | `campus`, `item_id`, `text` | `POST …/items/{id}/steer` | a message for the item's running office |
| `approvals` | `campus`; optional `status` | `GET …/approvals` | the gates at the door |
| `decide` | `campus`, `approval_id`, `decision`; optional `note` | `POST …/approvals/{ap}` | records the decision; see 16.3 |
| `mode` | `campus`, `mode` | `PUT …/mode` | `supervised`, `tiered` or `autonomous`: who decides the gates |
| `start`, `stop` | `campus` | `POST …/start`, `POST …/stop` | arms or stops the campus clock |
| `delete` | `campus` | `DELETE /v1/companies/{campus}` | deletes the campus and every row of it; the saved documents stay, so it can be applied again |

## 16.3 Deciding a gate

Only send `decide` after the user decided. For a `tool_permission` gate, `approve` continues the execution that paused for it, once, as you, and hands the result back to the company so the item moves on: the answer carries `execution_id` and `continued: true`. A continue that cannot run is reported beside the recorded decision (`continued: false` with `continue_error`: `not_paused`, `session_expired`, `execution_not_found` or `continue_failed`), never raised. `reject` leaves the run paused: nothing is continued.

## 16.4 Answers and refusals

An answer is a heading line (for example `` Created item `<id>` on `<campus>`. ``) and the REST response body as a JSON block; the same body is `structuredContent`. A refusal is `isError: true` text `<word>: <message> (<code>)`, and `structuredContent.error` is `{status, code, message}`:

| `status` word | REST status | Typical codes |
|---|---|---|
| `invalid` | 400, 422 | `invalid_params` (a missing or malformed argument; no call is made) |
| `not_found` | 404 | `company_not_found`, `building_not_found`, `item_not_found`, `approval_not_found` |
| `conflict` | 409 | `conflict` (`delete` while the campus runs — stop it first), `item_done`, `approval_not_pending` |
| `unavailable` | 5xx | `not_enabled` (no company service on this deployment), `upstream_error` (the call failed; retry) |

Try asking:

- *"Which companies do I have?"* → `list`
- *"Add an item to the docs building: write the onboarding guide."* → `item_create`
- *"What is waiting for my approval at plunge?"* → `approvals`, then `decide` once the user says so
- *"Shut plunge down and delete it."* → `stop`, then `delete`

List your companies (read-only):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_companies","arguments":{"user_request":"which companies do I have?","action":"list"}}}'
```

Put an item through a building. This changes state (not verified here):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_companies","arguments":{"user_request":"have the docs building write the onboarding guide","action":"item_create","campus":"<campus slug>","building":"<building slug>","title":"Write the onboarding guide","kind":"docs"}}}'
```