Pick the client, on every call.

In agency mode, monitors and other resources can belong to a client. The API has no “current client”: each request says which clients it means, and the key decides which ones it may see.

Agency mode must be on

Clients are available when agency mode is switched on for the Company. While it is off:

• Every client endpoint, such as GET /clients, answers 404 Not found.
• List endpoints ignore client_id and all_clients and return company-level resources only.

Choose clients when you read

Resources that can belong to a client carry an optional client_id: monitors, scheduled jobs, status pages, incidents, escalation policies, on-call schedules and playbooks. A resource without one is company-level. List endpoints take two query parameters:

export CLIENT_ID="…"   # from GET /clients

curl -s -G https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  --data-urlencode "client_id=$CLIENT_ID"

curl -s -G https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  --data-urlencode "all_clients=true"

• all_clients counts only when it is exactly true.
• A client_id that is not a UUID does not fail. The call falls back to company-level resources.
• There is no header for this. The choice belongs to each request, not to the key.

Choose a client when you write

Create and update calls take client_id in the JSON body. Leave it out and the resource is company-level.

curl -s -X POST https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Lakeside Bakery site",
    "url": "https://example.com",
    "monitor_type": "http",
    "client_id": "'"$CLIENT_ID"'"
  }'

• Creating a monitor with a client_id that is not a client of your Company, or that belongs to an archived client, is 400 bad_request.
• A key that may not write to that client gets 403 with the message “You do not have write access to this client”.

Keys limited to clients

A key can be limited to chosen clients when it is created in the app. What a key may see is its client set: for a personal key, what its owner may see, narrowed to the chosen clients; for a team key, the clients of its team plus company-level resources. GET /me shows it:

"client_set": { "All": false, "CompanyLevel": true, "IDs": ["…", "…"] }

• Lists never contain clients outside the set, whatever you pass in client_id.
• A single resource outside the set, such as a monitor, answers 404 and not 403, so ids of other clients cannot be probed.
• Company-level routes such as /organization answer 404 to team keys and to keys that cannot read company-level resources.

Common mistakes

• Creating a monitor without client_id and then listing with client_id. The monitor is company-level and does not appear.
• Passing all_clients=True or all_clients=1. Only true works; the rest means company-level.
• Expecting an error when agency mode is off. The parameters are ignored without a message.
• Sending client_id as a header. No header exists.
• Changing the client between pages. The cursor check does not cover it; keep it the same for every page.