Skip to content

Create a post

POST /public/v1/posts

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

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.

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.

Schedule one text post:

Terminal window
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:

Terminal window
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:

Terminal window
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": {}
}
]
}'

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.

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.

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.