Infra

The Infra endpoints of the Kenso API.

Deliverability3 endpointsKen-Version: 2026-11-02Authentication Workspaces Errors

Count the workspace's open infra findings

GET/v1/infra/summaryinfra.summary

Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

openCount and bySeverity count open findings; snoozedCount the snoozed ones. byKind lists each kind with open findings, with what its subjects cost a month where Kenso knows the price, and monthlyCostAtStake sums it. Money is { amount (cents), currency: "usd" }. Needs Delivery view and the infra_findings flag.

Parameters

Name

Type

Required

Description

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

The API version: a dated version (YYYY-MM-DD), or 1.1, another name for the first dated version. Without it the request uses your API key's pinned version; an unpinned key reaches the legacy shape of the same path. 1.0 selects the legacy shape explicitly.

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a InfraSummaryModel.

Field

Type

Description

openCount

integer (int32)

snoozedCount

integer (int32)

bySeverity

InfraSeverityCountsModel

byKind

array of InfraKindSummaryModel

monthlyCostAtStake

MoneyModel

lastSweep

InfraSweepModel

Request

curl -X GET "https://api.ken.so/v1/infra/summary" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": {
    "openCount": 1,
    "snoozedCount": 1,
    "bySeverity": {
      "critical": 1,
      "warning": 1,
      "info": 1
    },
    "byKind": [
      {
        "kind": "string",
        "openCount": 1,
        "critical": 1,
        "warning": 1,
        "info": 1,
        "monthlyCost": {
          "amount": 1,
          "currency": "string"
        }
      }
    ],
    "monthlyCostAtStake": {
      "amount": 1,
      "currency": "string"
    },
    "lastSweep": {
      "sweepId": 812,
      "trigger": "string",
      "status": "string",
      "startedAt": "2026-09-23T15:02:11Z",
      "finishedAt": "2026-09-23T15:02:11Z",
      "detectors": [
        {
          "kind": "string",
          "subjectType": "string",
          "outcome": "string",
          "found": 1,
          "opened": 1,
          "resolved": 1,
          "error": "string"
        }
      ],
      "error": "string"
    }
  }
}

List the workspace's infra findings, newest first

GET/v1/infra/findingsinfra.findings

Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

kind: billing_leak, provider_cancelled, warmup_missing, idle_domain, domain_expiring, inbox_no_domain, disconnected_inbox. status: open (the default), snoozed, ignored, resolved. severity: critical, warning, info. Each filter is comma-separated and its values OR together. evidence holds what the detector saw; suggestedAction names the fix. Needs Delivery view and the infra_findings flag.

Parameters

Name

Type

Required

Description

Kind

In: query

string

optional

Finding kinds, for example billing_leak,idle_domain.

Status

In: query

string

optional

open (the default), snoozed, ignored, resolved.

Severity

In: query

string

optional

critical, warning, info.

Cursor

In: query

string

optional

Limit

In: query

integer (int32)

optional

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Response 200

data is a list of InfraFindingModel. Each item has these fields. The response also carries pagination.

Field

Type

Description

integer (int64)

workspaceId

integer (int64)

Absent on the staff-only findings that belong to no workspace (renewal_shortfall, registrar_orphan).

workspaceName

string

Staff lists only.

kind

string

billing_leak, provider_cancelled, warmup_missing, idle_domain, domain_expiring, inbox_no_domain, disconnected_inbox, renewal_shortfall, registrar_orphan.

subjectType

string

inbox, domain, provider_account, registrar_domain.

subjectId

integer (int64)

The inbox or domain id; absent for a provider account or a registrar domain Kenso has no row for.

subjectKey

string

The finding's stable key, for example inbox:123 or registrar_domain:porkbun:example.com.

provider

string

inboxkit, porkbun, ken.

severity

string

critical, warning, info.

status

string

open, snoozed, ignored, resolved.

title

string

evidence

object

What the detector saw; its keys depend on the kind.

suggestedAction

string

monthlyCost

MoneyModel

firstSeenAt

string (date-time)

lastSeenAt

string (date-time)

resolvedAt

string (date-time)

snoozedUntil

string (date-time)

Request

