Post to a farm profile | Algorhythm

Queues a video or slideshow to be posted to the farm profile’s TikTok account. The response returns immediately with a task_id; the upload + publish runs on the cloud phone in the background and may take several minutes.

Preconditions:

Profile must be ready (fully warmed up). Posting before then risks TikTok flagging the account.
media_url must be HTTPS and publicly retrievable from our infrastructure.

Posts go out at the account’s default privacy. Explicit privacy controls are on the roadmap.

Cadence: TikTok bans accounts that post too frequently. We recommend ≤ 1–2 posts per day per profile. We don’t enforce a per-profile limit; pacing is your responsibility.

Idempotency: not yet supported. Retrying a request that returned 502 may produce a duplicate post. If you retry, watch for the same media_url going up twice. Idempotency-Key support is on the roadmap.

Rate limit: 30 requests per minute per team.

Queues a video or slideshow to be posted to the farm profile's TikTok account. The response returns immediately with a `task_id`; the upload + publish runs on the cloud phone in the background and may take several minutes. **Preconditions:** - Profile must be `ready` (fully warmed up). Posting before then risks TikTok flagging the account. - `media_url` must be HTTPS and publicly retrievable from our infrastructure. **Posts go out at the account's default privacy.** Explicit privacy controls are on the roadmap. **Cadence:** TikTok bans accounts that post too frequently. We recommend ≤ 1–2 posts per day per profile. We don't enforce a per-profile limit; pacing is your responsibility. **Idempotency:** not yet supported. Retrying a request that returned 502 may produce a duplicate post. If you retry, watch for the same `media_url` going up twice. Idempotency-Key support is on the roadmap. **Rate limit:** 30 requests per minute per team.

Authentication

X-API-Keystring

API Key authentication via header

Request

This endpoint expects an object.

profile_idstringRequired

The farm profile to post from. Must belong to your team. Posting is only permitted when status is ready.

media_typeenumRequired

video for a single MP4; slideshow for a .zip of JPGs.

media_urlstringRequired

Publicly retrievable HTTPS URL of the media. For video, an MP4 (H.264, ≤ 60s, 9:16 recommended). For slideshow, a .zip whose entries are named slide-1.jpg, slide-2.jpg, … (JPG only; PNG/AVIF not supported). Signed URLs are fine as long as they’re reachable from the public internet.

sound_idstringRequired

TikTok sound ID to attach to the post. We do not validate that the ID exists.

titlestringRequired

Title shown on the post. Required.

webhook_urlstringRequired

HTTPS URL we’ll POST {event: 'post.published', phone_id, post_url} to once the post goes live on TikTok, where post_url is the live TikTok URL. Fire-and-forget; no retries.

descriptionstringOptionalDefaults to

Caption text. Note: @ and # characters are stripped server-side — TikTok’s automation flow can’t reliably enter them. Native hashtag/mention support is on the roadmap.

execute_atinteger or nullOptional

Optional scheduled post time as a Unix epoch in milliseconds (same convention as created_at elsewhere). Must be in the future. Omit to publish immediately.

is_livebooleanOptionalDefaults to false

true publishes the post live to TikTok immediately. false (default) saves it as a draft on the device for review. Not a livestream toggle.

Response

Successful Response

task_idstring

Opaque ID for the queued post job. Reserved for future lookup; there is no read endpoint yet — post lifecycle webhooks are on the roadmap.

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error

Preconditions:

Profile must be ready (fully warmed up). Posting before then risks TikTok flagging the account.
media_url must be HTTPS and publicly retrievable from our infrastructure.

Posts go out at the account’s default privacy. Explicit privacy controls are on the roadmap.

Cadence: TikTok bans accounts that post too frequently. We recommend ≤ 1–2 posts per day per profile. We don’t enforce a per-profile limit; pacing is your responsibility.

Rate limit: 30 requests per minute per team.

$	curl -X POST https://api.algorhythm.app/v1/posts \
>	-H "X-API-Key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"profile_id": "f8a1c2d4-3b7e-4f9a-9c2d-1e5b7a8f9c3d",
>	"media_type": "video",
>	"media_url": "https://storage.googleapis.com/campaign-posts/processed/f0590215-34b8-4bbe-b7a4-b66c804d3cd6/593b166d-5fd3-4170-aac3-12ac91ab2ccc.mp4",
>	"sound_id": "7255433468434549509",
>	"title": "Morning farm vibes",
>	"webhook_url": "https://example.com/hooks/algorhythm",
>	"description": "starting the day right",
>	"is_live": true
>	}'

1	{
2	"task_id": "273a704c-0114-4e9e-a574-e8ae3a4d427e"
3	}