OPERATIONS GUIDE

Monitor API data reliability

Zorqelio supports two monitoring modes in the dashboard REST API: push-based freshness monitoring and scheduled polling of a public HTTPS JSON endpoint. Both validate data against the contract’s latest published schema.

Push monitoring (recommended for private APIs)

Your own service, workflow or scheduled job sends each upstream JSON result to Zorqelio. This works when your API is private or requires authentication because Zorqelio never needs to fetch the source endpoint.

1. Create a contract and note its ID.
2. POST to /api/v1/monitors with the workspace token, contract ID, label and expected interval.
3. Store the returned monitor bearer token in your server-side secret manager.
4. After each successful upstream fetch, POST the JSON response body to the monitor check endpoint.
5. Review decisions and freshness in the dashboard or MCP monitor_status/monitor_history tools.

curl -X POST https://zorqelio.xyz/api/v1/monitors/YOUR_MONITOR_ID/check \
  -H "Authorization: Bearer $ZORQELIO_MONITOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_42","state":"ready"}'

A valid payload returns HTTP 200 and ALLOW. A contract violation returns HTTP 422 and BLOCK with issue evidence. A revoked monitor returns HTTP 410. The body is validated in memory and is not retained.

Freshness states

• healthy — a validly authenticated submission arrived within the expected interval.
• stale — the expected interval elapsed without a fresh submission; a five-minute Cron Trigger evaluates overdue monitors.
• revoked — the monitor token has been revoked and submissions are no longer accepted.

Expected intervals are 5–1,440 minutes; default is 60. A new authenticated submission clears stale state. Freshness is a heartbeat signal: it does not prove that the upstream API is correct unless its response is submitted and validated.

Scheduled public API checks

For a public JSON API that needs no authentication, create a monitor with an optional endpointUrl field in the dashboard or REST API. Example:

curl -X POST https://zorqelio.xyz/api/v1/monitors \
  -H "Authorization: Bearer $ZORQELIO_WORKSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contractId":"YOUR_CONTRACT_UUID","label":"Public status API","expectedIntervalMinutes":15,"endpointUrl":"https://status.example.org/api/status"}'

Zorqelio performs an HTTP GET at the configured interval, parses JSON and validates it against the latest contract version. The dashboard displays scheduled mode, HTTP status, latest error and check counts.

Events and notifications

Monitor history includes creation, stale transitions, recovery, blocked checks and revocation. The dashboard can show browser notifications while open and permission is granted. Email delivery is not active until a production sender is configured; no email alerts should be expected at this time. Slack, SMS and outbound customer webhooks are not currently provided.

Security and retention

Monitor tokens are shown once and stored as SHA-256 hashes. Rotate or revoke exposed credentials using the available management tools. Submitted payloads are not stored; bounded validation summaries and monitor events are retained for operational history. Do not place tokens in browser code, source control or public logs.