Chainitor REST API reference

Manage monitors, alerts, alert channels, saved addresses and API keys over HTTP. The API is on every plan, including the free trial.

OpenAPI 3.1.0 · API version 1.0.0 · Reference updated November 12, 2026. Also available as the OpenAPI specification and the interactive Swagger UI.

Base URL

https://app.chainitor.com/api/v1

Every path below is relative to this URL. Requests and responses are JSON.

Authentication

Send an API key as a bearer token in the Authorization header on every request. API key in format cm_ followed by 64 hex characters. Pass as Authorization: Bearer cm_xxx.

To create a key:

Sign in to the Chainitor app and open API Keys in the sidebar.
Select Create New Key, give the key a name you will recognise, such as "CI pipeline", and select Create Key.
Copy the key from the dialog. It is shown only once; if you lose it, revoke it on the same page and create another.

A key acts within one organization and works while that organization has an active subscription or trial. Check it with GET /auth/me:

curl https://app.chainitor.com/api/v1/auth/me \
  -H "Authorization: Bearer cm_0123…"

Security scheme bearerAuth: HTTP bearer. AI agents can use the MCP server with OAuth instead of an API key.

Errors

Failed requests return an HTTP error status and an Error body with a machine-readable code and a human-readable message.

Response	Meaning
Unauthorized	Authentication required — provide a valid API key or session
Forbidden	Insufficient permissions or subscription required
NotFound	Resource not found
ValidationError	Request validation failed

Auth

Authentication and identity

GET `/auth/me`

Get current identity

Returns the authenticated user's profile. Use this to verify your API key works and check which organization you're scoped to.

Responses

200 Current user identity · MeResponse
401 Authentication required — provide a valid API key or session · Error

Monitors

Blockchain monitors — create, update, execute, and manage monitoring rules

GET `/monitors`

List all monitors for the organization

Returns all monitors in the current organization. Supports filtering by group, chain, status, and type.

Parameters

Name	In	Type	Description
group	query	string	Filter by monitor group name
chain	query	string	Filter by blockchain One of: `ethereum`, `ethereum-sepolia`, `polygon`, `polygon-amoy`, `bsc`, `bsc-testnet`, `arbitrum`, `arbitrum-sepolia`, `optimism`, `optimism-sepolia`, `base`, `base-sepolia`, `robinhood`, `local`.
status	query	string	Filter by enabled/disabled One of: `enabled`, `disabled`.
type	query	string	Filter by monitor type One of: `balance`, `transaction_count`, `erc20_balance`, `event_emitted`, `failed_transaction`, `transaction_value`, `function_call`, `safe_threshold_changed`, `safe_owner_added`, `safe_owner_removed`, `safe_guard_changed`, `safe_module_enabled`, `safe_module_disabled`, `safe_pending_config_change`, `safe_activity`.

Responses

200 List of monitors · data: array of Monitor
401 Authentication required — provide a valid API key or session · Error

POST `/monitors`

Create a new monitor

Creates a new blockchain monitor. The config object shape depends on the type field. Refer to the config schemas for each monitor type. Returns 403 when the monitor limit is reached, or when the monitor type reads every block (function_call, failed_transaction, transaction_value) and the chain is a fast one (Arbitrum, Arbitrum Sepolia, Robinhood), which requires the Pro plan (plans below Pro are refused).

Request body · CreateMonitorRequest

Field	Type	Description
name *	string	Length 1 to 255.
type *	string	One of: `balance`, `transaction_count`, `erc20_balance`, `event_emitted`, `failed_transaction`, `transaction_value`, `function_call`, `safe_threshold_changed`, `safe_owner_added`, `safe_owner_removed`, `safe_guard_changed`, `safe_module_enabled`, `safe_module_disabled`, `safe_pending_config_change`, `safe_activity`.
chain *	string	One of: `ethereum`, `ethereum-sepolia`, `polygon`, `polygon-amoy`, `bsc`, `bsc-testnet`, `arbitrum`, `arbitrum-sepolia`, `optimism`, `optimism-sepolia`, `base`, `base-sepolia`, `robinhood`, `local`.
intervalMinutes *	integer	Range 1 to 1440.
group	string	Length 0 to 100.
config *	object	Shape depends on `type`. See documentation for each monitor type.
channelIds *	array of string (uuid)	At least 1 item.

