Connect HTTP / JSON

The HTTP / JSON connector reads any address with a GET and watches what you pick in the answer: a JSON value, a JSON list, or a page’s status and text. There is no CoIsland server: requests go straight from your Mac.

Add the connector

1. Open Settings › Connectors, click + and choose HTTP / JSON.
2. For public addresses, give only a name (web is suggested) and click Add Connector.
3. For an API that needs a key:

Field	What to enter
Site	Where the key may go, like https://api.example.com. It is sent to addresses under this site and nowhere else, and a monitor on this connector may only read under it.
Header	The header carrying the key, and a prefix after a colon: X-API-Key, or Authorization: Bearer (used when you leave it empty)
Key	The token or API key the site gave you. It stays in your login Keychain.

Test connector sends one GET to the site with the key and says what it answered. A 401 or 403 means the key was refused.

Only https:// addresses are read; plain http:// only on this Mac (localhost, 127.0.0.1). Redirects are not followed: the error names the address to use instead. An answer over 5 MB is not read.

The path syntax

A path says where a value is in a JSON answer. It is a subset of JSONPath (RFC 9535):

Path	Reaches
$	The whole answer
$.status or status	The member status ($. may be left out)
$.data.items[0].state	Nested members and the first element
$.items[-1]	The last element
$.items[*].id or $.items.*.id	Every element’s id
$['a key with spaces']	A member whose name is not plain

Filters ([?(...)]) and recursive descent (..) are not supported. In the editor, Load Sample fetches the address once; every path you type is then read against it on your Mac, with each value found, its own path and its type.

The three monitor kinds

Kind	Query	What alerts
JSON value	url:https://api.example.com/health path:$.status	Any change of the value (its first check records it)
	... path:$.queue.depth above:100 (or below:, equals:, not:)	The value crossing the rule; again only after it cleared
New JSON items	url:https://api.example.com/orders items:$.data key:id title:name	An element whose key was not in the list before
Web page	url:https://example.com	A status other than 2xx (or status:200,301)
	url:https://example.com/product contains:In+stock (or lacks:)	The page starting (or stopping) to say the phrase

A phrase is one word in the query: write a space as + and a plus as %2B; the fields do it for you. With a connector that has a site, url:/v1/health is a path under it.

Clicking a row in the notch opens the alert in CoIsland: the value now beside the one that alerted (and “Cleared” once the rule no longer holds), the element’s whole JSON, or the page’s status now.

Troubleshooting

• “api.example.com/x refused the credentials (HTTP 401).” The key is wrong, expired, or the site needs one.
• “… is not under api.example.com, the only site this connector’s key is sent to.” Use a connector without a key, or one for that site.
• “… moved to https://… Use that address; redirects are not followed.” Paste the new address.
• “…: the answer is not JSON (text/html).” The address serves a page: use the Web page kind.
• “Nothing is at $.x in the answer of …” A warning on the card: the path reaches nothing; Load Sample shows what is there.