Publishing

Publishing lets you post content to social media platforms immediately or schedule it for later. Currently supports TikTok, with more platforms coming soon.

Note

Publishing requires authentication via the X-API-Key header. The agent must have a connected TikTok social account (via AURA) before publishing.

Publish content

Posts or schedules content to a social media platform. Uses the standard user job creation endpoint.

POST /v1/user_jobs?agent_id={agent_id}

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	The agent ID (query parameter).
user_job_type	string	Yes	Must be publish_content.
data	string (JSON)	Yes	JSON-stringified object containing the post configuration (see Data fields below).

Data fields

The data value is a JSON string containing:

Field	Type	Required	Description
platform	string	Yes	Target platform. Currently tiktok.
media_url	string	Yes	Public URL to the media file (S3 presigned URL, CDN link, etc). Must be accessible at post time.
description	string	Yes	Post caption/description. Max ~2200 characters for TikTok. Include hashtags inline.
title	string	No	Post title (used on some platforms).
media_type	string	No	VIDEO (default) or IMAGE.
schedule_type	string	Yes	now for immediate posting. scheduled for future posting.
scheduled_time	string	Conditional	ISO 8601 UTC datetime (e.g. 2026-03-16T15:00:00Z). Required when schedule_type is scheduled. Must be in the future.
thumbnail_url	string	No	Custom thumbnail URL. Auto-generated from video if not provided.
timezone_offset	integer	No	Timezone offset in minutes from UTC. Default 0.

Schedule types

Value	Behavior
now	Posts immediately via the connected social account.
scheduled	Queues for posting at scheduled_time.

Response

{
  "user_job_id": 138860
}

Status flow

Poll status via GET /v1/user_jobs/{id}?agent_id={agent_id}.

Status	Description
pending	Job created, queued for processing.
processing	Post is being submitted to the platform.
completed	Post published successfully. The result field contains the post_id from the platform.
failed	Publishing failed. Check failed_reason.

Example: Post now

curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_job_type": "publish_content",
    "data": "{\"platform\": \"tiktok\", \"media_url\": \"https://cdn.example.com/video.mp4\", \"description\": \"Factory price reveal #sourcing #china\", \"schedule_type\": \"now\", \"media_type\": \"VIDEO\"}"
  }'

Example: Schedule for later

curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_job_type": "publish_content",
    "data": "{\"platform\": \"tiktok\", \"media_url\": \"https://cdn.example.com/video.mp4\", \"description\": \"Your $12 beauty sponge costs 10 cents #beauty #factory\", \"title\": \"Beauty sponge price reveal\", \"schedule_type\": \"scheduled\", \"scheduled_time\": \"2026-03-16T15:00:00Z\", \"media_type\": \"VIDEO\"}"
  }'

Prerequisites

• Agent must have a connected TikTok social account (connected via AURA)
• Video/image must be publicly accessible via URL at post time
• For scheduled posts, scheduled_time must be in the future

Upload media

Posts reference media by URL — the media must be publicly fetchable at post time. Upload a local file with upload_asset to get a durable, hosted URL you can pass to media_url / media_urls. The uploaded file is also saved to the agent’s Assets, so you can reuse it later.

POST /v1/social/upload_asset

Send the file as multipart/form-data.

Parameters

Parameter	Type	Required	Description
file	file	Yes	The video or image file (multipart).
agent_id	string	Yes	The agent whose Assets the file is saved to.

Response

{
  "url": "https://cdn.gen.pro/....jpg",
  "cdn_url": "https://cdn.gen.pro/....jpg",
  "asset_id": "12345",
  "content_resource_id": 12345,
  "asset_registered": true
}

Use the returned url as media_url (single) or inside media_urls when scheduling a post.

Example

curl -X POST "https://api.gen.pro/v1/social/upload_asset" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/image.jpg" \
  -F "agent_id=your-agent-id"

Upload → post recipe

# 1. Upload the file, capture the hosted URL
URL=$(curl -s -X POST "https://api.gen.pro/v1/social/upload_asset" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/image.jpg" \
  -F "agent_id=your-agent-id" | python3 -c "import sys,json;print(json.load(sys.stdin)['url'])")

# 2. Post it (X example — a tweet with one image)
curl -X POST "https://api.gen.pro/v1/schedule/with-post" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\":\"your-agent-id\",\"platform\":[\"x\"],\"description\":\"from the API\",\"media_type\":\"IMAGE\",\"media_urls\":[\"$URL\"],\"schedule_type\":\"now\"}"

For up to 4 images on X, call upload_asset per file and pass all the URLs in media_urls.

Posting to X (Twitter)

X supports the richest set of post types: a plain text tweet, a tweet with up to 4 images, a tweet with a video, a thread (an ordered chain of tweets), and a reply to an existing tweet. X posts are created through the scheduling API.

POST /v1/schedule/with-post

Fields

Field	Type	Required	Description
agent_id	string	Yes	The agent whose connected X account posts.
platform	string[]	Yes	Include "x".
schedule_type	string	Yes	now, specific_time, or next_available.
scheduled_time	string	Conditional	Required when schedule_type is specific_time.
description	string	Conditional	The tweet text. Required for a text-only tweet or reply.
media_type	string	No	TWEET_VIDEO for video, IMAGE for images.
media_url	string	No	A single video URL.
media_urls	string[]	No	Up to 4 image URLs for a single tweet.
thread	object[]	No	X only. An ordered list of tweet segments to post as a chain. Each segment is { "text": "...", "media_urls": ["..."] } (per-segment images optional, up to 4).
reply_to_tweet_id	string	No	X only. Post as a reply to this tweet id. Combine with thread to reply and then continue a chain.

Note

thread and reply_to_tweet_id apply to X only. They are ignored for TikTok, Instagram, Facebook, and YouTube, which post a single piece of media.

Example: Text-only tweet

curl -X POST "https://api.gen.pro/v1/schedule/with-post" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "platform": ["x"],
    "description": "gm from the API 👋",
    "schedule_type": "now"
  }'

Example: Tweet with up to 4 images

curl -X POST "https://api.gen.pro/v1/schedule/with-post" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "platform": ["x"],
    "description": "four pics",
    "media_type": "IMAGE",
    "media_urls": [
      "https://cdn.example.com/1.jpg",
      "https://cdn.example.com/2.jpg",
      "https://cdn.example.com/3.jpg",
      "https://cdn.example.com/4.jpg"
    ],
    "schedule_type": "now"
  }'

Example: Thread

curl -X POST "https://api.gen.pro/v1/schedule/with-post" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "platform": ["x"],
    "schedule_type": "now",
    "thread": [
      { "text": "1/ Here is a thread about our launch." },
      { "text": "2/ With a screenshot", "media_urls": ["https://cdn.example.com/shot.jpg"] },
      { "text": "3/ Wrapping up. Thanks for reading!" }
    ]
  }'

Example: Reply to a tweet

curl -X POST "https://api.gen.pro/v1/schedule/with-post" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "platform": ["x"],
    "description": "Great point — here is our take.",
    "reply_to_tweet_id": "1780000000000000000",
    "schedule_type": "now"
  }'

If a thread fails partway through, posting stops at the failed segment; the tweets already posted are recorded and the post is marked failed (it is not retried, to avoid duplicate tweets).

Errors

Status	Error code	Description
401	unauthorized	Missing or invalid API key.
403	permission_denied	You do not have access to this agent.
422	validation_error	Invalid or missing required fields.
422	no_active_credit_purchase	The agent’s workspace has no active credit purchase.