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.

---

Method: How to Answer an APS Question

Follow these steps in order. Each step feeds into the next.

Step 1 — Read the Glossary to Decode Jargon

The glossary below covers the acronyms and terms used across APS docs. Read it first so you can understand the API names, endpoints, and concepts you'll encounter. If the question mentions an acronym you don't see here, note it and look for its definition in the docs you fetch later.

APS Glossary

• APS: Autodesk Platform Services (formerly Forge)
• ACC: Autodesk Construction Cloud
• 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 — service-level authentication for server-to-server APS access
• 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 determine which APS API documentation covers the question. For example:

• "file changes" → Data Management API (data_v2) for OSS/BIM 360 file events, ACC API (acc_v1) for ACC document events
• "model translate" → Model Derivative API (model-derivative_v2)
• "digital twin" → Tandem (tandem_v1)
• "events/callbacks" → Webhooks API (webhooks_v1) is the umbrella system, but specific events are documented under each API's webhook reference

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

---

Step 3 — Build a Breadcrumb from the TOC

Each API source has a JSON Table-of-Contents at:

https://developer.doc.config.autodesk.com/bPlouYTd/{source_id}

Use jq to navigate the TOC and find the pages you need. The TOC is structured as a tree of children nodes, each with display_name, url_path, and optionally a source field (the CDN path to the HTML page).

Navigate the TOC tree

# List top-level sections of an API
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '.children[] | {display_name, url_path}'

# Drill into a section
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '.children[] | select(.url_path == "developers_guide").children[] | {display_name, url_path, source}'

# Find all pages with their CDN source paths (recursive)
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '[.. | objects | select(.source? and .url_path?)] | .[] | {display_name, url_path, source}'

# Find pages whose name suggests "file change" or "document" events
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '[.. | objects | select(.source? and .display_name?)] | .[] | select(.display_name | test("file|document|version|item|folder"; "i")) | {display_name, source}'

URL structure

• TOC JSON: https://developer.doc.config.autodesk.com/bPlouYTd/{source}.json where {source} is a source ID from the Step 2 table
• Static HTML pages: https://developer.doc.autodesk.com/bPlouYTd/{path_from_toc} (the source field from each TOC node)
• APS Portal page: the human-readable documentation on aps.autodesk.com (JavaScript SPA — do not scrape)

Converting a Static CDN URL to an APS Portal URL

When you need to generate a clickable link for the user:

1. Strip the repo-slug — the first path segment after bPlouYTd/ (always has a numeric suffix, e.g. A360-platform-viewing-docs-master-633741).
2. The api-name is the next segment — e.g. model-derivative, design-automation.
3. Remove any duplicate api-name — the api-name sometimes appears again deeper in the path. If it does, remove that duplicate folder.
4. Strip .html from the page filename and add a trailing /.
5. Prepend https://aps.autodesk.com/en/docs/.

Examples:

Static CDN path (after bPlouYTd/)	Portal URL
…-633741/model-derivative/v2/reference/http/model-derivative/formats-GET.html	https://aps.autodesk.com/en/docs/model-derivative/v2/reference/http/formats-GET/
…-636116/design-automation/v3/reference/http/design-automation/activities-GET.html	https://aps.autodesk.com/en/docs/design-automation/v3/reference/http/activities-GET/
…-633590/aecdatamodel/v1/developers_guide/overview.html	https://aps.autodesk.com/en/docs/aecdatamodel/v1/developers_guide/overview/

Note: the duplicate api-name folder does not always exist — simpler paths like aecdatamodel/v1/developers_guide/overview.html have no duplicate. Only remove it if the api-name appears as a path segment again after {version}/.

---

Step 4 — Get headings to understand page structure (MANDATORY — run this first)

Do not skip this step. Before extracting any content, determine what kind of page you are looking at. Run this command first on every page you fetched from the TOC:

curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'h1, h2, h3, h4'

This reveals the page structure (a reference table, a tutorial, an overview, a list of events, etc.) and tells you which extraction approach to use in the following steps.

---

Step 5 — Retrieve visible text from a page

Run this after Step 4. Use this to get the full visible text content of a page:

curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style, noscript' --text '*'

---

Step 6 — Extract specific sections (optional)

Only run this if Step 5 did not capture enough detail. Choose the selector(s) that match the content type you identified in Step 4:

