media.requestUpload

Get a signed upload URL for a job photo or video. Before you call this, look at the file and say what it shows in summary: plain words, findings, any text you can read (model and serial plates), measurements, and for video a transcript, key moments and the length. If what you see does not match what the worker said, tell the worker before you upload. If you cannot look at it, send summary.unable_to_analyze with a reason and the media is listed by media.needsSummary. Summaries stay inside the shop and are searchable with media.list q and search.global. Photos: JPEG, PNG, WebP, HEIC or TIFF (HEIC and TIFF are kept as sent, with a JPEG copy for viewing). Video: MP4, MOV or WebM. Without object storage it is kept on this server, at most 100 MB and 10 minutes, and is not shared outside the shop. When R2 is configured, a video is uploaded in parts directly to storage (mode multipart, then media.videoPartUrls, media.completeVideoUpload or media.abortVideoUpload), up to 2 GB and 30 minutes unless DW_MAX_VIDEO_BYTES or DW_MAX_VIDEO_SECONDS set a different cap, and it can be included on a share link. The server does not download the video to recheck the hash. Declare the sha256 of the bytes you will send as exactly 64 hex characters (upper or lower case). Anything else is refused and no upload link is made. The upload is rejected if the bytes differ. Taken time, GPS location, heading and camera details are read from photos and kept for your shop. Copies shared outside the shop (share links, quote pages, PDFs) have that metadata removed. Pass provided_by customer when the customer sent the file, and channel for how it arrived (upload, email, text, capture, network_request, import). customer_id is optional and must be a customer of this shop.

WhoAgents can call this
RESTPOST /v1/media/uploads
MCP toolmedia_requestUpload
Writesyes, send an Idempotency-Key
AreaJob photos

When to use it

You have a photo file to add to a job. Hash the bytes (sha256), request the URL, then PUT the bytes.

What to tell the owner

I added the photo to the job. Location and camera data were removed first.

Input

FieldTypeRequired
job_idstring (uuid)yes
stagestring (one of before, during, after, other)yes
sha256string (sha256)yes
shows_interiorbooleanno
kindstring (one of photo, video)no
summaryobjectyes
summary.summarystringno
summary.notablearrayno
summary.notable[].kindstring (one of damage, leak, safety, code_issue, wear, pest, mold, access, other)yes
summary.notable[].textstringyes
summary.readable_textarrayno
summary.readable_text[].whatstringyes
summary.readable_text[].textstringyes
summary.measurementsarrayno
summary.measurements[].whatstringyes
summary.measurements[].valuenumberyes
summary.measurements[].unitstringyes
summary.measurements[].howstring (one of read, estimated)yes
summary.transcriptstringno
summary.key_momentsarrayno
summary.key_moments[].at_secondsnumberyes
summary.key_moments[].textstringyes
summary.duration_secondsnumberno
summary.languagestringno
summary.generated_bystringno
summary.unable_to_analyzeobjectno
summary.unable_to_analyze.reasonstring (one of no_vision, no_video, file_unreadable, too_large, not_allowed, other)yes
summary.unable_to_analyze.detailstringno
content_typestring (one of mp4, mov, webm)no
provided_bystring (one of shop, customer)no
channelstring (one of upload, email, text, capture, network_request, import)no
customer_idstring (uuid)no

Example

POST https://doingwork.work/v1/media/uploads
content-type: application/json
Idempotency-Key: 3f1c...

{
  "job_id": "00000000-0000-4000-8000-000000000000",
  "stage": "before",
  "sha256": "...",
  "summary": {
    "summary": "...",
    "notable": [
      {
        "kind": "damage",
        "text": "..."
      }
    ],
    "readable_text": [
      {
        "what": "...",
        "text": "..."
      }
    ],
    "measurements": [
      {
        "what": "...",
        "value": "...",
        "unit": "...",
        "how": "read"
      }
    ],
    "transcript": "...",
    "key_moments": [
      {
        "at_seconds": "...",
        "text": "..."
      }
    ],
    "duration_seconds": "...",
    "language": "...",
    "generated_by": "...",
    "unable_to_analyze": {
      "reason": "no_vision"
    }
  }
}

Output

JSON. The response shape isn't published yet; read the fields you need and ignore the rest. Errors are {code, message, status}.

Errors

CodeStatusWhat to do
invalid_input400A field is missing, the wrong type, or unknown. The message names the field. Fix the input; don't retry as is.
not_found404No such record, or this worker can't see it.
invalid_input, invalid_token, rate_limitedCan happen on any call. See errors.