Skip to content
UGC API
Get API key

Quickstart

This page takes you from zero to a published post. You need a UGC API account, one social account to post to, and a public video or image URL. New accounts get 50 free posts.

Updated

1. Create an API key

Sign in to the dashboard and create a key. Keys look like ugc_live_... and are shown once, so copy it somewhere safe. All requests go to https://ugcapi.dev/v1 with the key as a Bearer token. See authentication.

2. Connect an account

bash
curl https://ugcapi.dev/v1/accounts/connect \
  -H "Authorization: Bearer ugc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "tiktok", "external_id": "me"}'

The response is { "url": "..." }. Open the URL, log in on TikTok and approve. Then list your accounts to get the account ID:

bash
curl https://ugcapi.dev/v1/accounts -H "Authorization: Bearer ugc_live_..."

Each account has an id like acc_.... You post to these IDs.

3. Publish a post

curl

bash
curl https://ugcapi.dev/v1/posts \
  -H "Authorization: Bearer ugc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["acc_123"],
    "format": "video",
    "media": ["https://cdn.example.com/clip.mp4"],
    "caption": "First post from the API #test"
  }'

JavaScript

javascript
const res = await fetch("https://ugcapi.dev/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.UGCAPI_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accounts: ["acc_123"],
    format: "video",
    media: ["https://cdn.example.com/clip.mp4"],
    caption: "First post from the API #test",
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const post = await res.json();
console.log(post.id, post.status);

Python

python
import os, requests

res = requests.post(
    "https://ugcapi.dev/v1/posts",
    headers={"Authorization": "Bearer " + os.environ["UGCAPI_KEY"]},
    json={
        "accounts": ["acc_123"],
        "format": "video",
        "media": ["https://cdn.example.com/clip.mp4"],
        "caption": "First post from the API #test",
    },
)
res.raise_for_status()
post = res.json()
print(post["id"], post["status"])

Without scheduled_at, the post publishes right away. The response has the post id and a results array with one entry per account and placement.

4. Check the result

bash
curl https://ugcapi.dev/v1/posts/post_abc -H "Authorization: Bearer ugc_live_..."

Each result moves from scheduled to publishing to published (with a public url) or failed (with an error). For production, set up webhooks instead of polling.

Next steps

FAQ

Do I need to host my media?

No. Upload files with POST /v1/media and use the returned URL. You can also pass any public URL.

How many free posts do I get?

50. After that, buy a credit pack from the dashboard. Packs start at $10 for 1,000 posts.

Is there a sandbox?

There is no separate sandbox. Use your free posts on a test account, and set privacy options where the platform allows.

Related

DocsAuthenticationDocsConnect accountsDocsCreate a postDocsWebhooks