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

Field	Type	Description
limit	number	Page size. Defaults to 20 and cannot exceed 100.
cursor	string	Pagination cursor from a previous response.
status	string	Optional comma-separated status filter. Supported values: draft, scheduled, publishing, published, failed.
labels	string	Optional comma-separated label ID filter. Matching uses OR semantics.
socials	string	Optional comma-separated social account ID filter. Matching uses OR semantics.

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

Field	Type	Description
success	boolean	Whether the request succeeded.
data.items	Post[]	Returned posts for this page.
data.total	number	Total number of posts owned by the caller.
data.has_more	boolean	Whether another page of posts is available.
data.next_cursor	string \| null	Cursor for the next page, or null when there are no more results.

GET /posts/:id

Fetch a single post by ID.

Path parameters

Field	Type	Description
id	string	Post identifier.

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

Field	Type	Description
success	boolean	Whether the request succeeded.
data	Post	Requested post.

POST /posts

Create a new post.

Request body

Field	Type	Description
text	string \| null	Root post text. Required for regular and short publish types; conditionally required for story based on target accounts.
media	string[]	Ordered media IDs to attach.
subposts	SubpostInput[]	Optional thread replies.
accounts	string[] \| AccountReferenceInput[]	Optional social account IDs or account objects to target.
account_customizations	AccountCustomizationInput[]	Optional per-account overrides.
labels	string[]	Optional label IDs to attach.
status	draft \| scheduled	Optional post status. Defaults to draft.
scheduled_at	string	Conditional. ISO 8601 future datetime; required when status is scheduled.
notes	string \| null	Optional internal notes.
short_link_enabled	boolean	Optional short-link setting.
publish_type	regular \| short \| story	Optional publish mode. Defaults to regular.
title	string \| null	Optional platform-specific title (YouTube, Google Business, Pinterest).
link	string \| null	Optional platform-specific link (Google Business, Pinterest).
terms_and_conditions	string \| null	Optional Google Business offer terms.
coupon_code	string \| null	Optional Google Business offer coupon code.
start_date	string \| null	Optional Google Business event/offer start datetime.
end_date	string \| null	Optional Google Business event/offer end datetime.
cta	string \| null	Optional Google Business CTA.
topic_type	string \| null	Optional Google Business topic type.
privacy_status	string \| null	Optional YouTube/TikTok privacy status.
allow_comments	boolean \| null	Optional TikTok comment toggle.
allow_duet	boolean \| null	Optional TikTok duet toggle.
allow_stitch	boolean \| null	Optional TikTok stitch toggle.

`SubpostInput`

Field	Type	Description
text	string \| null	Subpost text.
media	string[]	Ordered media IDs for the subpost. Do not send duplicates.

`AccountReferenceInput`

Field	Type	Description
id	string	Account ID.
board_id	string \| null	Pinterest board ID.

`AccountCustomizationInput`

Field	Type	Description
id	string	Account ID. Must also appear in the accounts array.
text	string \| null	Override text for that account.
media	string[]	Override media IDs.
subposts	SubpostInput[]	Override subposts for that account.
title	string \| null	Platform-specific override title.
link	string \| null	Platform-specific override link.
terms_and_conditions	string \| null	Google Business offer terms override.
coupon_code	string \| null	Google Business offer coupon code override.
start_date	string \| null	Google Business event/offer start datetime override.
end_date	string \| null	Google Business event/offer end datetime override.
cta	string \| null	Google Business CTA override.

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.
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.

Public API callers are always treated as non-approvers. If the owner/workspace requires approval, creating with status: "scheduled" stores the post as pending approval while still storing scheduled_at.

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

Field	Type	Description
success	boolean	Whether the request succeeded.
data	Post	Created post.

PATCH /posts/:id

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

Path parameters

Field	Type	Description
id	string	Post identifier.

Request body

Field	Type	Description
text	string \| null	Replacement root text.
media	string[]	Replacement media IDs.
subposts	SubpostInput[]	Replacement subposts.
accounts	string[] \| AccountReferenceInput[]	Replacement social account IDs or account objects.
account_customizations	AccountCustomizationInput[]	Replacement per-account overrides.
labels	string[]	Replacement label IDs.
status	draft \| scheduled	Replacement status.
publish_type	regular \| short \| story	Replacement publish mode.
scheduled_at	string \| null	Replacement scheduled datetime. Send null to clear it.
notes	string \| null	Replacement notes value.
short_link_enabled	boolean	Replacement short-link setting.
title	string \| null	New platform-specific title.
link	string \| null	New platform-specific link.
terms_and_conditions	string \| null	New Google Business offer terms.
coupon_code	string \| null	New Google Business coupon code.
start_date	string \| null	New Google Business event/offer start datetime.
end_date	string \| null	New Google Business event/offer end datetime.
cta	string \| null	New Google Business CTA.
topic_type	string \| null	New Google Business topic type.
privacy_status	string \| null	New YouTube/TikTok privacy status.
allow_comments	boolean \| null	New TikTok comment toggle.
allow_duet	boolean \| null	New TikTok duet toggle.
allow_stitch	boolean \| null	New TikTok stitch toggle.

The same validation rules as POST /posts apply.

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

Field	Type	Description
success	boolean	Whether the request succeeded.
data	Post	Updated post.

DELETE /posts/:id

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

Path parameters

Field	Type	Description
id	string	Post identifier.

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

Field	Type	Description
success	boolean	Whether the request succeeded.
data	Post	Deleted post.

Post object Label object