---
updatedAt: 2026-06-12T14:47:10.000Z
agentTools:
  projectIndex: https://docs.formant.io/llms.txt
---

# Post

Create a new intervention request.
Resource: interventions
Authorized roles: administrator, device

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "NotificationMuted": {
        "properties": {
          "start": {
            "format": "date-time",
            "type": "string",
            "description": "Mute start time (inclusive)."
          },
          "end": {
            "format": "date-time",
            "type": "string",
            "description": "Mute end time (exclusive)."
          }
        },
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "nullable": true
      },
      "Label": {
        "properties": {
          "value": {
            "type": "string",
            "description": "Value corresponding to the user-friendly description for this label. This will be passed as the response to this intervention request."
          },
          "displayName": {
            "minLength": 1,
            "type": "string",
            "description": "User-friendly description of label. This will be presented to the user in a dropdown."
          },
          "description": {
            "maxLength": 1000,
            "type": "string",
            "minLength": 1
          }
        },
        "type": "object",
        "required": [
          "value"
        ]
      },
      "LabeledPolygon": {
        "properties": {
          "vertices": {
            "items": {
              "items": {},
              "maxItems": 2,
              "type": "array",
              "minItems": 2
            },
            "type": "array",
            "minItems": 3
          },
          "labels": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": true
          }
        },
        "type": "object",
        "required": [
          "vertices",
          "labels"
        ]
      },
      "LabelingRequestData": {
        "properties": {
          "instruction": {
            "type": "string",
            "description": "Prompt to be shown to the user to resolve the intervention request."
          },
          "imageUrl": {
            "format": "url",
            "type": "string",
            "description": "URL of the image file to be shown during the intervention request."
          },
          "labels": {
            "items": {
              "$ref": "#/components/schemas/Label"
            },
            "type": "array"
          },
          "hint": {
            "items": {
              "$ref": "#/components/schemas/LabeledPolygon"
            },
            "type": "array",
            "description": "(x,y) coordinates creating a box around the area in the image you would like to suggest as the most likely location of the object in question."
          },
          "title": {
            "type": "string",
            "description": "Title of the intervention request window."
          }
        },
        "type": "object",
        "required": [
          "instruction",
          "imageUrl",
          "labels"
        ]
      },
      "PhysicalRequestData": {
        "properties": {
          "reason": {
            "maxLength": 10000,
            "type": "string"
          },
          "startTime": {
            "format": "date-time",
            "type": "string"
          },
          "endTime": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object",
        "required": [
          "reason"
        ]
      },
      "SelectionRequestData": {
        "properties": {
          "instruction": {
            "type": "string",
            "description": "Prompt to be shown to the user to resolve the intervention request."
          },
          "imageUrl": {
            "format": "url",
            "type": "string",
            "description": "URL of the image file to be shown during the intervention request."
          },
          "options": {
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "type": "array",
            "description": "Array of strings to present to the user as selection options."
          },
          "hint": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Index of the option you would like to suggest as the most likely response (zero-indexed)."
          },
          "title": {
            "type": "string",
            "description": "Title of the intervention request window."
          }
        },
        "type": "object",
        "required": [
          "instruction",
          "imageUrl",
          "options"
        ]
      },
      "TeleopRequestData": {
        "properties": {
          "instruction": {
            "type": "string"
          }
        },
        "type": "object",
        "required": [
          "instruction"
        ]
      },
      "InterventionRequest": {
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "triggered-event",
              "datapoint-event",
              "device-online",
              "device-offline",
              "intervention-request",
              "intervention-response",
              "teleop-session-record",
              "port-forwarding-session-record",
              "command-request",
              "command-response",
              "command-delivery",
              "custom",
              "comment",
              "system",
              "annotation",
              "task-summary",
              "stateful"
            ],
            "description": "Enter `intervention-request`."
          },
          "interventionType": {
            "type": "string",
            "enum": [
              "selection",
              "labeling",
              "teleop",
              "physical"
            ],
            "description": "`selection` prompts user to select an option from a dropdown menu. `labeling` prompts user to draw a box around and object and give it a label."
          },
          "data": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/SelectionRequestData"
              },
              {
                "$ref": "#/components/schemas/LabelingRequestData"
              },
              {
                "$ref": "#/components/schemas/TeleopRequestData"
              },
              {
                "$ref": "#/components/schemas/PhysicalRequestData"
              }
            ]
          },
          "responses": {
            "items": {},
            "type": "array"
          },
          "agentId": {
            "format": "uuid",
            "type": "string",
            "description": "ID of the device which prompts this intervention request."
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "error",
              "critical"
            ],
            "description": "Severity of this event (`info`, `warning`, `error`, or `critical`)."
          },
          "deviceName": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "Name of the device associated with this intervention request."
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "tags": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "organizationId": {
            "format": "uuid",
            "type": "string",
            "description": "ID of the organization in which to create this new event."
          },
          "externalId": {
            "type": "string",
            "nullable": true,
            "description": "External ID of this event."
          },
          "userId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "User ID associated with this event."
          },
          "time": {
            "format": "date-time",
            "type": "string",
            "description": "Start time of the data range relevant to this event."
          },
          "endTime": {
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "description": "End time of the data range relevant to this event."
          },
          "parentId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "If this custom event is related to another event, you can add the ID of that parent event here."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "User-customizable metadata associated with this event in key-value pair format."
          },
          "message": {
            "maxLength": 1024,
            "type": "string",
            "description": "Message of this event. Must match the `message` field in the Formant UI when configuring a custom event."
          },
          "viewed": {
            "type": "boolean"
          },
          "deviceId": {
            "format": "uuid",
            "type": "string",
            "nullable": true,
            "description": "ID of the device relevant to this event."
          },
          "streamName": {
            "type": "string",
            "nullable": true
          },
          "streamType": {
            "type": "string",
            "enum": [
              "bitset",
              "localization",
              "point cloud",
              "location",
              "file",
              "health",
              "transform tree",
              "battery",
              "video",
              "numeric set",
              "json",
              "image",
              "numeric",
              "text"
            ],
            "nullable": true
          },
          "eventTriggerId": {
            "format": "uuid",
            "type": "string",
            "nullable": true
          },
          "notificationEnabled": {
            "type": "boolean",
            "description": "Set this to `true` to enable notifications for this event."
          },
          "notificationMuted": {
            "$ref": "#/components/schemas/NotificationMuted",
            "nullable": true,
            "description": "Set this to temporarily mute notifications for this event."
          },
          "deletedAt": {
            "nullable": true,
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object",
        "required": [
          "data",
          "time"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "info": {
    "title": "Formant admin-api",
    "version": "1.357.8"
  },
  "openapi": "3.0.0",
  "paths": {
    "/intervention-requests": {
      "post": {
        "operationId": "InterventionRequestController.post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InterventionRequest"
              }
            }
          },
          "description": "InterventionRequest",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterventionRequest"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Post",
        "tags": [
          "Intervention Request"
        ],
        "description": "Create a new intervention request.\nResource: interventions\nAuthorized roles: administrator, device",
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.formant.io/v1/admin"
    }
  ]
}
```