Getting started with the API

Everything the dashboard does to a monitor, the API can do too, subject to the same plan limits.

This page gets you to your first successful request. The endpoint-by-endpoint reference is the API documentation, and this guide deliberately does not duplicate it.

Create a key

Settings → API keys → New key.

The key is shown once. We store only a hash, so if you lose it, revoke it and make another. The visible prefix stays on screen afterwards so you can tell keys apart and identify one found in a log without it being usable.

Your first request

curl -H "Authorization: Bearer uc_live_..." \
  https://api.uptimecraft.com/api/v1/monitors

Create one:

curl -X POST https://api.uptimecraft.com/api/v1/monitors \
  -H "Authorization: Bearer uc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing site", "monitorType": "HTTP", "url": "https://example.com"}'

Then read its status back with GET /api/v1/monitors/{id}. Full parameters and responses are in the API documentation.

Access and limits

Access level, keys allowed, requests per minute and the daily cap all come from your plan — the current figures are on the API documentation page, rendered from the same records that enforce them. The free plan is read-only.

Every response carries X-RateLimit-* headers telling you where you stand. Exceed the limit and you get 429 with a Retry-After header; wait that many seconds.

If you are reading every monitor on a loop, use the list endpoint rather than fetching them one at a time. It is one request instead of twenty, and on the free plan it is the difference between fitting in the daily cap and not.

Errors

Errors come back as JSON with a machine-readable code and a human message, with the usual status codes: 400 for a bad request, 401 for a bad or missing key, 403 for a key without the scope, 404 for something that is not yours or does not exist, 429 for rate limiting. The full list is in the API documentation.

404 rather than 403 for another team's resource is deliberate: a different answer would confirm that the id exists.

Keeping a key safe

• Treat it like a password. It acts as your team.
• Keep it out of source control and out of browser code.
• Give it an expiry you will actually renew, rather than the maximum.
• Revoke immediately if it may have leaked; revocation takes effect at once.

Full reference

API documentation — every endpoint, parameter and response.