API Reference

Overview

Every request operates on exactly one connected workbook, identified by its API key. There's no separate "select a workbook" step: the key is the workbook.

Which ranges are exposed, and whether each is readable, writable, or both, is defined inside the workbook itself by a config table your team maintains, not by anything you configure through this API. That means the same integration keeps working unchanged as the model evolves; add a row to the config table and the new range shows up the next time GET /schema is called.

Two data shapes are supported: single named-range cells (numbers, text, dropdown-validated values) and, optionally, whole rows of a real Excel Table for cases like a monthly forecast or a list of cost centres.

Authentication

Every request carries one workbook's API key in a header. There is no OAuth handshake, no session, and no separate account login for this API: the key is the only credential.

X-API-Key: wk_live_9f2c...

A workbook's first API key is issued when it's connected from the dashboard (by an org admin, or by any member if the organisation allows it), and shown exactly once at that moment; any of a workbook's keys identifies it equally, so there's no separate workbook-selection step in a call. An org admin, or the member who connected that specific workbook, can add further keys (e.g. one per integration) and revoke any single one independently from the workbook's settings popup in the dashboard (click its settings icon) — revoking a key immediately invalidates just that key, without affecting any others issued for the same workbook.

Quickstart

Three calls: see what's available, change an input, read the recalculated result.

# GET /schema
curl https://api.accessanalytic.com.au/schema \
  -H "X-API-Key: wk_live_9f2c..."

# POST /run-scenario
curl https://api.accessanalytic.com.au/run-scenario \
  -X POST \
  -H "X-API-Key: wk_live_9f2c..." \
  -H "Content-Type: application/json" \
  -d '{"values": {"Revenue_Growth_Rate": 0.08}}'

{
  "status": "updated",
  "values_written": { "Revenue_Growth_Rate": 0.08 },
  "outputs": { "EBITDA": 4200000, "Net_Margin": 0.183 },
  "display_names": {
    "Revenue_Growth_Rate": "Revenue Growth Rate",
    "EBITDA": "EBITDA ($)",
    "Net_Margin": "Net Margin"
  }
}

That's the whole loop: write an input, get the recalculated outputs back in the same response, atomically. Use this pattern (run-scenario) for the common "what if I change X" case rather than calling update-inputs and outputs as two separate requests.

Preparing your workbook

Before an API key can read or write anything, the workbook needs a table named exactly APIConfigTable which has one row per named range you want exposed. For example:

Column reference

Column headers are matched leniently: Display Name, display_name, and DISPLAYNAME are all recognised as DisplayName. Edit the table any time and call POST /schema/refresh to pick up the change immediately, without a redeploy or reconnect.

Exposing tables (optional)

APIConfigTable covers single cells. To write (and optionally read back) a whole block of rows at once (a forecast, a list of cost centres), expose a real Excel Table via two further optional config tables.

APIBlocksConfigTable

One row per exposed table.

WriteMode is overwrite (clear existing rows, then write the new ones, the default if blank) or append (add after what's already there).

APIBlockColumnsConfigTable

One row per column of each table above: same Type / Min / Max / ValidationRangeName / DisplayName / Description semantics as the single-cell config, including number as a synonym for float. A column of the real table that isn't listed here is never exposed, even though it physically exists.

Both tables are optional and independent of APIConfigTable. A workbook with only the single-cell config behaves exactly as before. Either one missing simply means no tables are exposed ("blocks": {} in GET /schema).

Endpoints

Seven endpoints, all under the base URL above. Six are billable against your organisation's monthly quota on a successful response (marked below); schema/refresh never is. Of those six, five count as one call per request; the exception is writing to a block table (POST /blocks/{table_name}), which counts one call per row written instead — see Usage and quota.

Errors

Every error response is JSON with a detail field describing what went wrong and, where relevant, how to fix it.

Quota-exceeded body

{
  "detail": {
    "error": "quota_exceeded",
    "message": "Monthly API call allowance used (1000 of 1000). It resets at the start of the next billing period.",
    "calls_used": 1000,
    "quota": 1000
  }
}

Rate limits

Limits are per-endpoint and keyed to your workbook's own API key. Another org's traffic never affects your limit, and vice versa.

A request over the limit gets 429 with {"error": "Rate limit exceeded: …"}. Back off and retry. This is never a sign anything is misconfigured.

Usage and quota

Every successful call to a billable endpoint counts once against your organisation's monthly quota — except writing to a block table, where each row written counts as its own call, since a large import genuinely costs more than a single-cell write. Reading a single output still counts as just one call, the same as reading an entire block table back in one GET /blocks/{table_name} call.

• Quota is shared across every workbook your organisation has connected, not tracked per workbook.
• POST /schema/refresh never counts: it's a config sync, not a data operation.
• Writing N rows in one POST /blocks/{table_name} call uses N calls from your quota, not one — writing zero rows uses none.
• Any member can view current usage from the dashboard; choosing or changing the plan is admin-only. On a paid plan, calls beyond the included allowance are billed automatically at the plan's rate and are never blocked.
• Your plan also caps how many rows a single GET/POST /blocks/{table_name} call can read or write, from 100 rows on the free tier up to 100,000 on the top business tier. This is a per-call cap, not a cumulative total: a table that's grown past the limit can still be written to in smaller batches, it just can't be read back in one call until the org upgrades (or the table shrinks).