openapi: 3.2.0 info: title: Phare Maintenance Windows API description: Learn how to use the phare.io API. Most of the things that can be done on the web platform can also be achieved with the API documented on this page. termsOfService: https://phare.io/legal/terms-of-service contact: name: Phare email: support@phare.io version: '1.0' servers: - url: https://api.phare.io security: - BearerAuth: [] tags: - name: Maintenance Windows description: Maintenance Windows paths: /uptime/maintenance-windows: get: tags: - Maintenance Windows summary: List maintenance windows description: Get a paginated list of maintenance windows operationId: getUptimeMaintenanceWindows parameters: - name: monitor_id in: query description: Filter maintenance windows by monitor ID. Can be specified multiple times to filter by multiple monitor IDs. required: false style: form explode: true schema: type: integer - name: status_page_id in: query description: Filter maintenance windows by status page ID. Can be specified multiple times to filter by multiple status page IDs. required: false style: form explode: true schema: type: integer - name: state in: query description: Filter maintenance windows by state. required: false schema: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' responses: '200': description: Success, maintenance windows retrieved content: application/json: schema: properties: data: type: array items: type: object properties: id: description: Maintenance window ID type: integer example: 1 project_id: description: Parent project ID type: integer example: 1 state: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 created_at: description: Date of creation for the entity type: string format: date-time updated_at: description: Date of last update for the entity type: string format: date-time required: - title - monitoring_mode - starts_at - ends_at meta: $ref: '#/components/schemas/meta' links: $ref: '#/components/schemas/links' type: object '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' post: tags: - Maintenance Windows summary: Create a maintenance window operationId: createUptimeMaintenanceWindow requestBody: description: Maintenance window request required: true content: application/json: schema: type: object properties: title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 required: - title - monitoring_mode - starts_at - ends_at responses: '201': description: Success, maintenance window created content: application/json: schema: type: object properties: id: description: Maintenance window ID type: integer example: 1 project_id: description: Parent project ID type: integer example: 1 state: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 created_at: description: Date of creation for the entity type: string format: date-time updated_at: description: Date of last update for the entity type: string format: date-time required: - title - monitoring_mode - starts_at - ends_at '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '422': $ref: '#/components/responses/422' parameters: - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' /uptime/maintenance-windows/{maintenanceWindowId}: get: tags: - Maintenance Windows summary: Get a maintenance window description: Get a maintenance window by ID operationId: getUptimeMaintenanceWindow parameters: - name: maintenanceWindowId in: path description: ID of the maintenance window to show required: true schema: type: integer - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' responses: '200': description: Success, maintenance window retrieved content: application/json: schema: type: object properties: id: description: Maintenance window ID type: integer example: 1 project_id: description: Parent project ID type: integer example: 1 state: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 created_at: description: Date of creation for the entity type: string format: date-time updated_at: description: Date of last update for the entity type: string format: date-time required: - title - monitoring_mode - starts_at - ends_at '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' post: tags: - Maintenance Windows summary: Update a maintenance window description: Update a maintenance window by ID operationId: updateUptimeMaintenanceWindow parameters: - name: maintenanceWindowId in: path description: ID of the maintenance window to update required: true schema: type: integer - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' requestBody: description: Maintenance window request required: true content: application/json: schema: type: object properties: title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 responses: '200': description: Success, maintenance window updated content: application/json: schema: type: object properties: id: description: Maintenance window ID type: integer example: 1 project_id: description: Parent project ID type: integer example: 1 state: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 created_at: description: Date of creation for the entity type: string format: date-time updated_at: description: Date of last update for the entity type: string format: date-time required: - title - monitoring_mode - starts_at - ends_at '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' delete: tags: - Maintenance Windows summary: Delete a maintenance window description: Delete a maintenance window by ID operationId: deleteUptimeMaintenanceWindow parameters: - name: maintenanceWindowId in: path description: ID of the maintenance window to delete required: true schema: type: integer - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' responses: '204': description: Success, maintenance window deleted content: {} '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' /uptime/maintenance-windows/{maintenanceWindowId}/cancel: post: tags: - Maintenance Windows summary: Cancel a maintenance window description: Cancel a maintenance window by ID operationId: cancelUptimeMaintenanceWindow parameters: - name: maintenanceWindowId in: path description: ID of the maintenance window to cancel required: true schema: type: integer - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' responses: '204': description: Success, maintenance window cancelled content: {} '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '422': $ref: '#/components/responses/422' /uptime/maintenance-windows/{maintenanceWindowId}/complete: post: tags: - Maintenance Windows summary: Complete a maintenance window description: Complete a maintenance window by ID operationId: completeUptimeMaintenanceWindow parameters: - name: maintenanceWindowId in: path description: ID of the maintenance window to complete required: true schema: type: integer - $ref: '#/components/parameters/header_project_id' - $ref: '#/components/parameters/header_project_slug' responses: '200': description: Success, maintenance window completed content: application/json: schema: type: object properties: id: description: Maintenance window ID type: integer example: 1 project_id: description: Parent project ID type: integer example: 1 state: $ref: '#/components/schemas/Uptime.MaintenanceWindow.StateEnum' monitoring_mode: $ref: '#/components/schemas/Uptime.MaintenanceWindow.MonitoringModeEnum' title: description: Maintenance window title type: string example: Database upgrade maximum: 250 minimum: 1 description: description: Description of the maintenance window type: - string - 'null' example: Planned database upgrade and maintenance starts_at: description: Date and time when the maintenance window starts type: string format: date-time ends_at: description: Date and time when the maintenance window ends type: string format: date-time monitors: description: List of monitor IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 - 3 status_pages: description: List of status page IDs linked to the maintenance window type: array items: type: integer example: - 1 - 2 created_at: description: Date of creation for the entity type: string format: date-time updated_at: description: Date of last update for the entity type: string format: date-time required: - title - monitoring_mode - starts_at - ends_at '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '422': $ref: '#/components/responses/422' components: parameters: per_page: name: per_page in: query description: Number of resources to return per page required: false schema: type: integer example: 20 default: 20 maximum: 100 minimum: 1 header_project_id: name: X-Phare-Project-Id in: header description: A project header is required when using an organization-scoped API key. required: false schema: type: integer example: 1 header_project_slug: name: X-Phare-Project-Slug in: header description: A project header is required when using an organization-scoped API key. required: false schema: type: string example: luminous-guiding-tower page: name: page in: query description: Page number to show required: false schema: type: integer example: 1 default: 1 schemas: meta: description: Meta data for pagination properties: current_page: type: integer example: 2 from: type: integer example: 11 to: type: integer example: 20 per_page: type: integer example: 100 path: type: string example: https://api.phare.io/{resource}?page=2 type: object Uptime.MaintenanceWindow.MonitoringModeEnum: type: string enum: - pause - mute - normal Uptime.MaintenanceWindow.StateEnum: type: string enum: - scheduled - in_progress - completed - cancelled links: description: Links for pagination properties: first: type: string format: url example: https://api.phare.io/{resource}?page=2 last: type: - string - 'null' format: url example: https://api.phare.io/{resource}?page=10 prev: type: - string - 'null' format: url example: https://api.phare.io/{resource}?page=1 next: type: - string - 'null' format: url example: https://api.phare.io/{resource}?page=1 type: object responses: '403': description: Error, access forbidden content: application/json: schema: description: Access forbidden error schema properties: message: type: string example: The platform:write permission is required to perform this action. type: object '401': description: Error, access unauthorized content: application/json: schema: description: Access unauthorized error schema properties: message: type: string example: Unauthorized type: object '404': description: Error, resource not found content: application/json: schema: description: Not found error schema properties: message: type: string example: Resource not found type: object '422': description: Error, unprocessable entity content: application/json: schema: description: Validation error schema properties: message: type: string errors: properties: key: type: array items: type: string example: The key field is required type: object type: object securitySchemes: BearerAuth: type: http description: 'Use a user token to access authenticated routes. The token must be specified in the Authorization HTTP header with the following format ''Authorization: Bearer ''.' scheme: bearer x-tagGroups: - name: Phare platform tags: - Users - Projects - Alert Rules - name: Phare uptime tags: - Monitors - Incidents - Status Pages - Reports x-provenance: method: harvested publisher: Phare source: https://docs.phare.io/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)