Skip to content

Create a post

POST
/public/v1/posts
curl --request POST \
  --url https://api.loomta.com/public/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "platformIds": [ "8b2c1f4a-77d0-4e2c-9a1e-5c3b2a1d0e4f" ], "content": "We just shipped 🚀 #buildinpublic", "mode": "now", "mediaIds": [ "a1d4e9b2-3c5f-4a8d-b0e1-2f6c7a9d8b3e" ], "settings": { "privacy_level": "PUBLIC_TO_EVERYONE" } }'

Creates a post on one or more platforms. Each platform is processed independently, so a partial failure does not block the others.

mode decides when the post is sent and the resulting post state:

modeResult
now / scheduleQUEUE → PUBLISHED
draftDRAFT (saved in Loomta, nothing sent)
  • mode = when it goes out. schedule needs scheduledFor. draft sends nothing — promote it later with POST /posts/{id}/publish. TikTok uses Direct Post only. Select a current privacy_level returned by GET /platforms/{id}/schema; Loomta does not choose one by default.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
platformIds
required

Required. One or more platform IDs from GET /platforms.

Array<string>
>= 1 items
content
required

Required. The post caption / body.

string
>= 1 characters
mode
required

Required (no default). now publishes immediately; schedule requires scheduledFor; draft saves in Loomta without sending.

string
Allowed values: draft now schedule
scheduledFor

ISO 8601. Required when mode is schedule; ignored otherwise.

string format: date-time
mediaIds

Required. READY media object IDs from POST /media, in order. TikTok needs either exactly one video, or 1–35 images for a photo carousel (you cannot mix images and videos).

Array<string>
>= 1 items
settings

Provider-specific settings — see GET /platforms/{id}/schema. TikTok uses content_posting_method: DIRECT_POST; privacy_level is required and has no default. Interaction settings default off.

object
key
additional properties
any
comments

Optional. Replies posted after the root post (thread).

Array<object>
object
content
required

Required. The comment’s text.

string
>= 1 characters
delayInMinutes

Optional (default null). Minutes to wait after the root post before sending this comment; null/omitted posts it immediately after.

integer | null
settings

Optional (default {}). Provider-specific settings for this comment.

object
key
additional properties
any
mediaIds

Optional (default none). Media object IDs attached to this comment, if the platform supports it (see GET /platforms/{id}/schema).

Array<string>
Examples

Publish a video immediately

{
  "platformIds": [
    "8b2c1f4a-77d0-4e2c-9a1e-5c3b2a1d0e4f"
  ],
  "content": "We just shipped 🚀 #buildinpublic",
  "mode": "now",
  "mediaIds": [
    "a1d4e9b2-3c5f-4a8d-b0e1-2f6c7a9d8b3e"
  ],
  "settings": {
    "privacy_level": "PUBLIC_TO_EVERYONE"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Per-platform results.

Media typeapplication/json
object
results
required
Array
One of:
object
platformId
required
string format: uuid
status
required
string
Allowed value: created
post
required
object
root
required
object
id
string format: uuid
groupId
string format: uuid
parentPostId
string | null format: uuid
integrationId
string format: uuid
content
string
state
string
Allowed values: DRAFT QUEUE PUBLISHED ACTION_REQUIRED ERROR
scheduledFor
string | null format: date-time
delayInMinutes
integer | null
releaseId
string | null
releaseUrl
string | null
settings
object
key
additional properties
any
mediaIds
Array<string>
errorText
string | null
createdAt
string format: date-time
updatedAt
string format: date-time
children
required
Array<object>
object
id
string format: uuid
groupId
string format: uuid
parentPostId
string | null format: uuid
integrationId
string format: uuid
content
string
state
string
Allowed values: DRAFT QUEUE PUBLISHED ACTION_REQUIRED ERROR
scheduledFor
string | null format: date-time
delayInMinutes
integer | null
releaseId
string | null
releaseUrl
string | null
settings
object
key
additional properties
any
mediaIds
Array<string>
errorText
string | null
createdAt
string format: date-time
updatedAt
string format: date-time
Example
{
  "results": [
    {
      "status": "created",
      "post": {
        "root": {
          "state": "DRAFT"
        },
        "children": [
          {
            "state": "DRAFT"
          }
        ]
      }
    }
  ]
}

400

Section titled “400”

The request body failed validation.

Media typeapplication/json
object
code
required

A stable, machine-readable error code to branch on.

string
message
required

A human-readable description.

string
details

Optional structured detail (for example Zod validation issues).

Example
{
  "code": "invalid_request",
  "message": "The request payload is invalid.",
  "details": [
    {
      "path": [
        "slideCount"
      ],
      "message": "Number must be greater than or equal to 3"
    }
  ]
}

401

Section titled “401”

The API key is missing or invalid.

Media typeapplication/json
object
code
required

A stable, machine-readable error code to branch on.

string
message
required

A human-readable description.

string
details

Optional structured detail (for example Zod validation issues).

Examples
{
  "code": "missing_api_key",
  "message": "A Bearer API key is required."
}

409

Section titled “409”

A plan limit was reached (for example the monthly post cap).

Media typeapplication/json
object
code
required

A stable, machine-readable error code to branch on.

string
message
required

A human-readable description.

string
details

Optional structured detail (for example Zod validation issues).

Example
{
  "code": "post_limit_reached",
  "message": "The monthly post limit for this plan has been reached."
}