aps_docs

Instructions

Implementation Reference

• src/index.ts:1169-1171 (handler)

  The tool handler for 'aps_docs' – simply returns the APS_DOCS constant as the tool response.

  if (name === "aps_docs") {
    return ok(APS_DOCS);
  }

• src/index.ts:362-371 (schema)

  The tool registration / schema definition for 'aps_docs' – no input parameters needed.

  // 9 ── aps_docs
  {
    name: "aps_docs",
    description:
      "Return APS Data Management quick‑reference documentation: " +
      "common ID formats, typical browsing workflow, raw API paths, query parameters, " +
      "BIM file extensions, and error troubleshooting. " +
      "Call this before your first APS interaction or when unsure about ID formats or API paths.",
    inputSchema: { type: "object" as const, properties: {} },
  },

• src/index.ts:362-371 (registration)

  The 'aps_docs' tool is registered in the TOOLS array (index 9). It's listed in the tool definitions along with other APS tools.

  // 9 ── aps_docs
  {
    name: "aps_docs",
    description:
      "Return APS Data Management quick‑reference documentation: " +
      "common ID formats, typical browsing workflow, raw API paths, query parameters, " +
      "BIM file extensions, and error troubleshooting. " +
      "Call this before your first APS interaction or when unsure about ID formats or API paths.",
    inputSchema: { type: "object" as const, properties: {} },
  },

• src/aps-dm-helpers.ts:852-914 (helper)

  The APS_DOCS constant is defined in aps-dm-helpers.ts (line 852–914). It contains the Markdown quick-reference documentation for APS Data Management.

  export const APS_DOCS = `# APS Data Management – Quick Reference
  
  ## Common ID Formats
  - **Hub ID**: \`b.<account_id>\` (e.g. \`b.abc12345-6789-…\`)
  - **Project ID**: \`b.<project_id>\` (same format as hub)
  - **Folder URN**: \`urn:adsk.wipprod:fs.folder:co.<id>\`
  - **Item URN (lineage)**: \`urn:adsk.wipprod:dm.lineage:<id>\`
  - **Version URN**: \`urn:adsk.wipprod:fs.file:vf.<id>?version=<n>\`
  
  ## Typical Browsing Workflow
  \`\`\`
  1. aps_list_hubs                                      → pick a hub
  2. aps_list_projects        hub_id                    → pick a project
  3. aps_get_top_folders      hub_id + project_id       → see root folders
  4. aps_get_folder_contents  project_id + folder_id    → browse files
  5. aps_get_item_details     project_id + item_id      → file metadata
  \`\`\`
  
  ## Raw API Paths (for aps_dm_request)
  | Action | Method | Path |
  |--------|--------|------|
  | List hubs | GET | project/v1/hubs |
  | List projects | GET | project/v1/hubs/{hub_id}/projects |
  | Top folders | GET | project/v1/hubs/{hub_id}/projects/{project_id}/topFolders |
  | Folder contents | GET | data/v1/projects/{project_id}/folders/{folder_id}/contents |
  | Item details | GET | data/v1/projects/{project_id}/items/{item_id} |
  | Item tip version | GET | data/v1/projects/{project_id}/items/{item_id}/tip |
  | All versions | GET | data/v1/projects/{project_id}/items/{item_id}/versions |
  | Search folder | GET | data/v1/projects/{project_id}/folders/{folder_id}/search |
  | Create folder | POST | data/v1/projects/{project_id}/folders |
  | Download | GET | (use storage URL from version relationships.storage.meta.link.href) |
  
  ## Query Parameters
  - \`page[number]\` – page index (0‑based)
  - \`page[limit]\` – items per page (default 25, max 200)
  - \`filter[type]\` – filter by resource type
  - \`filter[extension.type]\` – filter by extension type
  - \`includeHidden\` – include hidden items (default false)
  
  ## Common BIM File Extensions
  | Extension | Description |
  |-----------|-------------|
  | .rvt | Revit Model |
  | .rfa | Revit Family |
  | .nwd | Navisworks (full) |
  | .nwc | Navisworks Cache |
  | .ifc | Industry Foundation Classes |
  | .dwg | AutoCAD Drawing |
  | .dwfx | Design Web Format |
  | .pdf | PDF Document |
  
  ## Error Troubleshooting
  | Code | Common Cause | Fix |
  |------|-------------|-----|
  | 401 | Expired / invalid token | Check credentials; token auto‑refreshes |
  | 403 | App not provisioned | Admin → Account Settings → Custom Integrations |
  | 404 | Wrong ID format | Hub/project use 'b.' prefix; folders/items use 'urn:' |
  | 429 | Rate limited | Wait 60 s, reduce request frequency |
  
  ## Full Specification
  - Docs: https://aps.autodesk.com/en/docs/data/v2/reference/http/
  - OpenAPI: https://github.com/autodesk-platform-services/aps-sdk-openapi/blob/main/datamanagement/datamanagement.yaml
  `;