Endpoints
Use the media endpoints to upload files into FeedHive and manage media library items that can be attached to posts. The response shape is documented on the Media object page.
Supported MIME types
| MIME type | Resulting type |
|---|---|
image/jpeg | image |
image/jpg | image |
image/png | image |
image/gif | gif |
video/mp4 | video |
video/quicktime | video |
video/mov | video |
Upload workflow
Create an upload session
Call POST /media/uploads with the original filename and declared content_type.
Upload the file directly to S3
Use the returned upload_url as a PUT target and send the exact same Content-Type header you declared in step 1.
Complete the upload
Call POST /media/uploads/:id/complete to verify the object and create the permanent media record.
POST /media/uploads
Create a new upload session and receive a pre-signed S3 URL.
Request body
| Field | Type | Description |
|---|---|---|
| filename | string | Required. Original filename and must be non-empty. |
| content_type | string | Required. MIME type for the file to upload. |
Example request
curl --request POST \
--url https://api.feedhive.com/media/uploads \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"filename": "launch-hero.png",
"content_type": "image/png"
}'Response body
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| data.upload_id | string | Upload session identifier. |
| data.upload_url | string | Pre-signed S3 URL for the direct file upload. |
| data.expires_at | string | Expiry datetime for the upload URL in ISO 8601 format. |
The returned upload_url is valid for 10 minutes. Upload the raw file bytes with an HTTP PUT request before calling the complete endpoint.
POST /media/uploads/:id/complete
Verify an upload session and create the permanent media record.
Path parameters
| Field | Type | Description |
|---|---|---|
| id | string | Upload session ID returned by POST /media/uploads. |
No request body is required.
Validation rules
- The upload session must exist and must not be expired.
- The upload session must not already be completed.
- The uploaded S3 object must exist and have a non-zero file size.
- The stored object content type must match the
content_typedeclared when the upload session was created.
Example request
curl --request POST \
--url https://api.feedhive.com/media/uploads/upl_xyz/complete \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'Response body
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| data.id | string | Media identifier created from the completed upload. |
Use the returned id in post media arrays after the upload is complete.
GET /media
List media library items owned by the authenticated caller.
Query parameters
| Field | Type | Description |
|---|---|---|
| limit | number | Page size. Defaults to 20 and cannot exceed 100. |
| cursor | string | Pagination cursor returned by a previous list response. |
Example request
curl --request GET \
--url 'https://api.feedhive.com/media?limit=20' \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'Response body
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| data.items | Media[] | Returned media records for this page. |
| data.total | number | Total number of media items owned by the caller. |
| data.has_more | boolean | Whether another page of media items is available. |
| data.next_cursor | string | null | Cursor for the next page, or null when there are no more results. |
GET /media/:id
Fetch a single media item.
Path parameters
| Field | Type | Description |
|---|---|---|
| id | string | Media item identifier. IDs may contain forward slashes and must be URL encoded when used in the request path. |
Example request
curl --request GET \
--url https://api.feedhive.com/media/med_abc123 \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'Response body
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| data | Media | Requested media item. |
DELETE /media/:id
Delete a media item. The API removes the database record first and then deletes the backing S3 objects.
Path parameters
| Field | Type | Description |
|---|---|---|
| id | string | Media item identifier. IDs may contain forward slashes and must be URL encoded when used in the request path. |
Example request
curl --request DELETE \
--url https://api.feedhive.com/media/med_abc123 \
--header 'accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'Response body
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| data | Media | Deleted media item. |