{
  "name": "ETH Balance Watch",
  "type": "balance",
  "chain": "ethereum",
  "intervalMinutes": 5,
  "config": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "threshold": "1.0",
    "comparisonType": "less_than"
  },
  "channelIds": [
    "uuid-of-channel"
  ]
}

Responses

201 Monitor created · data: Monitor
400 Request validation failed · Error
401 Authentication required — provide a valid API key or session · Error
403 Not allowed: monitor limit reached, or a block-scan monitor type (function_call, failed_transaction, transaction_value) on a plan below Pro (block-scan types are Pro-only on every chain). The message names the monitor type and chain. · Error

GET `/monitors/{id}`

Get a single monitor

Returns a monitor by ID, including its config, channels, and recent alerts.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Monitor details · data: Monitor
404 Resource not found · Error

PATCH `/monitors/{id}`

Update a monitor

Partially updates a monitor. Only included fields are changed.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Request body · UpdateMonitorRequest

Field	Type	Description
name	string	Length 1 to 255.
intervalMinutes	integer	Range 1 to 1440.
config	object
channelIds	array of string (uuid)
group	string, nullable	Length 0 to 100.

{
  "name": "Updated Name",
  "intervalMinutes": 10
}

Responses

200 Updated monitor · data: Monitor
400 Request validation failed · Error
404 Resource not found · Error

DELETE `/monitors/{id}`

Delete a monitor

Permanently deletes a monitor and all its associated alerts and execution history.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Monitor deleted · data: object
404 Resource not found · Error

POST `/monitors/{id}/execute`

Trigger immediate monitor execution

Sends a request to the monitor service to execute this monitor immediately, outside its normal schedule.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Execution result
404 Resource not found · Error

POST `/monitors/{id}/enable`

Enable a monitor

Re-enables a disabled monitor. Its next run is scheduled based on its interval. Safe monitors are rejected with 400 if the organization has no Safe API key or the monitor no longer fits its Safe API quota. Block-scan monitors (function_call, failed_transaction, transaction_value) cannot be re-enabled on plans below Pro and are rejected with 403; monitors that are already enabled are left alone.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Monitor enabled
400 Request validation failed · Error
403 Insufficient permissions or subscription required · Error
404 Resource not found · Error

POST `/monitors/{id}/disable`

Disable a monitor

Disables a monitor so it stops executing on its schedule.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Monitor disabled
404 Resource not found · Error

GET `/monitors/{id}/executions`

Get execution history for a monitor

Returns historical execution data and performance statistics for a monitor.

Parameters

Name	In	Type	Description
id *	path	string (uuid)
days	query	integer	Number of days of history Default `7`.
limit	query	integer	Maximum number of executions Default `100`.

Responses

200 Execution history and stats
404 Resource not found · Error

Alerts

Alerts generated when monitor thresholds are breached

GET `/alerts`

List all alerts for the organization

Returns alerts across all monitors in the organization. Filter by monitor_id to see alerts for a specific monitor, or by type. meta.pagination.stats carries org-wide counts per alert type, independent of the filters.

Parameters

Name	In	Type	Description
monitor_id	query	string (uuid)	Filter by monitor ID
status	query	string	Filter by alert status
type	query	string	Filter by alert type. An unknown value returns 400. `critical`: a breach. `recovery`: the monitor is healthy again; it closes the preceding `critical`. `info` (added October 2026): an event worth knowing that is neither, for example a Safe proposal or signature; it never closes anything. Integrations that switch on `critical`/`recovery` must handle or ignore `info`. One of: `critical`, `recovery`, `info`.
page	query	integer	Page number Default `1`.
limit	query	integer	Items per page Default `50`. Range … to 100.

Responses

200 Paginated list of alerts · data: array of Alert, meta: object

GET `/alerts/{id}`

Get a single alert

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Alert details · data: Alert
404 Resource not found · Error

POST `/alerts/archive`

Bulk archive (delete) alerts

Permanently removes the specified alerts. Only alerts belonging to the current organization are affected.

