Admin interest onboarding
These routes turn the interest picker on or off, set the official guild and the share of older accounts that must finish it, and curate its regions and options. Every route on this page requires interest_onboarding:manage and records an Admin audit entry with target type interest_onboarding, reads included. Every route returns the interest onboarding admin object.
The picker lives in the instance configuration under the interest_onboarding_config key, at most 20 regions of at most 40 options each, and no public instance route returns it. Writes are saved with a compare-and-set. A country belongs to at most one region and at most one region is the default, so the region a request resolves to never depends on list order. A value outside its range, or a write that breaks one of these rules, returns 400 INVALID_FORM_BODY. An unknown region or option returns 404 NOT_FOUND.
Interest onboarding settings object
Section titled “Interest onboarding settings object”| Field | Type | Description |
|---|---|---|
| enabled | boolean | Whether the picker is on |
| enabled_since | ?ISO8601 timestamp | When the picker was first turned on, null while it never was |
| official_guild_id | ?snowflake | The guild every account that finishes the picker joins first, outside the guild cap; null for none |
| existing_accounts_rollout_basis_points | integer | The share of accounts created before enabled_since that must finish the picker, in basis points (0-10000) |
The picker starts off, with no official guild and a rollout share of 0. The first turn-on stamps enabled_since; turning it off and on again keeps it. The rollout share picks accounts by a stable bucket of the account ID, so raising it keeps every account a smaller share reached.
Interest option admin object
Section titled “Interest option admin object”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the option |
| name | string | The card title (1-40 characters) |
| group | ?string | The heading the card is listed under (1-40 characters), null for none |
| asset | ?string | The logo hash, served at branding/cosmetic-interest-{id}/{asset}.webp; null for none |
| guild_ids | array[snowflake] | The guilds a chosen option joins (1-5) |
| position | integer | The order in the region, lowest first (0-999) |
| enabled | boolean | Whether the option is shown |
Interest region admin object
Section titled “Interest region admin object”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the region |
| name | string | The region label, also shown in the region switcher (1-64 characters) |
| countries | array[string] | Upper case ISO 3166-1 alpha-2 codes of the IP countries that get the region, at most 250 |
| languages | array[string] | Lower case app languages, such as tr, that get the region when no region lists the IP country, at most 20 |
| is_default | boolean | Whether the region is shown when neither the country nor the language matches |
| enabled | boolean | Whether the region is shown |
| options | array[interest option admin object] | Every option, disabled ones included, in admin order |
Interest onboarding admin object
Section titled “Interest onboarding admin object”| Field | Type | Description |
|---|---|---|
| settings | interest onboarding settings object | The switch, the official guild and the rollout share |
| regions | array[interest region admin object] | Every region, disabled ones included |
Get interest onboarding
Section titled “Get interest onboarding”GET/v1/admin/interest-onboardingReturns the interest onboarding admin object, read from storage.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The picker was returned |
| 403 | error response | The caller lacks interest_onboarding:manage |
Side effects
Section titled “Side effects”One entry is recorded with action view_interest_onboarding, target ID 0, and metadata key result_count, the number of regions.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Update interest onboarding settings
Section titled “Update interest onboarding settings”PATCH/v1/admin/interest-onboarding/settingsTurns the picker on or off, sets the official guild and the rollout share. At least one field is required; an omitted field stays as it is. Accounts created since the first turn-on must finish the picker within 30 days of being created; accounts created before it must finish it once the rollout share reaches them.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| enabled? | boolean | On shows the picker, off hides it |
| official_guild? | ?string | An invite code, an invite link or a guild ID (1-100 characters); the guild ID is stored. Null turns it off |
| existing_accounts_rollout_basis_points? | integer | The share of older accounts that must finish the picker (0-10000) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The settings were saved |
| 400 | error response | A value is outside its range, the body is empty, or the guild is unknown or has invites turned off |
| 403 | error response | The caller lacks interest_onboarding:manage |
Side effects
Section titled “Side effects”One entry is recorded with action update_interest_onboarding_settings, target ID 0, and a <field>_old and <field>_new metadata key for every settings field it changed.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Create interest region
Section titled “Create interest region”POST/v1/admin/interest-onboarding/regionsAdds a region with no options.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| name | string | The region label (1-64 characters) |
| countries? | array[string] | Two-letter country codes, in any case, without repeats (default empty) |
| languages? | array[string] | Two or three letter language codes, in any case, without repeats (default empty) |
| is_default? | boolean | Whether the region is the default (default false) |
| enabled? | boolean | Whether the region is on (default true) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The region was created |
| 400 | error response | A value is outside its range, 20 regions exist, a country is in another region, or another region is the default |
| 403 | error response | The caller lacks interest_onboarding:manage |
Side effects
Section titled “Side effects”One entry is recorded with action create_interest_region, the ID of the region as target ID, and metadata keys name, countries, languages, is_default and enabled; lists are joined with commas.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Update interest region
Section titled “Update interest region”PATCH/v1/admin/interest-onboarding/regions/{region_id}Changes a region. Any field of the create body is optional, and at least one is required; an omitted field stays as it is.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The ID of the region |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The region was saved |
| 400 | error response | A value is outside its range, the body is empty, a country is in another region, or another region is the default |
| 403 | error response | The caller lacks interest_onboarding:manage |
| 404 | error response | No region has the ID and the request returns NOT_FOUND |
Side effects
Section titled “Side effects”One entry is recorded with action update_interest_region, the ID of the region as target ID, and a <field>_old and <field>_new metadata key for every field it changed; lists are joined with commas.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Delete interest region
Section titled “Delete interest region”DELETE/v1/admin/interest-onboarding/regions/{region_id}Removes a region with its options. Their logos stay in storage.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The ID of the region |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The region was removed |
| 403 | error response | The caller lacks interest_onboarding:manage |
| 404 | error response | No region has the ID and the request returns NOT_FOUND |
Side effects
Section titled “Side effects”One entry is recorded with action delete_interest_region, the ID of the region as target ID, and metadata keys name and option_count.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Create interest option
Section titled “Create interest option”POST/v1/admin/interest-onboarding/regions/{region_id}/optionsAdds an option with its logo to a region. A guild is refused when it is unknown or has invites turned off.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The ID of the region |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| name | string | The card title (1-40 characters) |
| group? | ?string | The heading the card is listed under (1-40 characters), such as Games (default null) |
| asset | string | A base64 PNG, APNG or WebP logo, 96-480 pixels each side, at most 512 KB; SVG is refused |
| guilds | array[string] | 1-5 invite codes, invite links or guild IDs (1-100 characters each), without repeats; the guild IDs are stored |
| position? | integer | The order in the region (0-999, default 0) |
| enabled? | boolean | Whether the option is shown (default true) |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The option was created |
| 400 | error response | A value is outside its range, the logo or a guild is refused, or the region has 40 options |
| 403 | error response | The caller lacks interest_onboarding:manage |
| 404 | error response | No region has the ID and the request returns NOT_FOUND |
Side effects
Section titled “Side effects”One entry is recorded with action create_interest_option, the ID of the option as target ID, and metadata keys region_id, name, group when set, guild_ids, position, enabled and asset. A failed save removes the uploaded logo.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Update interest option
Section titled “Update interest option”PATCH/v1/admin/interest-onboarding/regions/{region_id}/options/{option_id}Changes an option. Any field of the create body is optional, and at least one is required; an omitted field stays as it is. A new asset replaces the current logo and a null asset removes it.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The ID of the region |
| option_id | snowflake | The ID of the option |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The option was saved |
| 400 | error response | A value is outside its range, the body is empty, or the logo or a guild is refused |
| 403 | error response | The caller lacks interest_onboarding:manage |
| 404 | error response | No region or option has the ID and the request returns NOT_FOUND |
Side effects
Section titled “Side effects”One entry is recorded with action update_interest_option, the ID of the option as target ID, metadata key region_id, and a <field>_old and <field>_new metadata key for every field it changed.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.
Delete interest option
Section titled “Delete interest option”DELETE/v1/admin/interest-onboarding/regions/{region_id}/options/{option_id}Removes an option. Members who joined its guilds stay, and its logo stays in storage.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| region_id | snowflake | The ID of the region |
| option_id | snowflake | The ID of the option |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | interest onboarding admin object | The option was removed |
| 403 | error response | The caller lacks interest_onboarding:manage |
| 404 | error response | No region or option has the ID and the request returns NOT_FOUND |
Side effects
Section titled “Side effects”One entry is recorded with action delete_interest_option, the ID of the option as target ID, and metadata keys region_id, name and guild_ids.
Rate limit
Section titled “Rate limit”60 requests per minute for each authenticated user, on the admin:interest_onboarding bucket.