No matching sections.

Migrate from API v1

If you already have a v1 integration, this page is the map: for each thing you do today, what does the same job in v2. v1 is not going away on a date we have announced - this is a guide for moving when it suits you, not a countdown.

Before you begin

The two APIs are separate surfaces, not two dialects of one. v2 is not a wrapper over v1 and does not call it: different paths, different request and response shapes, its own authentication, its own error format. Moving an integration is a port, not a configuration change - budget for it as such.

Nothing forces a big-bang cutover. The two APIs authenticate independently, so a client can hold a v1 token and a v2 token at once and move endpoint by endpoint - reads first is the usual order, since they are the easy half and prove your token, host and parsing before any write is at stake.

Authentication

This is the one change every v1 client has to make, and it is worth making first.

v1 exchanges credentials for a token at runtime: POST users/token with a login and password returns a ticket valid for 48 hours (HTTP Basic on every call is accepted too). The token is unscoped - it can do everything the account may do - and forLogin mints one that acts on behalf of a super-account.

v2 has no credential-exchange endpoint at all. A token is created in the web interface, on the API page of your account, with the scopes it needs and an optional IP allow-list; left alone it lasts ten years. You send it on every call and never handle a password in code again:

curl -X POST 'https://api1.host-tracker.com/users/token' \
  -H 'Content-Type: application/json' \
  -d '{"login":"[email protected]","password":"…"}'
# then, for the next 48 hours:
curl 'https://api1.host-tracker.com/tasks' \
  -H 'Authorization: bearer TICKET'

curl 'https://api2.host-tracker.com/monitor' \
  -H 'Authorization: Bearer YOUR_TOKEN'

• A script that logs in at runtime must stop doing that. Mint the token once, keep it where you keep your other secrets, and send it. There is nowhere to POST a password.
• Tokens are scoped, and a read leaf never implies a write leaf. Grant the integration exactly the actions it performs; a call whose token lacks the scope answers 403 missing_scope naming what was required and what was granted. See Authentication & scopes.
• There is no forLogin twin. Where a subaccount used impersonation to work inside a super-account, the v2 answer is a token minted by that account with the narrow scopes the integration needs.
• The reference tier is anonymous in v2. The agent, pool, IP and type catalogues need no token at all - in v1 most of them required one.

Concept map

Most of the port is renaming. The vocabulary changed once, consistently.

Tasks to monitors

The info= bitmask becomes expand=

The full /monitor vocabulary is wider than v1's four bits - settings, attached, subscription, lastIncident, maintenance, lastResult (and its .metrics/.recheck children), uptime, spans, summary, count - and an unknown token is refused with the allowed list rather than ignored.

Filters

Contacts

Alerts and subscriptions

v1 had one subscription list carrying both alert types and report types. v2 has two families with their own endpoints, because they answer different questions and have different rules - reports go only to email contacts, and their frequency is a package matter.

Statistics and results

Agents

curl -s 'https://api2.host-tracker.com/agent/ip' | jq -r '.data[].ip'

Conventions that changed

What has no successor

• POST users/token - v2 mints tokens in the UI, never from credentials, and there is no forLogin impersonation twin.
• HTTP Basic - the Bearer token is the only scheme.
• POST tasks/$batch and POST contacts/$batch - use the per-family bulk doors, which are asynchronous jobs with per-item outcomes.
• IM contacts and their gateways - retired. The messenger channels are their own contact types now.
• XML responses and X-HTTP-Method-Override.
• The interval filter on the monitor list, and the exclude* inversions of the id, type, url and name filters.

Where to go next

• Quickstart - mint the token and make the first call.
• The query surface - cursors, filters, expand and fields, once for every list.
• Monitors - the per-type settings a ported create needs.
• Errors - what to branch on now that X-HT-Reason is gone.
• The v1 reference - still here, still accurate for the API you are leaving.