Uploading files

Add an image, video or PDF to the Media Library in three steps, then use its fileId on a post. The file goes straight to storage, so large videos never pass through a tool call.

1. Start the upload

Send the file's name, exact size in bytes and type. Chirpy checks the type, the size limit and your storage, and returns a fileId and a link.

curl https://chirpy.me/api/v1/start_upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"launch-film.mp4","fileSize":55804631,"mimeType":"video/mp4"}'

{
  "ok": true,
  "data": {
    "fileId": 10234,
    "upload": {
      "method": "PUT",
      "url": "https://...",
      "headers": {
        "Content-Type": "video/mp4",
        "Content-Length": "55804631"
      },
      "expiresAt": "2026-10-29T13:00:00.000Z"
    }
  }
}

2. Send the file

PUT the bytes to upload.url with exactly the headers given, before expiresAt. The link is signed for that type and size, so anything else is refused.

curl -X PUT -H "Content-Type: video/mp4" --data-binary @launch-film.mp4 "UPLOAD_URL"

3. Finish it

Chirpy checks what arrived and adds it to the Media Library. Pass the fileId in mediaFileIds on create_drafts or attach_media.

curl https://chirpy.me/api/v1/finish_upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId":10234}'

Rules

Types	JPEG, PNG, GIF, WebP, SVG, MP4, MPEG, QuickTime (.mov), WebM, AVI, Matroska and PDF.
Size	Videos up to 2 GB. Images and PDFs up to 100 MB.
Storage	Uploads count towards your plan's Media Library storage, shared across your team.
Link	Works for one hour for videos and 15 minutes for other files. An upload with nothing sent before then is removed when you finish it; start again.
Checks	If the size or type that arrives differs from what you declared, the file is removed and `finish_upload` says why.
Open uploads	Up to 10 unfinished uploads an hour.
Videos	After finishing, videos are prepared for posting in the background. QuickTime files are converted to MP4.

In an AI app, these are the start_upload and finish_upload tools. Step 2 needs an app that can send an HTTP PUT, such as Claude Code or your own script. Chat apps that cannot do that can still use files already in your Media Library.