Netonica API

Add, change and read your monitors from a script or a pipeline. This page reads from the same OpenAPI spec the API serves.

OpenAPI spec

DocsAPI

Authentication

For authenticated requests, send this header:

Authorization: Bearer <key>

Create an API key on your workspace page. It acts as its creator within that workspace. Public requests need no key.

Quick start

Add a monitor:

curl -X POST https://netonica.com/api/v1/monitors \
  -H 'Authorization: Bearer <key>' \
  -H 'Content-Type: application/json' \
  -d '{"target":{"kind":"agent-card","fields":{"url":"example.com"}},"schedule":"0 * * * *"}'

The request returns 202 immediately. Changes take effect when the monitor process applies them. Poll the command to check its status:

curl -X GET https://netonica.com/api/v1/commands/{id} \
  -H 'Authorization: Bearer <key>'

Then read your monitors:

curl -X GET https://netonica.com/api/v1/monitors \
  -H 'Authorization: Bearer <key>'

Rate limits

Per key: 1200 requests in a 60-second window. This shared budget equals 6 requests × 200 monitors, the largest plan's capacity. That covers one add, about four polls a second apart and one read per monitor. Polls count toward the same budget.

Per key: up to 2 concurrent requests. Workspace write concurrency limit: 1, for any request that adds, removes, resumes or reschedules a monitor.

Exceeding the request or per-key concurrency limit returns 429 (rate_limited). Exceeding workspace write concurrency returns 429 (write_in_flight). Both responses include Retry-After.

Errors

Errors use application/problem+json and the Error schema. Match errors using code.

Response fields and error codes may be added. Ignore unknown fields. Use the HTTP status for unknown error codes.

API reference

GET /api/v1/commands/{id}

Read what became of a change

A command reads pending until it is durably saved. One with no outcome left reads refused: not_saved, so send it again, within 60 minutes of sending, and too_old after, when what became of it is unknown and the change may have applied. An id that names no time answers 404 command_not_found, as does one with a time ahead that was never saved; while that cannot yet be told, it reads pending.

Parameters

id
string in path required
The command id a change answered with.

Response 200: Command
Error responses: 401, 404, 422, 429, 500, 503

GET /api/v1/meta

Name the build that answers

Public endpoint. No API key required.

Response 200: Meta

GET /api/v1/monitors

List the workspace's monitors

Response 200: MonitorList
Error responses: 401, 429, 500, 503

POST /api/v1/monitors

Add a monitor

It answers at once; the monitor process applies it, and its command says what became of it. Adding a monitor the workspace already has leaves it as it was.

Request body: NewMonitor
Response 202: Added
Error responses: 400, 401, 403, 422, 429, 500, 503

DELETE /api/v1/monitors/{id}

Remove a monitor

It answers at once; the monitor process applies it, and its command says what became of it. Its history stays.

Parameters

id
string in path required
The monitor's id, as the list names it.

Response 202: Sent
Error responses: 401, 404, 422, 429, 500, 503

GET /api/v1/monitors/{id}

Read one monitor

Parameters

id
string in path required
The monitor's id, as the list names it.

Response 200: Monitor
Error responses: 401, 404, 422, 429, 500, 503

PATCH /api/v1/monitors/{id}

Change how a monitor runs

It answers at once; the monitor process applies it, and its command says what became of it.

Parameters

id
string in path required
The monitor's id, as the list names it.

Request body: MonitorEdit
Response 202: Sent
Error responses: 400, 401, 403, 404, 422, 429, 500, 503

GET /api/v1/monitors/{id}/alerts

Read where a monitor's alerts go

Parameters

id
string in path required
The monitor's id, as the list names it.

Response 200: Alerts
Error responses: 401, 404, 422, 429, 500, 503

PUT /api/v1/monitors/{id}/alerts

Choose where a monitor's alerts go

It saves at once.

Parameters

id
string in path required
The monitor's id, as the list names it.

Request body: Alerts
Response 200: Alerts
Error responses: 401, 404, 422, 429, 500, 503

GET /api/v1/monitors/{id}/assessment

Read a monitor's latest assessment

Parameters

id
string in path required
The monitor's id, as the list names it.

Response 200: Assessment
Error responses: 401, 404, 422, 429, 500, 503

GET /api/v1/monitors/{id}/history

Read a monitor's change history

Parameters

id
string in path required
The monitor's id, as the list names it.
limit
integer, int64 in query
How many changes to answer, from 1 to 200.
Default 50

Response 200: History
Error responses: 401, 404, 422, 429, 500, 503

POST /api/v1/monitors/{id}/history/{change}/ack

Acknowledge a waiting change

It answers at once; the monitor process applies it, and its command says what became of it. It acknowledges every older change too; newer ones keep waiting.

