Write Post API

Create Post

Create and optionally schedule a social post via the Write Post API.

POST /api/v1/write-post/posts/ Live

Create a post. Omit scheduled_at to publish now; set a future ISO datetime to schedule. Accepts JSON or multipart/form-data (for image uploads).

Authentication: Bearer API key required
Permission: write_post
Rate limit: Per-key default 60 req/min
Content-Type: application/json or multipart/form-data

Notes

Publish now = omit scheduled_at (or see Publish Post docs).
Schedule = set scheduled_at in the future (or see Schedule Post docs).
Insufficient wallet balance for overage posts returns HTTP 402 with VALIDATION_ERROR (domain details may include insufficient balance).
Plan limits may return HTTP 403 with error.details.code = "plan_limit".

Body fields

Name	Type	Required	Description
`headline`	string	Yes	Post headline/title. Alias: title.
`content`	string	Yes	Post body (HTML or plain text).
`connection_ids`	array[integer]	Yes	One or more connection IDs from GET /write-post/connections/.
`scheduled_at`	string (ISO 8601)	No	Future datetime to schedule. Omit to publish immediately.
`image`	file	No	Optional image — multipart/form-data only (FILES["image"]).

Headers

HTTP

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body

JSON

{
  "headline": "Hello from API",
  "content": "<p>Hello from API</p>",
  "connection_ids": [1]
}

Examples

cURL

curl -X POST "https://YOUR-DOMAIN/api/v1/write-post/posts/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headline":"Hello","content":"<p>Hi</p>","connection_ids":[1]}'

JavaScript

const response = await fetch("https://engagegrove.com/api/v1/write-post/posts/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    Accept: "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "headline": "Hello from API",
  "content": "<p>Hello from API</p>",
  "connection_ids": [1]
})
});
const data = await response.json();

Python

import requests
import json

url = "https://engagegrove.com/api/v1/write-post/posts/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json",
}
payload = json.loads("""{
  "headline": "Hello from API",
  "content": "<p>Hello from API</p>",
  "connection_ids": [1]
}""")
response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

PHP

$ch = curl_init("https://engagegrove.com/api/v1/write-post/posts/");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Accept: application/json",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "headline": "Hello from API",
  "content": "<p>Hello from API</p>",
  "connection_ids": [1]
}
JSON
]);
$response = curl_exec($ch);
curl_close($ch);

Response example

JSON

{
  "success": true,
  "request_id": "req_...",
  "data": {
    "post": {
      "id": 1,
      "headline": "Hello from API",
      "content_plain": "Hello from API",
      "status": "published",
      "status_label": "Published",
      "cost_display": "$0.00",
      "channel_count": 1,
      "channels": [],
      "image_url": "",
      "timezone": "UTC",
      "created_display": "2026-01-01 12:00:00",
      "scheduled_display": "—",
      "published_display": "2026-01-01 12:00:00",
      "error_message": "",
      "content_html": "<p>Hello from API</p>"
    }
  }
}

Status codes

Status	Meaning
`201`	Post created
`400`	Validation error
`401`	Invalid API key
`402`	Insufficient balance (overage)
`403`	Permission or plan limit
`429`	Rate limit exceeded

Try it

Paste your API key locally. It is sent only to this site’s API and is never saved.

API Key JSON body

Create API Key →

Errors

INVALID_API_KEY — missing/invalid Bearer token
SERVICE_ACCESS_DENIED — key lacks write_post
VALIDATION_ERROR — invalid payload or domain validation
RESOURCE_NOT_FOUND — unknown resource
RATE_LIMIT_EXCEEDED — too many requests

Full error reference →