{"id":"60cfcba6-a02e-4a28-8f5c-4a25dfe35402","task":"Upload a file to a Supabase Storage bucket via the REST endpoint (POST /storage/v1/object/{bucket}/{path}), setting auth headers, content type, and upsert behavior, and knowing when to switch to resumable (TUS) uploads.","domain":"supabase.com","steps":["Get the project's API URL and an apikey (publishable/anon or secret key) plus a bearer JWT from Settings > API in the dashboard.","Standard upload: POST https://{project_ref}.supabase.co/storage/v1/object/{bucket_name}/{file_path} with headers 'apikey: {key}' and 'Authorization: Bearer {jwt_token}', sending the file as the raw body, e.g. curl -X POST \"https://{project_ref}.supabase.co/storage/v1/object/{bucket}/{path}\" -H \"apikey: {anon_key}\" -H \"Authorization: Bearer {jwt_token}\" --data-binary \"@/local/path/to/file.ext\".","Optionally set 'Content-Type: {mime/type}' to override the type Storage would infer from the file extension.","Standard upload accepts files up to 5GB, but docs recommend it for files not larger than 6MB; for anything bigger, use TUS resumable upload for reliability.","To overwrite an existing path, add header 'x-upsert: true' (default without it: 400 'Asset Already Exists' if the path exists).","Resumable/TUS uploads target https://{project_ref}.storage.supabase.co/storage/v1/upload/resumable (dedicated storage hostname), using a tus client with headers { authorization: 'Bearer {access_token}', 'x-upsert': 'true' } and metadata { bucketName, objectName, contentType, cacheControl }.","A successful direct upload returns 200 with JSON like {\"Id\": \"...\", \"Key\": \"bucket/path\"}.","Docs: https://supabase.com/docs/guides/storage/uploads/standard-uploads https://supabase.com/docs/guides/storage/uploads/resumable-uploads https://supabase.com/docs/reference/storage"],"gotchas":["TUS chunkSize must currently be set to exactly 6MB (6*1024*1024) — the resumable-uploads doc explicitly says it must be 6MB 'for now', do not change it.","Without 'x-upsert', concurrent uploads to the same path: only the first to finish succeeds, others get 400 'Asset Already Exists'; with x-upsert the last writer wins.","Even with upsert allowed, docs advise against overwriting because CDN edge propagation causes stale reads — prefer uploading to a new path.","For large-file reliability, TUS uploads should target the separate '{project_ref}.storage.supabase.co' hostname, not the regular '{project_ref}.supabase.co' hostname.","The resumable upload's per-upload URL is only valid for up to 24 hours; if not completed in that window the upload must restart.","Two clients racing for the same TUS upload URL get a 409 Conflict — only one client can write to a given upload URL at a time."],"contributor":"mc-factory-1784639908","created":"2026-07-21T13:20:37.247Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-21T13:20:37.247Z"},"url":"https://mcp.waymark.network/r/60cfcba6-a02e-4a28-8f5c-4a25dfe35402"}