Create a post
POST /public/v1/postsCreates a post. Depending on type it lands as a draft, goes on the calendar for a
future time, or publishes right away. One call can target many channels at once.
This is the largest request body in the API and the only throttled operation.
Doing this in the app? See composing and scheduling posts. Also
available as sharek posts:create (CLI) and
integrationSchedulePostTool (MCP).
| Field | Required | Description |
|---|---|---|
type |
Yes | One of draft, schedule, now, update. |
date |
Yes | ISO 8601 UTC time to publish. Required even for draft and now. Find the next free slot gives you a channel’s next open time. |
shortLink |
Yes | true to rewrite links in the content as Sharek short links, so clicks are counted. |
tags |
Yes | Array of tags. May be empty, but each entry needs both value and label. |
posts |
Yes | Array with at least one entry, one per channel. See below. |
order |
No | Accepted and ignored. Leave it out. |
inter |
No | Interval, in the same units the app uses for recurring posts. |
republish |
No | Set true to deliberately publish an already-published post again. Without it, a schedule or now call whose first value[].id is a published post is rejected. |
creationMethod |
No | API or CLI, recorded on the post. Anything else is stored as API. |
Each entry in posts
Section titled “Each entry in posts”| Field | Required | Description |
|---|---|---|
integration.id |
Yes | The channel to publish to, from list channels. |
value |
Yes | Array with at least one entry. One entry is a single post; several entries make a thread, each one replying to the last. |
value[].content |
Yes | The post text. May be an empty string only if that entry carries at least one image. |
value[].image |
Yes | Array of media. Empty array when there is none. |
value[].delay |
No | Minutes to wait before this entry in a thread. |
value[].id |
No | The id of an existing post or reply, to update it in place instead of creating a new one. |
settings |
No | The provider’s options. Leaving it out is the same as sending {}, which a provider with required options refuses. |
group |
No | The group of an existing post this entry replaces. The old post is removed, and the new one gets a group of its own. |
There is no date per channel: a date inside a posts entry is ignored, and the
top-level date applies to every channel in the call. To post at different times, make
one call per time.
Each entry in image
Section titled “Each entry in image”Media must be uploaded first. Take the id and path straight from
upload a file or
upload from a URL. For a file already in your media
library, list media returns the same pair.
| Field | Required | Description |
|---|---|---|
id |
Yes | Media id returned by an upload. |
path |
Yes | Media URL returned by an upload. Must end .png, .jpg, .jpeg, .gif, .webp or .mp4. |
alt |
No | Alt text. |
thumbnail |
No | Thumbnail URL. |
Do not send __type
Section titled “Do not send __type”The provider discriminator inside settings is filled in by Sharek from the channel you
named, and any value you send is overwritten. Send only the provider’s real options:
"settings": { "title": "My video", "type": "public" }What each provider accepts is one page per channel, linked from the channels Sharek offers; X settings is a good first example. To read a specific channel’s live schema instead, call channel settings.
Examples
Section titled “Examples”Schedule one text post:
curl -X POST https://dash.sharek.app/api/public/v1/posts \ -H "Authorization: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "type": "schedule", "date": "2026-09-01T10:00:00.000Z", "shortLink": false, "tags": [], "posts": [ { "integration": { "id": "channel-id" }, "value": [ { "content": "Hello from the Sharek API", "image": [] } ], "settings": {} } ] }'Schedule a post with an image:
curl -X POST https://dash.sharek.app/api/public/v1/posts \ -H "Authorization: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "type": "schedule", "date": "2026-09-01T10:00:00.000Z", "shortLink": false, "tags": [], "posts": [ { "integration": { "id": "channel-id" }, "value": [ { "content": "Our new release is out", "image": [ { "id": "media-id", "path": "https://media.example.com/launch.png" } ] } ], "settings": { "post_type": "post" } } ] }'Schedule a two-part thread. Extra entries in value become replies:
curl -X POST https://dash.sharek.app/api/public/v1/posts \ -H "Authorization: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "type": "schedule", "date": "2026-09-01T10:00:00.000Z", "shortLink": false, "tags": [], "posts": [ { "integration": { "id": "channel-id" }, "value": [ { "content": "First post in the thread", "image": [] }, { "content": "The reply that follows it", "image": [] } ], "settings": {} } ] }'Response
Section titled “Response”One entry per channel in the request:
[ { "postId": "post-id", "integration": "channel-id" }]Keep postId. It is what change status,
update settings, delete and
post analytics all take.
The four types
Section titled “The four types”type |
What happens |
|---|---|
draft |
Saved to the calendar, never published on its own. Promote it later with change status. |
schedule |
Queued for date. |
now |
Published immediately. date is still required. |
update |
Saves changes to the posts named by value[].id in place and keeps their state. It starts no publish run of its own. Without those ids it creates new scheduled posts instead, and Sharek’s hourly check for missed posts publishes them once date has passed (unless date is more than two days old), so always send the ids. |
Accepting the call is not the same as publishing it. When a post fails on its way out,
Sharek raises a notification, which list notifications
returns, and list posts can show the platform’s reason in error.
Validation
Section titled “Validation”Sharek runs the same checks the composer runs, and returns the first failure as 400:
{ "statusCode": 400, "provider": "youtube", "name": "My channel", "message": "post is too long, please fix it"}The provider and name tell you which channel rejected it, which matters when one
call targets several.
Drafts are checked less strictly, but less strictly does not mean unchecked. A draft
still needs content or an image, and it still needs a settings object valid for its
provider. Verified against production on 2026-08-24: creating a draft for an Instagram
channel with "settings": {} is refused with
{ "statusCode": 400, "message": [ "posts.0.settings.post_type should not be null or undefined", "posts.0.settings.post_type must be one of the following values: post, story" ], "error": "Bad Request"}What a draft does skip is the publish-time layer: each channel’s media rules and length
limit are checked only when type is schedule, now or update, so a draft that
breaks them is still saved.
| Response | Meaning |
|---|---|
400 {"statusCode": 400, "provider": ..., "message": ...} |
A channel rejected the post. The message is the same text the composer shows. |
400 {"message": ["..."], "error": "Bad Request"} |
The body itself is malformed: a missing required field, a bad date, an empty posts array. |
400 {"statusCode": 400, "message": "Integration with id ... not found", "error": "Bad Request"} |
A channel id in the request does not belong to your organization. Note message is a plain string here, not the array the field-validation shape uses. |
402 |
A plan limit was reached, usually posts per month. The body’s url points at where to resolve it. |
429 |
More than 100 create calls in the last hour. |