Request body

Field	Type	Description
ids *	array of string (uuid)

{
  "ids": [
    "uuid-1",
    "uuid-2"
  ]
}

Responses

200 Number of archived alerts

Channels

Notification channels — where alerts are sent (Slack, email, webhook, etc.)

GET `/channels`

List notification channels

Responses

200 List of channels · data: array of Channel

POST `/channels`

Create a notification channel

Creates a new notification channel. The config shape depends on the type field.

Request body · CreateChannelRequest

Field	Type	Description
name *	string	Length 1 to 255.
type *	string	One of: `slack`, `telegram`, `email`, `webhook`, `pagerduty`.
config *	object	Shape depends on `type`.

{
  "name": "Ops Slack",
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/...",
    "channel": "#alerts"
  }
}

Responses

201 Channel created
400 Request validation failed · Error

GET `/channels/{id}`

Get a single channel

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Channel details
404 Resource not found · Error

PATCH `/channels/{id}`

Update a notification channel

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Request body · UpdateChannelRequest

Field	Type	Description
name	string	Length 0 to 255.
config	object

Responses

200 Updated channel
404 Resource not found · Error

DELETE `/channels/{id}`

Delete a notification channel

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Channel deleted
404 Resource not found · Error

POST `/channels/{id}/test`

Send a test notification

Sends a test message through the channel to verify it's configured correctly.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Test notification sent
404 Resource not found · Error

POST `/channels/{id}/set-default`

Set channel as organization default

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Channel set as default
404 Resource not found · Error

Address Book

Saved blockchain addresses for quick reference

GET `/address-book`

List saved addresses

Parameters

Name	In	Type	Description
search	query	string	Search by label or address

Responses

200 List of addresses · data: array of AddressBookEntry

POST `/address-book`

Create an address book entry

Request body · CreateAddressRequest

Field	Type	Description
label *	string
address *	string	Ethereum address (EIP-55)

{
  "label": "Treasury",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"
}

Responses

201 Address created
409 Label already exists

GET `/address-book/{id}`

Get a single address book entry

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Address details
404 Resource not found · Error

PATCH `/address-book/{id}`

Update an address book entry

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Request body · UpdateAddressRequest

Field	Type	Description
label	string
address	string

Responses

200 Updated address
404 Resource not found · Error

DELETE `/address-book/{id}`

Delete an address book entry

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 Address deleted
404 Resource not found · Error

Organization

Organization settings, integrations, and monitor groups

GET `/organization`

Get current organization

Returns the organization the API key is scoped to.

Responses

200 Organization details

GET `/organization/integrations`

Get integration settings

Returns integration configuration (e.g., Safe API key presence). Secrets are never exposed.

Responses

200 Integration settings (redacted)

PATCH `/organization/integrations`

Update integration settings

A Safe API key is checked with Safe before it is saved. A key Safe does not recognise is refused with 400 and not saved. If Safe cannot be reached, the key is saved unverified.

Request body

Responses

200 Updated integration settings
400 Request validation failed · Error

GET `/organization/groups`

List monitor groups

Responses

200 List of group names

POST `/organization/groups`

Create a monitor group

Request body

Field	Type	Description
groupName *	string

Responses

201 Group created
409 Group already exists

DELETE `/organization/groups/{name}`

Delete a monitor group

Parameters

Name	In	Type	Description
name *	path	string

Responses

200 Group deleted
404 Resource not found · Error

API Keys

Manage API keys for programmatic access

GET `/api-keys`

List API keys for the organization

Returns all API keys. The key hash is never returned — only the prefix for identification.

Responses

200 List of API keys · data: array of ApiKey

POST `/api-keys`

Create a new API key

Creates a new API key. The raw key is returned exactly once in the response — store it securely, as it cannot be retrieved later.

Request body · CreateApiKeyRequest

Field	Type	Description
name *	string	Human-readable label, e.g. "CI Pipeline" Length 1 to 100.
expiresAt	string (date-time)	Optional expiration date
scopes	array of string	Future use — currently all keys get full access

{
  "name": "CI Pipeline"
}

Responses

