Alerts API

Manage alerts and notification preferences.

List Alerts

curl "https://conto.finance/api/alerts?status=ACTIVE" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Results per page
`offset`	number	0	Pagination offset
`status`	string	all	`ACTIVE`, `ACKNOWLEDGED`, `RESOLVED`
`severity`	string	all	`INFO`, `WARNING`, `CRITICAL`
`type`	string	all	Alert type filter
`agentId`	string	-	Filter by agent

Response

{
  "alerts": [
    {
      "id": "alert_abc123",
      "type": "SPEND_LIMIT_WARNING",
      "severity": "WARNING",
      "status": "ACTIVE",
      "title": "Daily spend limit approaching",
      "message": "Agent 'Support Agent' has used 85% of daily limit",
      "agent": {
        "id": "agt_xyz789",
        "name": "Support Agent"
      },
      "metadata": {
        "currentSpend": 850,
        "limit": 1000,
        "percentage": 85
      },
      "createdAt": "2024-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Alert

curl https://conto.finance/api/alerts/{alertId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "id": "alert_abc123",
  "type": "SPEND_LIMIT_WARNING",
  "severity": "WARNING",
  "status": "ACTIVE",
  "title": "Daily spend limit approaching",
  "message": "Agent 'Support Agent' has used 85% of daily limit ($850 of $1000)",
  "agent": {
    "id": "agt_xyz789",
    "name": "Support Agent"
  },
  "wallet": {
    "id": "wal_abc123",
    "name": "Operations Wallet"
  },
  "metadata": {
    "currentSpend": 850,
    "limit": 1000,
    "percentage": 85,
    "remainingBudget": 150
  },
  "acknowledgedAt": null,
  "acknowledgedBy": null,
  "resolvedAt": null,
  "createdAt": "2024-01-15T14:30:00Z"
}

Alert Types

Type	Severity	Description
`SPEND_LIMIT_WARNING`	WARNING	Approaching spend limit (80%+)
`SPEND_LIMIT_EXCEEDED`	CRITICAL	Spend limit exceeded
`UNUSUAL_ACTIVITY`	WARNING	Anomalous spending pattern
`FAILED_TRANSACTION`	WARNING	Transaction failed
`POLICY_VIOLATION`	WARNING	Payment denied by policy
`NEW_COUNTERPARTY`	INFO	First payment to new address
`HIGH_VALUE_TRANSACTION`	INFO	Large transaction completed
`AGENT_SUSPENDED`	CRITICAL	Agent automatically suspended
`WALLET_LOW_BALANCE`	WARNING	Wallet balance running low
`BLOCKED_ADDRESS`	CRITICAL	Payment to blocked address attempted

Acknowledge Alert

Mark an alert as acknowledged.

curl -X POST https://conto.finance/api/alerts/{alertId}/acknowledge \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{"notes": "Investigating the issue"}'

Response

{
  "id": "alert_abc123",
  "status": "ACKNOWLEDGED",
  "acknowledgedAt": "2024-01-15T14:35:00Z",
  "acknowledgedBy": {
    "id": "user_xyz",
    "name": "John Doe"
  }
}

Resolve Alert

Mark an alert as resolved.

curl -X POST https://conto.finance/api/alerts/{alertId}/resolve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{"resolution": "Increased daily limit for agent"}'

Response

{
  "id": "alert_abc123",
  "status": "RESOLVED",
  "resolvedAt": "2024-01-15T15:00:00Z",
  "resolution": "Increased daily limit for agent"
}

Bulk Actions

Acknowledge Multiple

curl -X POST https://conto.finance/api/alerts/bulk/acknowledge \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertIds": ["alert_abc123", "alert_def456"],
    "notes": "Bulk acknowledgment"
  }'

Resolve Multiple

curl -X POST https://conto.finance/api/alerts/bulk/resolve \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertIds": ["alert_abc123", "alert_def456"],
    "resolution": "Issue resolved"
  }'

