### Vendor Item Components and Socket Plug Stack Sizes Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds DestinyVendorItemComponentSet for Vendor sale items and includes stack size properties for socket plugs. ```APIDOC 2024-10-08 Update for Episode: Revenant: - Added `DestinyVendorItemComponentSet` to return `DestinyItemComponent` objects for Vendor sale items. - Request the `itemComponents` with the `ItemCommonData` component type. - `DestinyItemComponent.state` provides Deepsight red-border status. - `DestinyItemComponent.tooltipNotificationIndexes` provides tooltips. - Added `stackSize` and `maxStackSize` to socket plugs for tracking brewed potions. ``` -------------------------------- ### Destiny 2 String Variable Placeholders Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Explains the format for string variable placeholders used in Destiny 2 definitions and how clients can resolve them using API data. ```APIDOC String Variable Placeholders: String variable placeholders are formatted as {var:1234567890} within Destiny definition localized strings. Clients can request the new StringVariables component via the D2 Profile API to obtain per-character integer values by hash. These integer values can then be used to replace the {var:(hash)} placeholders in localized strings. ``` -------------------------------- ### InsertSocketPlugFree API Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Introduces the InsertSocketPlugFree API for free and reversible socket actions, such as Armor 2.0 mods and weapon perks. It has restrictions on which plugs can be overwritten and is rate-limited to 2 actions per-second per-user. ```APIDOC InsertSocketPlugFree API: - Allows 'free and reversible' socket actions (Armor 2.0 mods, Weapon perks, Stasis abilities, Shaders, Ornaments, Ghost Projections). - Restrictions: - Only 'randomized' or 'reusable' socket plugs with no 'insertion material requirements' are allowed. - Cannot overwrite a 'non-free' plug with a 'free' plug (e.g., replacing a Weapon mod with an 'Empty Socket Mod'). - 3rd-party apps cannot spend currencies for socket actions (e.g., Masterwork tiers, Weapon mods, Armor 1.0 mods, Ghost 2.0 mods, Ship Transmat effects). - Destiny2CoreSettings includes new hash arrays for restrictions: - insertPlugFreeProtectedPlugItemHashes: Protected plug item hashes that cannot be overwritten (e.g., Riven's Curse, Transcendent Blessing mods). - insertPlugFreeBlockedSocketTypeHashes: Blocked socket type hashes that cannot be changed (e.g., Weapon 'Kill Tracker' sockets). - Rate Limiting: - Initially rate-limited to 2 socket actions per-second, per-user. - Rate can be adjusted based on feedback and service stability. ``` -------------------------------- ### Epic Games Account Support Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Notes the addition of support for Epic Games accounts. ```APIDOC 2022-08-23 Update for the Season of Plunder: - Added Support for Epic Games accounts. ``` -------------------------------- ### API Error Handling for Environment Downtime Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Describes the behavior when the Bungie API environment is unavailable, resulting in static HTML error pages being returned for API requests. Clients should implement robust error handling for these scenarios. ```APIDOC Environment Downtime Behavior: - When the API environment is down, requests may return static HTML error pages. - This is an undesirable side effect of environmental issues. - Clients must handle these HTML responses gracefully, implementing their own messaging and error handling logic. Example Scenario: If an API request normally returns JSON, but due to downtime returns an HTML page: Response Status: 5xx (or other error codes) Response Body: HTML content indicating an error page. Client Action: Detect HTML response, display user-friendly error message, retry later. ``` -------------------------------- ### Bungie API URL Formatting and Redirection Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Ensures correct API endpoint usage by specifying the preferred domain and URL structure to prevent unexpected redirections and loss of authorization headers. Always use 'www.bungie.net' and include a trailing slash. ```APIDOC API Endpoint Usage: - Use 'https://www.bungie.net' for all API requests. - Avoid 'https://bungie.net' as it may cause redirections and header loss. - Ensure all URLs terminate with a trailing slash ('/'). Example: Correct: https://www.bungie.net/Platform/... Incorrect: https://bungie.net/Platform/... Incorrect: https://www.bungie.net/Platform/... ``` -------------------------------- ### Bungie API User-Agent Header Best Practice Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Details the recommended format and purpose of the User-Agent header for requests made to the Bungie API. Including a User-Agent helps with metrics and potential direct contact for app owners. ```APIDOC User-Agent Header Best Practice: It is asked that clients send a User-Agent header as a best practice. Your agent string should include the app name and ap-id with an optional web url and/or email address. A suggested format is "AppName/Version AppId/appIdNum (+webUrl;contactEmail)". For example: User-Agent: Really Cool App/1.0 AppId/##### (+www.example.com;contact@example.com) This helps Bungie provide more detailed metrics and allows them to contact app owners if necessary, potentially preventing app disabling as a last resort. ``` -------------------------------- ### Destiny Sandbox and Objective Definitions Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Updates include new definitions for sandbox patterns, trait categories, and objective display styles. Deprecation warnings are added for outdated objective value styles, recommending the use of new properties. ```APIDOC DestinySandboxPatternDefinition: - New definition mapping and specification added. DestinyTraitCategoryDefinition: - Fixed traitHashes mapping to properly reference DestinyTraitDefinition. DestinyObjectiveDefinition: - Added deprecation warning to valueStyle, which is no longer populated. - Use inProgressValueStyle and completedValueStyle instead. - Added uiLabel and uiState properties. ``` -------------------------------- ### Season Pass Socket Overrides and Virtual Material Requirements Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Introduces support for socket override definitions and states on season passes, and adds support for virtual stack sizes on material requirements. ```APIDOC 2024-12-08 Update for the Dawning: - Added support for socket override definitions and states on season passes: - Added `socketOverrides` to `DestinyProgressionRewardItemQuantity` definitions to reference socket types and plug items. - Added `rewardItemSocketOverrideStates` to `DestinyProgression` for season pass rewards, including `rewardItemStats` for armor rolls and `itemState` for Deepsight red-border weapons. - Added support for virtual stack sizes on material requirements: - Added `hasVirtualStackSize` to `DestinyMaterialRequirement` definitions. - Added `materialRequirementSetStates` to `DestinyCurrenciesComponent` with the `CurrencyLookups` component, including `itemHash`, `count`, and `stackSize`. ``` -------------------------------- ### DestinyCharacterActivitiesComponent and Activity Interactables Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds `availableActivityInteractables` to `DestinyCharacterActivitiesComponent` to support Lost Sector activities and in-world interactables. ```APIDOC 2024-07-16 Update for Lost Sectors: - Added `availableActivityInteractables` to `DestinyCharacterActivitiesComponent`. - Supports Expert and Master Lost Sector activities. - Includes in-world activity interactables (totems). - Cross-reference with `availableActivities` for Director launchable activities. ``` -------------------------------- ### Destiny Material Requirements and Activity Definitions Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Material requirements can now have non-constant values, indicated by countIsConstant. Activity updates include activityWasStartedFromBeginning in DestinyPostGameCarnageReportData and a new DestinyActivityModeType for Offensive activities. ```APIDOC Material Requirements: - Added countIsConstant for constant count values. - Non-constant counts will have a value of 0 in the definition. - API support for non-constant counts is planned but has no ETA. DestinyPostGameCarnageReportData: - Added activityWasStartedFromBeginning as an alternative to startingPhaseIndex. DestinyActivityModeType: - Added Offensive enum value for activities. - Plan to add Master and Legend Lost Sector activity values soon. ``` -------------------------------- ### DestinySeasonDefinition, Guardian Ranks, and Commendations Updates Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Introduces new fields and enum values for Episodes, Guardian Ranks, Commendations, and activity types. ```APIDOC 2024-07-10 Update for The Final Shape: - Added `acts` to `DestinySeasonDefinition` for new Episodes. - Added an `isVisible` flag to `DestinyArtifactTierItem`. - Added a new `DestinyActivityModeType` enum value for 'Relic' activities. - Added a `recordTypeName` to `DestinyRecordDefinition`. - Replaced `obscuredString` with `obscuredName` and `obscuredDescription` on record definition state blocks. - Added `commendationNodePercentagesByHash` to `DestinySocialCommendationsComponent`. - Added a `tintedIcon` to `DestinySocialCommendationNodeDefinition`. - Added `guardianRankHashes` to `DestinyGuardianRankConstantsDefinition`. - Added the `renewedGuardianRank` to `DestinyProfileComponent`. ``` ```APIDOC 2023-02-28 Update for Lightfall: - Added Loadouts, Guardian Ranks, and Commendations! ``` -------------------------------- ### Destiny Data Definitions (Talent Grids, Sockets, Items) Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md This section covers key Destiny data definitions related to item customization and character progression. Talent Grids are largely deprecated but still relevant for character builds and subclasses. Sockets and Plugs are the primary means of item customization, replacing Talent Grids in many areas. ```APIDOC DestinyTalentGridDefinition - Represents the definition of a Talent Grid, including its nodes and perks. - Used for character builds and subclasses. DestinyItemSocketBlockDefinition - Defines the socket configuration for an item, including available plug slots. - A child property of DestinyInventoryItemDefinition. DestinyItemPlugDefinition - Defines a plug that can be inserted into an item's socket, providing customization. - A child property of DestinyInventoryItemDefinition. DestinyInventoryItemDefinition - The base definition for any inventory item, often containing references to socket blocks and plugs. ``` -------------------------------- ### News Article API Parameters and DestinyEventCardDefinition Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds new parameters to the News Article RSS API and introduces DestinyEventCardDefinition for seasonal event cards. ```APIDOC 2022-12-06 Update for the Season of the Seraph (cont.): - Added `categoryfilter` and `includebody` parameters to the `/Content/Rss/NewsArticle//` API for news content. ``` ```APIDOC 2022-07-19 Update for Solstice 2022: - Added `DestinyEventCardDefinition` for the new seasonal Event Card feature. - Event Card challenges root node has three child nodes (one for each character class), clients should respect node visibility. - Added new properties for `eventCardHashesOwned` and `activeEventCardHash` to `DestinyProfileComponent`. ``` -------------------------------- ### Destiny2 Core Operations (GetProfile, GetCharacter, GetItem) Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md These are the fundamental building blocks for Destiny data requests. They utilize a component-based system where you can specify desired data components via the '?components=' querystring parameter to reduce round trips and bandwidth usage. GetProfile is anticipated for most calls, while GetCharacter and GetItem are for specific known entities. ```APIDOC Destiny2.GetProfile(components: string) - Retrieves the player's Destiny profile information. - Parameters: - components: A comma-separated list of component types to include in the response (e.g., "CharacterInventories", "ProfileInventories", "CharacterActivities"). - Returns: A DestinyProfileResponse object containing the requested components. Destiny2.GetCharacter(characterId: string, components: string) - Retrieves specific character information. - Parameters: - characterId: The unique identifier for the character. - components: A comma-separated list of component types to include (e.g., "CharacterInventories", "CharacterEquipment"). - Returns: A DestinyCharacterResponse object. Destiny2.GetItem(itemId: string, components: string) - Retrieves information about a specific item. - Parameters: - itemId: The unique identifier for the item. - components: A comma-separated list of component types to include (e.g., "ItemSockets", "ItemPlugObjectives"). - Returns: A DestinyItemResponse object. ``` -------------------------------- ### Bungie API OpenAPI Extension Properties Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Details custom extension properties used in the Bungie API's OpenAPI specifications to provide richer metadata for client generation. These extensions clarify data mapping, mobile manifest tables, enum values, component dependencies, dictionary key types, and preview status. ```APIDOC x-mapped-definition: Description: Maps hash identifiers to a Manifest Database definition. This property reveals the type of Manifest Database definition it points to. It can be a single uint32, a List, or a Dictionary. Example: "uint32" Example: "List" Example: "Dictionary" ``` ```APIDOC x-mobile-manifest-name: Description: If populated, this is the name of the Mobile Manifest table that holds this data as a first-class entity. The existence of this field implies that this entity is a first-order Destiny Definition aggregate. Example: "DestinyInventoryItemDefinition" ``` ```APIDOC x-enum-values: Description: Provides identifiers and numeric values for enum members, along with documentation. This extension offers more detail than the base 'enum' property. Example: "[ { "identifier": "Red", "numericValue": 1, "description": "The color red" }, { "identifier": "Blue", "numericValue": 2, "description": "The color blue" } ]" ``` ```APIDOC x-destiny-component-type-dependency: Description: Indicates that an entity is only returned if its named Component Identifier is passed into GetProfile/GetCharacter/GetItem methods. This is part of the Destiny 2 API's component-based data retrieval system. Example: "100" (representing a specific component type) ``` ```APIDOC x-dictionary-key: Description: Specifies the intended type of a dictionary key when it's not a string, even if encoded as a string in JSON. Allows for strong typing and conversion. Example: "uint32" ``` ```APIDOC x-preview: Description: A boolean flag indicating that the associated Operation is not yet ready for production use. Further details on its readiness status must be obtained from separate documentation. Example: "true" ``` -------------------------------- ### DestinyActivityModeType and DestinyTraitDefinition Updates Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds new DestinyActivityModeType enum values for game modes and a displayHint string property to DestinyTraitDefinition. ```APIDOC 2022-05-24 Update for the Season of the Haunted: - Added new `DestinyActivityModeType` enum values for Zone Control, Rift, and Iron Banner: Rift. - Added a `displayHint` string property to `DestinyTraitDefinition`. - Added a `shouldShowLargeIcons` boolean property to `DestinyRecordDefinition`. - Added a new `DestinyVendorItemState` enum value for `Locked` sale items. ``` -------------------------------- ### Vendor Endpoint Reliability Advisory Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Informs users about temporary unreliability of the Vendor endpoint, with fixes planned for a future release (Forsaken). Users should anticipate inconsistent data until the update. ```APIDOC Vendor Endpoint Status: - Currently experiencing unreliability, showing incorrect items in certain situations. - A fix requiring significant work is scheduled to go live with the 'Forsaken' release. - The Vendor endpoint will be somewhat unreliable until that time. - Apologies for the inconvenience. ``` -------------------------------- ### Bungie API OAuth Scope Requirements Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Details the OAuth scope requirements for accessing specific Bungie API components. Explains which scopes are necessary for profile and character data, and how missing scopes or privacy settings affect returned data. ```APIDOC API Endpoint Data Access via OAuth Scopes: Certain Bungie API endpoints require specific OAuth scopes to access their full data components. Failure to provide the necessary scopes will result in those components not being returned, even if the request is otherwise authenticated. Key Scopes and Affected Components: - ReadDestinyVendorsAndAdvisors: Required for: - characterActivities - characterProgressions - kiosks - characterKiosks - ReadDestinyInventoryAndVault: Required for: - profileCurrencies - profileInventory - characterInventories - vendorReceipts General Considerations: - Privacy Settings: Users can mark certain data as private. Your application should always be prepared to handle situations where an expected component is not returned, regardless of scope, due to user privacy settings. - Error Handling: Implement robust error handling to gracefully manage missing components, potentially by informing the user or providing a fallback experience. - Future Spec Improvements: The API specification may be updated to better encode partial success scenarios related to OAuth scopes or privacy settings. Example Scenario: If a user has not granted the 'ReadDestinyInventoryAndVault' scope, requests to endpoints like GetProfile will succeed but will omit data for 'profileCurrencies', 'profileInventory', 'characterInventories', and 'vendorReceipts'. ``` -------------------------------- ### Destiny Item and Crafting Definitions Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Introduces new ItemState flags for crafted and deepsight weapons, and adds DestinyItemCraftingBlockDefinition for crafting recipe details. Includes recipeItemHash, craftingRequirements, and a new itemSubType for Glaive weapons. ```APIDOC ItemState: - Crafted: New flag for Shaped weapons. - HighlightedObjective: New flag for Deepsight weapons. DestinyItemCraftingBlockDefinition: - Added for more details in crafting recipe (Pattern) item definitions. DestinyItemInventoryBlockDefinition: - Added recipeItemHash for a reference to the crafted item's recipe (Pattern) definition. DestinyItemSocketEntryPlugItemRandomizedDefinition: - Added craftingRequirements for plugs used in crafting. - Note: 'Enhanced Trait' plug items have inventory.tierType value of Common (3) instead of Basic (2). DestinyItemSubType: - Added Glaive value for weapons. ``` -------------------------------- ### DestinyEventCardDefinition and Fireteam Finder Updates Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds new fields to DestinyEventCardDefinition for Heavy Metal event cards and fixes a Fireteam Finder error code to be unique. ```APIDOC 2025-05-09 Update for Rites of the Nine: - Added new fields to `DestinyEventCardDefinition` to support Heavy Metal event cards: - `eventCardCurrencyList` - `weeklyChallengesPresentationNodeHash` - `rewardProgressionHash` - Fixed the `FireteamFinderApplicantNotInGame` Fireteam Finder error code to be unique. ``` -------------------------------- ### Bungie Name Search API Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md New Bungie Name search APIs are available using POST requests, designed to handle special characters like colons, slashes, and angle brackets for more robust player name searches. ```APIDOC Bungie Name Search API: - Added new APIs using POST requests. - Supports special characters in player names (e.g., ':', '/', '<', '>'). ``` -------------------------------- ### Bungie Names and Cross Play Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Introduces Bungie Names and Bungie Friends features, likely related to cross-play initiatives and improved player identity management within the Destiny ecosystem. ```APIDOC Cross Play and Season of the Lost: - Added Bungie Names. - Added Bungie Friends. ``` -------------------------------- ### Destiny Crafting and Presentation Node Definitions Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Enhancements for crafting progress display, including craftingRootNodeHash and exoticCatalystsRootNodeHash in Destiny2CoreSettings. Adds 'craftables' as children of DestinyPresentationNodeDefinition and a new DestinyComponentType enum value. ```APIDOC Destiny2CoreSettings: - Added craftingRootNodeHash for display of Shaping progress. - exoticCatalystsRootNodeHash now includes unlock progress records for weapon shaping 'Patterns' and Exotic Catalysts. DestinyPresentationNodeDefinition: - Added 'craftables' (crafting recipe items) as children. DestinyComponentType: - Added Craftables enum value for use with GetProfile. DestinyProfileResponse: - Added characterCraftables state. Note: Only initial Shaping state is returned, not Reshaping state. ``` -------------------------------- ### Uninstanced Item Perk State Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Support added for perk state components on uninstanced items, primarily for tracking states like 'Mercy' usage on Trials of Osiris 'Passage' quest items. ```APIDOC Uninstanced Item Perks: - Added support for perk state components on uninstanced items. - Example: Trials of Osiris 'Passage' quest items to show 'Mercy' usage. ``` -------------------------------- ### Destiny Definition Attribute Mapping Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds missing hash-to-definition-type mapping attributes for many contract class properties, improving data integrity and lookup capabilities. ```APIDOC Definition Attribute Mapping: - Added hash-to-definition-type mapping attributes for many contract class properties. ``` -------------------------------- ### DestinyProfileResponse Timestamps and Equip Failure Reasons Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Adds new timestamps to DestinyProfileResponse for handling stale cached responses and updates EquipFailureReason enum values. ```APIDOC 2022-12-06 Update for the Season of the Seraph: - Added `responseMintedTimestamp` and `secondaryComponentsMintedTimestamp` to `DestinyProfileResponse` for handling stale cached responses from `Destiny2.GetProfile`. - Added new EquipFailureReason enum flag values and renamed `ItemNotOnCharacter` to `ItemWrapped`. ``` -------------------------------- ### Bungie Name and Stasis Energy Type Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Documentation added for the new Bungie Name search API and the Stasis Energy type enum value, enhancing player identification and game mechanics representation. ```APIDOC Bungie Name Search API: - Docs added for new API. Stasis Energy: - Added type enum value documentation. ``` -------------------------------- ### Destiny2 GetPublicMilestones Source: https://github.com/d2orbc/bungie-api-go/blob/main/api-src/README.md Retrieves information about current "Public" Milestones, which reflect activities a player can do in the game right now, agnostic to an individual player's state. This endpoint provides data similar to the former 'Advisors' but with matching Definition data. ```APIDOC Destiny2.GetPublicMilestones() - Fetches a list of current public milestones available in the game. - Returns: A DestinyPublicMilestonesResponse object containing milestone data. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.