201 API key created — includes the raw key (shown only once) · ApiKeyCreated

PATCH `/api-keys/{id}`

Update an API key name

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Request body

Field	Type	Description
name *	string	Length 0 to 100.

Responses

200 Updated API key
404 Resource not found · Error

DELETE `/api-keys/{id}`

Revoke an API key

Deactivates an API key. Revoked keys immediately stop working.

Parameters

Name	In	Type	Description
id *	path	string (uuid)

Responses

200 API key revoked
404 Resource not found · Error

Schemas

Monitor

Field	Type	Description
id	string (uuid)
name	string
type	string	One of: `balance`, `transaction_count`, `erc20_balance`, `event_emitted`, `failed_transaction`, `transaction_value`, `function_call`, `safe_threshold_changed`, `safe_owner_added`, `safe_owner_removed`, `safe_guard_changed`, `safe_module_enabled`, `safe_module_disabled`, `safe_pending_config_change`, `safe_activity`.
chain	string	One of: `ethereum`, `ethereum-sepolia`, `polygon`, `polygon-amoy`, `bsc`, `bsc-testnet`, `arbitrum`, `arbitrum-sepolia`, `optimism`, `optimism-sepolia`, `base`, `base-sepolia`, `robinhood`, `local`.
intervalMinutes	integer
isEnabled	boolean
config	object	Monitor-type-specific configuration
group	string, nullable
lastStatus	string, nullable
lastBalance	string, nullable
organizationId	string (uuid)
createdAt	string (date-time)
updatedAt	string (date-time)

CreateMonitorRequest

Field	Type	Description
name *	string	Length 1 to 255.
type *	string	One of: `balance`, `transaction_count`, `erc20_balance`, `event_emitted`, `failed_transaction`, `transaction_value`, `function_call`, `safe_threshold_changed`, `safe_owner_added`, `safe_owner_removed`, `safe_guard_changed`, `safe_module_enabled`, `safe_module_disabled`, `safe_pending_config_change`, `safe_activity`.
chain *	string	One of: `ethereum`, `ethereum-sepolia`, `polygon`, `polygon-amoy`, `bsc`, `bsc-testnet`, `arbitrum`, `arbitrum-sepolia`, `optimism`, `optimism-sepolia`, `base`, `base-sepolia`, `robinhood`, `local`.
intervalMinutes *	integer	Range 1 to 1440.
group	string	Length 0 to 100.
config *	object	Shape depends on `type`. See documentation for each monitor type.
channelIds *	array of string (uuid)	At least 1 item.

UpdateMonitorRequest

Field	Type	Description
name	string	Length 1 to 255.
intervalMinutes	integer	Range 1 to 1440.
config	object
channelIds	array of string (uuid)
group	string, nullable	Length 0 to 100.

Alert

Field	Type	Description
id	string (uuid)
monitorId	string (uuid)
type	string	`critical`: a breach. `recovery`: the monitor is healthy again; it closes the preceding `critical`. `info` (added October 2026): an event worth knowing that is neither, for example a Safe proposal or signature; it never closes anything. Integrations that switch on `critical`/`recovery` must handle or ignore `info`. One of: `critical`, `recovery`, `info`.
status	string
message	string
details	object
createdAt	string (date-time)

AlertStats

Org-wide alert counts. total in the pagination block counts every type, including info.

Field	Type	Description
critical	integer
recovery	integer
info	integer
emailsSent	integer

WebhookAlertPayload

Field	Type	Description
alertId *	string
monitorId *	string
monitorName *	string
alertType *	string	`critical`: a breach. `recovery`: the monitor is healthy again; it closes the preceding `critical`. `info` (added October 2026): an event worth knowing that is neither, for example a Safe proposal or signature; it never closes anything. Integrations that switch on `critical`/`recovery` must handle or ignore `info`. One of: `critical`, `recovery`, `info`.
severity *	string	`critical` for critical alerts; `info` for recovery and info alerts. One of: `critical`, `warning`, `info`.
timestamp *	string (date-time)
monitor *	object
results	array of object
metadata *	object

Channel

