Create a publication

POST

/projects/{id}/publications

const url = 'https://api.warmup.social/projects/00000000-0000-0000-0000-000000000000/publications';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"kind":"photo","platforms":["instagram"],"text":"New work","mediaId":"00000000-0000-0000-0000-000000000000"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.warmup.social/projects/00000000-0000-0000-0000-000000000000/publications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "photo", "platforms": [ "instagram" ], "text": "New work", "mediaId": "00000000-0000-0000-0000-000000000000" }'

The publication is queued (202) and sent to the selected networks asynchronously. The result for each network is in targets[].status — poll “Get a publication” to see it.

What each network supports:

Network	text	photo	story	Text limit
facebook	yes	yes	yes	63,206
instagram	no	yes	yes	2,200
threads	yes	yes	no	500

Body rules:

kind: text — text is required, mediaId is not allowed;
photo / story — mediaId from “Upload an image” is required;
1–3 networks, no duplicates;
for an Instagram photo the aspect ratio must be between 4:5 and 1.91:1.

Scheduling:

state: scheduled (default) without scheduledAt — goes out right away;
state: scheduled with a future scheduledAt — goes out at that moment (within about half a minute); a past scheduledAt is rejected with scheduled_at_past;
state: draft — stays in the planner and is never sent until you change it to scheduled or call “Publish now”. Drafts do not require connected networks.
timezone is the IANA zone the time was entered in; it is stored for display only.

Counts towards the publishing rate limit, like image upload.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

00000000-0000-0000-0000-000000000000

Project UUID.

Request Body^required

application/json

object

kind

required

string

Allowed values: text photo story

platforms

required

Array<string>

>= 1 items <= 3 items unique items

Allowed values: facebook instagram threads

text

Required for kind: text. Leading and trailing spaces are trimmed.

string

>= 1 characters

mediaId

Required for photo and story, not allowed for text.

string format: uuid

state

draft stays in the planner; scheduled goes out at scheduledAt or right away without it.

string

default: scheduled

Allowed values: draft scheduled

scheduledAt

When to publish, ISO 8601 with offset. Omit to publish right away (scheduled) or to leave a draft without a date.

string format: date-time

timezone

IANA time zone the time was entered in, e.g. Europe/Kyiv. Stored for display.

string

default: UTC <= 64 characters

Example

{
  "kind": "photo",
  "platforms": [
    "instagram"
  ],
  "text": "New work",
  "mediaId": "00000000-0000-0000-0000-000000000000"
}

Responses

202

Publication queued.

application/json

object

required

string format: uuid

kind

required

string

Allowed values: text photo story

state

required

draft and scheduled — not sent yet. After sending: publishing while any network is still in progress, published when every network succeeded, otherwise failed (see targets[] for the per-network outcome).

string

Allowed values: draft scheduled publishing published failed

platforms

required

Array<string>

Allowed values: facebook instagram threads

text

required

string

nullable

media

required

object

required

string format: uuid

url

required

string format: uri

width

required

integer

height

required

integer

scheduledAt

required

When the publication goes (or went) out. null only for a draft without a date.

string format: date-time

nullable

timezone

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

targets

required

Per-network outcome. Empty until the publication is sent.

Array<object>

object

platform

required

string

Allowed values: facebook instagram threads

status

required

string

Allowed values: queued publishing published failed

externalPostId

required

string

nullable

permalink

required

string

nullable

errorCode

required

Why the target failed. published_unconfirmed — Meta published the post but did not return its id; the post most likely went out.

string

nullable

Allowed values: connection_missing connection_not_ready media_not_found media_aspect_ratio needs_reauth rate_limit meta_unavailable media_rejected published_unconfirmed

publishedAt

required

string format: date-time

nullable

Example

{
  "kind": "text",
  "state": "draft",
  "platforms": [
    "facebook"
  ],
  "media": {
    "width": 1080,
    "height": 1350
  },
  "timezone": "Europe/Kyiv",
  "targets": [
    {
      "platform": "facebook",
      "status": "queued",
      "errorCode": "connection_missing"
    }
  ]
}

400

Validation failed (text_required, media_required, media_not_allowed, duplicate_platform, <platform>_<kind>_unsupported, <platform>_text_too_long, invalid_timezone), the image was not found (media_not_found), its aspect ratio does not fit the Instagram feed (media_aspect_ratio) or scheduledAt is in the past (scheduled_at_past).

application/json

Error with a machine-readable code. Body validation errors come as formErrors / fieldErrors; business errors carry a code.

object

code

string

platform

string

Allowed values: facebook instagram threads

formErrors

Array<string>

fieldErrors

object

key

additional properties

Array<string>

Example

{
  "code": "connection_missing",
  "platform": "facebook",
  "fieldErrors": {
    "mediaId": [
      "media_required"
    ]
  }
}

401

The Bearer token is missing or invalid.

application/json

object

statusCode

required

integer

message

required

One of:

string

error

string

key

additional properties

any

Example

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

404

The requested resource was not found.

application/json

object

statusCode

required

integer

message

required

One of:

string

error

string

key

additional properties

any

Example

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

409

The network is not connected to the project (connection_missing) or the connection is not active, e.g. it needs re-authorization (connection_not_ready).

application/json

Error with a machine-readable code. Body validation errors come as formErrors / fieldErrors; business errors carry a code.

object

code

string

platform

string

Allowed values: facebook instagram threads

formErrors

Array<string>

fieldErrors

object

key

additional properties

Array<string>

Example

{
  "code": "connection_missing",
  "platform": "facebook",
  "fieldErrors": {
    "mediaId": [
      "media_required"
    ]
  }
}

429

The publishing rate limit was exceeded.

application/json

object

statusCode

required

integer

message

required

One of:

string

error

string

key

additional properties

any

Example

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

Create a publication

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Responses

202

Example

400

Example

401

Example

404

Example

409

Example

429

Example

Request Body^required