Maintenance Windows API

API endpoints for managing maintenance windows.

Base URL: /api/maintenance-windows

Authentication: JWT Bearer token

http

Authorization: Bearer <your-jwt-token>

Create Maintenance Window

http

POST /api/maintenance-windows
Content-Type: application/json

{
  "name": "Production Deployment - Payment Service",
  "description": "Deploy v2.5.0 with new checkout flow",
  "startTime": "2024-01-15T14:00:00Z",
  "endTime": "2024-01-15T14:30:00Z",
  "recurrenceType": "OneTime",
  "behavior": "SuppressIssues",
  "scope": "TaggedTests",
  "scopeConfig": "[\"payment-service\",\"production\"]"
}

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Maintenance window name
`description`	string	No	Optional description
`startTime`	ISO 8601 datetime	Yes	Window start time (UTC)
`endTime`	ISO 8601 datetime	Yes	Window end time (UTC)
`recurrenceType`	string	Yes	"OneTime", "Daily", "Weekly", or "Monthly"
`behavior`	string	Yes	"SuppressIssues" or "PauseTests"
`scope`	string	Yes	"AllTests", "SpecificTests", or "TaggedTests"
`scopeConfig`	string (JSON array)	Yes	Test IDs (SpecificTests) or tags (TaggedTests)

Response (201 Created):

json

