Notifications & workspace

200 success

The stored object, or null when none was ever saved.

As application/json.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

200 success

The stored object.

As application/json.

400 error

Bad Request. Codes: workspace_invalid (the body is not a JSON object), workspace_too_large (over 32 KB serialized; the body carries max_bytes), malformed_json (the body is not valid JSON, or uses an unsupported content encoding).

As application/problem+json.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it). A sandbox key: sandbox_read_only (it may write only clusters).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

413 error

Payload Too Large. Codes: body_too_large (the body is over this endpoint's 64 KB limit; the body carries limit_bytes).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

200 success

The bell.

As application/json.

dataarray of AcctNotificationalways present

Undismissed notifications, newest first, at most 200 (90-day retention).

data[].idstring (uuid)always present

The notification id.

data[].kindstringalways present

What happened. Known kinds: vintage_release, vintage_withdrawn, county_window_opening, county_batch_applied, api_limit_hit, payment_failed, payment_recovered, plan_changed, plan_reset_at_switch, downgrade_applied, seat_granted, seat_removed, member_left, member_departed, join_request, join_decision, ownership_claim, trial_started, trial_expiring, announcement, new_device, password_changed, org_suspended, account_suspended, account_unsuspended, composite_shed, keys_revoked, support_reply. A kind not in this list may appear; it still renders a generic title and body.

data[].groupstringalways present

The bell's group for it: Data, Counties, Keys, Billing, Members, Account or Announcements.

data[].titlestringalways present

One-line title.

data[].bodystringalways present

The sentence.

data[].actionobject

The one action that resolves it, when there is one (absent otherwise).

data[].action.labelstringalways present

Button label.

data[].action.tostringalways present

A route in DTG's web app (for example /account/billing). A client that does not use the app reads payload instead.

data[].emailedbooleanalways present

True when the same fact was also sent by email.

data[].created_atstring (date-time)always present

When it was written.

data[].read_atstring (date-time) or nullalways present

When it was marked read; null while unread.

data[].payloadAcctNotificationPayloadVintageRelease or AcctNotificationPayloadVintageWithdrawn or AcctNotificationPayloadCountyWindowOpening or AcctNotificationPayloadCountyBatchApplied or AcctNotificationPayloadApiLimitHit or AcctNotificationPayloadPaymentFailed or AcctNotificationPayloadPaymentRecovered or AcctNotificationPayloadPlanChanged or AcctNotificationPayloadDowngradeApplied or AcctNotificationPayloadSeatGranted or AcctNotificationPayloadSeatRemoved or AcctNotificationPayloadMemberLeft or AcctNotificationPayloadMemberDeparted or AcctNotificationPayloadJoinRequest or AcctNotificationPayloadJoinDecision or AcctNotificationPayloadOwnershipClaim or AcctNotificationPayloadTrialStarted or AcctNotificationPayloadTrialExpiring or AcctNotificationPayloadAnnouncement or AcctNotificationPayloadNewDevice or AcctNotificationPayloadPasswordChanged or AcctNotificationPayloadOrgSuspended or AcctNotificationPayloadAccountSuspended or AcctNotificationPayloadAccountUnsuspended or AcctNotificationPayloadCompositeShed or AcctNotificationPayloadKeysRevoked or AcctNotificationPayloadSupportReplyalways present

The structured facts, by kind (one schema per kind below). Never a secret.

data[].payload.vintagestring

The new current vintage id.

data[].payload.labelstring

Its display label.

data[].payload.supersededobject

Present only when this release corrects a build the organization exported from.

data[].payload.superseded.vintagestringalways present

The corrected (withdrawn) vintage id.

data[].payload.superseded.labelstringalways present

Its display label.

data[].payload.superseded.exportsintegeralways present

How many exports (API, CSV, XLSX) the organization made from it.

data[].payload.currentstring

The vintage now current.

data[].payload.current_labelstring

Its display label.

data[].payload.withdrawn_atstring

When the withdrawal was recorded (ISO 8601).

data[].payload.was_currentboolean

True when the withdrawn build was the current vintage.

data[].payload.exportedobject

Present only for an organization that exported from the withdrawn build.

data[].payload.exported.exportsintegeralways present

How many exports (API, CSV, XLSX) it made from it.

data[].payload.anchor_dayinteger

The organization's anchor day of the month.

data[].payload.effective_onstring (date)

The next anchor date (YYYY-MM-DD), when changes made now take effect.

data[].payload.removedinteger

Counties removed.

data[].payload.change_idstring (uuid)

The scheduled change's id.

data[].payload.limit"points" | "rate" | "csv" | "api"

Which limit: points (the monthly points allowance) or rate (the per-minute ceiling). csv and api are reserved for re-armed monthly quotas.

data[].payload.api_key_idstring (uuid)

The refused key's id; absent when the request was not made with a key.

data[].payload.key_namestring

The key's name (T108: written whenever the refusal was a key's).

data[].payload.orgstring

The organization's name.

data[].payload.recovered_atstring (date-time)

