# Connect HTTP / JSON

> Point CoIsland at any address. A JSON value that changes or crosses a threshold, a new element of a JSON list, or a page that goes down or starts saying "In stock" reaches your Mac's notch.

Source: https://coisland.app/docs/connect-http/

## What you need

- **You need:** Nothing for public addresses, from An API key only when the site asks for one
- **The form asks:** Connector name, Site (optional), Header (optional), Key (optional)
- **You can watch:** JSON value, New JSON items, Web page
- **Access:** GET requests only, 5 MB at most, https (http only on localhost)

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.