{
  "id": "mw-123",
  "name": "Production Deployment - Payment Service",
  "description": "Deploy v2.5.0 with new checkout flow",
  "startTime": "2024-01-15T14:00:00Z",
  "endTime": "2024-01-15T14:30:00Z",
  "recurrenceType": "OneTime",
  "behavior": "SuppressIssues",
  "scope": "TaggedTests",
  "scopeConfig": "[\"payment-service\",\"production\"]",
  "status": "Scheduled",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

List Maintenance Windows

http

GET /api/maintenance-windows?status=<status>&includeRecurring=true

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: "Scheduled", "Active", "Completed"
`includeRecurring`	boolean	Include recurring windows (default: true)

Response (200 OK):

json

{
  "items": [
    {
      "id": "mw-123",
      "name": "Production Deployment - Payment Service",
      "startTime": "2024-01-15T14:00:00Z",
      "endTime": "2024-01-15T14:30:00Z",
      "recurrenceType": "OneTime",
      "behavior": "SuppressIssues",
      "scope": "TaggedTests",
      "status": "Scheduled",
      "createdAt": "2024-01-15T10:00:00Z"
    },
    {
      "id": "mw-456",
      "name": "Weekly Database Backup",
      "startTime": "2024-01-14T02:00:00Z",
      "endTime": "2024-01-14T03:00:00Z",
      "recurrenceType": "Weekly",
      "behavior": "SuppressIssues",
      "scope": "TaggedTests",
      "status": "Active",
      "nextOccurrence": "2024-01-21T02:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Maintenance Window

http

GET /api/maintenance-windows/{id}

Response (200 OK):

json

{
  "id": "mw-123",
  "name": "Production Deployment - Payment Service",
  "description": "Deploy v2.5.0 with new checkout flow",
  "startTime": "2024-01-15T14:00:00Z",
  "endTime": "2024-01-15T14:30:00Z",
  "recurrenceType": "OneTime",
  "behavior": "SuppressIssues",
  "scope": "TaggedTests",
  "scopeConfig": "[\"payment-service\",\"production\"]",
  "status": "Scheduled",
  "createdByUserId": "user-123",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

Update Maintenance Window

http

PUT /api/maintenance-windows/{id}
Content-Type: application/json

{
  "name": "Production Deployment - Payment Service (Extended)",
  "endTime": "2024-01-15T15:00:00Z"
}

All fields are optional - only specified fields will be updated.

Response (200 OK):

json

{
  "id": "mw-123",
  "name": "Production Deployment - Payment Service (Extended)",
  "endTime": "2024-01-15T15:00:00Z",
  ...
}

Delete Maintenance Window

http

DELETE /api/maintenance-windows/{id}

Response: 204 No Content (success)

Note: Deleting an active window immediately resumes normal monitoring. Recurring windows will no longer create future occurrences.

End Maintenance Window Early

Terminate an active maintenance window before its scheduled end time.

http

POST /api/maintenance-windows/{id}/end

Response: 204 No Content (success)

Tests resume normal monitoring immediately.

Maintenance Window Statuses

Status	Description
`Scheduled`	Window created but not started yet
`Active`	Currently in effect (current time between start and end)
`Completed`	One-time window finished, or recurring window's last occurrence ended

Recurring windows show status: "Scheduled" with nextOccurrence timestamp.

Scope Configuration

All Tests

json

{
  "scope": "AllTests",
  "scopeConfig": "[]"
}

Applies to all tests in the workspace.

Specific Tests

json

{
  "scope": "SpecificTests",
  "scopeConfig": "[\"test-123\",\"test-456\",\"test-789\"]"
}

Array of test IDs.

Tagged Tests

json

{
  "scope": "TaggedTests",
  "scopeConfig": "[\"payment-service\",\"production\"]"
}

Array of tags. Matches tests with any of the specified tags.

Recurrence Types

One-Time

Window occurs exactly once.

json

{
  "recurrenceType": "OneTime",
  "startTime": "2024-01-15T14:00:00Z",
  "endTime": "2024-01-15T14:30:00Z"
}

Daily

Repeats every day at the same time.

json

{
  "recurrenceType": "Daily",
  "startTime": "2024-01-15T02:00:00Z",
  "endTime": "2024-01-15T03:00:00Z"
}

Effective schedule:

Jan 15, 02:00-03:00
Jan 16, 02:00-03:00
Jan 17, 02:00-03:00
(continues daily)

Weekly

Repeats every 7 days.

json

{
  "recurrenceType": "Weekly",
  "startTime": "2024-01-14T00:00:00Z",  // Sunday
  "endTime": "2024-01-14T02:00:00Z"
}

Repeats every Sunday at the same time.

Monthly

Repeats on the same day of each month.

json

{
  "recurrenceType": "Monthly",
  "startTime": "2024-01-01T03:00:00Z",  // 1st of month
  "endTime": "2024-01-01T05:00:00Z"
}

Repeats on the 1st of every month.

Behaviors

Suppress Issues

What it does:

Tests continue running
Results recorded
Issues created but marked "During Maintenance"
No alerts sent (Slack, email, SMS, webhooks)
Issues auto-resolve when window ends

Use when: You want visibility into failures during maintenance.

Pause Tests

What it does:

Tests do not run during window
No results recorded
No issues created
No alerts sent
Tests resume when window ends

Use when: Service will definitely be down, no point monitoring.

Error Responses

400 Bad Request

Invalid request body or parameters.

json

{
  "error": "Bad request",
  "message": "End time must be after start time"
}

404 Not Found

Maintenance window not found.

json

{
  "error": "Not found"
}

Examples

Weekly Backup Window

bash

curl -X POST https://api.pingward.com/api/maintenance-windows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Database Backup",
    "description": "Sunday night backup window",
    "startTime": "2024-01-14T02:00:00Z",
    "endTime": "2024-01-14T03:00:00Z",
    "recurrenceType": "Weekly",
    "behavior": "SuppressIssues",
    "scope": "TaggedTests",
    "scopeConfig": "[\"database\"]"
  }'

One-Time Deployment

bash

curl -X POST https://api.pingward.com/api/maintenance-windows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API v3.0 Deployment",
    "startTime": "2024-01-20T16:00:00Z",
    "endTime": "2024-01-20T16:30:00Z",
    "recurrenceType": "OneTime",
    "behavior": "PauseTests",
    "scope": "AllTests",
    "scopeConfig": "[]"
  }'

Maintenance Windows Guide - Feature overview and best practices
Issues API - Issue management endpoints

Maintenance Windows API ​

Create Maintenance Window ​

List Maintenance Windows ​

Get Maintenance Window ​

Update Maintenance Window ​

Delete Maintenance Window ​

End Maintenance Window Early ​

Maintenance Window Statuses ​

Scope Configuration ​

All Tests ​

Specific Tests ​

Tagged Tests ​

Recurrence Types ​

One-Time ​

Daily ​

Weekly ​

Monthly ​

Behaviors ​

Suppress Issues ​

Pause Tests ​

Error Responses ​

400 Bad Request ​

404 Not Found ​

Examples ​

Weekly Backup Window ​

One-Time Deployment ​

Related Documentation ​

Maintenance Windows API

Create Maintenance Window

List Maintenance Windows

Get Maintenance Window

Update Maintenance Window

Delete Maintenance Window

End Maintenance Window Early

Maintenance Window Statuses

Scope Configuration

All Tests

Specific Tests

Tagged Tests

Recurrence Types

One-Time

Daily

Weekly

Monthly

Behaviors

Suppress Issues

Pause Tests

Error Responses

400 Bad Request

404 Not Found

Examples

Weekly Backup Window

One-Time Deployment

Related Documentation