Create Machine Downtime Event

Beta

POST/v1/operations/machine-downtime-events

Idempotent with Idempotency-Key header. Learn more

Logs a machine downtime event.

Give the stoppage an end either as ended_at or as a duration counted in a unit of time — sending both is rejected. Omit ended_at while the machine is still down. A machine can only have one open event at a time, so logging a second open stoppage against a machine that is already down is rejected until the first is closed.

The department is taken from the machine, the business day is taken from started_at, the event is attributed to the credentials that made the request, and the duration is calculated when the event is closed.

Permissions requiredValues:machine_downtime:create

The role behind your API key or agent must grant every one of these permissions.

include[]optional arrayenumValues:machinedepartmentitem

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

machine_idstring

ID of the machine that stopped.

reasonstringenumValues:breakdownchangeovermaterial_shortage

Why the machine stopped.

The reason decides which OEE term the stoppage charges, so it does more than label the event. Retrieve the available reasons and the term each one charges from the downtime reasons list.

started_atstring (date-time)

When the machine stopped.

Cannot be in the future beyond a few minutes of clock skew, which is allowed so a shop-floor tablet running fast can still log "just now". The business day the stoppage counts against is taken from this timestamp.

ended_atoptional string (date-time)

When the machine started running again.

Omit it while the machine is still down; that leaves the event open, and the duration is filled in once the event is closed. It must be later than started_at.

durationoptional object

How long the machine was down, counted in a unit of time.

The end time is derived from started_at plus this. Send either send ended_at or duration. The unit must measure time.

valuestring (decimal)

Decimal value, as a string to preserve precision.

unit_idstring

ID of the unit of measure for the value.

item_idoptional string

ID of the item the machine was running when it stopped.

production_run_idoptional string

ID of the production run in progress when the machine stopped.

batch_idoptional string

ID of the batch in progress when the machine stopped.

noteoptional string

Free-form notes about the stoppage.

Searchable from the downtime events list. Maximum 2000 characters.

sourceoptional stringenumValues:manualscannerinferred

How the event was recorded.

Records the stoppage as manually logged unless you say otherwise, so an integration or shop-floor station should send its own source to keep hand-entered downtime distinguishable.

idstring

Downtime event ID.

objectstringenumValues:machine_downtime_event

Resource type identifier.

machinemachineExpandablenullable

The machine that stopped.

idstring

Machine ID.

objectstringenumValues:machine

Resource type identifier.

namestring

Display name of the machine.

Unique within the account.

serial_numberstring

Serial number of the machine.

notesstringnullable

Free-form notes about the machine.

departmentdepartmentExpandablenullable

The department this machine belongs to.

Set when the machine is created; a machine cannot be moved to another department afterwards.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

departmentdepartmentExpandablenullable

The department the machine belongs to, captured when the event was logged.

idstring

Department ID.

objectstringenumValues:department

Resource type identifier.

namestring

Display name of the department.

Unique within the account.

notesstringnullable

Free-form notes about the department.

locationlocationnullable

The storage location where this department operates.

Always returned as null in this endpoint.

scanning_stationslistnullable

Scanning stations in this department.

Always returned as null in this endpoint.

machineslistnullable

Machines in this department.

Always returned as null in this endpoint.

labor_rateratenullable

Hourly labor rate for work done in this department, such as a changeover technician.

Production scheduling costs changeovers with the constraint department's rate when one is set, falling back to the account-wide changeover labor rate setting.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last update timestamp.

reasonmachine_downtime_reasonnullable

Why the machine stopped.

objectstringenumValues:machine_downtime_reason

Resource type identifier.

codestringenumValues:breakdownchangeovermaterial_shortage

Stable code identifying the reason.

namestringnullable

Display name of the reason.

oee_bucketstringnullableenumValues:availabilityperformancequality

Which OEE term this reason charges.

started_atstring (date-time)

When the machine stopped.

ended_atstring (date-time)nullable

When the machine started running again.

duration_secondsintegernullable

How long the machine was down, in seconds.

Calculated when the event is closed, and recalculated whenever its start or end time changes.

shift_atstring (date-time)

The business day the stoppage is counted against.

Taken from the calendar date of started_at, so correcting the start time can move the stoppage onto a different day's totals.

shift_codestringnullable

The shift the stoppage is counted against.

itemitemExpandablenullable

What the machine was running when it stopped.

idstring

Item ID.

objectstringenumValues:item

Resource type identifier.

skustring

Stock keeping unit code, unique within the account.

descriptionstringnullable

Item description.

notesstringnullable

Free-form notes about the item.

typestringenumValues:productmaterialpart

What kind of item this is.

product: a finished product.
material: a raw material or component consumed in production.
part: a part used in production.

categoryitem_categorynullable

The category this item belongs to.

The category's unit group determines the base unit the item's rates (unit_value, unit_cost, burn_rate) are expressed in.

Always returned as null in this endpoint.

unit_valueratenullable

Selling value per unit, expressed as a rate (e.g. $25.50 / kg).

Always returned as null in this endpoint.

unit_costratenullable

Cost per unit, expressed as a rate (e.g. $10.00 / kg).

For items a production flow produces, retrieving the item's costs recomputes this from the flow and stores the result here, so it can change without the item having been edited.

Always returned as null in this endpoint.

burn_rateratenullable

Rate at which this item is consumed in production, expressed as a quantity over time (e.g. 100 kg / hr).

Always returned as null in this endpoint.

attributeslistnullable

Attributes assigned to this item.

Always returned as null in this endpoint.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

production_runentitynullable

The production run in progress when the machine stopped.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

batchentitynullable

The batch in progress when the machine stopped.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

schedule_lineentitynullable

The scheduled campaign the stoppage interrupted.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

notestringnullable

Free-form notes about the stoppage.

