> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

## Entity types

**Entity types** are vendor-defined categories of resource that can be governed. You define them once per environment — they describe the *shape* of your governance model, not specific instances of it.

Entity types fall into two roles:

* **Hierarchical** — levels in your customers' org structure, such as `org`, `team`, `user`, or `agent`. Entities of these types can be arranged in a parent–child tree so that consuming against a team also counts against its parent org.
* **Dimensional** — cross-cutting attributes such as `region`, `model`, or `product`. These are not placed in a hierarchy but can be used as scope filters on assignments (see [Scope](#scope-dimension-scoped-sub-budgets)).

Both roles use the same underlying entity type object. The difference is only how the type is used: in a hierarchy, or as a scoping axis on an assignment.

```json theme={null}
{ "id": "org",    "displayName": "Organization", "attributionKeys": ["orgId"] }
{ "id": "team",   "displayName": "Team",         "attributionKeys": ["teamId"] }
{ "id": "model",  "displayName": "AI model",     "attributionKeys": ["modelId"] }
{ "id": "region", "displayName": "Region",       "attributionKeys": ["regionId"] }
```

The `attributionKeys` field tells the governance engine which keys in a usage event's `dimensions` map correspond to instances of this type. When an event carries `{ "orgId": "acme", "modelId": "gpt-4o" }`, the engine resolves entity `acme` of type `org` and entity `gpt-4o` of type `model`. The `dimensions` field in check and ingest requests is simply how you pass these attribution key–value pairs when you don't know the entity IDs directly.

## Entities

An **entity** is a specific instance of an entity type, owned by one of your customers (the *owner*). Each entity belongs to exactly one owner and has a unique `id` within that owner's scope.

```json theme={null}
{ "id": "org-acme",     "typeRefId": "org",   "metadata": { "plan": "enterprise" } }
{ "id": "team-eng",     "typeRefId": "team",  "metadata": {} }
{ "id": "user-alice",   "typeRefId": "user",  "metadata": {} }
{ "id": "agent-claude", "typeRefId": "agent", "metadata": {} }
```

Entities are the rows that assignments and usage counters bind to. You provision them from your backend whenever a customer creates an org, team, user, or AI agent in your product.

## Capabilities

A **capability** is a metered resource that you allow customers to consume — for example `api-calls`, `tokens`, or `seats`. Capabilities form the column axis of the governance matrix.

In V1 all capabilities are of type `METER` (a counter that increments on ingest and resets on cadence rollover).

```json theme={null}
{ "id": "api-calls", "type": "METER" }
{ "id": "ai-tokens", "type": "METER" }
```

## Assignments

An **assignment** is the per-`(entity, capability)` governance rule: how much of a capability an entity is allowed to consume per cadence period. Assignments are the governance equivalent of entitlements — they appear as entitlement columns in the Stigg console's Governance tab. The natural key is `(entityId, capabilityId, scopeEntityIds)`.

```json theme={null}
{
  "entityId":    "team-eng",
  "capabilityId": "ai-tokens",
  "usageLimit":  50000,
  "cadence":     "P1M"
}
```

Assignments are typically created by your customers through an in-app interface you build, though you can also set them programmatically on their behalf.

### Cadence

The cadence is an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) that controls how often the usage counter resets.

| Cadence | Resets every     |
| ------- | ---------------- |
| `PT1H`  | 1 hour           |
| `P1D`   | 1 day            |
| `P7D`   | 7 days           |
| `P30D`  | 30 days          |
| `P1M`   | 1 calendar month |

A short cadence (e.g., `PT1H`) acts as a rate-limit window.

### Scope (dimension-scoped sub-budgets)

An assignment's `scopeEntityIds` field lets you attach a tighter budget that applies only when a specific sub-context is present. For example, you might give `team-eng` a global budget of 50,000 tokens per month, and a tighter budget of 5,000 tokens that applies only when the `model-gpt4o` entity is in the request's resolved set.

```json theme={null}
// Node-wide budget — always applies
{ "entityId": "team-eng", "capabilityId": "ai-tokens", "scopeEntityIds": [],            "usageLimit": 50000, "cadence": "P1M" }

// Scoped sub-budget — only applies when model-gpt4o is in the resolved set
{ "entityId": "team-eng", "capabilityId": "ai-tokens", "scopeEntityIds": ["model-gpt4o"], "usageLimit": 5000,  "cadence": "P1M" }
```

## Hierarchy

Entities can be arranged in a parent–child tree to reflect a customer's organizational structure. The `parentId` field on an assignment places the entity in the hierarchy.

```
org-acme
  └── team-eng
        ├── user-alice
        └── agent-claude
```

The check endpoint evaluates the entire chain from the target entity up to the root. A request is granted only when every budget in the chain allows it.

## Governance is opt-in

If an entity has no assignment for a capability, the check endpoint returns `hasAccess: true` with an empty `checks` array. There is no default deny. You can roll out governance incrementally — ungoverned entities continue to work exactly as before.

## Check and Ingest

Governance exposes two runtime endpoints:

* **Check** (`POST /owners/:ownerId/check`) — read-only; returns `hasAccess` and current usage. Call this *before* allowing consumption.
* **Ingest** (`POST /owners/:ownerId/ingest`) — increments the usage counter. Call this *after* consumption. Ingest never gates — it always succeeds.

The typical pattern is: check → allow or deny → ingest (only on allow).

***

## Coming in early access

The following capabilities are on the governance roadmap and available in early access. [Contact us](https://www.stigg.io/contact) to learn more.

### Allocated budgets per entity

Today, a limit is set directly on an entity. Allocated budgets let a parent entity distribute a portion of its own budget down to children — for example, an org allocates 200,000 tokens to `team-eng` out of its own 1,000,000 total. Consuming against the child's allocation reduces the parent's remaining pool automatically.

### Soft limits

Hard limits block consumption when the limit is reached. Soft limits allow consumption to continue past the threshold but trigger a warning — giving your customers visibility and the chance to act before being cut off. Useful for grace periods and overage-aware pricing.

### Alerts

Notify your customers (or your own systems) when an entity approaches or reaches its limit. Alerts will be configurable per threshold (e.g. 80%, 100%) and delivered via webhook or in-app notification.