aps-docs-portal

---
name: aps-docs-portal
description: >
license: MIT
---

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

```bash
# 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:

```bash
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:

```bash
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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://aps.autodesk.com/en/docs/data/v2/reference/webhooks/events/)
- [Webhooks API overview](https://aps.autodesk.com/en/docs/webhooks/v1/developers_guide/overview/)