id: pagerduty
name: PagerDuty
version: 1.0.0
description: "PagerDuty (Events API v2 + REST API v2) — SOC alerting and on-call: trigger/acknowledge/resolve incidents via the routing key, list and read incidents, add notes, and read on-calls, users, and services. Token + routing-key authentication; stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: trigger/acknowledge/resolve incident, list/get incident, add note, list on-calls/users/services."
category: notification

# Per-instance configuration. api_token authenticates the REST API
# ('Authorization: Token token=<api_token>'); routing_key is the Events API v2
# integration key used to trigger/acknowledge/resolve. from_email is the
# PagerDuty user email required by the REST API for writes such as add-note.
config_schema:
  properties:
    api_token:
      type: string
      description: "PagerDuty REST API token"
      x-soar-sensitive: true
    routing_key:
      type: string
      description: "Events API v2 integration/routing key (for trigger/ack/resolve)"
      x-soar-sensitive: true
    from_email:
      type: string
      description: "A valid PagerDuty user email (required for add-note and other REST writes)"
  required:
    - api_token

commands:
  - id: trigger_incident
    name: pagerduty-trigger-incident
    description: "Trigger an incident through the Events API v2. Returns a dedup_key used to acknowledge/resolve it."
    inputs_schema:
      properties:
        summary: { type: string, description: "Short incident summary" }
        source: { type: string, description: "Affected source (host, service, IP)" }
        severity: { type: string, description: "critical | error | warning | info (default critical)" }
        dedup_key: { type: string, description: "Optional dedup key (auto-generated if omitted)" }
        component: { type: string, description: "Optional component" }
      required: [summary, source]
    outputs_schema: { properties: {} }
  - id: acknowledge_incident
    name: pagerduty-acknowledge-incident
    description: "Acknowledge an incident by its dedup_key (Events API v2)."
    inputs_schema:
      properties:
        dedup_key: { type: string, description: "The incident dedup_key" }
      required: [dedup_key]
    outputs_schema: { properties: {} }
  - id: resolve_incident
    name: pagerduty-resolve-incident
    description: "Resolve an incident by its dedup_key (Events API v2)."
    inputs_schema:
      properties:
        dedup_key: { type: string, description: "The incident dedup_key" }
      required: [dedup_key]
    outputs_schema: { properties: {} }
  - id: list_incidents
    name: pagerduty-list-incidents
    description: "List incidents (filter by status, urgency, and time window)."
    risk: read
    inputs_schema:
      properties:
        statuses: { type: string, description: "Comma-separated: triggered,acknowledged,resolved" }
        urgencies: { type: string, description: "Comma-separated: high,low" }
        since: { type: string, description: "ISO-8601 start time" }
        until: { type: string, description: "ISO-8601 end time" }
        limit: { type: number, description: "Max incidents (default 25)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_incident
    name: pagerduty-get-incident
    description: "Get a single incident by ID."
    risk: read
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident ID" }
      required: [incident_id]
    outputs_schema: { properties: {} }
  - id: add_note
    name: pagerduty-add-note
    description: "Add a note to an incident (requires from_email in the configuration)."
    inputs_schema:
      properties:
        incident_id: { type: string, description: "Incident ID" }
        note: { type: string, description: "Note content" }
      required: [incident_id, note]
    outputs_schema: { properties: {} }
  - id: list_oncalls
    name: pagerduty-list-oncalls
    description: "List current on-call assignments."
    risk: read
    inputs_schema:
      properties:
        schedule_ids: { type: string, description: "Optional comma-separated schedule IDs to filter" }
        limit: { type: number, description: "Max entries (default 25)" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_users
    name: pagerduty-list-users
    description: "List users (optionally filter by a search query)."
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "Optional name/email search filter" }
        limit: { type: number, description: "Max users (default 25)" }
      required: []
    outputs_schema: { properties: {} }
  - id: list_services
    name: pagerduty-list-services
    description: "List services (optionally filter by a search query)."
    risk: read
    inputs_schema:
      properties:
        query: { type: string, description: "Optional name search filter" }
        limit: { type: number, description: "Max services (default 25)" }
      required: []
    outputs_schema: { properties: {} }

  - id: test_connection
    name: pagerduty-test-connection
    description: "Verify connectivity and the REST API token (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }