Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.
/api/v2/postsPOST
Publishes or schedules a post targeting one or more connected accounts. The top-level content is shared; each target can override it and add typed platformSpecificData options. Media is referenced by public URL in mediaItems (upload local files with the media upload endpoint first).
  • publishNow: true publishes immediately.
  • scheduledFor schedules for a future time.
  • To save without publishing, create a draft instead.
Publishing may still be in progress when the response returns — poll the get post endpoint while status is pending or publishing.
Requires an active subscription (402 otherwise). Post and account limits from your plan are enforced (403 when exceeded).
X (Twitter) posts have their own monthly cap on top of the overall post limit, because X charges for API posting far above every other platform. A tweet containing a link counts as 10 X posts (X bills link tweets at 10x the plain rate). During the 7-day free trial the X cap is lower. Hitting it returns 403 with code x_post_limit_reached; other platforms are unaffected.
Authorization
apiKey *Bearer <token>
Akarso API key from the dashboard. Token in: header
Request Bodyapplication/jsonrequired
content *string
Post text body, shared by every platform target
mediaItems?object[]
Media attachments (images, videos, GIFs) referenced by public URL
Show item properties
type *"image" | "video" | "gif" | "document"
Media kind
url *string (uri)
Publicly accessible URL of the media file
thumbnail?string (uri)
Thumbnail image URL for video items. JPEG, PNG, or GIF, max 2 MB, min 640 px wide.
platforms *object | object | object | object | object | object | object | object | object | object[]
Target accounts to publish to
publishNow?boolean
Publish immediately. Required when scheduledFor is omitted.
scheduledFor?string (date-time)
ISO 8601 datetime to schedule the post for future publishing
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
timezone?string
IANA timezone for the scheduled time (e.g. America/New_York). Defaults to UTC.
Response
200
success *boolean
False only when every platform failed
status *"draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"
scheduledFor?string | null
ISO 8601 datetime the post is scheduled for (scheduled posts only)
postId *string
ID of the saved post
platforms *object[]
Show item properties
platform *"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
success *boolean
For publish-now timeout fallback, true means accepted and final status still pending
platformPostUrl?string | null
Direct URL to the published post
error?string | null
Error message when success is false
warningMessage?string | null
Warning when the post published but a non-critical follow-up failed
400 · Invalid request body, path, or query parameters
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
401 · Missing or invalid API key
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
402
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
subscribeUrl?string
URL to start a subscription
403
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
limit?number
The plan limit that was hit
used?number
Current usage in this billing period
connected?number
Currently connected accounts
429 · Upstream rate limit reached
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
502 · Upstream platform request failed
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
503 · Upstream service temporarily unavailable or submission outcome unknown
error *string
Human-readable error message
code?string
Machine-readable error code
message?string
Additional error details
Request example
curl -X POST "https://akarso.co/api/v2/posts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://example.com",
      "thumbnail": "https://example.com"
    }
  ],
  "platforms": [
    {
      "platform": "twitter",
      "accountId": "string",
      "content": "string",
      "platformSpecificData": {
        "communityId": "string",
        "shareWithFollowers": true,
        "replyToTweetId": "string",
        "replySettings": "following",
        "threadItems": [
          {
            "content": "string",
            "mediaItems": [
              {
                "type": "image",
                "url": "https://example.com",
                "thumbnail": "https://example.com"
              }
            ]
          }
        ],
        "poll": {
          "options": [
            "string",
            "string"
          ],
          "durationMinutes": 5
        }
      }
    }
  ],
  "publishNow": true,
  "scheduledFor": "2024-01-15T09:30:00Z",
  "timezone": "string"
}'
Powered byHolocron