EDB Postgres Enterprise Manager REST APIs v17.0: Blackout v10.5

Manage alert blackouts. A blackout suppresses alerts for a specific agent or server for a defined period.

get__blackout_

Code samples

GET /blackout/

List blackouts

Returns blackout records from pem.blackout (active + future scheduled). Optionally filter by object_type, object_id, or source. Pass include_history=true to also return archived records from pem.blackout_history.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
object_typequeryintegerfalseFilter by object type: 100 (agent) or 200 (server)
object_idqueryintegerfalseFilter by specific object ID
sourcequerystringfalseFilter by source: manual, scheduled, or auto
include_historyquerybooleanfalseIf true, also include archived blackout records
Enumerated Values
ParameterValue
object_type100
object_type200
sourcemanual
sourcescheduled
sourceauto

Example responses

200 Response
{
  "blackouts": [
    {
      "id": 0,
      "start_time": "2019-08-24T14:15:22Z",
      "end_time": "2019-08-24T14:15:22Z",
      "object_type": 0,
      "object_id": 0,
      "source": "manual",
      "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
      "created_by": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKList of blackout recordsInline

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
» blackouts[oneOf]falsenoneActive blackout records. When include_history=true, may also contain BlackoutHistory objects with additional actual_end_time and archived fields.

oneOf

NameTypeRequiredRestrictionsDescription
»» anonymousBlackoutfalsenonenone
»»» idintegerfalsenonenone
»»» start_timestring(date-time)falsenonenone
»»» end_timestring(date-time)¦nullfalsenonenone
»»» object_typeintegerfalsenone100=agent, 200=server
»»» object_idintegerfalsenonenone
»»» sourcestringfalsenonenone
»»» batch_idstring(uuid)¦nullfalsenonenone
»»» created_bystringfalsenonenone
»»» created_atstring(date-time)falsenonenone

xor

NameTypeRequiredRestrictionsDescription
»» anonymousBlackoutHistoryfalsenoneArchived blackout record. Returned by GET /blackout/?include_history=true (mixed with live rows) and by GET /blackout/{id} when the id is found only in pem.blackout_history.
»»» idintegerfalsenonenone
»»» start_timestring(date-time)falsenonenone
»»» scheduled_end_timestring(date-time)¦nullfalsenoneOriginal end_time when the blackout was created
»»» actual_end_timestring(date-time)falsenoneWhen the blackout actually ended
»»» object_typeintegerfalsenone100=agent, 200=server
»»» object_idintegerfalsenonenone
»»» sourcestringfalsenonenone
»»» batch_idstring(uuid)¦nullfalsenonenone
»»» created_bystringfalsenonenone
»»» created_atstring(date-time)falsenonenone
»»» archivedbooleanfalsenoneAlways true for history records
Enumerated Values
PropertyValue
sourcemanual
sourcescheduled
sourceauto
sourcemanual
sourcescheduled
sourceauto
Info

This operation does not require authentication

post__blackout_

Code samples

POST /blackout/

Create one or more blackouts

Creates blackout records for specified objects. Multiple object_ids can be provided to create a batch.

Body parameter

{
  "start_time": "2019-08-24T14:15:22Z",
  "duration": 1,
  "object_type": 100,
  "object_ids": [
    0
  ]
}

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
bodybodyobjecttruenone
» start_timebodystring(date-time)trueWhen the blackout starts (ISO 8601)
» durationbodyintegertrueLength of the blackout in hours. Must be an integer from 1 to 24, matching the values offered by the Schedule Alert Blackout dialog so that REST-created blackouts render correctly in the UI.
» object_typebodyintegertrue100 = agent, 200 = server
» object_idsbody[integer]trueArray of agent or server IDs
Enumerated Values
ParameterValue
» duration1
» duration2
» duration3
» duration4
» duration5
» duration6
» duration7
» duration8
» duration9
» duration10
» duration11
» duration12
» duration13
» duration14
» duration15
» duration16
» duration17
» duration18
» duration19
» duration20
» duration21
» duration22
» duration23
» duration24
» object_type100
» object_type200

Example responses

201 Response
{
  "ids": [
    0
  ],
  "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20"
}

Responses

StatusMeaningDescriptionSchema
201CreatedBlackout(s) created successfullyInline
428Precondition RequiredValidation error (invalid input, constraint violation)None

Response Schema

Status Code 201

NameTypeRequiredRestrictionsDescription
» ids[integer]falsenonenone
» batch_idstring(uuid)falsenonenone
Info

This operation does not require authentication

get__blackout_{blackout_id}

Code samples

GET /blackout/{blackout_id}

Get a specific blackout

Returns a blackout record. If the id is not present in pem.blackout, the handler falls back to pem.blackout_history and returns the archived record (distinguishable by "archived": true and the presence of actual_end_time / scheduled_end_time fields). Returns 404 if the id is not found in either table.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
blackout_idpathintegertruenone

Example responses

200 Response
{
  "id": 0,
  "start_time": "2019-08-24T14:15:22Z",
  "end_time": "2019-08-24T14:15:22Z",
  "object_type": 0,
  "object_id": 0,
  "source": "manual",
  "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
  "created_by": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Responses

StatusMeaningDescriptionSchema
200OKBlackout record. May be a live row from pem.blackout (Blackout schema) or, when the id is found only in pem.blackout_history, an archived row (BlackoutHistory schema with archived=true).Inline
404Not FoundBlackout not foundNone

Response Schema

Enumerated Values
PropertyValue
sourcemanual
sourcescheduled
sourceauto
sourcemanual
sourcescheduled
sourceauto
Info

This operation does not require authentication

delete__blackout_{blackout_id}

Code samples

DELETE /blackout/{blackout_id}

End a blackout

Ends (archives) a blackout record, moving it to history.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
blackout_idpathintegertruenone

Example responses

200 Response
{
  "id": 0,
  "deleted": true,
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKBlackout ended and archivedInline
404Not FoundBlackout not foundNone

Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
» idintegerfalsenoneID of the ended blackout
» deletedbooleanfalsenoneAlways true on success
» warnings[BlackoutWarning]falsenoneOptional non-fatal warnings — present only when the archive INSERT affected fewer rows than the DELETE returned (e.g. RLS or trigger drift on pem.blackout_history). Each warning carries the BlackoutId, ArchivedCount, and ExpectedArchived for diagnostics.
»» codestringtruenoneStable warning identifier. Known codes: manual_post_state_unavailable (toggle response-shape SELECT failed after COMMIT), in_blackout_post_state_unavailable (likewise for the synced flag), flag_select_failed (status helper fell back to records-derived in_blackout), history_archive_incomplete (DELETE archived fewer rows than expected — investigate RLS / triggers on pem.blackout_history).
»» messagestringtruenonenone
Info

This operation does not require authentication

get__blackout_server_{sid}

Code samples

GET /blackout/server/{sid}

Get blackout status for a server

Returns the synced alert_blackout flag and the breakdown of active records by source for the specified server.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
sidpathintegertrueServer id

Example responses

200 Response
{
  "object_type": 100,
  "object_id": 0,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "scheduled": [
    {
      "id": 0,
      "start_time": "2019-08-24T14:15:22Z",
      "end_time": "2019-08-24T14:15:22Z",
      "object_type": 0,
      "object_id": 0,
      "source": "manual",
      "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
      "created_by": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "auto": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKBlackout status for the server.ObjectBlackoutStatus
404Not FoundNo server with the given id exists.None
428Precondition RequiredThe server id was not provided in the path.None
Info

This operation does not require authentication

put__blackout_server_{sid}

Code samples

PUT /blackout/server/{sid}

Enable manual blackout for a server

Idempotent. Inserts a manual indefinite record if none exists for this server; otherwise returns the existing record with changed=false. Only one active manual record per object is allowed (enforced by pem.idx_blackout_one_active_indefinite).

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
sidpathintegertrueServer id

Example responses

200 Response
{
  "changed": true,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "ended_records": [
    {
      "id": 0,
      "source": "manual",
      "scheduled_end": "2019-08-24T14:15:22Z",
      "ended_early": true
    }
  ],
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKToggle result. changed=true on first enable; changed=false on idempotent no-op.ObjectBlackoutToggleResult
404Not FoundNo object with the given id exists.None
Info

This operation does not require authentication

delete__blackout_server_{sid}

Code samples

DELETE /blackout/server/{sid}

End all blackouts on a server

Idempotent. Ends every active blackout record on this server regardless of source (manual + scheduled + auto). Matches the dashboard checkbox unchecking-an-already-active behaviour: the user intent is "alerts back on now". Records that had started are archived to pem.blackout_history; future-scheduled records are simply deleted.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
sidpathintegertrueServer id

Example responses

200 Response
{
  "changed": true,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "ended_records": [
    {
      "id": 0,
      "source": "manual",
      "scheduled_end": "2019-08-24T14:15:22Z",
      "ended_early": true
    }
  ],
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKToggle result. changed=true when at least one record was ended; changed=false on idempotent no-op.ObjectBlackoutToggleResult
404Not FoundNo object with the given id exists.None
Info

This operation does not require authentication

get__blackout_agent_{aid}

Code samples

GET /blackout/agent/{aid}

Get blackout status for an agent

Returns the synced alert_blackout flag and the breakdown of active records by source for the specified agent.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
aidpathintegertrueAgent id

Example responses

200 Response
{
  "object_type": 100,
  "object_id": 0,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "scheduled": [
    {
      "id": 0,
      "start_time": "2019-08-24T14:15:22Z",
      "end_time": "2019-08-24T14:15:22Z",
      "object_type": 0,
      "object_id": 0,
      "source": "manual",
      "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
      "created_by": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "auto": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKBlackout status for the agent.ObjectBlackoutStatus
404Not FoundNo agent with the given id exists.None
428Precondition RequiredThe agent id was not provided in the path.None
Info

This operation does not require authentication

put__blackout_agent_{aid}

Code samples

PUT /blackout/agent/{aid}

Enable manual blackout for an agent

Idempotent. Inserts a manual indefinite record if none exists for this agent; otherwise returns the existing record with changed=false. Only one active manual record per object is allowed (enforced by pem.idx_blackout_one_active_indefinite).

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
aidpathintegertrueAgent id

Example responses

200 Response
{
  "changed": true,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "ended_records": [
    {
      "id": 0,
      "source": "manual",
      "scheduled_end": "2019-08-24T14:15:22Z",
      "ended_early": true
    }
  ],
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKToggle result. changed=true on first enable; changed=false on idempotent no-op.ObjectBlackoutToggleResult
404Not FoundNo object with the given id exists.None
Info

This operation does not require authentication

delete__blackout_agent_{aid}

Code samples

DELETE /blackout/agent/{aid}

End all blackouts on an agent

Idempotent. Ends every active blackout record on this agent regardless of source (manual + scheduled + auto). Matches the dashboard checkbox unchecking-an-already-active behaviour: the user intent is "alerts back on now". Records that had started are archived to pem.blackout_history; future-scheduled records are simply deleted.

Parameters

NameInTypeRequiredDescription
X-Auth-TokenheaderstringtrueToken for authentication
aidpathintegertrueAgent id

Example responses

200 Response
{
  "changed": true,
  "in_blackout": true,
  "manual": {
    "id": 0,
    "start_time": "2019-08-24T14:15:22Z",
    "end_time": "2019-08-24T14:15:22Z",
    "object_type": 0,
    "object_id": 0,
    "source": "manual",
    "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
    "created_by": "string",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "ended_records": [
    {
      "id": 0,
      "source": "manual",
      "scheduled_end": "2019-08-24T14:15:22Z",
      "ended_early": true
    }
  ],
  "warnings": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKToggle result. changed=true when at least one record was ended; changed=false on idempotent no-op.ObjectBlackoutToggleResult
404Not FoundNo object with the given id exists.None
Info

This operation does not require authentication