aps-docs-portal

This skill provides a step-by-step method to answer APS-related questions by navigating the documentation portal.

Behavior

1. When a user's first question is ambiguous or broad, ask one short clarifying question to identify their intent before diving into a long answer.
2. Always provide reference links with your answers.
3. Always attempt to answer APS-related questions directly.
4. Tailor depth to the visitor: Business gets summaries & ROI, Builder gets step-by-step, Developer gets REST schemas & auth flows. Ask if unsure.

Ground rules

• Never fetch aps.autodesk.com/en/docs/... (WebFetch, curl, or otherwise). The portal is a JavaScript SPA: every URL under it — valid or not — returns the same ~10 KB HTML shell. It contains no docs content and can't even tell you whether a URL exists.
• All content lives in two static places: the TOC JSON (developer.doc.config.autodesk.com) and the page HTML (developer.doc.autodesk.com). Use only these.
• Never show those CDN URLs to the user, and never hand-build portal links from CDN paths. Every portal link comes from column 1 of the TOC index (Step 3).
• Answer from the glossary alone when the question is only about terminology — no fetching needed.

---

Method: How to Answer an APS Question

Step 1 — Read the Glossary to Decode Jargon

If the question mentions an acronym you don't see here, look for its definition in the docs you fetch later.

APS Glossary

• APS: Autodesk Platform Services (formerly Forge)
• ACC: Autodesk Construction Cloud. Recent docs pages also say Forma for ACC services (e.g. "Forma Issues", "Forma Data Management"); the separate Forma Site Design API is forma_v1.
• BIM 360: Legacy construction management platform (predecessor to ACC)
• MD: Model Derivative API — translates design files into viewable formats (SVF/SVF2)
• DM: Data Management API — manages files, folders, and storage (OSS, BIM 360, ACC hubs)
• URN: Base64-encoded resource identifier used across APS APIs
• SVF/SVF2: Scalable Viewing Format — optimized 3D web viewing format produced by Model Derivative and consumed exclusively by the APS Viewer SDK, similar concept to glTF format with openCTM compression
• OSS: Object Storage Service — APS cloud storage for uploading design files
• Webhook: Server-to-server callback triggered by APS events (e.g., model translation complete, file version added)
• 2LO/3LO: Two-legged / three-legged OAuth authentication flows
• Hub: Top-level container in Data Management (maps to an ACC or BIM 360 account)
• Manifest: Translation status and output metadata from Model Derivative
• ACAD: AutoCAD — Autodesk's flagship 2D/3D CAD drafting software (produces .dwg files)
• Civil: Autodesk Civil 3D — civil engineering design software for infrastructure projects
• Revit: Autodesk Revit — BIM software for architecture, structure, and MEP design (produces .rvt files)
• Build: Autodesk Build — construction management module within ACC (field management, cost, etc.)
• IFC: Industry Foundation Classes — open standard file format for BIM data exchange between tools
• RFI: Request for Information — formal question submitted during construction, tracked in ACC/BIM 360
• SSA: Secure Service Accounts — a server-to-server identity that signs a JWT assertion with its private key and exchanges it for a three-legged (user-context) access token, without any interactive sign-in
• AEC: Architecture, Engineering, and Construction — the industry vertical APS primarily serves
• AECDM: AEC Data Model API — unified API for accessing design and construction data across ACC
• DX: Data Exchange — API for exchanging design data between applications in a neutral format
• Auth: Authentication — APS OAuth flows including 2LO, 3LO, PKCE, PAT (Personal Access Tokens), and SSA

Translation Cost (Model Derivative API): Complex jobs are Revit (.rvt), IFC, and Navisworks (.nwd/.nwc). Everything else is a simple job.

---

Step 2 — Identify the Relevant APIs

Use the source table below to pick the TOC(s) to open. For example:

• "file changes" → Data Management events, documented in the Webhooks API (webhooks_v1)
• "model translate" → Model Derivative API (model-derivative_v2)
• "digital twin" → Tandem (tandem_v1)
• "events/callbacks" → Webhooks API (webhooks_v1) — all event families (dm.*, issue.*, extraction.*, cost, reviews, …) live under its reference/events/ section

Source ID	API Title
acc_v1	Autodesk Construction Cloud APIs
aecdatamodel_v1	AEC Data Model API
applications_v1	Application Management API
bim360_v1	BIM 360 API
buildingconnected_v2	BuildingConnected & TradeTapp APIs
data_v2	Data Management API
dataviz_v1	Data Visualization
design-automation_v3	Automation API
dx-sdk-beta_v7.2.0	Data Exchange .NET SDK v7.2.0
fdxgraph_v1	Data Exchange GraphQL
flow_graph_engine_v1	Flow Graph Engine
forma_v1	Forma Site Design API (Beta)
informed-design_v1	Informed Design API (Beta)
insights_v1	Business Success Plan Reporting API
mfgdataapi_v3	Manufacturing Data Model API
model-derivative_v2	Model Derivative API
oauth_v2	Authentication API
parameters_v1	Parameters API
profile_v2	User Profile API
ssa_v1	Secure Service Account API
sustainability_v3	Sustainability Data API
tandem_v1	Tandem Data
tokenflex_v1	Token Flex Usage Data API
vaultdataapi_v2	Vault Data API
viewer_v7	Viewer
webhooks_v1	Webhooks API

Portal URL ↔ source ID: a portal URL https://aps.autodesk.com/en/docs/{api}/{version}/… always belongs to source ID {api}_{version} (e.g. /en/docs/acc/v1/… → acc_v1).

---

Step 3 — Download and Index the TOC (once per source)

