> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.algorhythm.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.algorhythm.app/_mcp/server. # Create a farm profile POST https://api.algorhythm.app/v1/farm-profiles Content-Type: application/json Provisions a new farm account under your team. This creates a cloud phone, rents an SMS number, and queues account signup as a background job that may take up to 24 hours to complete. TikTok signup challenges (captcha, age gate, SMS verification, recovery-email codes) are handled automatically. The response returns immediately with a `profile_id`. We POST lifecycle webhooks as the profile progresses — `profile.cold` when provisioning completes, warming and account-detail events during warmup (see `webhook_url`), `profile.ready` when warmup finishes, and `profile.banned` if the account is banned (a `failed` webhook is still on the roadmap). The profile is also retrievable at `GET /v1/farm-profiles/{profile_id}` with its current `status`. Each successful provisioning increments your monthly billing quantity. Pricing follows volume tiers — the more accounts you have, the lower the per-account rate. **Rate limit:** 10 requests per minute per team. Reference: https://docs.algorhythm.app/api-reference/farm-profiles/create-farm-profile-v-1-farm-profiles-post ## Authentication - `X-API-Key` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a CreateFarmProfileRequest. - `platform` (string, required) — Target social platform for the new account (e.g. `tiktok`). All profiles are currently provisioned in the US — country localization is on the roadmap. - `username` (string, required) — Desired handle for the new account. - `webhook_url` (string, required) — HTTPS URL we POST profile lifecycle events to, each as `{event, tiktok_username, phone_id}`: `profile.cold` once provisioning finishes; `profile.warming_started` and `profile.warming_completed` around each \~15-minute warmup run (`profile.warming_completed` also carries `warmup_count` and the resulting `status`); `profile.username_updated`, `profile.bio_updated`, `profile.nickname_updated`, and `profile.avatar_updated` as account details are applied during the warm phase; `profile.ready` once warmup completes and the profile is postable; and `profile.banned` if the platform bans the account (terminal). Fire-and-forget; no retries. - `account_name` (string, optional, nullable) — Display name for the profile. Defaults to `username` if omitted. - `keywords` (list of string, optional) — Search terms used to seed organic browsing during automated warmup. Used literally as TikTok search queries — pick whatever a real user of this account would search for. One is chosen at random per warmup run. - `bio` (string, optional, nullable) — Account bio/about text set on the profile during setup. Optional. - `profile_picture_url` (string, optional, nullable) — HTTPS URL of an image to set as the account's profile picture during setup. Optional. ## Response ### 200 Successful Response - `profile_id` (string, required) — Unique profile identifier. Provisioning runs asynchronously and may take up to 24 hours. Use this ID to look the profile up later — its `status` starts at `configuring` and progresses through `cold` → `warming` ↔ `warm` → `ready`. ## Errors ### 402 Payment Required Error Subscription not in good standing. - `any` ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ### 429 Too Many Requests Error Rate limit exceeded. - `any` ### 502 Bad Gateway Error Upstream content-server failure during provisioning. - `any` ## Types ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) - `input` (any, optional) - `ctx` (ValidationErrorCtx, optional) ### ValidationErrorLocItems - string - integer ### ValidationErrorCtx ## Examples **Request** ```json { "platform": "tiktok", "username": "greenfarm_guru", "webhook_url": "https://example.com/hooks/algorhythm", "account_name": "Green Farm Guru", "keywords": [ "farming", "homestead" ], "bio": "Homestead life, one harvest at a time 🌱", "profile_picture_url": "https://cdn.example.com/avatar.png" } ``` **Response** ```json { "profile_id": "f8a1c2d4-3b7e-4f9a-9c2d-1e5b7a8f9c3d" } ``` **SDK Code** ```python import requests url = "https://api.algorhythm.app/v1/farm-profiles" payload = { "platform": "tiktok", "username": "greenfarm_guru", "webhook_url": "https://example.com/hooks/algorhythm", "account_name": "Green Farm Guru", "keywords": ["farming", "homestead"], "bio": "Homestead life, one harvest at a time 🌱", "profile_picture_url": "https://cdn.example.com/avatar.png" } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.algorhythm.app/v1/farm-profiles'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"platform":"tiktok","username":"greenfarm_guru","webhook_url":"https://example.com/hooks/algorhythm","account_name":"Green Farm Guru","keywords":["farming","homestead"],"bio":"Homestead life, one harvest at a time 🌱","profile_picture_url":"https://cdn.example.com/avatar.png"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.algorhythm.app/v1/farm-profiles" payload := strings.NewReader("{\n \"platform\": \"tiktok\",\n \"username\": \"greenfarm_guru\",\n \"webhook_url\": \"https://example.com/hooks/algorhythm\",\n \"account_name\": \"Green Farm Guru\",\n \"keywords\": [\n \"farming\",\n \"homestead\"\n ],\n \"bio\": \"Homestead life, one harvest at a time 🌱\",\n \"profile_picture_url\": \"https://cdn.example.com/avatar.png\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.algorhythm.app/v1/farm-profiles") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"platform\": \"tiktok\",\n \"username\": \"greenfarm_guru\",\n \"webhook_url\": \"https://example.com/hooks/algorhythm\",\n \"account_name\": \"Green Farm Guru\",\n \"keywords\": [\n \"farming\",\n \"homestead\"\n ],\n \"bio\": \"Homestead life, one harvest at a time 🌱\",\n \"profile_picture_url\": \"https://cdn.example.com/avatar.png\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.algorhythm.app/v1/farm-profiles") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"platform\": \"tiktok\",\n \"username\": \"greenfarm_guru\",\n \"webhook_url\": \"https://example.com/hooks/algorhythm\",\n \"account_name\": \"Green Farm Guru\",\n \"keywords\": [\n \"farming\",\n \"homestead\"\n ],\n \"bio\": \"Homestead life, one harvest at a time 🌱\",\n \"profile_picture_url\": \"https://cdn.example.com/avatar.png\"\n}") .asString(); ``` ```php request('POST', 'https://api.algorhythm.app/v1/farm-profiles', [ 'body' => '{ "platform": "tiktok", "username": "greenfarm_guru", "webhook_url": "https://example.com/hooks/algorhythm", "account_name": "Green Farm Guru", "keywords": [ "farming", "homestead" ], "bio": "Homestead life, one harvest at a time 🌱", "profile_picture_url": "https://cdn.example.com/avatar.png" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.algorhythm.app/v1/farm-profiles"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"platform\": \"tiktok\",\n \"username\": \"greenfarm_guru\",\n \"webhook_url\": \"https://example.com/hooks/algorhythm\",\n \"account_name\": \"Green Farm Guru\",\n \"keywords\": [\n \"farming\",\n \"homestead\"\n ],\n \"bio\": \"Homestead life, one harvest at a time 🌱\",\n \"profile_picture_url\": \"https://cdn.example.com/avatar.png\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "platform": "tiktok", "username": "greenfarm_guru", "webhook_url": "https://example.com/hooks/algorhythm", "account_name": "Green Farm Guru", "keywords": ["farming", "homestead"], "bio": "Homestead life, one harvest at a time 🌱", "profile_picture_url": "https://cdn.example.com/avatar.png" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.algorhythm.app/v1/farm-profiles")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```