Calculeaf Features Blog Guide Pricing Open app

API tokens

Calculeaf user guide · Updated 2026-08-27

When a value in a worksheet really lives somewhere else — a test rig, a spreadsheet, a build script — you can let that thing read or set it directly instead of retyping the number. Calculeaf exposes one addressable value per math region. Your account has a bearer token. Each saved assignment has a stable address. The two together are enough to GET or POST that value. There is no wider API here. You cannot list, create, or delete worksheets this way.

Get a token and an address

  1. Open Account settings. Under API Access, Copy puts your token on the clipboard, and Refresh Token issues a new one. Refreshing immediately invalidates the old token, so anything still using it starts failing. Anyone holding the token can read and update your worksheet values, so treat it as a credential.
  2. In the worksheet, sign in and save. Right-click a math assignment (:=) and choose Copy variable address. The item only appears when you are signed in and the region has been saved, because the address is that saved region's identifier.
  3. Call the API with the address and the token.
GET  /api/v1/cells/<address>/
POST /api/v1/cells/<address>/
     {"value": 42, "unit": "in"}
Authorization: Bearer <your-token>

Both GET and POST answer with the same object: the address, the variable name it assigns, the numeric value, its unit, the formatted result string, and any evaluation error. On POST, omit unit to keep the region's existing unit, or pass "unit": "" to make it dimensionless. A POST does not patch the number in place — it rewrites the assignment and re-evaluates the whole worksheet, so every region that depends on the value is up to date by the time the response comes back.

What the endpoint will refuse

  • An address must belong to a math region on a worksheet you own; anything else answers 404 with Region not found. A token cannot reach another user's sheet.
  • Only a numeric input can be written. Posting to a computed line such as y := x^2 returns 400 and Region value is a formula, not a numeric input — cannot set it, and a region with no := at all reports that it is not a variable assignment.
  • A body without a numeric value returns 400. A bad or refreshed token returns 401 and Invalid API token.
  • Opening a shared worksheet makes a copy with fresh region addresses, so an address you were given by a colleague will not resolve against your token. Copy the address from your own copy.

The Inventor add-in drives the same endpoint with the same addresses, which is why Copy variable address on the region context menu serves both. API Access sits on the same Account settings page as billing, a little below the subscription, though nothing on this page needs a paid plan.