11 CAD Viewer (APS)
6 operations.
11.0.1 getApsViewerToken
GET /api/aps/auth
Issues the view-only token the browser CAD viewer needs from Autodesk (upload/write powers stay server-side).
Why it exists. † Issue a viewer-scoped token for the CAD viewer, deliberately narrower than the server’s own credential so the browser can render a model without being able to modify anything.
Returns an Autodesk Platform Services 2-legged OAuth token scoped to viewables:read only (cached server-side; expires_in reports the remaining lifetime) for the browser CAD viewer. The full-scope token used by upload/translate never leaves the server. Requires APS_CLIENT_ID/APS_CLIENT_SECRET server-side.
Authentication: CookieAuth, SupabaseAuth
Returns — access_token · expires_in
Field names as the handler returns them; the source states no types for them.
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Access token. | |
401 |
Unauthorized. | Error |
500 |
APS credentials unset or token request failed. | Error |
11.0.2 getApsModel
GET /api/aps/model
Returns the CAD model a campaign declares, ready for the viewer — or says it has none.
Why it exists. ‡ Return the CAD model to display for a dataset, and its translation status, so the viewer can show a model, a progress indicator, or a failure, rather than only the first of the three.
Called by — components/workspaces/storage-client.tsx · modules/cad-viewer/ui/components/asset-cad-panel.tsx
Reached from — /w/data-explorer/assets · /w/data-explorer/storage · /w/integrity/assets · /w/integrity/storage
Returns the CAD model the given dataset declares on datasets.cad_models, as a viewer URN. Reads only — nothing uploads or translates here; seeding APS and writing back the urn is an operator step. hasCad: false is a normal outcome, not an error. A model whose translation has not succeeded is returned with its status and a null urn so the viewer can explain itself rather than render blank. The caller must be able to read the dataset under RLS, and the urn’s OSS bucket must belong to an organization they are a member of.
Authentication: CookieAuth, SupabaseAuth
Returns — hasCad · model
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets · organizations
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
dataset |
query | yes | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The dataset’s CAD model, or hasCad false. | |
400 |
dataset is required. | Error |
401 |
Unauthorized. | Error |
403 |
The model’s bucket is outside the caller’s organizations. | Error |
404 |
Dataset not found, or not visible to the caller. | Error |
500 |
Server error. | Error |
11.0.3 getCadObjectLocation
GET /api/aps/model/locate
Locates an equipment tag in the dataset’s CAD model — returns the CAD object ids (for highlighting in the viewer) and the model’s description of it. Matches the tag against the equipment objects’ Equip no. Reads the property database the viewer translation already built.
Why it exists. † Find an equipment tag inside a dataset’s 3D model and return the objects that are that asset, so the viewer can isolate the vessel itself rather than a label beside it.
Returns the CAD object ids for an equipment tag in the dataset’s 3D model (for isolating/highlighting in the viewer), plus the model’s own description. Matches the tag against the equipment objects’ Equip no (accepting a shorthand via suffix). Reads the property database the SVF2 viewer translation already built — no re-processing. Option A of the CAD queryable-data proposal.
Authentication: SupabaseAuth, CookieAuth
Returns — hasCad · tag · objectids · urn · guid · model_name · equip_no · description · count · tag_nodes · geometry_nodes
Field names as the handler returns them; the source states no types for them.
Effect — reads datasets · organizations
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
dataset |
query | yes | string | |
tag |
query | yes | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
The located CAD objects (empty when the dataset has no model or no match). | |
400 |
dataset and tag are required. | Error |
401 |
Not authenticated. | Error |
404 |
Dataset not found. | Error |
500 |
Server error. | Error |
502 |
no viewable in model | Error |
11.0.4 getApsTranslationStatus
GET /api/aps/status/{urn}
Reports how far along that conversion is (only for models in your organization).
Why it exists. † Report how far a CAD conversion has got, so the viewer can show progress on a translation that takes minutes.
Polls the APS Model Derivative manifest for a URN and reports translation status/progress. The URN must decode to the caller’s org bucket or the shared demo bucket (403 otherwise).
Authentication: CookieAuth, SupabaseAuth
Returns — status · progress · urn
Field names as the handler returns them; the source states no types for them.
Effect — reads organizations
Parameters
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
urn |
path | yes | string |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Translation status. | |
400 |
URN is required or malformed. | Error |
401 |
Unauthorized. | Error |
403 |
URN is outside the caller’s organization. | Error |
500 |
Manifest fetch failed (including unknown URN). | Error |
11.0.5 startApsTranslation
POST /api/aps/translate
Starts Autodesk’s conversion of a CAD file into a viewable format (only for models in your organization).
Why it exists. † Start converting an uploaded CAD file into the form the viewer can display, restricted to models in the caller’s own bucket.
Starts an APS Model Derivative SVF2 translation job (2D + 3D views) for a URN. The URN must decode to the caller’s org bucket or the shared demo bucket (403 otherwise).
Authentication: CookieAuth, SupabaseAuth
Returns — urn · result
Field names as the handler returns them; the source states no types for them.
Effect — reads organizations
Request body
| Field | Type | Required |
|---|---|---|
urn |
string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Job accepted. | |
400 |
URN is required or malformed. | Error |
401 |
Unauthorized. | Error |
403 |
URN is outside the caller’s organization. | Error |
500 |
Job start failed (also covers malformed JSON bodies). | Error |
11.0.6 uploadApsCadFile
POST /api/aps/upload
Uploads a CAD file to your organization’s own Autodesk storage for viewing (you must be a member).
Why it exists. ‡ Upload a CAD file into the organisation’s own model bucket, so a plant model can be brought in for viewing alongside the imagery.
Called by — modules/cad-viewer/services/aps-client.ts
Reached from — /datasets/<slug> · /w/data-explorer/assets · /w/data-explorer/cad-viewer · /w/integrity/assets
Uploads a CAD file to the target organization’s own APS OSS bucket (created lazily) and returns its viewer URN. The caller must be a member of organizationId. The whole file is buffered in memory; no size limit is enforced.
Authentication: CookieAuth, SupabaseAuth
Returns — urn · objectKey · objectId · size
Field names as the handler returns them; the source states no types for them.
Effect — reads organizations
Request body
| Field | Type | Required |
|---|---|---|
file |
string (binary) | yes |
organizationId |
string (uuid) | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
200 |
Uploaded object. | |
400 |
No file provided, or organizationId missing/invalid. | Error |
401 |
Unauthorized. | Error |
403 |
Not a member of the target organization. | Error |
500 |
Upload failed. | Error |