Endpoints

Use the posts endpoints to create, schedule, update, fetch, list, and delete posts in FeedHive. The response shape is documented on the Post object page.

GET /posts

List all posts owned by the authenticated caller.

Query parameters

Example request

curl --request GET \
  --url 'https://api.feedhive.com/posts?limit=20&status=draft,scheduled&labels=lbl_campaign_q4&socials=social_123' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response body

GET /posts/:id

Fetch a single post by ID.

Path parameters

Example request

curl --request GET \
  --url https://api.feedhive.com/posts/post_123 \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response body

POST /posts

Create a new post.

Request body

SubpostInput

AccountReferenceInput

AccountCustomizationInput

Validation rules

• publish_type must be one of: regular, short, story.
• For publish_type = regular:
  • text is required and must be non-empty.
  • media is optional.
• For publish_type = short:
  • text is required and must be non-empty.
  • media is required.
  • If accounts are present, all accounts must be short-compatible: facebook, instagram, youtube, tiktok.
  • Posts with no accounts are allowed in draft state.
  • thumbnail_media_id is supported when the post targets Instagram or YouTube and media contains exactly one video.
  • The thumbnail must be a completed image upload owned by the same user/workspace. GIFs, videos, incomplete uploads, and inaccessible media are rejected.
• For publish_type = story:
  • media is required.
  • If no accounts are present, text is optional.
  • If all accounts are story-compatible (facebook, instagram), text is optional.
  • If any account is not story-compatible, text is required and must be non-empty.
• Media ID, account ID, and label ID arrays must not contain duplicates.
• For accounts, you may pass either plain account IDs or { id, board_id } objects.
• Both snake_case and legacy camelCase are accepted for platform-specific request fields, but snake_case is the official public API format.
• Every account_customizations[].id value must also be present in accounts.
• Each account_customizations entry inherits the top-level publish_type and must satisfy that publish type's validation rules.
• When status is scheduled:
  • accounts must be provided.
  • scheduled_at must be provided.
  • scheduled_at must be a future datetime.
• scheduled_at is only permitted when status is scheduled.

Custom Reel and Short thumbnails

Upload and complete both files through the media upload flow before creating the post. Use the completed video media ID in media and the completed image media ID in thumbnail_media_id. Do not pass an upl_... upload-session ID.

YouTube Short:

{
  "text": "Watch the full walkthrough",
  "media": ["med_short_video"],
  "thumbnail_media_id": "med_short_thumbnail",
  "accounts": ["youtube_account_id"],
  "publish_type": "short"
}

Instagram Reel:

{
  "text": "A quick product walkthrough",
  "media": ["med_reel_video"],
  "thumbnail_media_id": "med_reel_thumbnail",
  "accounts": ["instagram_account_id"],
  "publish_type": "short"
}

Publish type examples

Regular post:

{
  "text": "Launch update for this week",
  "publish_type": "regular"
}

Short post:

{
  "text": "Quick update",
  "media": ["med_short_video"],
  "accounts": ["social_fb"],
  "publish_type": "short"
}

Story post:

{
  "media": ["med_story_image"],
  "accounts": ["social_ig"],
  "publish_type": "story"
}

Story post with no accounts yet:

{
  "media": ["med_story_image"],
  "publish_type": "story"
}

Story post targeting a non-story-compatible account (text required):

{
  "text": "Cross-posting this story asset",
  "media": ["med_story_image"],
  "accounts": ["social_linkedin"],
  "publish_type": "story"
}

Example request

curl --request POST \
  --url https://api.feedhive.com/posts \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Launch update for this week",
    "media": ["med_hero_image"],
    "subposts": [
      {
        "text": "Thread follow-up with the main rollout checklist.",
        "media": []
      }
    ],
    "accounts": [
      "social_123",
      { "id": "social_456", "board_id": null }
    ],
    "account_customizations": [
      {
        "id": "social_456",
        "text": "A LinkedIn-specific version of the launch update.",
        "media": [],
        "subposts": [],
        "title": "Launch week teaser",
        "link": "https://feedhive.com/launch",
        "terms_and_conditions": "Valid while supplies last.",
        "coupon_code": "LAUNCH20",
        "start_date": "2026-04-15T00:00:00.000Z",
        "end_date": "2026-04-22T00:00:00.000Z",
        "cta": "learn_more"
      }
    ],
    "labels": ["lbl_campaign_q4"],
    "status": "scheduled",
    "scheduled_at": "2026-04-15T13:00:00.000Z",
    "notes": "Use the updated CTA once legal signs off.",
    "short_link_enabled": true,
    "title": "Launch week teaser",
    "link": "https://feedhive.com/launch",
    "terms_and_conditions": "Valid while supplies last.",
    "coupon_code": "LAUNCH20",
    "start_date": "2026-04-15T00:00:00.000Z",
    "end_date": "2026-04-22T00:00:00.000Z",
    "cta": "learn_more",
    "topic_type": "offer",
    "privacy_status": "private",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": true
  }'

Response body

PATCH /posts/:id

Update an existing post. Fields use replace semantics, so any field you send fully overwrites the current value.

Path parameters

Request body

The same validation rules as POST /posts apply.

You can change only the thumbnail without replacing media; the existing root media must still contain exactly one video.

When updating to status: "scheduled", Public API callers are always treated as non-approvers. If the owner/workspace requires approval, the post is stored as pending approval, with scheduled_at preserved.

Example request

curl --request PATCH \
  --url https://api.feedhive.com/posts/post_123 \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Launch update for this week - revised",
    "labels": ["lbl_campaign_q4", "lbl_product_launch"],
    "scheduled_at": "2026-04-16T13:00:00.000Z",
    "notes": "Approved for the final review pass.",
    "short_link_enabled": false,
    "title": "Launch week teaser - revised",
    "link": "https://feedhive.com/launch-revised",
    "terms_and_conditions": "Valid while supplies last.",
    "coupon_code": "LAUNCH20",
    "start_date": "2026-04-16T00:00:00.000Z",
    "end_date": "2026-04-23T00:00:00.000Z",
    "cta": "learn_more",
    "topic_type": "offer",
    "privacy_status": "private",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": true
  }'

Response body

DELETE /posts/:id

Soft-delete a post. Deleted posts no longer appear in list results, but the underlying record is retained internally.

Path parameters

Example request

curl --request DELETE \
  --url https://api.feedhive.com/posts/post_123 \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response body