Usage

AI credits used and left this period.4 operations

Headers on every response

Every response on this page carries these headers.

X-Trace-Id: — The W3C trace id of this request — the same id in the log and in the traceId of a problem. Quote it when reporting.
Server-Timing: — Where the time went: total, db;dur=…;desc="N queries", and every step the handler named (ADR-163).
X-Diagnostics: — Only when the request asked with X-Diagnostics: 1 or ?diagnostics=1: the same breakdown as one JSON object, with the trace id (ADR-163).

Operations

GET/api/v1/households/{householdId}/usage

Get the household's AI credits for the current billing period

Any household member. Credits, never tokens or cost (SUBS.md §23–24): used, limit, remaining and bonus, the soft/allowance-spent/hard flags the apps warn on, and what one chat turn costs (#418). Reading rolls the period forward when it has ended but never spends anything.

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Responses

200OK

application/jsonUsageResponse

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

426The build named in X-App-Version is below its platform's version floor (ADR-070). Problem type app-version-unsupported; the only way forward is the store. Callers without the header are never turned away.

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/usage"

Example response

200application/json

{
  "period": {
    "startsAt": "2026-09-07T16:30:00Z",
    "endsAt": "2026-09-07T16:30:00Z"
  },
  "credits": {
    "used": 0,
    "limit": 0,
    "remaining": 0,
    "percentage": 0,
    "bonus": 0,
    "bonusGranted": 0,
    "welcomeRemaining": 0,
    "monthlyRemaining": 0,
    "drawsFrom": {}
  },
  "limits": {
    "softLimitReached": false,
    "allowanceSpent": false,
    "hardLimitReached": false
  },
  "plan": {
    "code": "string",
    "name": "string"
  },
  "chatTurnCredits": 0
}

GET/api/v1/households/{householdId}/milestones

Get the household's first-week milestones and where the first week stands

Any household member. Each milestone (first plan, first list opened, first trip completed, first receipt read, first swap, first useful week) is written once, by the server, when the work happens. FirstWeek is the phase in the order plan, list, receipt, swap, and the step Bryti suggests next (ADR-391 (#3342)).

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Responses

200OK

application/jsonHouseholdMilestonesResponse

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/milestones"

Example response

200application/json

{
  "milestones": [
    {
      "kind": {},
      "reachedAt": "2026-09-07T16:30:00Z",
      "source": "string"
    }
  ],
  "firstWeek": {
    "phase": {},
    "next": {},
    "done": false
  }
}

GET/api/v1/households/{householdId}/upgrade-prompts

List the upgrade moments that are active for the household right now

Any household member. The server decides (ADR-391 (#3342)): Introduction after the first plan and list on the free plan, QuotaHigh at 80 % of the period with five days left, SustainedHighUse for Familie at 80 % two periods running, never both of the last two. Moment 4 is the 429 quota_exceeded itself and is never listed. The clients draw what they get, never in a chat reply.

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Responses

200OK

application/jsonUpgradePromptsResponse

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/upgrade-prompts"

Example response

200application/json

{
  "prompts": [
    {
      "moment": {},
      "showOnHome": false,
      "currentPlanCode": "string",
      "suggestedPlanCode": "string",
      "suggestedMonthlyCredits": 0,
      "suggestedPriceMinor": 0,
      "creditsUsed": 0,
      "creditsLimit": 0,
      "resetsAt": "2026-09-07T16:30:00Z",
      "recentPeriods": [
        {}
      ]
    }
  ]
}

POST/api/v1/households/{householdId}/upgrade-prompts

Record that an upgrade moment was shown, dismissed or opened

Any household member. Kept on the household, not in the browser, so «Ikke nå» holds on every device: Dismissed hides Introduction from Home for good, QuotaHigh for the period and SustainedHighUse for 90 days. OverQuota may be posted too, only to be counted. Idempotent per moment and window.

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Request body

application/jsonRequiredRecordUpgradePromptRequest

Responses

204No Content

400The request could not be read as the route needs it: a body that is not the documented shape (a required field left out, a null where none is allowed, a value too long for its field), a parameter that does not parse, or a NUL character anywhere (#3540, #3541, #3543). Code validation_failed or value_too_long.

application/problem+jsonProblemDetails

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  -X POST \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/upgrade-prompts" \
  -H "Content-Type: application/json" \
  -d '{"moment":"Introduction","action":"Shown"}'

Schemas

CreditPot

Type

Values

WelcomeMonthlyNone

Default "Monthly"

FirstWeekPhase

Type

Values

EmptyPlannedShoppedReceiptReadSwappedDone

FirstWeekResponse

Property	Type	Required
`phase`	`FirstWeekPhase`	Required
`next`	`FirstWeekStep \| null`	Required
`done`	`boolean`	Required

FirstWeekStep

Type

Values

PlanOpenListReceiptSwap

or null

HouseholdMilestoneKind

Type

Values

FirstPlanFirstListOpenedFirstTripCompletedFirstReceiptReadFirstSwapFirstUsefulWeek

HouseholdMilestoneResponse

Property	Type	Required
`kind`	`HouseholdMilestoneKind`	Required
`reachedAt`	`string (date-time)`	Required
`source`	`string`	Required

HouseholdMilestonesResponse

Property	Type	Required
`milestones`	`HouseholdMilestoneResponse[]`	Required
`firstWeek`	`FirstWeekResponse`	Required

ProblemDetails

Property	Type	Required
`type`	`string \| null`	—
`title`	`string \| null`	—
`status`	`integer (int32) \| null`	—
`detail`	`string \| null`	—
`instance`	`string \| null`	—
`code`	`string \| null`	—

RecordUpgradePromptRequest

Property	Type	Required
`moment`	`UpgradeMoment`	Required
`action`	`UpgradePromptAction`	Required

UpgradeMoment

Type

Values

IntroductionQuotaHighSustainedHighUseOverQuota

UpgradePromptAction

Type

Values

ShownDismissedOpened

UpgradePromptPeriodResponse

Property	Type	Required
`startsAt`	`string (date-time)`	Required
`endsAt`	`string (date-time)`	Required
`creditsUsed`	`integer (int32)`	Required
`creditsLimit`	`integer (int32)`	Required

UpgradePromptResponse

Property	Type	Required
`moment`	`UpgradeMoment`	Required
`showOnHome`	`boolean`	Required
`currentPlanCode`	`string`	Required
`suggestedPlanCode`	`string`	Required
`suggestedMonthlyCredits`	`integer (int32)`	Required
`suggestedPriceMinor`	`integer (int32) \| null`	Required
`creditsUsed`	`integer (int32)`	Required
`creditsLimit`	`integer (int32)`	Required
`resetsAt`	`string (date-time)`	Required
`recentPeriods`	`UpgradePromptPeriodResponse[] \| null`	Required

UpgradePromptsResponse

Property	Type	Required
`prompts`	`UpgradePromptResponse[]`	Required

UsageCreditsResponse

Property	Type	Required
`used`	`integer (int32)`	Required
`limit`	`integer (int32)`	Required
`remaining`	`integer (int32)`	Required
`percentage`	`number (double)`	Required
`bonus`	`integer (int32)`	Required
`bonusGranted`	`integer (int32)`	Required
`welcomeRemaining`	`integer (int32)`	—
`monthlyRemaining`	`integer (int32)`	—
`drawsFrom`	`CreditPot`	—

UsageLimitsResponse

Property	Type	Required
`softLimitReached`	`boolean`	Required
`allowanceSpent`	`boolean`	Required
`hardLimitReached`	`boolean`	Required

UsagePeriodResponse

Property	Type	Required
`startsAt`	`string (date-time)`	Required
`endsAt`	`string (date-time)`	Required

UsagePlanResponse

Property	Type	Required
`code`	`string`	Required
`name`	`string`	Required

UsageResponse

Property	Type	Required
`period`	`UsagePeriodResponse`	Required
`credits`	`UsageCreditsResponse`	Required
`limits`	`UsageLimitsResponse`	Required
`plan`	`UsagePlanResponse`	Required
`chatTurnCredits`	`integer (int32)`	Required