AI generation

Chat or generate with account voice

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

Scope · ai:writeIdempotency-Key required10 expensive operations / minute / user

Request

POST/api/v1/ai/chat

Example requestcURL

curl -X POST 'https://postlift.io/api/v1/ai/chat' \
  -H "Authorization: Bearer $POSTLIFT_API_KEY" \
  -H 'Idempotency-Key: integration-operation-0001' \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-6-luna",
  "kind": "chat",
  "messages": [
    {
      "role": "user",
      "content": "Help me plan my next post."
    }
  ],
  "maxOutputTokens": 1024,
  "stream": true
}'

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

modeloptional stringDefault: "openai/gpt-6-luna".

kindoptional stringDefault: "chat". Values: chat, draft, rewrite, thread, hook, reply, ideas.

messagesrequired

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

Nested fields ↓

Field	Type & constraints
`role`required	stringValues: user, assistant.
`content`required	stringMin. characters: 1. Max. characters: 32000.

maxOutputTokensoptional integerDefault: 1024. Minimum: 32. Maximum: 2048.

streamoptional booleanDefault: true.

xAccountIdoptional stringMin. characters: 1. Max. characters: 128.

View JSON schema

{
  "type": "object",
  "properties": {
    "model": {
      "default": "openai/gpt-6-luna",
      "type": "string"
    },
    "kind": {
      "default": "chat",
      "type": "string",
      "enum": [
        "chat",
        "draft",
        "rewrite",
        "thread",
        "hook",
        "reply",
        "ideas"
      ]
    },
    "messages": {
      "minItems": 1,
      "maxItems": 32,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant"
            ]
          },
          "content": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32000
          }
        },
        "required": [
          "role",
          "content"
        ],
        "additionalProperties": false
      }
    },
    "maxOutputTokens": {
      "default": 1024,
      "type": "integer",
      "minimum": 32,
      "maximum": 2048
    },
    "stream": {
      "default": true,
      "type": "boolean"
    },
    "xAccountId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "messages"
  ],
  "additionalProperties": false
}

Response

200 Successful operation.

Streaming supported. Set stream:false for JSON. Stream errors can occur after HTTP 200; retain X-AI-Request-ID and inspect request status.

Field	Type & constraints
`requestId`required	string
`model`required	string
`text`required	string
`finishReason`required	string
`usage`required	object

Explore Generation ↗

View JSON schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "model": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "finishReason": {
      "type": "string"
    },
    "usage": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "required": [
    "requestId",
    "model",
    "text",
    "finishReason",
    "usage"
  ],
  "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 ↗