FlowynBETA
LoginSign up

API checks

Requests an API on an interval and evaluates assertions on the status code, headers, JSON body, text body, or response time. A failed assertion stores evidence.

What api checks does

Requests an API on an interval and evaluates assertions on the status code, headers, JSON body, text body, or response time. A failed assertion stores evidence.

When to use api checks

  • Contract checks on APIs
  • Post-deploy verification
  • Partner API monitoring

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/monitors

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/monitors \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: check-orders-api" \
  -d '{
    "name": "Orders API",
    "type": "api_check",
    "method": "GET",
    "url": "https://api.example.com/orders/health",
    "interval_seconds": 300,
    "timeout_ms": 5000,
    "assertions": [
      {
        "source": "status_code",
        "operator": "equals",
        "expected": 200
      },
      {
        "source": "json_body",
        "property": "$.status",
        "operator": "equals",
        "expected": "ok"
      }
    ]
  }'

Response

Flowyn returns HTTP 201. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "8e3c5a7b-1d9f-4e2a-b6c4-0a7f3d1e9b52",
  "environment": "test",
  "name": "Orders API",
  "type": "api_check",
  "current_status": "waiting",
  "interval_seconds": 300
}

Lifecycle

  1. Create the check with its assertions.
  2. Each run evaluates every assertion; all must pass.
  3. A failed assertion stores evidence. Three consecutive failed results open an incident.
  4. A passing run records recovery.

Status values

StatusMeaning
waitingNo result yet.
healthyThe latest result passed.
degradedResults are mixed.
failingRecent results failed.
pausedNot checking.

Retries

Not applicable; the next interval runs again.

Idempotency

Send Idempotency-Key on create.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • interval_seconds 30–86,400
  • timeout_ms 100–30,000
  • Up to 20 assertions

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/monitors/8e3c5a7b-1d9f-4e2a-b6c4-0a7f3d1e9b52/results \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

See how repeated failures become one Issue.