Docs/Uploads

Uploads

Upload media for feeds, items and social posts.

Start Upload

POSThttps://api.fountain.fm/v1/uploads

Split the file into part_size-byte chunks and PUT chunk i to upload.urls[i]. The last chunk may be smaller; small files use one URL. Then finalize and poll until READY.

Request body

Fields depend on kind. SOCIAL_POST_VIDEO requires only kind, content_type and num_bytes. Attach it as upload_id with Update Social Post.

kindMediaKindrequired

Kind of media to upload.

feed_idstringoptional

ID of the target feed. Not for SOCIAL_POST_VIDEO.

File MIME type.

num_bytesnumberrequired

File size in bytes. Max 10 MB for images, 400 MB for audio, 20 GB for item video, 16 GB for social video.

item_idstringoptional

ID of the target item. For ITEM_IMAGE, ITEM_AUDIO and ITEM_VIDEO.

access'DEFAULT' | 'PAID'optional

Item slot the upload can attach to. For ITEM_AUDIO and ITEM_VIDEO. Defaults to DEFAULT.

Responses

200Upload started.

mediaMediarequired

Upload with status PENDING.

uploadobjectrequired

The presigned multipart upload.

urlsstring[]required

Ordered presigned part URLs; PUT each chunk to its URL.

part_sizenumberrequired

Chunk size in bytes. The last chunk may be smaller.

Example request

curl -X POST "https://api.fountain.fm/v1/uploads" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"ITEM_AUDIO","feed_id":"a1b2c3d4","item_id":"e5f6g7h8","content_type":"audio/mpeg","num_bytes":48218112}'

Request body

{
  "kind": "ITEM_AUDIO",
  "feed_id": "a1b2c3d4",
  "item_id": "e5f6g7h8",
  "content_type": "audio/mpeg",
  "num_bytes": 48218112
}

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "PENDING"
  },
  "upload": {
    "urls": [
      "https://r2.fountain.fm/uploads/6f1a2b3c/part-1?...",
      "https://r2.fountain.fm/uploads/6f1a2b3c/part-2?..."
    ],
    "part_size": 100000000
  }
}

Get Upload

GEThttps://api.fountain.fm/v1/uploads/{id}

Poll until READY, then attach the upload ID as image_id, audio_default_id, audio_paid_id, video_default_id or video_paid_id. Failed uploads return ERROR. Transcription runs separately and does not block media attachment.

Path parameters

idstringrequired

The upload to poll.

Responses

200The upload.

mediaMediarequired

The upload.

Example request

curl -X GET "https://api.fountain.fm/v1/uploads/{id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "READY",
    "preview_url": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3"
  }
}

Finalize Upload

POSThttps://api.fountain.fm/v1/uploads/{id}/finalize

Start processing after all chunks are uploaded. Missing parts return 409 MEDIA_NOT_READY. Images and audio process in seconds; video transcodes to HLS and can take minutes. Poll Get Upload until READY. SOCIAL_POST_VIDEO uploads are ready immediately.

Path parameters

idstringrequired

The upload to finalize.

Responses

200Upload finalized.

mediaMediarequired

The upload (status PROCESSING, or READY for a SOCIAL_POST_VIDEO).

Example request

curl -X POST "https://api.fountain.fm/v1/uploads/{id}/finalize" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "PROCESSING"
  }
}