docs: add API reference for the Symbols endpoint - #333
Conversation
Documents /api/v2/symbols, which lists the individual symbol files uploaded to a database. The endpoint was previously undocumented and only reachable at the deprecated /api/symbolDetails route. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Srwo6xf7eRjVWbX3E3ZL5j
There was a problem hiding this comment.
Pull request overview
Adds a missing API reference page for the Symbols “symbol file details” endpoint and wires it into the docs navigation so it’s discoverable under the API Reference section.
Changes:
- Adds a new API reference page documenting
GET https://app.bugsplat.com/api/v2/symbols, including examples and a response-fields table. - Updates
SUMMARY.mdto include the new Symbols page in the API Reference navigation. - Updates the API reference landing page (
api/README.md) to include a content-ref to the new Symbols page.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
SUMMARY.md |
Adds a navigation entry for the new Symbols API reference page. |
introduction/development/web-services/api/symbols.md |
New documentation page for GET /api/v2/symbols with examples and field descriptions. |
introduction/development/web-services/api/README.md |
Adds a content-ref link to symbols.md so it appears in the API reference index. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| Get a list of the individual symbol files that have been uploaded to a database. | ||
|
|
||
| This endpoint returns one row per symbol file. To list symbol stores grouped by application and version, along with their crash counts and retired/full dump flags, use the [Versions](versions.md) endpoint instead. |
There was a problem hiding this comment.
Fixed in 0007b84.
Added an explicit warning callout right under the intro:
Do not confuse this endpoint with the legacy
https://app.bugsplat.com/api/symbolsroute. Despite the similar name,/api/symbolsis a deprecated alias for the Versions endpoint and returns symbol stores grouped by application and version, not individual symbol files.
You were right that the page only compared against Versions by name and never named the route that actually collides. Since /api/symbols and /api/v2/symbols differ by one path segment and return different payloads, that is exactly the mistake worth heading off. Confirmed against the backend: api/symbols.php is a six-line shim that sets $useLegacyResponseFormat and requires api/versions_v2.php.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Srwo6xf7eRjVWbX3E3ZL5j
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
Suppressed comments (1)
introduction/development/web-services/api/symbols.md:13
- The PR description mentions a common confusion with the legacy
/api/symbolsroute. The intro currently only contrasts this endpoint withVersions, so readers may still miss that/api/symbolsand/api/v2/symbolsare different endpoints. Consider adding an explicit note calling out the legacy path to prevent accidental use of the wrong route.
This endpoint returns one row per symbol file. To list symbol stores grouped by application and version, along with their crash counts and retired/full dump flags, use the [Versions](versions.md) endpoint instead.
|
|
||
| <mark style="color:blue;">`GET`</mark> `https://app.bugsplat.com/api/v2/symbols` | ||
|
|
||
| Returns the symbol files uploaded to a given database. This query supports paging, filtering, and sorting. All of the property keys in the rows object can be used as column values for filtering and sorting, e.g., application, version, moduleName, size, etc. Results are sorted by `lastModified` unless a `sortdatafield` is supplied. |
There was a problem hiding this comment.
Fixed in 0007b84. Reworded to:
All of the property keys on the row objects returned in
rowscan be used as column values for filtering and sorting…
The original phrasing was inherited from crashes.md, which has the same imprecision, but there is no reason to propagate it onto a new page.
| { | ||
| "database": "fred", | ||
| "pageData": [], | ||
| "rows": [ |
There was a problem hiding this comment.
Declined (page) / Fixed (description).
The page is correct as written; the PR description was stale, and that is what you were reading. I have rewritten it.
/api/v2/symbols genuinely returns the lowercase envelope with size as a number. Verified live against a local stack just now:
GET /api/v2/symbols?database=UnitTests -> {"database":"unittests","pageData":[],"rows":[{..."size":1047851...}]}
GET /api/symbolDetails?database=UnitTests -> {"Database":"unittests","PageData":null,"Rows":[{..."size":"1047851"...}]}
So the deprecation note attributing the capitalized envelope and string size to /api/symbolDetails is accurate.
The confusion is mine: I opened this PR describing the response before BugSplat-Git/webroot#1894 gained the lowercase envelope, updated the page in dc69bbd, and never updated the PR description to match. Both descriptions now describe the shipped behavior.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Srwo6xf7eRjVWbX3E3ZL5j
Summary
Adds a missing API reference page for the symbol details endpoint. It was live but completely undocumented — no page, no
SUMMARY.mdentry, and no mention anywhere in the docs.Pairs with BugSplat-Git/webroot#1894, which exposes the endpoint at
/api/v2/symbolswith a lowercase response envelope. Merge that first — this page documents the new route as canonical.Changes
introduction/development/web-services/api/symbols.mddocumentingGET /api/v2/symbolsSUMMARY.md: new Symbols entry under 🔌 API Reference, between Support Response and User (GDPR)introduction/development/web-services/api/README.md: new content-ref in the same positionContent notes
/api/symbolsroute, which despite the near-identical name is a deprecated alias for Versions and returns symbol stores rather than individual symbol files. That collision is easy to trip over, so it is called out explicitly rather than left implicit.database/pageData/rows, withsizeas a number. This matches/api/v2/versions.guid,symbolType,lastAccessedand its link to symbol expiry)./api/symbolDetailsusers at the new route, and spelling out that the deprecated route still returns the old capitalizedDatabase/PageData/Rowsenvelope withsizeas a string.Verification
Every documented behavior was exercised against a local BugSplat stack rather than inferred:
GET /api/v2/symbolsresponsepagesize,sortdatafield/sortorder, and thefilterscount/filterdatafield0/filtercondition0/filtervalue0filter syntax all confirmed workingdatabaseis optional and falls back to the current database, so it is documented without a required marker/api/symbolDetailsroute still returns the capitalized envelope, so the deprecation note is accurate../paging-filtering-and-grouping.md,versions.md×2,../../working-with-symbol-files/managing-symbol-storage.md) resolve to existing filesSample values in the example use the docs' usual Fred / myConsoleCrasher convention.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Srwo6xf7eRjVWbX3E3ZL5j