Appearance

Contexts and context types ​

A context type is the schema — what kind of thing it is (a user, a device, an organization). A context instance is one of those things — a specific user, a specific device. Together, they describe the typed entities your code passes to flag evaluations and other operations.

A concrete example ​

You want to roll out a new checkout flow to enterprise users in the US region. Two context types are involved:

  • user — the person logged in
  • account — the workspace they belong to

Your code passes both as contexts during a flag evaluation:

python
@client.contexts.provider
def contexts():
    return [
        Context(type="user", key=current_user.id, attributes={"plan": current_user.plan}),
        Context(type="account", key=current_account.id, attributes={"region": current_account.region}),
    ]

if client.flags.boolean_flag("checkout-v2", default=False).get():
    show_new_checkout()

The targeting rule on the flag matches user.plan == "enterprise" AND account.region == "us". The SDK evaluates locally — no per-call network round-trip.

Context types are the schema ​

A context type defines:

  • The key of the type (user, account, device).
  • The attributes instances of that type are expected to carry (e.g. a user has plan, email, country).

Context types matter because rule builders in the console use them to suggest valid attributes when authoring rules. Once a rule references user.plan, that column becomes part of the schema — changing the type silently invalidates rules across all flags.

Two context types are built in:

  • environment — auto-managed by the platform. The SDK's environment parameter routes here, but the rows live in a dedicated environments table for performance.
  • service — auto-managed by the platform. The SDK's service parameter creates a context instance under this type.

Other context types you create yourself, either through the console or by letting your SDK auto-register them on the first evaluation.

Context instances are the data ​

A context instance is one entry under a context type:

  • user:jane — a user with key jane
  • account:acme-corp — an account with key acme-corp
  • device:ios-13.4-sim — a device

Instance attributes are free-form JSON and stored sparsely — they only need to hold values that targeting rules want to reference.

The SDK auto-registers context instances when it sees them during flag evaluations, capped at the account-wide limit. This means your rule builder can autocomplete attribute values from real production traffic instead of needing manual seeding.

The schema/data permission split ​

Writing context types (creating, renaming, editing attributes, deleting) is admin-gated. Writing context instances (creating one, renaming, editing attributes, deleting) is a regular member-level action.

Why: changing a type's schema can silently invalidate targeting rules across every flag in the account. Changing an instance just changes one entity's data. The blast radius is fundamentally different.

ActionOWNERADMINMEMBERVIEWER
Read types and instances✓✓✓✓
Write context instances (create, edit, delete)✓✓✓
Write context types (create, edit, delete)✓✓✓
Auto-register instances (SDK)✓✓✓

Note on type writes

The platform currently allows MEMBER-level write access to context types in addition to instances. The original design intent was to gate type schema writes to OWNER+ADMIN; this is on the roadmap and may tighten in a future release.

Limits ​

  • 50 context types per account.
  • 10,000 context instances per account. Includes services, since they're stored as instances of the built-in service type.

Both are platform-wide caps not tied to your subscription tier.

API surface ​

  • GET /api/v1/context_types — list types

  • POST /api/v1/context_types — create a type (id is the type key)

  • PUT /api/v1/context_types/{id} — rename or edit attribute schema

  • DELETE /api/v1/context_types/{id} — delete (cascades to instances)

  • GET /api/v1/contexts — list instances; filter by filter[context_type]

  • GET /api/v1/contexts/{type:key} — fetch one (composite id type:key)

  • POST /api/v1/contexts/bulk — bulk-register instances (used by the SDK)

  • PUT /api/v1/contexts/{type:key} — rename one

  • DELETE /api/v1/contexts/{type:key} — remove one