curl --request POST \
  --url https://post.chatclean.com.br/api/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "We just shipped scheduled threads. Here is how they work.",
  "status": "scheduled",
  "scheduled_at": "2026-10-12T14:00:00Z",
  "media": [
    {
      "url": "https://example.com/launch.jpg",
      "alt": "Product launch banner"
    }
  ],
  "social_account_id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
  "content_type": "x_post",
  "meta": {
    "thread_replies": [
      {
        "text": "2/ Replies publish under the first post."
      }
    ]
  },
  "label_ids": [
    "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f"
  ]
}
'

{
  "id": "9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41",
  "post_group_id": "9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03",
  "author": {
    "id": "9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "name": "Ana Souza"
  },
  "content": "We just shipped scheduled threads. Here is how they work.",
  "media": [
    {
      "id": "9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
      "path": "medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "url": "https://example.com/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "type": "image",
      "mime_type": "image/jpeg",
      "original_filename": "launch.jpg",
      "size": 482113,
      "meta": {
        "width": 1080,
        "height": 1350,
        "alt_text": "Product launch banner"
      }
    }
  ],
  "status": "scheduled",
  "schedule_mode": "custom",
  "scheduled_at": "2026-10-12 14:00:00",
  "published_at": null,
  "approval_requested_by": null,
  "approval_requested_at": null,
  "approved_by": null,
  "approved_at": null,
  "recurrence": null,
  "origin": "trypost",
  "publish_status": "pending",
  "platform": "x",
  "content_type": "x_post",
  "meta": {
    "thread_replies": [
      {
        "text": "2/ Replies publish under the first post.",
        "media": []
      }
    ]
  },
  "platform_url": null,
  "error_message": null,
  "display_name": "PostClean",
  "display_username": "postclean",
  "display_avatar": "https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg",
  "social_account": {
    "id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
    "platform": "x",
    "display_name": "PostClean",
    "username": "postclean",
    "status": "connected",
    "has_posting_schedule": true,
    "timezone": "America/Sao_Paulo",
    "posting_goal": 5,
    "max_content_length": 280,
    "long_posts": false,
    "verified_badge": null
  },
  "labels": [
    {
      "id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "name": "Launch",
      "color": "#2563EB",
      "created_at": "2026-09-01 10:00:00",
      "updated_at": "2026-09-01 10:00:00"
    }
  ],
  "created_at": "2026-10-08 13:20:11",
  "updated_at": "2026-10-08 13:20:11"
}

{
  "message": "Unauthenticated."
}

{
  "message": "Active subscription required."
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

{
  "name": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 30 seconds."
}

Posts

Create post

Creates one post on one social account.

status: draft (default) saves a draft.
status: scheduled with scheduled_at schedules it at that time; with queue (next or top) it takes a slot of the channel’s posting schedule; with queue_slot it takes that exact free slot (from GET /channels/{account}/queue/slots).
status: publishing publishes it now.

Omitted content_type is chosen like the app does: on Pinterest a video makes pinterest_video_pin and several images pinterest_carousel, on TikTok images only make tiktok_photo, every other network takes its default format.

To schedule or publish, the post needs its network’s required settings in meta (see PlatformMeta). Sending platforms is refused with 422; validation errors name the field directly (meta.board_id, content_type). API keys belong to workspace admins, who publish directly, so a post created through the API is never stored as pending_approval.

To post the same text on several channels at once, use POST /posts/batch.

POST

posts

curl --request POST \
  --url https://post.chatclean.com.br/api/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "We just shipped scheduled threads. Here is how they work.",
  "status": "scheduled",
  "scheduled_at": "2026-10-12T14:00:00Z",
  "media": [
    {
      "url": "https://example.com/launch.jpg",
      "alt": "Product launch banner"
    }
  ],
  "social_account_id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
  "content_type": "x_post",
  "meta": {
    "thread_replies": [
      {
        "text": "2/ Replies publish under the first post."
      }
    ]
  },
  "label_ids": [
    "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f"
  ]
}
'

{
  "id": "9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41",
  "post_group_id": "9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03",
  "author": {
    "id": "9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "name": "Ana Souza"
  },
  "content": "We just shipped scheduled threads. Here is how they work.",
  "media": [
    {
      "id": "9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
      "path": "medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "url": "https://example.com/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "type": "image",
      "mime_type": "image/jpeg",
      "original_filename": "launch.jpg",
      "size": 482113,
      "meta": {
        "width": 1080,
        "height": 1350,
        "alt_text": "Product launch banner"
      }
    }
  ],
  "status": "scheduled",
  "schedule_mode": "custom",
  "scheduled_at": "2026-10-12 14:00:00",
  "published_at": null,
  "approval_requested_by": null,
  "approval_requested_at": null,
  "approved_by": null,
  "approved_at": null,
  "recurrence": null,
  "origin": "trypost",
  "publish_status": "pending",
  "platform": "x",
  "content_type": "x_post",
  "meta": {
    "thread_replies": [
      {
        "text": "2/ Replies publish under the first post.",
        "media": []
      }
    ]
  },
  "platform_url": null,
  "error_message": null,
  "display_name": "PostClean",
  "display_username": "postclean",
  "display_avatar": "https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg",
  "social_account": {
    "id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
    "platform": "x",
    "display_name": "PostClean",
    "username": "postclean",
    "status": "connected",
    "has_posting_schedule": true,
    "timezone": "America/Sao_Paulo",
    "posting_goal": 5,
    "max_content_length": 280,
    "long_posts": false,
    "verified_badge": null
  },
  "labels": [
    {
      "id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "name": "Launch",
      "color": "#2563EB",
      "created_at": "2026-09-01 10:00:00",
      "updated_at": "2026-09-01 10:00:00"
    }
  ],
  "created_at": "2026-10-08 13:20:11",
  "updated_at": "2026-10-08 13:20:11"
}