# Get paragraphs and list items (main content)
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'p, li'

# Get code samples (endpoint URLs, request/response bodies)
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'pre, code'

# Get tables (parameter tables, status codes, response fields)
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'table, th, td, tr'

Deduplication requirement: HTML tables often produce duplicated text because <td> cells contain nested elements and the CSS selector matches both the cell and its children. Whenever you extract tables, you must pipe through sort -u or sort -u | awk '!seen[$0]++' to remove duplicates. If the table is still too noisy, prefer fetching individual sub-pages (found in the TOC) instead of the summary table.

---

Step 7 — Compile Into a Coherent Answer

After collecting the content, synthesize it into a clear 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 or features (from the reference pages)
4. Provide reference links (convert CDN URLs to portal URLs for clickable links)
5. Include a practical example if applicable (curl command, code snippet, etc.)

---

Gotchas

• htmlq is not pre-installed — it's required for Steps 4–6. Install it with brew install htmlq on macOS or cargo install htmlq if you have Rust installed. If htmlq is unavailable, fall back to pup or use python3 -c with html.parser for simple extractions.
• The TOC JSON URL 404s if the source_id is wrong — double-check against the source table in Step 2. The source_id is case-sensitive and versioned (e.g., data_v2, not data).
• CDN paths change when docs are re-deployed — the repo-slug segment (the hex/numeric hash before the API name) changes when the docs team pushes updates. If a CDN URL returns 404, re-fetch the TOC to get the current slug.
• "dm." vs "documents." prefix — Data Management webhook events use the dm. prefix (e.g., dm.version.added). ACC document webhooks use the documents. prefix (e.g., documents.document.created). Mixing them up returns empty results.

---

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

This demonstrates the method end-to-end.

Step 1 — Glossary

A webhook is a server-to-server callback triggered by APS events. Data Management handles files. ACC handles construction documents. Model Derivative handles translations of those files.

Step 2 — Identify APIs

"File changes" could mean:

• Data Management API (data_v2) — files stored in OSS, BIM 360 Docs, or ACC Docs (item creation, version added, folder changes)
• ACC API (acc_v1) — ACC-specific document management events
• Webhooks API (webhooks_v1) — the umbrella system; each API documents its own webhook events in its own reference section

Step 3 — Build breadcrumbs from TOCs

# 1. Check the Webhooks API overview for system-level info
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '.children[] | {display_name, url_path}'

# 2. Find the Data Management webhook events reference
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/data_v2.json" | jq '[.. | objects | select(.source? and .display_name?)] | .[] | select(.display_name | test("webhook|hook|event|file|item|version|folder"; "i")) | {display_name, source}'

# 3. Find the ACC webhook events reference
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/acc_v1.json" | jq '[.. | objects | select(.source? and .display_name?)] | .[] | select(.display_name | test("webhook|hook|event|file|document|item|version|folder"; "i")) | {display_name, source}'

From the TOC, you'll discover source paths like:

• data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.created.html
• data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.updated.html
• data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.deleted.html
• data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/version.added.html
• data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/folder.created.html
• And similar ACC document events

Step 4 — Get headings to understand page structure

# Check the structure of the events overview page
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events.html" | htmlq -r 'script, style' --text 'h1, h2, h3, h4'

# Check the structure of the specific event detail page
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.updated.html" | htmlq -r 'script, style' --text 'h1, h2, h3, h4'

Step 5 — Retrieve visible text from the event pages

# Get the full text of the events overview page
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events.html" | htmlq -r 'script, style' --text 'p, li'

# Get the full text of the specific event detail page
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/data-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.updated.html" | htmlq -r 'script, style, noscript' --text '*'

Step 7 — Compile

From the fetched content you can now answer:

Data Management webhooks for file changes:

• dm.item.created — a new file item is created
• dm.item.updated — a file item's properties are updated
• dm.item.deleted — a file item is deleted or moved to trash
• dm.version.added — a new version of a file is uploaded
• dm.version.deleted — a file version is deleted
• dm.folder.created / dm.folder.updated / dm.folder.deleted — folder changes

ACC document webhooks:

• documents.document.created — a document is uploaded
• documents.document.updated — document metadata changes
• documents.document.deleted — document is removed

And provide the portal links (after converting CDN URLs):

• Data Management webhooks overview
• Webhooks API overview