Field	Type	Description
id	string (uuid)
name	string
type	string	One of: `slack`, `telegram`, `email`, `webhook`, `pagerduty`.
isEnabled	boolean
isVerified	boolean
isDefault	boolean
createdAt	string (date-time)

CreateChannelRequest

Field	Type	Description
name *	string	Length 1 to 255.
type *	string	One of: `slack`, `telegram`, `email`, `webhook`, `pagerduty`.
config *	object	Shape depends on `type`.

UpdateChannelRequest

Field	Type	Description
name	string	Length 0 to 255.
config	object

AddressBookEntry

Field	Type	Description
id	string (uuid)
label	string
address	string
organizationId	string (uuid)
createdAt	string (date-time)
updatedAt	string (date-time)

CreateAddressRequest

Field	Type	Description
label *	string
address *	string	Ethereum address (EIP-55)

UpdateAddressRequest

Field	Type	Description
label	string
address	string

ApiKey

API key metadata. The key hash is never returned.

Field	Type	Description
id	string (uuid)
name	string
keyPrefix	string	First 11 characters for identification
scopes	array of string
lastUsedAt	string (date-time), nullable
expiresAt	string (date-time), nullable
isActive	boolean
createdAt	string (date-time)

ApiKeyCreated

Field	Type	Description
data	object

CreateApiKeyRequest

Field	Type	Description
name *	string	Human-readable label, e.g. "CI Pipeline" Length 1 to 100.
expiresAt	string (date-time)	Optional expiration date
scopes	array of string	Future use — currently all keys get full access

MeResponse

Field	Type	Description
data	object

Pagination

Field	Type	Description
page	integer
limit	integer
total	integer
pages	integer

Error

Field	Type	Description
error	object
meta	object

Chainitor REST API reference

Base URL

Authentication

Errors

Auth

GET /auth/me

Responses

Monitors

GET /monitors

Parameters

Responses

POST /monitors

Request body · CreateMonitorRequest

Responses

GET /monitors/{id}

Parameters

Responses

PATCH /monitors/{id}

Parameters

Request body · UpdateMonitorRequest

Responses

DELETE /monitors/{id}

Parameters

Responses

POST /monitors/{id}/execute

Parameters

Responses

POST /monitors/{id}/enable

Parameters

Responses

POST /monitors/{id}/disable

Parameters

Responses

GET /monitors/{id}/executions

Parameters

Responses

Alerts

GET /alerts

Parameters

Responses

GET /alerts/{id}

Parameters

Responses

POST /alerts/archive

Request body

Responses

Channels

GET /channels

Responses

POST /channels

Request body · CreateChannelRequest

Responses

GET /channels/{id}

Parameters

Responses

PATCH /channels/{id}

Parameters

Request body · UpdateChannelRequest

Responses

DELETE /channels/{id}

Parameters

Responses

POST /channels/{id}/test

Parameters

Responses

POST /channels/{id}/set-default

Parameters

Responses

Address Book

GET /address-book

Parameters

Responses

POST /address-book

Request body · CreateAddressRequest

Responses

GET /address-book/{id}

Parameters

Responses

PATCH /address-book/{id}

Parameters

GET `/auth/me`

GET `/monitors`

POST `/monitors`

GET `/monitors/{id}`

PATCH `/monitors/{id}`

DELETE `/monitors/{id}`

POST `/monitors/{id}/execute`

POST `/monitors/{id}/enable`

POST `/monitors/{id}/disable`

GET `/monitors/{id}/executions`

GET `/alerts`

GET `/alerts/{id}`

POST `/alerts/archive`

GET `/channels`

POST `/channels`

GET `/channels/{id}`

PATCH `/channels/{id}`

DELETE `/channels/{id}`

POST `/channels/{id}/test`

POST `/channels/{id}/set-default`

GET `/address-book`

POST `/address-book`

GET `/address-book/{id}`

PATCH `/address-book/{id}`

DELETE `/address-book/{id}`

GET `/organization`

GET `/organization/integrations`

PATCH `/organization/integrations`

GET `/organization/groups`

POST `/organization/groups`

DELETE `/organization/groups/{name}`

GET `/api-keys`

POST `/api-keys`

PATCH `/api-keys/{id}`

DELETE `/api-keys/{id}`