Insights API · Reference

The interface, in full.

What goes into a call to the HABLA^™ Insights API, what comes back from one, how a withheld value arrives, and what the interface was never given a shape for.

The interface, field by field. Authentication, the shape of a request and a response, how a withheld value arrives, the query budget, the errors, and the things this interface is not permitted to return. An institution can require every line of it in an agreement, section by section.

Request a walkthrough Why it is built this way

A publishing interface, not a query interface

One decision shapes every section below, so it goes first. This interface publishes what a report already publishes — the same aggregates, under the same floors, with suppression already applied, for the same caller. Every endpoint it has serves something a report would already render.

An API is ordinarily a query interface, and a query interface over anonymous activity is the one thing HABLA’s governing documents refuse outright. So the answer here is a published set of choices rather than a query engine with rules around it. A caller picks from that set and gets back a response carrying its own caveat, and an institution can require every line of that in an agreement.

Authentication

A credential decides what a caller may read, and a caller cannot widen it by asking.

The organization is on the credential, never in the request: An organization credential is bound server-side to exactly one organization. There is no parameter by which a caller names an organization, so there is no parameter to get wrong.
A benchmark credential cannot name one at all: National benchmark access is a separate service with no field for an organization anywhere in its interface. The separation is structural because a validation bug is the likeliest way one class of access would answer as the other.
Keys are hashed at rest and revoked individually: A credential is storable only as a hash, and revocable on its own without disturbing any other credential held by the same institution.
The log records the credential, not the key: Every call is logged and attributable to a credential identifier. That log is Platform Configuration — a plane separate from the anonymous activity the figures are computed from — and carries no audience-member identity.

The shape of a request

A request is a choice among published options rather than a description of a query. There are three things a caller chooses and nothing else.

A topic: A topic key from the published vocabulary. Not free text, and not a search: the vocabulary is fixed, and a key outside it is not a request the interface can express.
A reporting period: One of the periods a report already publishes, named by its label. Start and end dates are not caller-supplied, because a caller who can choose the window can choose a second window that differs from the first by a single day.
A segment, from the published list: For a benchmark, one of the declared segments — sector, region, and an organization-size band. Arbitrary cross-tabulation is forbidden, because that is how a segment narrows to a single organization without any one filter looking wrong.

What is not a parameter

A date range of the caller’s choosing
A free combination of filters
A unit, a team, a shift or a department
A minimum count, or any threshold at all
An organization name, on a benchmark credential

The shape of a response

A response carries its own interpretation, because a number that travels without its caveat will be presented without it. The caveat ships in the body rather than in the documentation.

The topic: The topic the figure is about, as the published vocabulary words it.
Activity events: The count, named as what it is. The field is called activity events and not activity, because a reporting tool renders whatever the field is called, and no standard connector surfaces a nested object beside a series it is plotting. The honest word has to be the column header.
The status: Whether the figure is reportable or withheld. One value, with nothing behind it — see the section below for why there is no second value explaining which floor applied.
Unique people: unknown: Carried as a value in the body, not as prose in a document. HABLA counts activity events and does not count people, so the field states that rather than omitting it and letting a reader assume.
Prevalence: not measured: The same, for the figure a reader is most likely to believe they are holding. Prevalence is not something HABLA can calculate, and the response says so in the same object as the count.

No example body appears on this page, and that is deliberate. A sample figure is a number a reader could quote and no one could verify, and HABLA does not print figures it cannot stand behind. The fields above are that body with the meanings kept and the sample number left out.

Shipping the caveat in the body is necessary and not sufficient. The other half is contractual: the licence terms will require that any visualisation of a figure co-displays its interpretation.

How a withheld value arrives

This is the part of the interface a differencing attacker would read first, so it is the part where the rules are most exact.

Absent, or marked withheld: A value beneath a floor is missing from the response, or present and marked as withheld. Those are the forms it may take, and there is no third.
The real figure is never returned with a flag beside it: The real figure never travels beside a field saying it should not be shown. A flag a client may ignore is a value a client will publish.
The value is never serialized as a zero: A withheld value is never serialized as a zero. Zero is a figure, it is plottable, and it is wrong.
One status, with no reason behind it: The status is a single undifferentiated value. A response that explained which floor applied — population, activity, or a rollup — would narrow the residual possibility space for a differencing attacker at no cost to them, which is a worse trade than a caller not knowing why.
Suppression happens before serialization: This is a property of what is built rather than of what is sent: the figures the interface can reach have already had suppression applied, so there is no step at which a suppressed value exists in a response and is then removed.

The budget, and what it is actually for

There is a query budget, and it is an easy thing to oversell. An early version of this design did; the corrected account is the one below.

The floors and the share cap are construction-time properties: they bound what can be disclosed regardless of how many permitted queries any number of parties ever issue. The budget is a serving-time control, and its job is narrower than that. It bounds automated enumeration scale. A person clicking through a console could in principle enumerate cells and solve by subtraction, but not at the volume needed to build a useful system of equations. A script can, and that is what the budget is for.

It counts solvable combinations, not repeats: The dangerous sequence is a set of legitimately distinct calls — different segments, different periods, each one permitted — whose differences triangulate a withheld value. Refusing near-identical repeats does not touch that, so the budget tracks the combinations rather than the repetitions.
It accumulates against the institution, not the key: A budget scoped per credential is defeated by holding several: a large customer with departmental keys, or a research organization and its sponsoring institution, split the calls so no single budget trips and reconcile the answers offline. The budget accumulates against the legal customer.
Re-polling is free; a new cell is not: A reporting job refetching an unchanged period costs nothing, and a genuinely new cell counts. Without that distinction a budget either fails to stop abuse or breaks every legitimate integration on its first day.

No figure is published for any of this, and the absence is deliberate. A budget number means something only once it has been calibrated against the traffic it governs; a number published ahead of that is one a customer would plan against and HABLA could not defend.

Errors

What constrains an error answer is not its code. It is the rule below, which every error obeys: an error may help a caller fix their call, and may never tell them anything about a figure.

An error may say what a caller can do differently: An unknown topic key, a period that is not published, a segment outside the declared list, a credential that is revoked or exhausted — each of them is answerable, because none of them tells a caller anything about a figure.
An error may not say why a value was withheld: Withholding is reported as a status on the figure and never as an error carrying a reason. The single-undifferentiated-value rule above is the whole argument, and an error channel is the obvious place for it to leak.
Refusing a call leaks nothing either: A call refused on the budget says that it was refused on the budget. It does not say which of the caller’s earlier calls made this one solvable, because that is the same disclosure in a different field.

What this interface was never given a shape for

These are not routes that exist and return an error. They are not shapes the design has, which is a different and stronger statement. The anonymous activity underneath a figure is what none of them could reach: the interface reads the reporting engine’s already-suppressed output and holds no connection of its own.

No endpoint for raw or per-event anonymous data
No endpoint that resolves a topic to the people who selected it
No endpoint that says which organizations contributed, or ranks them
No endpoint that returns a figure beneath a floor, in any form, including its existence
No parameter anywhere that lowers a threshold

The rule the whole interface reduces to: an endpoint that returned something a report would not render is not an endpoint this interface has.

Put it in the agreement

This page is written for the person who will sign for an integration as much as for the one who will write it. What it is for is deciding whether this is an interface worth building against, and requiring, in an agreement, that it behave the way this page says it does.

Request a walkthrough What an institution needs to know