curl -X GET "https://api.ken.so/v1/infra/findings" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 812,
      "workspaceId": 812,
      "workspaceName": "string",
      "kind": "string",
      "subjectType": "string",
      "subjectId": 812,
      "subjectKey": "string",
      "provider": "string",
      "severity": "string",
      "status": "string",
      "title": "string",
      "evidence": null,
      "suggestedAction": "string",
      "monthlyCost": {
        "amount": 1,
        "currency": "string"
      },
      "firstSeenAt": "2026-09-23T15:02:11Z",
      "lastSeenAt": "2026-09-23T15:02:11Z",
      "resolvedAt": "2026-09-23T15:02:11Z",
      "snoozedUntil": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}

Snooze, ignore or reopen one of the workspace's infra findings

PATCH/v1/infra/findings/{findingId}infra.update-finding

Needs the infra_findings feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Body: status is snoozed (with snoozedUntil, ISO 8601 UTC, in the future and at most a year ahead), ignored or open (reopen). A snoozed finding opens again on the first sweep after snoozedUntil; an ignored one stays ignored until reopened, and the sweep never resolves it. A resolved finding refuses (409 invalid_state); another workspace's finding is 404. A billing_leak cannot be snoozed or ignored here (403): Kenso pays it and fixes it, and only Kenso staff change it. Records who changed it and an audit line in the workspace; changes nothing at a provider. Returns the finding. Needs Delivery edit and the infra_findings flag.

Parameters

Name

Type

Required

Description

findingId

In: path

integer (int64)

required

Ken-Version

In: header

string, one of: 2026-11-02, 1.1

required

X-Ken-Workspace-Id

In: header

integer (int64)

optional

Workspace to act in. Required when your credential can reach more than one workspace (otherwise 400 workspace_required).

Request body

application/json, optional.

Field

Type

Required

Description

status

string

optional

open (reopen), snoozed or ignored. Required.

snoozedUntil

string (date-time)

optional

When a snoozed finding opens again (ISO 8601 UTC), in the future and at most a year ahead. Required with snoozed, refused with the other statuses.

Response 200

data is a InfraFindingModel.

Field

Type

Description

integer (int64)

workspaceId

integer (int64)

Absent on the staff-only findings that belong to no workspace (renewal_shortfall, registrar_orphan).

workspaceName

string

Staff lists only.

kind

string

billing_leak, provider_cancelled, warmup_missing, idle_domain, domain_expiring, inbox_no_domain, disconnected_inbox, renewal_shortfall, registrar_orphan.

subjectType

string

inbox, domain, provider_account, registrar_domain.

subjectId

integer (int64)

The inbox or domain id; absent for a provider account or a registrar domain Kenso has no row for.

subjectKey

string

The finding's stable key, for example inbox:123 or registrar_domain:porkbun:example.com.

provider

string

inboxkit, porkbun, ken.

severity

string

critical, warning, info.

status

string

open, snoozed, ignored, resolved.

title

string

evidence

object

What the detector saw; its keys depend on the kind.

suggestedAction

string

monthlyCost

MoneyModel

firstSeenAt

string (date-time)

lastSeenAt

string (date-time)

resolvedAt

string (date-time)

snoozedUntil

string (date-time)

Request

curl -X PATCH "https://api.ken.so/v1/infra/findings/812" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "string",
  "snoozedUntil": "2026-09-23T15:02:11Z"
}'

Response 200

{
  "success": true,
  "data": {
    "id": 812,
    "workspaceId": 812,
    "workspaceName": "string",
    "kind": "string",
    "subjectType": "string",
    "subjectId": 812,
    "subjectKey": "string",
    "provider": "string",
    "severity": "string",
    "status": "string",
    "title": "string",
    "evidence": null,
    "suggestedAction": "string",
    "monthlyCost": {
      "amount": 1,
      "currency": "string"
    },
    "firstSeenAt": "2026-09-23T15:02:11Z",
    "lastSeenAt": "2026-09-23T15:02:11Z",
    "resolvedAt": "2026-09-23T15:02:11Z",
    "snoozedUntil": "2026-09-23T15:02:11Z"
  }
}

More in Deliverability:Inboxes Inbox imports LinkedIn accounts Domains Domain health checks Outbound site Placement tests Sending capacity All resources