bundle-social-uploads

Author: Anton Gulin · Tool: opencode-skill-creator · GitHub: @antongulin · Registry: skills.sh

Bundle.social Uploads

This skill covers media file upload and management on Bundle.social.

Authentication

x-api-key: <your-api-key>

Base URL: https://api.bundle.social

Reference Docs

Read references/README.md for platform enums and standard errors. Read references/05-upload.md for endpoint details.

How to Use This Skill

When a user needs to upload or manage media files:

1. Determine upload type — direct file, URL import, or large file multipart
2. Read the reference doc for the specific endpoint
3. Generate curl command examples with <your-api-key> as placeholder (NEVER call the actual API)
4. Return the upload ID — the user will need it for creating posts (cross-reference with bundle-social-posts skill)

Upload Types

Direct Upload (small/medium files)

POST /api/v1/upload/ with multipart/form-data containing the file. Best for images and short videos under ~100MB.

URL Import (files already online)

POST /api/v1/upload/from-url — Bundle.social fetches the file from a URL. Useful when the file is already hosted somewhere accessible.

Multipart Upload (large files)

For files over ~100MB, use the three-step process:

1. POST /api/v1/upload/init — Initialize with fileName, fileSize, mimeType, teamId
2. Upload parts to the returned uploadUrl (standard S3 multipart upload)
3. POST /api/v1/upload/finalize — Finalize with ETags and PartNumbers

Endpoint Reference Summary

• GET /api/v1/upload/ — List uploads (filterable by teamId, type, search)
• POST /api/v1/upload/ — Upload file (multipart/form-data)
• GET /api/v1/upload/{id} — Get single upload
• DELETE /api/v1/upload/{id} — Delete single upload
• DELETE /api/v1/upload/ — Bulk delete uploads
• POST /api/v1/upload/from-url — Create upload from remote URL
• POST /api/v1/upload/init — Initialize large file upload
• POST /api/v1/upload/finalize — Finalize multipart upload

Common Patterns

1. Simple post with image: Upload file → Get upload ID → Create post with upload ID as media
2. Import from web: Found an image online → Use from-url → Get upload ID → Use in post
3. Large video upload: Init → Upload parts (client-side) → Finalize → Use in post
4. Media management: List uploads by team → Search by filename → Delete old/unused files
5. Bulk cleanup: List uploads → Bulk delete old/unused media

Important Notes

• Upload endpoint uses multipart/form-data — not JSON
• For from-url, Bundle.social fetches the file server-side
• Multipart upload follows S3 conventions — parts can be uploaded in parallel
• Check org upload usage before uploading large files
• Upload type enum: image, video, other