One of the biggest gaps in mature API programmes is governance that only runs on demand. If your linting rules or compliance checks only execute when someone remembers to run them — or only in your CI pipeline — you have blind spots. APIs get published with violations. Policies change and old APIs fall out of compliance. API Connect v12.1.1 addresses this with scheduled governance scans: the ability to attach a recurring schedule to any governance rule set so checks run automatically, continuously, and without human intervention.

In this article, I’ll explain why scheduled governance scans matter at scale, how to attach a recurring schedule to any governance scan in v12.1.1, the CLI steps to configure them, and best practices for recurring schedules.

Table of Contents

  1. Why Scheduled Governance Scans Matter at Scale
  2. How Scheduled Governance Scans Work in v12.1.1
  3. CLI/API Steps to Configure a Scheduled Scan
  4. Best Practices for Recurring Governance Schedules
  5. Example: Full Governance Scan Schedule Workflow
  6. Monitoring Scheduled Scan Results

Why Scheduled Governance Scans Matter at Scale

When you’re managing a handful of APIs, running governance checks manually or as part of a CI pipeline is manageable. But as your API programme grows, several problems emerge:

The “It Was Clean When It Shipped” Problem

Your CI pipeline checks OpenAPI compliance before deployment. But what happens 6 months later when a governance rule is updated and some of your 200 existing APIs no longer comply? Without scheduled scans, you only find out when an auditor does, or when you run a manual scan.

The “Nobody Remembers to Run It” Problem

Even with good intentions, teams deprioritise manual governance runs. Scheduled scans remove the human dependency entirely.

The “Different Teams, Different Pipelines” Problem

In decentralised API programmes, not all teams use the same CI system — or any CI system at all. Scheduled scans run against your API Connect registry directly, regardless of how the API was published or by whom.

Compliance and Audit Requirements

Many regulatory frameworks (financial services, healthcare, government) require evidence of ongoing compliance, not just point-in-time compliance. Scheduled scans generate the audit trail you need.

How Scheduled Governance Scans Work in v12.1.1

In API Connect v12.1.1, governance rule sets can have a schedule attached. When a schedule fires, the governance scan runs against all APIs (or a targeted subset) in the specified scope — catalog, space, or provider organisation.

Results are:

  • Stored in the governance history
  • Available in the API Manager UI
  • Emitted as events (which can trigger alerts)
  • Available via the REST API

You can schedule scans at multiple levels:

  • Organisation level: All products across all catalogs in a provider org
  • Catalog level: All products in a specific catalog
  • Space level: All products in a specific space

CLI/API Steps to Configure a Scheduled Scan

Prerequisites

  • API Connect v12.1.1.0 or later
  • apic CLI installed and authenticated
  • Governance rule sets already created (if you need to create one, see the IBM docs)

Step 1: List Available Governance Rule Sets

# Connect to your management server
apic --server ${MANAGEMENT_SERVER} --org ${PROVIDER_ORG} \
  governance-rulesets:list --catalog ${CATALOG_NAME}

# Example output:
# NAME                    ID                               SCOPE
# api-security-rules       abc123-ruleset-uuid             catalog
# naming-conventions       def456-ruleset-uuid             catalog
# openapi-best-practices   ghi789-ruleset-uuid            catalog

Step 2: Create a Schedule for a Governance Ruleset

apic governance-rulesets:schedules:create \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID} \
  --cron "0 2 * * *" \
  --timezone "Europe/London" \
  --scope catalog \
  --enabled true

This creates a schedule that runs the governance scan at 02:00 UTC every day. The --cron expression uses standard cron syntax.

Step 3: Verify the Schedule Was Created

apic governance-rulesets:schedules:get \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID} \
  --schedule ${SCHEDULE_ID}

Step 4: Run an On-Demand Scan to Test

Before relying on the schedule, verify the ruleset is working:

apic governance-rulesets:run \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID}

Step 5: Review Scan Results

apic governance-rulesets:results:list \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID} \
  --format json

Via the REST API

If you’re integrating with an external scheduling system or building a custom UI:

# Create a schedule via REST API
curl -X POST \
  "https://${MANAGEMENT_SERVER}/api/orgs/${ORG_ID}/governance-schedules" \
  -H "accept: application/json" \
  -H "authorization: Bearer ${TOKEN}" \
  -H "content-type: application/json" \
  -d '{
    "ruleset_id": "abc123-ruleset-uuid",
    "cron_expression": "0 2 * * *",
    "timezone": "Europe/London",
    "enabled": true,
    "scope": {
      "type": "catalog",
      "id": "${CATALOG_ID}"
    },
    "notification": {
      "on_failure": true,
      "webhook_url": "https://your-alerting-system.example.com/webhook"
    }
  }'

Best Practices for Recurring Governance Schedules

1. Start with a Lightweight Schedule

Don’t schedule every ruleset to run every hour on day one. Start with daily scans, observe the results and alert volume, then adjust.

2. Separate Critical and Advisory Rules