Parameters

id
string in path required
The monitor's id, as the list names it.
change
string in path required
The change's id, as the history names it.

Response 202: Sent
Error responses: 401, 404, 409, 422, 429, 500, 503

PUT /api/v1/monitors/{id}/pins/{assertion}

Pin the value an assertion holds to

It answers at once; the monitor process applies it, and its command says what became of it. It ticks the assertion and pins the value the named reading shows.

Parameters

id
string in path required
The monitor's id, as the list names it.
assertion
string in path required
The assertion's id, as the assessment names it.

Request body: Pin
Response 202: Sent
Error responses: 400, 401, 404, 409, 422, 429, 500, 503

DELETE /api/v1/monitors/{id}/ticks/{assertion}

Stop alerting on an assertion

It answers at once; the monitor process applies it, and its command says what became of it. A retired assertion unticks too.

Parameters

id
string in path required
The monitor's id, as the list names it.
assertion
string in path required
The assertion's id, as the assessment names it.

Response 202: Sent
Error responses: 401, 404, 422, 429, 500, 503

PUT /api/v1/monitors/{id}/ticks/{assertion}

Alert when an assertion fails or recovers

It answers at once; the monitor process applies it, and its command says what became of it. A tier unticks the others of its family.

Parameters

id
string in path required
The monitor's id, as the list names it.
assertion
string in path required
The assertion's id, as the assessment names it.

Response 202: Sent
Error responses: 400, 401, 404, 422, 429, 500, 503

Targets

What a monitor watches: kind picks the check, and fields are what that check asks for. Each kind's x-assertions lists what it can offer; a given target may offer fewer.

agent-card

Fields

url
string required
Card URL or domain
Example: example.com

Assertions

card-served
Card present
Selected by default
card-valid
Required card fields present
Selected by default
endpoints-stay
Endpoint URLs and bindings unchanged
Selected by default
auth-schemes-stay
Authentication schemes unchanged
Selected by default
skill-descriptions
Skill wording unchanged
Selected by default
no-new-skills
No new skills
Selected by default
endpoints-https
Endpoints use HTTPS
Selected by default
current-path
Card found via /.well-known/agent-card.json
Selected by default
no-skills-removed
No skills removed
endpoints-on-domain
Endpoints on target domain
auth-declared
Authentication requirements present
card-signed
Card signature present
provider-stays
Provider unchanged
protocol-0-3
Protocol at least 0.3
Mutually exclusive group: protocol
protocol-1-0
Protocol at least 1.0
Mutually exclusive group: protocol

dns

Fields

name
string required
Name
Example: example.com
type
string
Record type
One of a aaaa caa cname mx ns srv txt spf dmarc dns-persist-01
Default a

Assertions

name-exists
Name exists
Selected by default
has-records
DNS answer present
Selected by default
records-stay
DNS answer unchanged
Selected by default
alias-resolves
No dangling alias
Selected by default
spf-present
SPF present
Selected by default
spf-no-duplicate
No duplicate SPF record
Selected by default
spf-lookups-within-limit
Within 10 DNS lookups
Selected by default
spf-voids-within-limit
At most 2 void lookups
Selected by default
spf-includes-resolve
Includes resolve
Selected by default
spf-record-valid
SPF record valid
Selected by default
spf-not-open
Not open to all senders
Selected by default
spf-ends-in-fail
Ends in fail or softfail
spf-no-ptr
No ptr mechanism
dmarc-present
DMARC present
Selected by default
dmarc-enforces
DMARC set to quarantine or reject
Selected by default
dmarc-reports-requested
DMARC reports requested
dmarc-not-testing
DMARC not in testing mode
dmarc-subdomains-strict
DMARC subdomains as strict as the domain
dmarc-known-tags
Only known DMARC tags
caa-limits-issuers
CAA limits issuers
Selected by default
persist-absent
No persistent authorization
Selected by default
persist-present
Persistent authorization present
persist-no-wildcard
No wildcard authorization
Selected by default
not-expired
Not expired
Selected by default
over-7-days
Expires in more than 7 days
Mutually exclusive group: expiry
over-14-days
Expires in more than 14 days
Mutually exclusive group: expiry
over-30-days
Expires in more than 30 days
Selected by default
Mutually exclusive group: expiry
over-90-days
Expires in more than 90 days
Mutually exclusive group: expiry

headers

Fields

url
string required
Page URL
Example: https://example.com/

Assertions

answers-directly
HTTP 200 from target site
Selected by default
hsts-on
HSTS enabled
Selected by default
csp-present
CSP present
Selected by default
no-new-script-sources
No new script sources
Selected by default
framing-blocked
Framing restricted
Selected by default
nosniff-set
Nosniff enabled
Selected by default

