MagicDoorAPI
SupportOpen MagicDoor
Runbooks

Update a runbook

Changes a runbook's script, title or description. Anything you leave out keeps its current value — except that changing the script alone makes MagicDoor rewrite the title and description to match it. Only the company's own runbooks can be edited; a runbook MagicDoor supplies is reported as not found. Requires the maintenance_runbooks:write permission.

PUT
https://services.magicdoor.com/maintenance/company-portal/run-books/{runBookId}

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

runBookIdstringrequired

The runbook to act on. A Snowflake id, sent as a decimal string.

example: 1827400938471029248

Body

application/json

scriptstring

The new instructions. At least one character. Leave it out to keep the current script.

titlestring

The new name. Between 1 and 500 characters. Leave it out and MagicDoor writes one from the script.

descriptionstring

The new explanation. Between 1 and 2000 characters. Leave it out and MagicDoor writes one from the script.

Response

200 · The updated runbook.

publicRunBookbooleanrequired

true when MagicDoor supplies this runbook to every company. A shared runbook can be switched on and configured for your company, but its title, description and script cannot be edited or deleted.

idstringrequired

The runbook.

titlestringrequired

The runbook's name. MagicDoor writes one from the script when you do not supply it.

descriptionstringrequired

What the runbook is for. MagicDoor writes one from the script when you do not supply it.

createdstring · date-timerequired

When the runbook was created, in the company's timezone and without an offset.

updatedstring · date-time

When the runbook was last changed, in the company's timezone and without an offset.

defaultVendorIdstring

The vendor this runbook sends work to when nothing more specific applies. Absent when none is set.

defaultPropertyManagerIdstring

The property manager this runbook hands requests to when nothing more specific applies. Absent when none is set.

enabledbooleanrequired

Whether the runbook is allowed to pick up this company's maintenance requests. A runbook your company has never configured reads as enabled.

usageCountintegerrequired

How many times this runbook has been used for this company.

lastUsedstring · date-time

When it was last used, in the company's timezone and without an offset. Absent when it has never run.

vendorIdstringdeprecated

A copy of defaultVendorId. Read defaultVendorId instead.

scriptstringrequired

The instructions MagicDoor follows when the runbook handles a request, in plain English.

lastUseMaintenanceRequestIdstring

The last maintenance request this runbook handled for the company. Absent when it has never run.

vendorOverwritesobject[]required

Per-portfolio or per-property vendor overrides. An empty array when there are none.

propertyManagerOverwritesobject[]required

Per-portfolio or per-property property manager overrides. An empty array when there are none.

actionExitCountsobjectrequired

How many times the runbook has finished each way, as a map. The keys are askQuestion, closeRequest, createWorkOrder, handOverToHuman and reselectRunBook; only the ways it has actually finished appear. An empty object when it has never run.

lastUseMaintenanceRequestobject

The last maintenance request this runbook handled, in the short row shape used by the maintenance request list. Absent when it has never run, or when that request no longer exists.

400 · The title, description or script is outside its allowed length.

401 · The request carried no valid access token.

403 · The token is not a property manager token, or it lacks the `maintenance_runbooks:write` permission.

404 · No such runbook, it belongs to another company, or it is one MagicDoor supplies rather than one of yours.