Configure schedules differently for different rule severities:

  • Critical rules (security, compliance): Run daily or more frequently
  • Advisory rules (naming conventions, documentation): Run weekly

3. Use Non-Peak Hours

Schedule governance scans during low-traffic periods — typically early morning UTC (02:00-04:00) or late evening. Governance scans read API metadata, not traffic, so they have minimal performance impact, but you want to avoid contention with other administrative operations.

4. Set Up Alerting on Scan Failures

Configure webhook notifications so that failed scans (e.g., a ruleset that crashes mid-run) trigger alerts:

apic governance-rulesets:schedules:update \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID} \
  --schedule ${SCHEDULE_ID} \
  --notification-on-failure true \
  --webhook-url "https://hooks.example.com/governance-failure"

Don’t just fix violations and forget them. Use the governance history to track:

  • Which APIs are repeat violators
  • Whether overall violation rates are decreasing
  • Whether new governance rules are causing unexpected failures

6. Scope Schedules Appropriately

Don’t run org-wide scans if you only need catalog-level checks. Smaller scopes run faster and produce more actionable results.

7. Document Your Governance Schedule Policy

Create a runbook that documents:

  • Which rulesets run on which schedule and why
  • Who receives governance failure notifications
  • What constitutes a governance violation that requires immediate action vs. one that can be scheduled for remediation

Example: Full Governance Scan Schedule Workflow

Here’s a complete example combining everything:

#!/usr/bin/env bash
# Full governance schedule setup for a production catalog

MANAGEMENT_SERVER="mgmt-api.example.com"
PROVIDER_ORG="payments-provider"
CATALOG="production"
RULESET_ID="api-security-rules-v2"

# 1. Create daily security scan at 02:00 UTC
SCHEDULE_ID=$(apic governance-rulesets:schedules:create \
  --server $MANAGEMENT_SERVER \
  --org $PROVIDER_ORG \
  --catalog $CATALOG \
  --ruleset $RULESET_ID \
  --cron "0 2 * * *" \
  --timezone "UTC" \
  --scope catalog \
  --enabled true \
  --output - \
  --fields id \
  --format json | jq -r '.[].id')

echo "Created schedule: $SCHEDULE_ID"

# 2. Enable failure notifications to your Slack webhook
apic governance-rulesets:schedules:update \
  --server $MANAGEMENT_SERVER \
  --org $PROVIDER_ORG \
  --catalog $CATALOG \
  --ruleset $RULESET_ID \
  --schedule $SCHEDULE_ID \
  --notification-on-failure true \
  --webhook-url "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# 3. Run immediately to verify
echo "Running on-demand scan to verify ruleset..."
apic governance-rulesets:run \
  --server $MANAGEMENT_SERVER \
  --org $PROVIDER_ORG \
  --catalog $CATALOG \
  --ruleset $RULESET_ID

echo "Done. Check results with:"
echo "apic governance-rulesets:results:list --server $MANAGEMENT_SERVER --org $PROVIDER_ORG --catalog $CATALOG --ruleset $RULESET_ID"

Monitoring Scheduled Scan Results

To monitor results programmatically:

# Get the latest scan result for a ruleset
apic governance-rulesets:results:list \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG_NAME} \
  --ruleset ${RULESET_ID} \
  --limit 1 \
  --format json | jq '.[0]'

This returns the most recent scan result including:

  • Timestamp
  • Number of violations found (by severity)
  • List of violated rules with affected APIs

Summary

Scheduled governance scans in API Connect v12.1.1 are a game-changer for API programmes that need ongoing compliance assurance, not just point-in-time checks. By attaching schedules to your existing governance rule sets, you can ensure that new violations are caught automatically — regardless of how or when an API was published — and that your governance programme actually scales as your API portfolio grows.

Set up your first scheduled scan this week. Start small, monitor results, and iterate.

Screenshots to Capture

  1. [Placeholder: /images/governance-ruleset-schedule-config.png] What to capture: The schedule creation dialog for a governance ruleset showing cron expression input, timezone selector, scope selection, and enabled toggle. Where: API Manager → Governance → Rulesets → Select a ruleset → Schedules tab → New Schedule

  2. [Placeholder: /images/governance-scan-results-ui.png] What to capture: The governance scan results view showing violations grouped by severity (error, warning, info) with affected API names and rule descriptions. Where: API Manager → Governance → [Run a scan] → Results tab

  3. [Placeholder: /images/governance-scan-history.png] What to capture: The governance history view showing past scan runs with timestamps, violation counts, and pass/fail status for each ruleset over time. Where: API Manager → Governance → History or scan results → History tab

  4. [Placeholder: /images/governance-webhook-notification-config.png] What to capture: The webhook notification configuration for governance scan failures, showing the webhook URL field and notification triggers. Where: API Manager → Governance → Rulesets → Select ruleset → Schedules → Notification settings

Questions about governance as code or scheduled scans? Reach out on Twitter @cminion or open a discussion on GitHub.