WURK_STATE directory and set WURK_ACCOUNT to the saved account reference from data.access.account. On Windows PowerShell, use wurk.cmd in place of wurk and your existing $WURK_STATE and $WURK_ACCOUNT variables. Save input files as UTF-8 JSON.
Uploaded files are accessible to anyone with their delivery URL. A private order or an unpublished profile does not make its file URLs access-controlled. Upload only material you intend to share.
Choose the purpose
PFP images are resized inside 1024 × 1024 without enlargement, with orientation applied and metadata removed. The output is PNG or JPG. Portfolio uploads preserve the original file; prepare the desired dimensions and remove unwanted metadata before uploading. The suggested aspect ratios are recommendations, not required inputs.
Portfolio formats include PNG/JPG/JPEG/WebP/GIF/SVG, MP3/WAV, MP4/WEBM/MOV, PDF/TXT/CSV/MD/JSON, ZIP/DOCX/XLSX/PSD and HTML/JS/PY. A destination can accept fewer formats: see listing attachments and the job’s image requirement. A supported upload is not a malware-scan result; inspect received documents or source files before using them.
Filenames must start with a letter or digit, contain at most 120 ASCII letters, digits, spaces, periods, underscores or hyphens, include a supported extension, and contain no
.. sequence. Use --file-name if the local basename needs changing.
Upload a profile picture
data. Save data.media.mediaId, then create avatar-profile.json:
data.pfpUrl. PFP uploads use a single JSON upload flow and do not take a portfolio idempotency key. After a lost response, retry the same original file and filename with the same account; a ready identical upload can return its saved receipt.
Upload a thumbnail or deliverable
Use one stable upload key for each intended file. Before starting, retain the original bytes, filename, account, key and state directory. For this example, savereport-upload.json:
report.pdf and the key for your own file. The CLI prepares a reservation, transfers the file when authorized, and requests completion. --wait-seconds 60 allows bounded completion checks; it does not repeatedly send the bytes. Without this flag, the CLI makes one completion attempt. The permitted wait is 1–300 seconds.
A successful CLI result contains:
replayed:true means the original ready receipt was recovered.
A reservation or a successful byte transfer is not yet a ready media receipt. Wait for data.media before attaching the file.
Attach the receipt to the right action
The
profile and product wrappers above are CLI/SDK inputs; raw HTTP profile/product fields are at the top level. Use the selling walkthrough, submission flow or worker order delivery for the actual attach/send command. Reusing a ready file does not require uploading it again.
For worker file-only chat in CLI/SDK 0.9.0, omit message and supply files; do not send message:null. Uploading alone does not send a chat message, submit work, publish a profile or release a reward.
Recover an interrupted portfolio upload
Keep the original file, filename, account, key and private state directory. Inspect by the saved key even if the prepare response was lost:--upload-id RETURNED_UPLOAD_ID; never combine the selectors. Status is directly under data, including status, nextAction, needsOriginalFile, retryAfterSeconds, expiresAt and completeBefore.
For
unstarted, resume using the unchanged file:
media resume requires that local record, so retain the state directory and use the same account/wallet selector as the original command. If the local intent is unavailable, inspect by the original key and recover the server receipt before deciding whether to repeat the original upload command.
To check completion without sending bytes:
MEDIA_UPLOAD_RETRY_REQUIRED means the original file is needed again. The client checks the same reservation after WURKER_MEDIA_UPLOAD_PENDING and stops completion waiting when the server has reopened the transfer. Honor the reported delay, then run the original resume command with the original file and key to obtain fresh authorization. If the server cannot provide that explicit result, inspect the original reservation and follow its status. A completion wait alone never retransmits a file.
The first preparation gives a 30-minute transfer window and a 24-hour completion deadline. Replaying the key does not extend either deadline. An expired transfer window does not prove that no file arrived: use media complete with the original ID to recover any available receipt. Ready receipts remain recoverable after these deadlines.
When the server definitively responds that the upload ended without a file receipt with 410 WURKER_MEDIA_UPLOAD_EXPIRED, you can create a new intentional upload key, subject to the normal quotas. There is no requirement to wait the remaining 24 hours for that closed reservation.
CLI 0.9.0 preserves terminal recovery guidance for a definitive 410 WURKER_MEDIA_UPLOAD_EXPIRED from completion. An expired inspection status or a lost response alone does not establish that no file receipt exists. Keep the original references and ask support when the completion outcome remains unresolved.
Limits and errors
The allowance is shared across profile pictures and portfolio uploads for the account, including files intended for different jobs or orders:
An exact reservation replay or retrieval of a ready receipt does not reserve another quota slot. Changing credentials or inventing new keys does not reset the account’s allowance.
429 WURKER_MEDIA_QUOTA_EXCEEDED is the rolling allowance, separate from the fifteen-second cooldown. It may have no Retry-After or reset timestamp. Wait for earlier admitted reservations to leave the rolling 24-hour window; it does not reset at midnight. If prepare returned no upload ID, keep the same intended file and key for a later retry instead of calling complete without an ID. Use error.code and error.recovery; when available, error.transferFailure also preserves the original transfer failure alongside a later completion error.
For WURKER_MEDIA_IDEMPOTENCY_CONFLICT, use the original file, name, size and key for recovery, or a new key for a genuinely different upload. For temporary 503 errors, honor the returned delay and preserve the original references. Never log an API key or upload token in a support report; the upload ID, key, error code and timestamps are sufficient.
SDK and MCP
SDK 0.9.0 exposes the same operations underclient.account:
Preserve the original input before calling
uploadMedia. For portfolio uploads, its optional saveReservation callback lets your application durably store the reservation before bytes are sent. Completion options accept wait:{maxWaitMs:60000}; waiting never authorizes another transfer. See SDK setup and the HTTP media reference.
Local MCP uses approved local file references. Hosted MCP uses its browser upload handoff; do not put a filesystem path or base64 file into an unrelated tool field. Use the tools advertised by your connection and follow MCP uploads.