Files

This page covers:

• GET /api/File
• PUT /api/File
• DELETE /api/File
• PUT /api/FileBinary
• PUT /api/FileBinaryDirect
• GET /api/FileStatus

Fetch a file record by UID or by full file path.

{
  "UID": "b5d3674c-488c-41cb-a9f7-58a42cac85dd",
  "VizSpaceID": "24395dfe-7917-4976-a198-0fe3aa9a6a06",
  "FileName": "Design/example-assembly.step",
  "DisplayName": "example-assembly.step",
  "Attributes": [
    "document_number=AX-1000",
    "document_type=Assembly",
    "weight(kg)=12.7"
  ],
  "ExtractedAttributes": [
    "Volume=123.4",
    "SurfaceArea=88.2"
  ],
  "ThumbNailURLFromID": "https://your-server.example.com/.../sm.jpg",
  "PNGURLFromID": "https://your-server.example.com/.../lg.png",
  "HasThumbnail": true,
  "IndexingFinished": true
}

curl -G "https://your-server.example.com/api/File" \
  -H "Authorization: Bearer USER_BEARER_TOKEN" \
  --data-urlencode "fileUID=b5d3674c-488c-41cb-a9f7-58a42cac85dd" \
  --data-urlencode "includeShapelets=true"

Upload a file as either:

• a search-input file (isSearchInput=true, the default), or
• a persistent file in the company database (isSearchInput=false)

The body is a JSON string whose value is the base64-encoded file bytes:

"BASE64_FILE_BYTES"

Do not send raw binary here. Use /api/FileBinary or /api/FileBinaryDirect for raw binary uploads.

• If isSearchInput=true, the file query value should be an extension, not a path. Use .png, .pdf, .stp, and so on.
• If isSearchInput=false, the attributes query parameter is decoded and parsed as a nested query string such as Width=10.5&Color=Blue.
• The current controller only reads attributes when isSearchInput=false.
• .ifz uploads must preserve the original extension before .ifz, for example gear.stl.ifz, not just .ifz.
• Uploads under 1024 bytes are rejected with HTTP 400. For PUT /api/File the 1024 is measured against the base64 string length, not the decoded byte count.

By default, a search-input upload (isSearchInput=true) blocks until indexing completes, so the returned fileUID is immediately searchable. For large inputs, indexing can take long enough to exceed client or proxy timeouts.

Set indexAsync=true to make the upload non-blocking. The file is queued for indexing and the fileUID is returned immediately, before indexing has finished:

1. PUT /api/File?...&isSearchInput=true&indexAsync=true returns a fileUID right away.
2. Poll GET /api/FileStatus?fileUID=... until it returns HTTP 200 with the index timestamp. HTTP 204 means indexing is still in progress; HTTP 422 means indexing failed and polling should stop. See GET /api/FileStatus for the full status-code contract.
3. Once indexing has completed, search by that fileUID with GET /api/Search.

• indexAsync applies only to search-input uploads on PUT /api/File and PUT /api/FileBinary. It has no effect on company-database uploads (isSearchInput=false) and is not available on PUT /api/FileBinaryDirect.
• .zip search inputs are not supported with indexAsync=true and return HTTP 400. Upload the file without indexAsync, or expand the archive and upload each file individually.
• Searching by a fileUID before GET /api/FileStatus reports completion yields no matches, because the input has not finished indexing.

import base64
import json
import requests

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"
filename = "example-input.dxf"

with open(filename, "rb") as f:
    body = json.dumps(base64.b64encode(f.read()).decode("ascii"))

resp = requests.put(
    f"{server}/api/File?file=.dxf&isSearchInput=true",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    data=body,
)
resp.raise_for_status()
print(resp.text)

import base64
import json
import requests
import urllib.parse

server = "https://your-server.example.com"
token = "USER_BEARER_TOKEN"
filename = "example-assembly.step"

with open(filename, "rb") as f:
    body = json.dumps(base64.b64encode(f.read()).decode("ascii"))

attributes_raw = (
    "document_number=AX-1000"
    "&document_type=Assembly"
    "&material=Stainless Steel"
    "&weight(kg)=12.7"
)
attributes_qs = urllib.parse.quote(attributes_raw, safe="")

resp = requests.put(
    f"{server}/api/File?file=Design/example-assembly.step"
    f"&isSearchInput=false"
    f"&attributes={attributes_qs}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    data=body,
)
resp.raise_for_status()
print(resp.text)

PUT /api/File?file=.stp&isSearchInput=true HTTP/1.1
Host: your-server.example.com
Authorization: Bearer USER_BEARER_TOKEN
Content-Type: application/json

"BASE64_FILE_BYTES"

Delete a file by UID.

The outcome is communicated through the HTTP status code. Branch on the status code; treat the body as supplementary detail.

Deletion is not idempotent at the status-code level: deleting the same fileUID twice returns 200 the first time and 404 the second. If your integration deletes defensively, treat 404 as “already gone” rather than as an error.

curl -X DELETE "https://your-server.example.com/api/File?fileUID=b5d3674c-488c-41cb-a9f7-58a42cac85dd" \
  -H "Authorization: Bearer USER_BEARER_TOKEN"

Same logical behavior as PUT /api/File, but the body is raw binary instead of a JSON base64 string.

Use the same query parameters described for PUT /api/File.

with open("example-input.dxf", "rb") as f:
    resp = requests.put(
        f"{server}/api/FileBinary?file=.dxf&isSearchInput=true",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/octet-stream",
        },
        data=f.read(),
    )

resp.raise_for_status()
print(resp.text)

Same raw-binary upload pattern as FileBinary, but the response is a populated FileMap object instead of only the UID.

with open("example-input.dxf", "rb") as f:
    resp = requests.put(
        f"{server}/api/FileBinaryDirect?file=.dxf&isSearchInput=true&includeShapelets=true",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/octet-stream",
        },
        data=f.read(),
    )

resp.raise_for_status()
print(resp.json())

Poll the indexing state of an uploaded file. This is the completion signal for asynchronous uploads: after PUT /api/File or PUT /api/FileBinary with indexAsync=true, poll this endpoint until it returns HTTP 200 before searching by the fileUID.

The indexing state is communicated through the HTTP status code. Branch on the status code; treat the body as supplementary detail.

204 is the only “try again” signal. 422 and 404 are terminal: further polling will not change the outcome.

• Responses are served with Cache-Control: no-store. Ensure your HTTP client and any intermediaries honor it — a cached “in progress” response can mask completion indefinitely.
• Poll at a modest interval (2–5 seconds is typical) and apply an overall timeout appropriate to your file sizes.

curl -G "https://your-server.example.com/api/FileStatus" \
  -H "Authorization: Bearer USER_BEARER_TOKEN" \
  --data-urlencode "fileUID=b5d3674c-488c-41cb-a9f7-58a42cac85dd"

import time
import requests

def wait_until_indexed(server, token, file_uid, timeout_seconds=600, poll_interval=3):
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{server}/api/FileStatus",
            headers={"Authorization": f"Bearer {token}"},
            params={"fileUID": file_uid},
            timeout=30,
        )
        if resp.status_code == 200:
            return resp.text.strip().strip('"')   # indexing complete
        if resp.status_code == 204:
            time.sleep(poll_interval)             # still indexing
            continue
        if resp.status_code == 422:
            raise RuntimeError(f"Indexing failed for {file_uid}")
        if resp.status_code == 404:
            raise LookupError(f"Unknown fileUID: {file_uid}")
        resp.raise_for_status()                   # 400 / 401 / unexpected
    raise TimeoutError(f"Indexing did not complete within {timeout_seconds}s")