Create monitor

POST /v1/monitors

Creating with notify_webhook: true and a webhook_url enables HMAC-signed webhook delivery and returns the signing secret (monitor.webhook_secret) in this response. Store it securely. A retry with the original Idempotency-Key recovers the same secret for up to 24 hours while it remains the current secret or the valid previous secret. An expired or displaced secret returns 409 idempotency_result_expired without rotating again. Reads do not expose the secret. All subsequent reads expose only webhook_secret_set and webhook_secret_hint. Creating monitors and trackers is free. Each alert uses 25 credits once, however many channels and recipients deliver it: credits from your plan, then your on-demand budget. When the account is out of credits, alerts wait instead of sending.

Parameters

Name	Location	Description
Idempotency-Key	header	One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation.

Request body

{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Display name (1-100 characters). Required on create."
          },
          "notify_emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "maxItems": 20,
            "description": "Desired email recipients. External recipients must confirm before delivery. Free includes one additional recipient per monitor; paid plans allow up to 20 total. Default []."
          },
          "notify_frequency": {
            "type": "string",
            "enum": [
              "realtime",
              "hourly",
              "daily"
            ],
            "description": "Delivery cadence. Default realtime. Values: realtime (as analysis completes), hourly (hourly digest), daily (daily digest)."
          },
          "digest_day": {
            "type": "string",
            "description": "Digest day of week. Default \"monday\". Consulted only by weekly digests, which are dashboard-configured today; inert for API-set frequencies."
          },
          "digest_time": {
            "type": "string",
            "description": "Digest send hour as HH:MM (account timezone). Default \"09:00\". Applies to daily digests."
          },
          "notify_webhook": {
            "type": "boolean",
            "description": "Enable HMAC-signed webhook delivery (paid plans). When enabled together with webhook_url, the response returns the signing secret (monitor.webhook_secret), recoverable with the original Idempotency-Key during the valid recovery window. PATCHing true also re-enables an auto-disabled webhook and resets its failure counter."
          },
          "webhook_url": {
            "type": "string",
            "description": "Destination URL for webhook alert deliveries."
          },
          "notify_slack": {
            "type": "boolean",
            "description": "Enable Slack delivery. Requires a Slack integration connected in the dashboard."
          },
          "slack_integration_id": {
            "type": "string",
            "description": "Slack integration id from the dashboard OAuth flow."
          },
          "slack_channel_id": {
            "type": "string",
            "description": "Slack channel id to deliver to."
          },
          "team_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Retired. A monitor belongs to the account the key acts in. Absent or null is ignored; any other value answers 400 team_id_retired. Create only.",
            "deprecated": true
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  }
}

Responses

200 Success

{
  "description": "Success",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "RateLimit-Limit": {
      "$ref": "#/components/headers/RateLimit-Limit"
    },
    "RateLimit-Remaining": {
      "$ref": "#/components/headers/RateLimit-Remaining"
    },
    "RateLimit-Reset": {
      "$ref": "#/components/headers/RateLimit-Reset"
    },
    "Idempotency-Replayed": {
      "$ref": "#/components/headers/Idempotency-Replayed"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MonitorMutationResponse"
      }
    }
  }
}

201 Monitor created. When this request enabled webhook signing, monitor.webhook_secret is present and recoverable by retrying with the original Idempotency-Key during its recovery window.

{
  "description": "Monitor created. When this request enabled webhook signing, monitor.webhook_secret is present and recoverable by retrying with the original Idempotency-Key during its recovery window.",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "RateLimit-Limit": {
      "$ref": "#/components/headers/RateLimit-Limit"
    },
    "RateLimit-Remaining": {
      "$ref": "#/components/headers/RateLimit-Remaining"
    },
    "RateLimit-Reset": {
      "$ref": "#/components/headers/RateLimit-Reset"
    },
    "Idempotency-Replayed": {
      "$ref": "#/components/headers/Idempotency-Replayed"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MonitorMutationResponse"
      }
    }
  }
}

400 InvalidRequest

{
  "$ref": "#/components/responses/InvalidRequest"
}

401 AuthenticationError

{
  "$ref": "#/components/responses/AuthenticationError"
}

403 PermissionError

{
  "$ref": "#/components/responses/PermissionError"
}

404 NotFound

{
  "$ref": "#/components/responses/NotFound"
}

409 Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.

