| name | aps-docs-portal |
| description | Navigate the Autodesk Platform Services (APS) documentation portal — find the right API docs, decode glossary terms, crawl table-of-contents JSON trees, extract content from static HTML pages, and convert CDN URLs to clickable portal links. Covers ACC, BIM 360, Model Derivative, Data Management, Viewer, Design Automation, Authentication, Webhooks, and all related APS APIs.
|
| metadata | {"author":"Developer Advocates @ Autodesk","version":"0.1"} |
| compatibility | Requires curl, jq, and htmlq for documentation scraping and TOC navigation. |
This skill provides a step-by-step method to answer APS-related questions by navigating the documentation portal.
Behavior
- 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.
- Always provide reference links with your answers.
- Always attempt to answer APS-related questions directly.
- 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
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '.children[] | {display_name, url_path}'
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}'
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '[.. | objects | select(.source? and .url_path?)] | .[] | {display_name, url_path, source}'
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:
- Strip the repo-slug — the first path segment after
bPlouYTd/ (always has a numeric suffix, e.g. A360-platform-viewing-docs-master-633741).
- The api-name is the next segment — e.g.
model-derivative, design-automation.
- Remove any duplicate api-name — the api-name sometimes appears again deeper in the path. If it does, remove that duplicate folder.
- Strip
.html from the page filename and add a trailing /.
- 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:
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'p, li'
curl -sL "https://developer.doc.autodesk.com/bPlouYTd/{source_path}" | htmlq -r 'script, style' --text 'pre, code'
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:
- Define the terms (from the glossary or what you found in the docs)
- Explain the relevant APIs and endpoints (from the TOC and fetched pages)
- List the specific events or features (from the reference pages)
- Provide reference links (convert CDN URLs to portal URLs for clickable links)
- 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
curl -sL "https://developer.doc.config.autodesk.com/bPlouYTd/webhooks_v1.json" | jq '.children[] | {display_name, url_path}'
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}'
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.htmldata-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.updated.htmldata-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/item.deleted.htmldata-v2-docs-master-XXXXXX/data/v2/reference/webhooks/events/version.added.htmldata-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
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'
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
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'
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 createddm.item.updated — a file item's properties are updateddm.item.deleted — a file item is deleted or moved to trashdm.version.added — a new version of a file is uploadeddm.version.deleted — a file version is deleteddm.folder.created / dm.folder.updated / dm.folder.deleted — folder changes
ACC document webhooks:
documents.document.created — a document is uploadeddocuments.document.updated — document metadata changesdocuments.document.deleted — document is removed
And provide the portal links (after converting CDN URLs):