mcp

Fields

endpoint
string required
Endpoint
Example: https://example.com/mcp

Assertions

auth-required
Authentication required
Selected by default
auth-servers
Authorization servers unchanged
Selected by default
connector-ready
Connector ready
registration-current
Client registration not deprecated
issuer-in-response
Issuer identification advertised
tool-descriptions
Tool wording unchanged
Selected by default
no-new-tools
No new tools
Selected by default

pqc

Fields

endpoint
string required
Domain
Example: example.com or example.com:8443

Assertions

tls-1-3
Supports TLS 1.3
Selected by default
pq-key-exchange
Supports post-quantum key exchange
Selected by default
prefers-pq
Prefers post-quantum key exchange
Selected by default

securitytxt

Fields

site
string required
Site
Example: https://example.com

Assertions

file-present
File present
Selected by default
not-expired
Not expired
Selected by default
over-7-days
Expires in more than 7 days
Mutually exclusive group: expiry
over-14-days
Expires in more than 14 days
Mutually exclusive group: expiry
over-30-days
Expires in more than 30 days
Selected by default
Mutually exclusive group: expiry
over-90-days
Expires in more than 90 days
Mutually exclusive group: expiry
no-new-contacts
No new contacts
Selected by default
well-formed
Well-formed
Selected by default
canonical-lists-url
Canonical matches URL when present
stays-signed
PGP signature present
served-here
Served by this site

tls

Fields

endpoint
string required
Domain
Example: example.com or example.com:8443

Assertions

trusted
Certificate trusted
Selected by default
not-expired
Not expired
Selected by default
over-7-days
Expires in more than 7 days
Mutually exclusive group: expiry
over-14-days
Expires in more than 14 days
Selected by default
Mutually exclusive group: expiry
over-30-days
Expires in more than 30 days
Mutually exclusive group: expiry
min-tls-1-2
No TLS below 1.2
Selected by default
tls-1-3
Supports TLS 1.3
Selected by default
issuer-stays
Issuing CA unchanged
Selected by default
covers-names
No pinned names removed
Selected by default

x402

Fields

url
string required
Resource URL
Example: https://api.example.com/summarise

Assertions

payment-required
Payment required
Selected by default
quote-readable
Payment quote present
Selected by default
pay-to
Payment address unchanged
Selected by default
token
Payment token unchanged
Selected by default
signing-domain
Additional payment details unchanged
Selected by default
cache-guarded
Cache protection headers present
Selected by default

Schemas

Optional request fields set to null are treated as omitted.

Added

command_id
string required
Read it at /commands/{id} to learn what became of the change. That call says how long it keeps it.
existing
Settings
Present when the workspace already had this monitor: the add leaves it as it was, and these are its settings.
monitor_id
string required
The monitor the change names.

Alerts

email
boolean required
Every member gets a message.
slack
boolean required
One line to the workspace's Slack channel.
webhook
boolean required
A JSON POST to the workspace URL.

Assertion

id
string required
Names the assertion. A published id never changes.
label
string required
The check's words for it.

AssertionResult

id
string required
Names the assertion. A published id never changes.
label
string required
The check's words for it.
result
string
How the reading judges it. Unknown means the scan did not see what it reads. Absent when there is no reading, or when an unticked assertion awaits a pin.
One of awaiting_pin fail needs_pin pass retired unknown
ticked
boolean required
Whether the monitor alerts when it breaks.

Assessment

assertions
array of AssertionResult required
In the check's order. Ticked assertions the check retired come last.
read_at
string, date-time
When the monitor last checked its target. Absent before the first scan.
ref
string
Names the reading judged. Opaque: compare it, never parse it. A new rendering of the check changes it. Absent before the first scan.

Change

broke
array of Assertion required
Ticked assertions it broke.
class
string required
Names the kind of change, such as endpoint_removed. Each check adds its own.
fixed
array of Assertion required
Ticked assertions it fixed.
label
string required
What it broke and fixed, else its class, in the check's words.
observed_at
string, date-time required
When a scan saw it.
severity
string required
How loudly it reads. Any break is an alarm.
One of alarm info notice
waiting
boolean required
Whether it still waits for someone to acknowledge it.

Command

existed
boolean required
Whether an add found its monitor already there, and left it alone.
problem
Error
Why it was refused, in the shape every refusal takes. Present only when refused.
state
string required
Pending until it is durably saved. Applied and refused are final.
One of applied pending refused

Error