Alert Statistics

Get alert statistics for your organization.

curl "https://conto.finance/api/alerts/stats?period=7d" \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "period": "7d",
  "summary": {
    "total": 45,
    "active": 5,
    "acknowledged": 10,
    "resolved": 30
  },
  "bySeverity": {
    "INFO": 20,
    "WARNING": 20,
    "CRITICAL": 5
  },
  "byType": {
    "SPEND_LIMIT_WARNING": 15,
    "POLICY_VIOLATION": 10,
    "NEW_COUNTERPARTY": 12,
    "FAILED_TRANSACTION": 8
  },
  "trend": [
    { "date": "2024-01-09", "count": 5 },
    { "date": "2024-01-10", "count": 8 },
    { "date": "2024-01-11", "count": 6 }
  ]
}

Notification Preferences

Get Preferences

curl https://conto.finance/api/alerts/preferences \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "email": {
    "enabled": true,
    "address": "alerts@company.com",
    "severities": ["WARNING", "CRITICAL"],
    "types": ["SPEND_LIMIT_EXCEEDED", "AGENT_SUSPENDED", "BLOCKED_ADDRESS"]
  },
  "webhook": {
    "enabled": true,
    "url": "https://api.company.com/webhooks/conto",
    "secret": "whsec_***",
    "severities": ["WARNING", "CRITICAL"],
    "types": ["all"]
  },
  "slack": {
    "enabled": false,
    "channel": null
  }
}

Update Preferences

curl -X PUT https://conto.finance/api/alerts/preferences \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "enabled": true,
      "address": "alerts@company.com",
      "severities": ["CRITICAL"],
      "types": ["SPEND_LIMIT_EXCEEDED", "AGENT_SUSPENDED"]
    },
    "webhook": {
      "enabled": true,
      "url": "https://api.company.com/webhooks/conto",
      "severities": ["WARNING", "CRITICAL"]
    }
  }'

Webhooks

When webhooks are enabled, alerts are sent as HTTP POST requests.

Webhook Payload

{
  "event": "alert.created",
  "timestamp": "2024-01-15T14:30:00Z",
  "alert": {
    "id": "alert_abc123",
    "type": "SPEND_LIMIT_WARNING",
    "severity": "WARNING",
    "title": "Daily spend limit approaching",
    "message": "Agent 'Support Agent' has used 85% of daily limit",
    "metadata": {
      "currentSpend": 850,
      "limit": 1000
    }
  }
}

Webhook Signature

Verify webhook authenticity using the signature header:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Webhook Events

Event	Description
`alert.created`	New alert generated
`alert.acknowledged`	Alert acknowledged
`alert.resolved`	Alert resolved

Error Responses

Status	Code	Description
400	`INVALID_INPUT`	Invalid request data
401	`AUTH_FAILED`	Authentication failed
403	`INSUFFICIENT_SCOPE`	Missing required scope
404	`NOT_FOUND`	Alert not found
409	`ALREADY_RESOLVED`	Alert already resolved

API Reference

​Alerts API

​List Alerts

​Query Parameters

​Response

​Get Alert

​Response

​Alert Types

​Acknowledge Alert

​Response

​Resolve Alert

​Response

​Bulk Actions

​Acknowledge Multiple

​Resolve Multiple

​Alert Statistics

​Response

​Notification Preferences

​Get Preferences

​Response

​Update Preferences

​Webhooks

​Webhook Payload

​Webhook Signature

​Webhook Events

​Error Responses

Alerts API

List Alerts

Query Parameters

Response

Get Alert

Response

Alert Types

Acknowledge Alert

Response

Resolve Alert

Response

Bulk Actions

Acknowledge Multiple

Resolve Multiple

Alert Statistics

Response

Notification Preferences

Get Preferences

Response

Update Preferences

Webhooks

Webhook Payload

Webhook Signature

Webhook Events

Error Responses