Download each TOC you need once to a local file, then query the file. TOCs are large (ACC ≈ 140 KB, Data Exchange SDK ≈ 650 KB) — never print one raw, and don't re-download it.

curl -sL --create-dirs -o /tmp/aps-docs/acc_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/acc_v1.json"

Turn it into a flat index — one line per page: portal URL, title, and CDN source path, tab-separated:

jq -r '.url_path as $api | .doc_version as $v | def w($p): ($p + [.url_path // ""]) as $q | (if .source then "https://aps.autodesk.com/en/docs/\($api)/\($v)/\($q | map(select(. != "")) | join("/"))/\t\(.display_name)\t\(.source)" else empty end), (.children[]? | w($q)); .children[] | w([])' /tmp/aps-docs/acc_v1.json | grep -i 'issues'

Filter with grep -i on topic words; for a quick look at the structure, list the top-level sections with jq -r '.children[] | .url_path' FILE.

Example output:

https://aps.autodesk.com/en/docs/acc/v1/reference/http/issues-issues-GET/	GET issues	acs-acs-api-documentation-main-52/acc/v1/reference/http/issues/issues-GET.html

• Column 1 is the only valid portal link for that page. The portal resolves pages by the TOC's url_path values, not by the CDN file path, and the two often differ:

  CDN source path (after the repo slug)	Correct portal URL
  acc/v1/reference/http/issues/issues-GET.html	…/en/docs/acc/v1/reference/http/issues-issues-GET/
  model-derivative/v2/overview.html	…/en/docs/model-derivative/v2/developers_guide/overview/
  dx-sdk-beta/v1/v720/developers_guide/overview.html	…/en/docs/dx-sdk-beta/v7.2.0/developers_guide/overview/

• Column 3 is the page HTML path for Step 4.

• Given a portal URL (from the user or elsewhere): map it to its source ID (Step 2), index that TOC, and grep -F for the exact URL (with trailing /) to get its CDN source. Given a CDN URL: grep -F the path after bPlouYTd/ in column 3; if the repo slug is outdated, grep for the tail of the path instead.

• Section nodes without a page have no source, so they aren't in the index; link to their first child page instead.

---

Step 4 — Fetch Each Page Once, Extract Locally

Download the page HTML once, then run every extraction on the local file:

curl -sL -o /tmp/aps-docs/page.html "https://developer.doc.autodesk.com/bPlouYTd/{source}"

# 1. Structure first — tells you whether it's a reference page, guide, tutorial, or event list
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'h1, h2, h3, h4'

# 2. Prose, lists, and code samples
htmlq -f /tmp/aps-docs/page.html -r 'script, style, noscript' --text 'p, li, pre'

# 3. Tables (parameters, response fields, status codes) — one row per line
htmlq -f /tmp/aps-docs/page.html -r 'script, style' --text 'tr' | sed 's/^[[:space:]]*//' | grep -v '^$'

Notes:

• REST reference pages start with a table holding Method and URI, Authentication Context (e.g. "User context required"), and Required OAuth Scopes; then headers, URI/query parameters, request body, and response body tables. Required fields are marked with *. Grep the table rows for the parameter or field you need (e.g. grep -A2 '^limit') instead of reading the whole page.
• Use a different file name per page if you need several at once.
• Select tr, not td/table: nested cells otherwise repeat the same text several times.

---

Step 5 — Compile Into a Coherent Answer

1. Define the terms (from the glossary or what you found in the docs)
2. Explain the relevant APIs and endpoints (from the TOC and fetched pages)
3. List the specific events, parameters, or features (from the reference pages — quote values exactly)
4. Provide reference links — portal URLs copied from index column 1 only
5. Include a practical example if applicable (curl command, code snippet, etc.)

---

Gotchas

• htmlq is not pre-installed — install it with brew install htmlq (macOS) or cargo install htmlq. If unavailable, fall back to python3 -c with html.parser.
• The TOC JSON URL fails if the source ID is wrong — it is case-sensitive and versioned (data_v2, not data). Use the table in Step 2.
• Old CDN repo slugs keep resolving but serve stale content — always take the source path from the current TOC rather than reusing a path from memory or from an older answer.
• Webhook events are documented only in webhooks_v1, under reference/events/{family}/ (e.g. data_management_events/dm.version.added/). Data Management events use the dm. prefix; ACC Issues events are versioned (issue.created-1.0).

---

Worked Example: "What webhooks are available for when a file changes?"

Step 1 — Glossary. A webhook is a server-to-server callback. Data Management handles files in OSS, BIM 360 Docs, and ACC Docs.

Step 2 — Identify APIs. File events are Data Management events, documented in the Webhooks API (webhooks_v1).

Step 3 — Index the TOC.

curl -sL --create-dirs -o /tmp/aps-docs/webhooks_v1.json "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json"
jq -r '<index filter from Step 3>' /tmp/aps-docs/webhooks_v1.json | grep 'data_management_events'

This yields one line per event — dm.version.added, dm.version.modified, dm.version.deleted, dm.version.moved, dm.version.copied, dm.lineage.reserved, dm.lineage.unreserved, dm.lineage.updated, dm.folder.added, dm.folder.modified, dm.folder.deleted, dm.folder.purged, dm.folder.moved, dm.folder.copied, dm.operation.started, dm.operation.completed, and more — each with its portal URL and source path.

Step 4 — Fetch the pages you need (e.g. the dm.version.added page from column 3) and extract headings, then the payload table.

Step 5 — Compile.

• dm.version.added — "When a new version of an item is added to a Folder" (scope: folder)
• dm.version.modified / dm.version.deleted / dm.version.moved / dm.version.copied — version changes
• dm.folder.* — folder changes

Links (copied from column 1):

• Data Management events
• dm.version.added
• Webhooks API overview