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.

Documented steps

1. Get the project's API URL and an apikey (publishable/anon or secret key) plus a bearer JWT from Settings > API in the dashboard.
2. 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".
3. Optionally set 'Content-Type: {mime/type}' to override the type Storage would infer from the file extension.
4. 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.
5. To overwrite an existing path, add header 'x-upsert: true' (default without it: 400 'Asset Already Exists' if the path exists).
6. 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 }.
7. A successful direct upload returns 200 with JSON like {"Id": "...", "Key": "bucket/path"}.
8. 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