reported_byactorExpandablenullable

The actor that logged the event — a user, API key, or agent.

Recorded from the credentials that created the event and not settable by the caller.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

user: a human user account.
api_key: a programmatic caller authenticating with an API key.
agent: an automated agent acting on the account's behalf.
group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.

namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

For user actors: the user's email address.
For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.

sourcestringenumValues:manualscannerinferred

How the event was recorded.

manual: a person logged the stoppage.
scanner: a shop-floor station logged it.
inferred: the system derived it from a gap in activity.
api: an integration reported it.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

201

Successful response for Create Machine Downtime Event

Create Machine Downtime Event

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const machineDowntimeEvent = await client.operations.machineDowntimeEvents.create({
  machine_id: 'mc_ffcfk9dxixis',
  reason: 'breakdown',
  started_at: '2026-05-10T00:00:00Z',
});

console.log(machineDowntimeEvent.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const machineDowntimeEvent = await client.operations.machineDowntimeEvents.create({
  machine_id: 'mc_ffcfk9dxixis',
  reason: 'breakdown',
  started_at: '2026-05-10T00:00:00Z',
});

console.log(machineDowntimeEvent.id);

201 example

{
  "id": "mcdt_ff5te1hqttco",
  "object": "machine_downtime_event",
  "machine": {
    "id": "mc_ffcfk9dxixis",
    "object": "machine",
    "name": "CNC Router",
    "serial_number": "SN-2024-0001",
    "notes": "Spindle rebuilt March 2026; torque calibration due quarterly.",
    "department": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "department": {
    "id": "dp_m0jayebxnkos",
    "object": "department",
    "name": "Fabrication",
    "notes": null,
    "location": null,
    "scanning_stations": null,
    "machines": null,
    "labor_rate": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "reason": {
    "object": "machine_downtime_reason",
    "code": "breakdown",
    "name": "Breakdown",
    "oee_bucket": "availability"
  },
  "started_at": "2026-05-10T00:00:00Z",
  "ended_at": "2026-05-10T00:23:00Z",
  "duration_seconds": 1380,
  "shift_at": "2026-05-10T00:00:00Z",
  "shift_code": "A",
  "item": {
    "id": "it_pej07ckhvu62",
    "object": "item",
    "sku": "ALM-2024-1001",
    "description": "6061-T6 aluminum sheet, 4ft x 8ft, 0.125in thick",
    "notes": null,
    "type": "product",
    "category": null,
    "unit_value": null,
    "unit_cost": null,
    "burn_rate": null,
    "attributes": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "production_run": {
    "id": "prru_sglzcyflxk59",
    "object": "entity",
    "type": "production_run",
    "name": null,
    "handle": null
  },
  "batch": {
    "id": "bt_fuies8j4pk45",
    "object": "entity",
    "type": "batch",
    "name": null,
    "handle": null
  },
  "schedule_line": {
    "id": "pnscln_l28dutdpl81r",
    "object": "entity",
    "type": "production_schedule_line",
    "name": null,
    "handle": null
  },
  "note": "Needle bar jam; replaced needle 42.",
  "reported_by": {
    "id": "us_43irtlt2ajz6",
    "object": "actor",
    "type": "user",
    "name": "John Doe",
    "handle": "jdoe@openmrp.ai",
    "avatar_url": "https://cdn.openmrp.ai/avatars/us_43irtlt2ajz6.jpg",
    "role": null
  },
  "source": "manual",
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "mcdt_ff5te1hqttco",
  "object": "machine_downtime_event",
  "machine": {
    "id": "mc_ffcfk9dxixis",
    "object": "machine",
    "name": "CNC Router",
    "serial_number": "SN-2024-0001",
    "notes": "Spindle rebuilt March 2026; torque calibration due quarterly.",
    "department": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "department": {
    "id": "dp_m0jayebxnkos",
    "object": "department",
    "name": "Fabrication",
    "notes": null,
    "location": null,
    "scanning_stations": null,
    "machines": null,
    "labor_rate": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "reason": {
    "object": "machine_downtime_reason",
    "code": "breakdown",
    "name": "Breakdown",
    "oee_bucket": "availability"
  },
  "started_at": "2026-05-10T00:00:00Z",
  "ended_at": "2026-05-10T00:23:00Z",
  "duration_seconds": 1380,
  "shift_at": "2026-05-10T00:00:00Z",
  "shift_code": "A",
  "item": {
    "id": "it_pej07ckhvu62",
    "object": "item",
    "sku": "ALM-2024-1001",
    "description": "6061-T6 aluminum sheet, 4ft x 8ft, 0.125in thick",
    "notes": null,
    "type": "product",
    "category": null,
    "unit_value": null,
    "unit_cost": null,
    "burn_rate": null,
    "attributes": null,
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z"
  },
  "production_run": {
    "id": "prru_sglzcyflxk59",
    "object": "entity",
    "type": "production_run",
    "name": null,
    "handle": null
  },
  "batch": {
    "id": "bt_fuies8j4pk45",
    "object": "entity",
    "type": "batch",
    "name": null,
    "handle": null
  },
  "schedule_line": {
    "id": "pnscln_l28dutdpl81r",
    "object": "entity",
    "type": "production_schedule_line",
    "name": null,
    "handle": null
  },
  "note": "Needle bar jam; replaced needle 42.",
  "reported_by": {
    "id": "us_43irtlt2ajz6",
    "object": "actor",
    "type": "user",
    "name": "John Doe",
    "handle": "jdoe@openmrp.ai",
    "avatar_url": "https://cdn.openmrp.ai/avatars/us_43irtlt2ajz6.jpg",
    "role": null
  },
  "source": "manual",
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Create Machine Downtime Event

Authorization

Query Parameters

Request Body

Returns

Responses