When the recovery was recorded.

data[].payload.changesarray of AcctPlanChangeItem

What changed now, in the Billing screen's order. Empty when the request only scheduled a change.

data[].payload.changes[].item"plan" | "seats" | "counties" | "api"always present

data[].payload.changes[].beforealways present

The value before the change.

data[].payload.changes[].afteralways present

The value after it.

data[].payload.effective_atstring (date-time) or null

When the changes in changes took effect; null when there are none.

data[].payload.scheduledobject or null

What the request scheduled for the end of the billing period; null when nothing.

data[].payload.scheduled.changesarray of AcctPlanChangeItemalways present

The changes scheduled.

data[].payload.scheduled.changes[].item"plan" | "seats" | "counties" | "api"always present

data[].payload.scheduled.changes[].beforealways present

The value before the change.

data[].payload.scheduled.changes[].afteralways present

The value after it.

data[].payload.scheduled.effective_atstring (date-time) or nullalways present

The end of the current billing period, when they take effect.

data[].payload.planstring

The new plan's display name.

data[].payload.detailstring

A sentence: how many counties were read-locked and members became free members.

data[].payload.reasonstring

Why the composite ran (an internal label).

data[].payload.emailstring

The leaver's email address.

data[].payload.role"owner" | "admin" | "member"

The role they held.

data[].payload.request_idstring (uuid)

The join request's id (approve or deny it under /v2/account/join-requests).

data[].payload.approvedboolean

True when approved (the only value written today; a denial writes no notification).

data[].payload.claimantstring

The claimant's email address.

data[].payload.completes_atstring (date)

The date the claim completes unless an owner signs in first (YYYY-MM-DD).

data[].payload.countystring

The trial county's name.

data[].payload.fipsstring

Its 5-digit FIPS code.

data[].payload.expires_atstring (date)

The trial's last date (YYYY-MM-DD).

data[].payload.titlestring

The announcement's title.

data[].payload.bodystring

The announcement's text.

data[].payload.announcement_idstring (uuid)

The announcement's id.

data[].payload.keysarray of AcctNotificationKeyListed

The person's active API keys when the password changed, every organization (empty when none; absent on rows written before T110).

data[].payload.keys[].namestringalways present

The key's name.

data[].payload.keys[].key_prefixstringalways present

The key's first characters.

data[].payload.keys[].key_last4string or nullalways present

The key's last four characters; null for a key minted before T110.

data[].payload.keys[].modestringalways present

live or sandbox.

data[].payload.keys[].organizationstring

The organization the key belongs to (password_changed only).

data[].payload.keys[].created_atstring (date-time)

When it was minted (password_changed only).

data[].payload.keys[].last_used_atstring (date-time) or null

When it last authenticated a request; null if never (password_changed only).

data[].payload.keys[].holderstring or null

The holder's address (keys_revoked only).

data[].payload.shedinteger

Counties released (read-locked).

data[].payload.countinteger

How many keys.

data[].payload.ticket_idstring (uuid)

The support request's id.

data[].payload.ticket_refstring

Its first eight characters, as the mails name it.

unreadintegeralways present

The badge: unread, undismissed notifications in total (may exceed what data holds).

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

200 success

How many were marked.

As application/json.

readintegeralways present

Notifications newly marked read.

400 error

Bad Request. Codes: malformed_json (the body is not valid JSON, or uses an unsupported content encoding).

As application/problem+json.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it). A sandbox key: sandbox_read_only (it may write only clusters).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

413 error

Payload Too Large. Codes: body_too_large (the body is over this endpoint's 8 KB limit; the body carries limit_bytes).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

200 success

The notification's id and read time.

As application/json.

idstring (uuid)always present

The notification id.

read_atstring (date-time)always present

When it was (first) marked read.

400 error

Bad Request. Codes: malformed_json (the body is not valid JSON, or uses an unsupported content encoding).

As application/problem+json.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it). A sandbox key: sandbox_read_only (it may write only clusters).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own), notification_not_found (no such notification for this person in this organization; also a non-uuid id answers not_found).

As application/problem+json.

413 error

Payload Too Large. Codes: body_too_large (the body is over this endpoint's 8 KB limit; the body carries limit_bytes).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

202 success

Accepted.

As application/json.

recordedinteger

Events written (0 while PRODUCT_EVENTS is off).

product_events"on" | "off"

The switch.

400 error

Bad Request. Codes: events_invalid (not 1 to 50 events of name screen_opened and a route family; index names the first bad entry), malformed_json.

As application/problem+json.

401 error

Unauthorized. Codes: unauthenticated (no session, or the session is not live).

As application/problem+json.

403 error

Forbidden. Codes: session_required (an API key), no_membership, account_suspended, org_suspended, org_closed, terms_acceptance_required.

As application/problem+json.

429 error

Too Many Requests. Only rate_limited here, from this route's own ceiling (20 batches a minute per account, with Retry-After); a batch never spends the per-credential or per-organization ceilings of the other routes.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).