{
  "message": "Unauthenticated."
}

{
  "message": "Active subscription required."
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

{
  "name": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 30 seconds."
}

Authorizations

Authorization

string

header

required

Workspace API key from Settings → API Keys.

Body

application/json

Social account of this workspace. A post has exactly one; use POST /posts/batch for several.

content

string | null

Post text, at most 25000 characters. When status is scheduled or publishing it must also fit each account's limit (max_content_length of the social account, for example 280 on X or 25000 for X accounts with long posts, 300 on Bluesky, 500 on Mastodon including the content warning), measured on the text the network receives. A scheduled or published post needs text or media.

Maximum string length: 25000

media

object[]

Media in order. Each item is one of upload_token, url or id. Types the channel does not accept are refused.

Show child attributes

status

enum<string>

default:draft

draft keeps the post editable. scheduled schedules it at scheduled_at or in the channel queue (queue). publishing publishes it now.

Available options:

draft,

scheduled,

publishing

content_type

enum<string> | null

Format; must belong to the account's network. Omitted, it is chosen from the media.

Available options:

instagram_feed,

instagram_reel,

instagram_story,

linkedin_post,

linkedin_page_post,

facebook_post,

facebook_reel,

facebook_story,

tiktok_video,

tiktok_photo,

youtube_short,

x_post,

x_poll,

threads_post,

threads_ghost_post,

pinterest_pin,

pinterest_video_pin,

pinterest_carousel,

bluesky_post,

mastodon_post,

telegram_post,

discord_message,

google_business_post

Response

The created post.

A post on one channel. Posts created together from several channels are independent posts that share a post_group_id.

string<uuid>

post_group_id

string<uuid> | null

Shared by the posts created in one batch.

author

object | null

A workspace member. Only the id and name are exposed.

Show child attributes

content

string | null

Post text, stored as sent (posts written in the app hold the editor's HTML).

media

object[] | null

Show child attributes

status

enum<string>

Lifecycle of the post in PostClean. pending_approval is a post a member who needs approval asked to schedule or publish. The outcome on the network is publish_status.

Available options:

draft,

pending_approval,

scheduled,

publishing,

published,

failed

schedule_mode

enum<string> | null

queue: the post holds a slot of the channel's posting schedule. custom: it is scheduled at its own time.

Available options:

queue,

custom,

null

scheduled_at

string | null

UTC, format Y-m-d H:i:s.

published_at

string | null

UTC, format Y-m-d H:i:s.

approval_requested_by

object | null

Who asked for approval (not always the author).

Show child attributes

approval_requested_at

string | null

UTC, format Y-m-d H:i:s.

approved_by

object | null

A workspace member. Only the id and name are exposed.

Show child attributes

approved_at

string | null

UTC, format Y-m-d H:i:s.

recurrence

object | null

Repeat rule, or null.

Show child attributes

origin

enum<string>

network for posts imported from the network (published outside PostClean).

Available options:

trypost,

network

publish_status

enum<string>

Publishing state on the network. pending until the post is sent; retrying waits for a retry after a network limit or a temporary network problem (such as a LinkedIn post not yet ready for its comment); pending_review and rejected come from networks that review posts (Google Business).

Available options:

pending,

publishing,

retrying,

pending_review,

published,

failed,

rejected

platform

enum<string> | null

Network of the post's channel.

Available options:

linkedin,

linkedin-page,

x,

tiktok,

youtube,

facebook,

instagram,

instagram-facebook,

threads,

pinterest,

bluesky,

mastodon,

telegram,

discord,

google_business

content_type

enum<string> | null

Post format on one network. It must belong to the destination's network. GET /content-types lists the formats of each network with their media rules. Instagram and Facebook stories publish no text. An X poll (x_poll) takes no media; its choices and length are in meta.poll.

Available options:

instagram_feed,

instagram_reel,

instagram_story,

linkedin_post,

linkedin_page_post,

facebook_post,

facebook_reel,

facebook_story,

tiktok_video,

tiktok_photo,

youtube_short,

x_post,

x_poll,

threads_post,

threads_ghost_post,

pinterest_pin,

pinterest_video_pin,

pinterest_carousel,

bluesky_post,

mastodon_post,

telegram_post,

discord_message,

google_business_post

Visão geral

Posts

Notas de posts

Aprovações

Recorrência

Mídia e uploads

Contas sociais

Canais

Ideias

Etapas de ideias

Análises

Etiquetas

Assinaturas

Workspace

Chaves de API

Webhooks

Repost

Plataforma

Create post

Authorizations

Body

Response