POST
/
monitorings
/
bulk-create
curl --request POST \
  --url https://api.godiligent.ai/monitorings/bulk-create \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '[
  {
    "website": "https://example.com",
    "checks": [
      "non_operational_website",
      "high_risk_diligent_classification"
    ],
    "frequency": "weekly",
    "run_now": true,
    "expires_at": "2024-12-31T23:59:59.000Z"
  }
]'
{
  "is_successful": true,
  "items": [
    {
      "id": "d6e3b214-30b1-4401-a1b8-a1bd3c6a84e4",
      "website": "https://example.com",
      "customer_id": "<string>",
      "checks": [
        "non_operational_website"
      ],
      "frequency": "weekly",
      "is_active": true,
      "running_state": "IDLE",
      "next_run_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "last_execution": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "execution_results": [
        {}
      ]
    }
  ]
}

Overview

The bulk create monitorings endpoint allows you to create multiple monitoring configurations in a single API call. This endpoint is useful for onboarding multiple websites or setting up monitoring for a large portfolio efficiently.

Key Features

  • Batch Processing: Create up to 200 monitorings in one request
  • Duplicate Detection: Duplicate websites within the same request will be rejected with an error
  • Existing Monitoring Check: If any monitoring already exists for a website for this customer, the entire request is rejected with a list of duplicates
  • Immediate Execution: Option to run monitoring checks immediately after creation (run_now flag)
  • Flexible Scheduling: Configure custom frequencies and expiration dates
  • Atomic Operation: If there are any validation or duplicate errors, no monitorings are created
  • URL Security: All website URLs are validated and sanitized for security

Request

  • Method: POST
  • Path: /monitorings/bulk-create
  • Body: JSON array of monitoring objects (minimum 1, maximum 200)

Each object must include:

  • website (string, required, unique in array) - The URL to monitor (will be validated and sanitized)
  • checks (array, required) - Array of monitoring checks to perform:
    • "non_operational_website" - Check if website is operational
    • "high_risk_diligent_classification" - Check for high-risk classification
    • "catalog_contain_loan_flipping_indicators" - Check for loan flipping indicators
  • frequency (string, required, case-insensitive) - How often to run checks:
    • "weekly" - Every 7 days
    • "every_2_weeks" - Every 14 days (default)
    • "every_3_weeks" - Every 21 days
    • "every_4_weeks" - Every 28 days
  • expires_at (ISO8601 string, optional) - When monitoring expires (defaults to 6 months from creation)
    • Must be a future date
    • Must be at least N days ahead where N equals the frequency period (e.g., weekly requires at least 7 days ahead)
  • run_now (boolean, optional) - Execute immediately after creation (defaults to true)

Example Request

[
  {
    "website": "https://example.com",
    "checks": ["non_operational_website", "high_risk_diligent_classification"],
    "frequency": "weekly",
    "run_now": true,
    "expires_at": "2024-12-31T23:59:59.000Z"
  },
  {
    "website": "https://shop.example.com",
    "checks": ["catalog_contain_loan_flipping_indicators"],
    "frequency": "every_4_weeks",
    "run_now": false
  }
]

Success Response

  • Status: 200 OK
{
  "is_successful": true,
  "items": [
    {
      "id": "string",
      "website": "https://example.com",
      "checks": ["non_operational_website", "high_risk_diligent_classification"],
      "frequency": "weekly",
      "expires_at": "2024-12-31T23:59:59.000Z",
      "customer_id": "string",
      "created_at": "2024-06-03T10:46:00.000Z",
      "updated_at": "2024-06-03T10:46:00.000Z",
      "is_active": true,
      "running_state": "IDLE",
      "next_run_at": "2024-06-10T10:46:00.000Z",
      "last_execution": null,
      "execution_results": []
    }
  ]
}

Error Handling

  • 400 Bad Request
    • Invalid JSON body, schema validation errors, duplicate websites in request, or monitorings already exist for one or more websites for this customer.
    • Invalid JSON:
      { "error": "Invalid JSON body:: Unexpected token '}' in JSON at position 1" }
      
    • Validation errors:
      { "error": "Validation failed :: [{\"code\":\"custom\",\"message\":\"Invalid check name(s)\",\"path\":[\"checks\"]}]" }
      
    • Duplicate websites in request:
      { "error": "Validation failed :: [{\"code\":\"custom\",\"message\":\"Duplicate monitoring found for website: https://example.com\",\"path\":[1,\"website\"]}]" }
      
    • Existing monitorings:
      {
        "error": "Duplicate monitorings found",
        "duplicates": [
          { "website": "https://example.com", "index": 0 },
          { "website": "https://shop.duplicate.com", "index": 2 }
        ]
      }
      
  • 401 Unauthorized
    • Missing or invalid customer authentication.
    • Example:
      { "error": "Unauthorized: no customer id" }
      
  • 500 Internal Server Error
    • Unexpected server error during creation or SQS publishing.
    • Example:
      { "error": "Failed to create monitorings" }
      

Validation Rules

  • Website URLs: All URLs are validated and sanitized for security. Invalid or disallowed URLs will be rejected.
  • Unique Checks: Each monitoring must have unique check names (no duplicates within the same monitoring).
  • Frequency: Case-insensitive input (e.g., “WEEKLY” becomes “weekly”). Must be one of the supported frequencies.
  • Expiration Date:
    • Must be a valid ISO8601 date string
    • Must be a future date
    • Must be at least N days ahead based on frequency (weekly=7 days, every_2_weeks=14 days, etc.)
    • Defaults to 6 months from creation if not provided
  • Array Limits: Minimum 1 monitoring, maximum 200 monitorings per request
  • Duplicate Detection: No duplicate websites allowed within the same request or existing for the customer

Notes

  • All monitorings must have unique websites in the request and not already exist for the customer.
  • If run_now is set to true, the monitoring will be queued for immediate execution after creation.
  • Frequency input is case-insensitive and will be normalized to lowercase.
  • The system processes monitorings in batches for SQS publishing (batch size: 10).

Authorizations

X-API-KEY
string
header
required

Body

application/json · object[]

The body is of type object[].

Response

200
application/json

Successful bulk creation

The response is of type object.