Docs

Type a word or a question. Esc closes the search.
DE
Sign in Start free
Developers/Basics

One version, and a log of every change.

The API has one version, /v1. Changes land inside it, and the changelog records each one, including the ones that can break a client.

What the API does today

TopicBehavior
URL versionEvery operation is served under /v1. There is no other version and no /v2.
X-API-Version request headerAccepted. Any non-empty value marks the request as a public API request, which gives it the data envelope and, on GET /monitors, cursor pagination. The value itself is not read.
api_version of a keyEach key stores one, 2026-05-07 by default. GET /me returns it. No behavior changes with it.
Deprecation and Sunset headersThe API sends neither.
 
curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "X-API-Version: 2026-05-07"

The call above behaves exactly like one without the header, because a request made with an API key already gets the public API behavior.

How changes reach you

The changelog labels every change to the contract as breaking, added, changed, deprecated or documented, and has a “Breaking only” filter. It is generated from the history of the OpenAPI file. Watch it, or the OpenAPI file itself, for the operations you use.

The stated intention is that a breaking change gets its own version, /v2, with 12 months of parallel support and Deprecation and Sunset headers. That is an intention, not behavior you can test: there is no /v2 and no header today, and the changelog shows breaking changes that were made inside /v1. Plan for the changelog, not for a header.

Write a tolerant client

  • Ignore response fields you do not know; new ones appear as added.
  • Do not depend on the order of keys, or of scopes in GET /me.
  • Branch on error.code, not on error.message. See responses.
  • Cover the operations you use with tests. A changed required scope is labeled breaking in the changelog.

Common mistakes

  • Sending X-API-Version to pin an old behavior. It pins nothing.
  • Changing a key’s api_version to get a different response. There is no such effect.
  • Waiting for a Sunset header before checking for removals. Read the changelog.
  • Building against /v2 paths. They do not exist.
Full size ↗