Glossary

Most of these terms you can guess. A few you cannot, and those are the reason this page exists: each one has misled someone reading a payload — a word that names two different quantities, a null that looks like a zero, a verdict that qualifies something other than what it sits next to.

Capability

The unit of authorisation. Every call — REST, MCP or chat — resolves to a capability, and the capability carries its own permission check, plan check, output masking and audit trail. There is no second path to the same data.

Each capability declares an effect:

A write capability is never listed and never directly callable. It is reached only through the proposal it belongs to — listing it would invite a client to try.

Proposal

The two-step shape of every change. A propose capability returns a diff and an identifier; nothing has happened yet. POST /v1/proposals/{proposalId}/apply is what commits it, and it recomputes the diff before applying — a proposal that no longer matches the current state is refused as diff_stale rather than applied blindly.

Surface

Where a call arrives from: api (REST), mcp, or dashboard. The same capability publishes different fields per surface. A field you see in the dashboard is not necessarily a field this API returns; what api publishes is declared in the OpenAPI document and nothing else comes out.

Content item, scored item

Two counts, one word, and they are routinely different.

• totalItems — every content item the project has.
• scoredItems — those that carry a numeric score.

avgScore is an average over scoredItems, never over totalItems. A project can hold sixty content items with none scored: totalItems: 60, scoredItems: 0, and avgScore: null. Dividing by totalItems yourself would report a collapse that has not happened.

Score

Always out of 100, and null is never a zero.

null means the score was not produced — read scoreAvailabilityState on the module to learn why. suppressed-incomplete-coverage says the module ran but measured too little to score honestly; stale-last-known says the number is real but comes from an earlier run. A module whose status is completed can still carry score: null: the run finished, the score did not.

Freshness — two clocks

This is the one that catches people.

A competitor marked stale under assetFreshness does not contradict a High Confidence cohort. They measure different things on different horizons. The field was named assetFreshness rather than something generic precisely so the two would stop sharing a word.

Posture, coverage, and a null average

competitorPosture and competitorCoverage are verdicts on the cohort — how many retained competitors were measured, and how recently. They never qualify an individual radar axis.

So a High Confidence cohort can sit next to five axes whose competitorAvg is null, and nothing is wrong. competitorAvgReason says which of the two causes applies:

• cohort-below-minimum — the cohort itself is under the retention threshold;
• no-competitor-measured-this-pillar — the cohort is sufficient, but no retained competitor measured this particular pillar.

Credential

A dga_ bearer token, scoped to one project. It is not an account-wide API key: it opens the capabilities that project's plan and the bearer's permissions allow, and nothing beyond. See credentials for how to obtain one.

Routing hint

The {projectId} segment in every path. It exists so multi-project code stays uniform — it authorises nothing. The project comes from the credential. If the segment names a project outside the token, the call is refused with routing_hint_mismatch; it is never used to widen access.

Refusal

A call that was understood and declined, returned as an RFC 9457 problem document. The type URI dereferences to the error reference, and the reason is the stable, machine-readable field — branch on it, not on the prose. A refusal is not an outage.

Plan gating

Capabilities a plan does not include are listed and marked as such, not hidden. Gating happens when a connection is authorised, not when you read a page: you should be able to see what you would get before you buy it.

Search intent

The intent field on content and topics carries French values, including one with a diacritic:

informationnelle · commerciale · éducationnelle · inspirationnelle
transactionnelle · navigationnelle · locale · unclassified

They are stored values, not display labels, and they are stable — comparing against 'informational' will never match. Normalise or map them on your side; branch on the exact strings above, éducationnelle included.