code
string required
Names the refusal. A code never changes once published, and new ones may appear: read one you do not know by its status.
One of apply_failed assertion_not_offered body_too_large cannot_apply cannot_save change_not_waiting command_not_found internal_error invalid_change invalid_input invalid_json invalid_key invalid_schedule invalid_target method_not_allowed monitor_gone monitor_id_taken monitor_not_found no_change not_saved one_tier_per_family pin_empty pin_stale pin_too_large pin_unseen plan_hold plan_interval_limit plan_monitor_limit queue_full rate_limited rebuilding request_timeout schedule_too_often service_unavailable target_collision too_old unknown_kind unknown_path unsupported_media_type workspace_full workspace_not_found write_in_flight
detail
string required
The words the website shows for this refusal.
errors
array of ErrorDetail
Each input that failed the schema, when one did.
status
integer, int64 required
The HTTP status this refusal answers with.
type
string required
Always about:blank. The code names the problem.
One of about:blank

ErrorDetail

location
string required
Where the input failed, such as body.schedule.
message
string required
Why it failed.

History

changes
array of HistoryEntry required
Newest first. A change waiting for acknowledgement shows past the plan's window.

HistoryEntry

broke
array of Assertion required
Ticked assertions it broke.
class
string required
Names the kind of change, such as endpoint_removed. Each check adds its own.
fixed
array of Assertion required
Ticked assertions it fixed.
id
string required
Names the change, as an acknowledgement names it.
label
string required
What it broke and fixed, else its class, in the check's words.
observed_at
string, date-time required
When a scan saw it.
severity
string required
How loudly it reads. Any break is an alarm.
One of alarm info notice
waiting
boolean required
Whether it still waits for someone to acknowledge it.

Monitor

every_change
boolean required
Whether a change alerts even when no ticked assertion fails or recovers.
id
string required
Names the monitor in every other call.
kind
string required
The check it runs, such as tls.
last_change
Change
Its latest change the plan shows. Absent when none shows.
schedule
string required
When it runs, as a cron spec in UTC.
standing
string required
Held means the plan paused it. It lifts once the monitors fit the plan.
One of held paused running
target
string required
What it watches, in the spelling webhooks carry.

MonitorEdit

every_change
boolean
Whether a change alerts even when no ticked assertion fails or recovers.
paused
boolean
True pauses it, false resumes it. A held monitor refuses either, and the whole edit, with plan_hold; only the plan lifts a hold.
schedule
string
When it runs, as a cron spec in UTC. The plan sets how often it may.

MonitorList

monitors
array of Monitor required
Sorted by target name, as the website lists them.

NewMonitor

every_change
boolean
Whether a change alerts even when no ticked assertion fails or recovers. Off unless true.
schedule
string required
When it runs, as a cron spec in UTC. The plan sets how often it may.
target
Target required
What it watches.
ticks
array of string
Assertions it alerts on, by id. Absent or null ticks the ones the target stars; empty ticks none. At most one tier of a family.

ref
string required
The ref of the assessment that shows the value. One a newer scan replaced is refused.

Sent

command_id
string required
Read it at /commands/{id} to learn what became of the change. That call says how long it keeps it.
monitor_id
string required
The monitor the change names.

Settings

every_change
boolean required
Whether a change alerts even when no ticked assertion fails or recovers.
schedule
string required
When it runs, as a cron spec in UTC.
standing
string required
Held means the plan paused it. It lifts once the monitors fit the plan.
One of held paused running

Netonica API

Authentication

Quick start

Rate limits

Errors

API reference

GET /api/v1/commands/{id}

Parameters

GET /api/v1/meta

GET /api/v1/monitors

POST /api/v1/monitors

DELETE /api/v1/monitors/{id}

Parameters

GET /api/v1/monitors/{id}

Parameters

PATCH /api/v1/monitors/{id}

Parameters

GET /api/v1/monitors/{id}/alerts

Parameters

PUT /api/v1/monitors/{id}/alerts

Parameters

GET /api/v1/monitors/{id}/assessment

Parameters

GET /api/v1/monitors/{id}/history

Parameters

POST /api/v1/monitors/{id}/history/{change}/ack

Parameters

PUT /api/v1/monitors/{id}/pins/{assertion}

Parameters

DELETE /api/v1/monitors/{id}/ticks/{assertion}

Parameters

PUT /api/v1/monitors/{id}/ticks/{assertion}

Parameters

Targets

agent-card

Fields

Assertions

dns

Fields

Assertions

headers

Fields

Assertions

mcp

Fields

Assertions

pqc

Fields

Assertions

securitytxt

Fields

Assertions

tls

Fields

Assertions

x402

Fields

Assertions

Schemas

Added

Alerts

Assertion

AssertionResult

Assessment

Change

Command

Error

ErrorDetail

History

HistoryEntry

Meta

Monitor

MonitorEdit

MonitorList

NewMonitor

Pin

Sent

Settings

Customize cookies

Cookie settings