Insights API
An interface that publishes what a report publishes.
The HABLA™ Insights API is how an institution reads HABLA signals in the systems it already runs — a district executive system, a data warehouse, a state agency’s benchmark, a research platform — without a person copying numbers off a screen. It is a publishing interface and not a query interface, and that is the whole design.
A publishing interface, not a query interface
Every endpoint serves something a report would already render.
An API is, by default, a query interface — and an unrestricted query interface over anonymous activity is the one thing HABLA has refused in writing more times than anything else. HABLA does not answer that by adding rules to a query engine. It answers it by not building one.
How a figure is asked for, and how it comes back
An institution does not compose a question. It chooses from a published list, and what comes back is the same figure a report would already render for the same caller — so the interface has no query engine to bound, harden or get wrong.
-
Four things this interface was designed without: an address for raw or per-event data, a way to resolve a topic to the people who selected it, a way to say which organizations contributed to a figure, and a parameter that lowers a threshold. They are absent by design rather than unfinished, which is why the drawing gives this one a dashed outline rather than a solid one.
-
A topic key from the published vocabulary, one of the published reporting periods, and a segment from the declared list. No caller-supplied date range and no free filter combination, for a reason that takes one line: whoever can choose the window can choose a second window that differs from the first by a single day.
-
This is the whole design. An unrestricted query interface over anonymous activity is the thing HABLA has refused in writing more times than anything else, and the answer is not a query engine with rules bolted to it. It is not building one.
-
Figures that have been through both reporting floors and through suppression, for the caller the credential names. A figure an institution can see on a screen is a figure it can read here, and one it cannot see is absent from both. A value beneath a floor arrives absent or marked as withheld, never as a number with a flag beside it and never as a zero.
- The same aggregates a report renders
- Each endpoint serves figures that have already been through both reporting floors and through suppression, for the caller the credential names. A figure an institution can see on a screen is a figure it can read over the interface, and one it cannot see is absent from both.
- Fixed periods, fixed segments
- There are no caller-supplied date ranges and no arbitrary filter combinations. A caller chooses from the same published periods and segments a report offers, for a reason that takes one line: a caller who can choose the window can choose a second window that differs from the first by a single day.
- Suppression before serialization
- A value beneath a floor is absent from the response, or marked as withheld. It is never a real number with a flag beside it that a client may ignore, and never a zero.
- One set of rules, in one place
- The suppression rules live in one shared reporting package that both the console and the interface consume. Two implementations of a floor drift the first time one of them is patched, and a floor that drifts is not a floor.
What access includes
What is licensed is access to aggregated intelligence. It is never the sale of anyone’s behavioral data, and that distinction belongs in the contract rather than only in the documentation.
Included
- Aggregate topic signals, already floored
- Period comparison and access-timing distributions
- National and segment benchmarks, above the contributor floor
- The organization’s own action record
What is not sold, at any price
- Raw or per-event anonymous data
- Anything that permits a join to customer HR data
- Contact-domain data, in any form
- A lowered floor, a private endpoint, or a bespoke export
The last line is the one the specification expects to be tested. The first large institution to ask for a lower floor “just for our instance” will offer real money for it, and the answer is already written down: a threshold sold for money is not a threshold. No floor, cap or budget in this system can be represented as a per-customer or per-credential override, so there is no field in which such a concession could be recorded.
The floors an institution inherits
Access changes nothing about what HABLA is willing to publish. Every figure reaching the interface has passed the same thresholds a figure on a screen passes, and a national benchmark passes two more. These are the reason a benchmark is worth reading at all.
- Both reporting floors, per organization, before anything is shared
- An organization contributes only what was already reportable to that organization. Suppressed values do not become reportable by being added to other people’s.
- Ten contributing organizations, for a national or segment figure
- No cross-organization figure is published unless at least ten independent organizations contribute to it. That number is the founder’s, and it is a stored platform constant rather than a literal in code.
- A share cap, because ten is not enough on its own
- No single organization contributes more than forty per cent of a figure. The count floor stops one-organization disclosure; the cap stops the case where ten contribute but one of them is almost all of it. A combined limit on the largest two or three is needed as well, and HABLA has not set that number — so no cross-organization figure has been published yet, and the code refuses to publish one rather than assume a limit nobody decided.
- A suppressed period when the contributing set changes
- An organization joining or leaving a segment suppresses the period that brackets the change, rather than starting a new series with a new label. Relabelling would not help: the arithmetic does not care that the interface declined to draw a trend line.
Contributing to a national figure is a separate term an organization agrees to, with the ability to decline and to withdraw, and declining carries no product penalty. The reason is blunt: selling a derived product built from a customer’s data without that being in their agreement is not a privacy question, it is a breach of contract.
How access is arranged
Access is granted under a written agreement rather than issued from a page. The agreement is where the boundary lives: what is licensed is access to aggregated intelligence, and that is a clause rather than a footnote.
- A conversation, not a signup
- There is no self-serve key and there will not be one. An institution asks, HABLA and the institution agree what is licensed and for how long, and a credential is issued against that agreement.
- The class of credential follows the agreement
- An organization reading its own figures and an institution reading a national benchmark are different agreements, answered by different services.
- Contribution is agreed separately, or declined
- Whether an organization’s already-reportable aggregates contribute to a national figure is a term of its own, and declining costs nothing.
- Revocation is a term, not a request
- Credentials are revocable individually, and withdrawal from contribution is available for the life of the agreement.
Credential classes are kept apart by architecture rather than by a validation branch, since a validation bug is the likeliest way one would ever answer as the other. An organization credential is bound server-side to exactly one organization and is never named by the caller. A national benchmark credential is served by a separate service that has no field for an organization anywhere in it — not one that declines to name one, one that cannot. Keys are hashed at rest and revoked individually, and the call log records a credential identifier rather than the key. The pressure HABLA expects on this is not technical: it is a reseller asking for one key across several clients, which arrives as a sales conversation rather than as a code review, and the answer is written down here so that it is a published one.
What it costs
Access starts at $4,500 a year, for an organization reading its own figures. What that buys is the access described on this page, under the floors on it, and it buys no exception to any of them. Reading a figure that spans organizations is a different agreement, and it is not priced here because no such figure has been published yet.
Who it is for
The institutions this is being built for. It is an intended audience and not a customer list — no organization has this access and none is named on this site.
- School systems and districts consolidating signals into an executive system
- State and public agencies consuming a benchmark without copying numbers
- Hospital systems and public-health organizations reading workforce signals
- Universities and research platforms working from aggregates
- Employers connecting signals to the reporting tools they already run
Ask what it will be allowed to do
Any vendor will tell you what their interface returns. Ask this one what it is not permitted to return — take every refusal on this page into an agreement, and hold HABLA to it. That is the question worth asking, and it is the one this page is written to answer.