{
  "description": "Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

429 RateLimited

{
  "$ref": "#/components/responses/RateLimited"
}

500 ServerError

{
  "$ref": "#/components/responses/ServerError"
}

Operation definition

{
  "tags": [
    "Monitors"
  ],
  "operationId": "create_monitor",
  "summary": "Create monitor",
  "description": "Creating with notify_webhook: true and a webhook_url enables HMAC-signed webhook delivery and returns the signing secret (monitor.webhook_secret) in this response. Store it securely. A retry with the original Idempotency-Key recovers the same secret for up to 24 hours while it remains the current secret or the valid previous secret. An expired or displaced secret returns 409 idempotency_result_expired without rotating again. Reads do not expose the secret. All subsequent reads expose only webhook_secret_set and webhook_secret_hint. Creating monitors and trackers is free. Each alert uses 25 credits once, however many channels and recipients deliver it: credits from your plan, then your on-demand budget. When the account is out of credits, alerts wait instead of sending.",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "schema": {
        "type": "string"
      },
      "required": false,
      "name": "Idempotency-Key",
      "in": "header",
      "example": "8b2f6c3e-4d1a-4e7b-9c05-2f6a1b7d3e90",
      "description": "One key per intent, 1 to 255 printable ASCII characters (0x21 to 0x7E); anything else is 400 invalid_idempotency_key. Keys are scoped to the account, credential and resource family. The same key and normalized method, path and body returns the committed response with Idempotency-Replayed: true. A changed intent within the same family returns 409 idempotency_conflict. Monitor and tracker families have independent namespaces. Secret recovery is limited as described by the operation."
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "description": "Display name (1-100 characters). Required on create."
            },
            "notify_emails": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "email"
              },
              "maxItems": 20,
              "description": "Desired email recipients. External recipients must confirm before delivery. Free includes one additional recipient per monitor; paid plans allow up to 20 total. Default []."
            },
            "notify_frequency": {
              "type": "string",
              "enum": [
                "realtime",
                "hourly",
                "daily"
              ],
              "description": "Delivery cadence. Default realtime. Values: realtime (as analysis completes), hourly (hourly digest), daily (daily digest)."
            },
            "digest_day": {
              "type": "string",
              "description": "Digest day of week. Default \"monday\". Consulted only by weekly digests, which are dashboard-configured today; inert for API-set frequencies."
            },
            "digest_time": {
              "type": "string",
              "description": "Digest send hour as HH:MM (account timezone). Default \"09:00\". Applies to daily digests."
            },
            "notify_webhook": {
              "type": "boolean",
              "description": "Enable HMAC-signed webhook delivery (paid plans). When enabled together with webhook_url, the response returns the signing secret (monitor.webhook_secret), recoverable with the original Idempotency-Key during the valid recovery window. PATCHing true also re-enables an auto-disabled webhook and resets its failure counter."
            },
            "webhook_url": {
              "type": "string",
              "description": "Destination URL for webhook alert deliveries."
            },
            "notify_slack": {
              "type": "boolean",
              "description": "Enable Slack delivery. Requires a Slack integration connected in the dashboard."
            },
            "slack_integration_id": {
              "type": "string",
              "description": "Slack integration id from the dashboard OAuth flow."
            },
            "slack_channel_id": {
              "type": "string",
              "description": "Slack channel id to deliver to."
            },
            "team_id": {
              "type": [
                "string",
                "null"
              ],
              "description": "Retired. A monitor belongs to the account the key acts in. Absent or null is ignored; any other value answers 400 team_id_retired. Create only.",
              "deprecated": true
            }
          },
          "required": [
            "name"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimit-Limit"
        },
        "RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimit-Remaining"
        },
        "RateLimit-Reset": {
          "$ref": "#/components/headers/RateLimit-Reset"
        },
        "Idempotency-Replayed": {
          "$ref": "#/components/headers/Idempotency-Replayed"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MonitorMutationResponse"
          }
        }
      }
    },
    "201": {
      "description": "Monitor created. When this request enabled webhook signing, monitor.webhook_secret is present and recoverable by retrying with the original Idempotency-Key during its recovery window.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "RateLimit-Limit": {
          "$ref": "#/components/headers/RateLimit-Limit"
        },
        "RateLimit-Remaining": {
          "$ref": "#/components/headers/RateLimit-Remaining"
        },
        "RateLimit-Reset": {
          "$ref": "#/components/headers/RateLimit-Reset"
        },
        "Idempotency-Replayed": {
          "$ref": "#/components/headers/Idempotency-Replayed"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MonitorMutationResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/InvalidRequest"
    },
    "401": {
      "$ref": "#/components/responses/AuthenticationError"
    },
    "403": {
      "$ref": "#/components/responses/PermissionError"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "description": "Conflict. idempotency_conflict means the Idempotency-Key was finalized with a different request intent.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/ServerError"
    }
  }
}