Upload a file from a public source URL into an ACC project folder. Runs the full four-step APS Data Management flow: top-folder discovery → storage object creation → OSS PUT of bytes → first-version item creation.
When to use: The user wants to push a document/photo/model into ACC Docs — e.g. 'upload this site photo to the Tower project Photos folder' or an automation needs to archive an exported report into Project Files.
When NOT to use: Do not use for files already in ACC; do not use for files behind auth-gated URLs (fetch step is an unauthenticated GET). For very large files (>100MB), prefer the chunked/signed-S3 upload flow, not this single-PUT implementation.
APS scopes: data:read data:write data:create account:read.
Rate limits: APS Data Management ~50 req/min per endpoint; OSS upload bandwidth typically 100 MB/min per app. This tool issues 3–5 APS calls per upload, so budget accordingly.
Errors: 401 (APS token expired — refresh); 403 (user lacks folder write permission — ask account admin to grant 'Edit' on folder); 404 (project_id not found or folder_path does not match any top folder — verify 'b.' prefix, hub membership, and folder name); 422 (invalid file_name or conflicting version); 429 (rate limit — back off 60s); 5xx (ACC/OSS upstream — retry with jitter BUT be cautious: storage object may already be created so reuse, do not re-create). Also: if source file_url returns non-2xx, the tool throws before touching ACC.
Side effects: Creates a storage object, uploads bytes, and creates a versioned item in the target folder. NOT idempotent — a retry may create a duplicate item with a new version. Surface the returned item_id to the user to avoid re-uploads.