Getting started with Tino Uptime

Tino Uptime checks websites, servers, service ports, DNS records, SSL certificates and domain expiry from probes in Vietnam and abroad. When a target fails, Tino Uptime opens an incident and alerts by email, Telegram, Discord, Slack, webhook or Zalo. The service API lets your application manage monitors and read uptime, check results, incidents and alert channels of a Tino Uptime plan.

Updated: 2026-10-24. Sources: Tino's Tino Uptime module and the Tino Uptime OpenAPI.

Calling the API

• The body is always JSON. With Update a monitor, send only the fields to change.
• Only the parameters listed on each route are relayed. Tino Uptime refuses unknown body fields (422 validation_failed).
• Monitor, incident and channel IDs in the path are UUIDs; a malformed one answers 400 invalid_request.
• What this API does not cover (status pages, servers, WordPress, CVE alerts) opens in the Tino Uptime dashboard through the login_url of the plan overview.

The /v1 gateway does not expose the Tino Uptime routes yet: app tokens (tinoat_) and personal API tokens (tinopat_) cannot call them. The sign-in token is the one customers use in the tino.vn client area; the SDK gets it with an OTP sign-in:

from tino_userapi import TinoClient

client = TinoClient()
client.request_login_otp("you@example.com")
client.verify_login_otp("you@example.com", input("OTP code: "))
print(client.request("GET", "/service/100002/uptime/monitors", query={"state": "down"}))

100002 is the Tino Uptime service ID: how to find it is below.

Find the Tino Uptime service

Each Tino account has one Tino Uptime account; the current plan belongs to exactly one service.

1. Identify it by the service's module: Service details (GET https://api.tino.vn/service/<id>, same sign-in token) has service.acc_module set to "tino_uptime". Candidates come from the service list.
2. Call the plan overview (GET /service/<id>/uptime):

Plan limits

Limits are in subscription.limits of the plan overview, current numbers in usage. Read the limits from the API, do not hard-code them: each plan's numbers may change.

Going over a limit answers 403 entitlement_exceeded; details.resource names the limit (monitors, min_interval_s, locations, channels). While the service is suspended, the Tino Uptime account is read-only: writes answer 403 account_suspended. After a downgrade, monitors over the limit are paused (disabled_reason: paused_by_plan, counted in monitors_paused_by_plan).

Monitor types

Create a monitor takes name, interval_s (30–86400 seconds, not below limits.min_interval_s), locations and settings. settings.type decides the other fields:

• heartbeat works the other way round: your system calls settings.ping_url after each run. ping_url is only in the create answer: store it right away.
• Headers, body and the Basic auth password are never returned; settings only tells header_names, body_set, basic_auth_set.
• international_critical: true: a failure seen only by the international probe also counts as down (default false).
• Internal or unsafe targets are refused: 422 validation_failed with details.reason: blocked_destination. A target checked too often (counting other customers) answers 422 target_rate_exceeded: pick a longer interval.

A monitor's state: pending (no result yet), up, suspect, down, partial, down_international, paused (turned off, stopped by the system per disabled_reason, or within paused_until).

Alert channels

Create a channel with a kind from the plan's limits.channels; a new channel awaits verification (except an email to the account owner's own verified address). A channel without opted_in_at receives nothing.

• A webhook channel returns webhook_secret (whsec_…) once only, in the create answer: store it to check the signature of incoming messages.
• Verification emails: at most 5 an hour per account and 3 a day per address; beyond that 429 rate_limited. A wrong code answers 422 token_invalid.
• Send a test message works only for a verified, enabled channel; otherwise 409 conflict.

Lists and safe retries

Lists (monitors, incidents, channels, per-check results) use cursor pagination: send the previous page's next_cursor as cursor; next_cursor is null at the end. limit defaults to 50, at most 100 (per-check results: default 100, at most 1000).

{ "data": { "data": [], "next_cursor": null } }

Create a monitor and Create an alert channel take idempotency_key (8–128 characters A-Za-z0-9._:-). If the connection drops midway, resend the same body with the same key: nothing extra is created. The same key with a different body, or while the earlier call is still running, answers 409 idempotency_conflict. Without a key every call is a new command: read the list again before retrying.

Responses

Success: {"data": …}, where data is Tino Uptime's answer. HTTP 200, 201 on create, 202 once a test message is queued, 204 on delete (no content). Times are RFC 3339; IDs are UUIDs.

Errors

{ "error": ["entitlement_exceeded"], "message": "Đã vượt hạn mức của gói.", "details": { "resource": "monitors" }, "request_id": "…" }

Branch on error[0], not on message (a Vietnamese sentence that may change). With validation_failed, details.field names the wrong field and details.reason the reason when there is one. Errors Tino returns before relaying (service_not_found, invalid method) only have error. When reporting a problem to Tino, include request_id.