Posts & scheduling

Create a draft or scheduled post/thread

Use this endpoint from your own integration, with the same account permissions and safeguards as the app.

Scope · posts:writeIdempotency-Key required

Request

POST/api/v1/posts

Example requestcURL

curl -X POST 'https://postlift.io/api/v1/posts' \
  -H "Authorization: Bearer $POSTLIFT_API_KEY" \
  -H 'Idempotency-Key: integration-operation-0001' \
  -H 'Content-Type: application/json' \
  --data '{
  "xAccountId": null,
  "items": [
    {
      "text": "A small release beats a perfect plan.",
      "mediaIds": []
    }
  ],
  "scheduledAt": null,
  "timezone": "UTC",
  "linkInReply": false,
  "aiAssisted": false,
  "publishNow": false
}'

Replace path placeholders with your Postlift resource IDs. Example timestamps must be replaced with a future time; preserve the same timestamp when retrying the same operation.

Parameters

Name	Location	Description
`Idempotency-Key`required	header	Unique operation key. Reuse only for the same payload/account. See retry semantics in the guide.Pattern: ^[A-Za-z0-9_-]{8,128}$.

Request body

Send JSON with Content-Type: application/json.

Field Type & constraints

xAccountIdoptional string | nullDefault: null.

itemsrequired

object[]Min. items: 1. Max. items: 20.

Nested fields ↓

Field	Type & constraints
`text`required	stringPlain text only; URLs and domain addresses are not allowed. Max. characters: 10000.
`mediaIds`optional	string[]Default: []. Max. items: 4.

scheduledAtoptional integer | nullDefault: null.

timezoneoptional stringDefault: "UTC". Max. characters: 64.

linkInReplyoptional booleanDeprecated; must be false. Links are not supported. Default: false.

aiAssistedoptional booleanDefault: false.

publishNowoptional booleanDefault: false.

View JSON schema

{
  "type": "object",
  "properties": {
    "xAccountId": {
      "default": null,
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "items": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 10000,
            "description": "Plain text only; URLs and domain addresses are not allowed."
          },
          "mediaIds": {
            "default": [],
            "maxItems": 4,
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            }
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false
      }
    },
    "scheduledAt": {
      "default": null,
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "timezone": {
      "default": "UTC",
      "type": "string",
      "maxLength": 64
    },
    "linkInReply": {
      "default": false,
      "description": "Deprecated; must be false. Links are not supported.",
      "type": "boolean"
    },
    "aiAssisted": {
      "default": false,
      "type": "boolean"
    },
    "publishNow": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false
}

Response

200 Idempotent replay of the original post creation.
201 Successful operation.

Field	Type & constraints
`post`required	Post ↗
`replayed`required	boolean

Explore PostCreated ↗

View JSON schema

{
  "type": "object",
  "properties": {
    "post": {
      "$ref": "#/components/schemas/Post"
    },
    "replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "post",
    "replayed"
  ],
  "additionalProperties": true
}

Errors & retries

Failures use a stable error code and request ID. Check the current resource version or request status before retrying a write.

Status	Meaning
`400`	Invalid input or Jev rejection
`401`	Invalid, expired or revoked API key
`402`	Plan, publishing quota or AI credit requirement
`403`	Missing scope
`404`	Resource not found or not owned
`409`	Version conflict, missing voice or duplicate AI operation
`413`	Payload too large
`429`	Rate or concurrency limit
`500`	Internal error
`502`	Upstream failure; inspect operation status
`503`	Service or review unavailable

Read the retry guide ↗