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 post_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 `post_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.

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.

titlestring or nullOptional

Title shown on the post. Applies to slideshow posts only; ignored for video posts.

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. 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.

use_official_soundbooleanOptionalDefaults to true

true (default) plays the linked sound_id as the post’s audio at full volume. false uses the video’s own original audio while still tagging the linked sound_id as the official sound, so the two coexist. Applies to video posts only; ignored for slideshows.

hashtagslist of stringsOptional

Hashtags to append to the post. Enter the words only, without # (e.g. ["viral", "trending"]); we add the # and strip any non-alphanumeric characters server-side. Omit or leave empty for none.

Response

Successful Response

post_idstring

Opaque ID for the post, stable for its lifetime. Poll GET /v1/posts/{post_id} with it to track status and, once live, retrieve the TikTok post ID and URL.

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

$	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",
>	"webhook_url": "https://example.com/hooks/algorhythm",
>	"description": "starting the day right",
>	"is_live": true,
>	"use_official_sound": false,
>	"hashtags": [
>	"farmlife",
>	"morning"
>	]
>	}'

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