ugcinc

Official TypeScript/JavaScript client for the UGC Inc API.

Use this README as a quick reference. For full API details, examples, onboarding, and product information, go to:

• Docs: https://docs.ugc.inc
• Website: https://ugc.inc

Installation

npm install ugcinc

Quick Start

import { UGCClient } from "ugcinc";

const client = new UGCClient({
  apiKey: process.env.UGC_API_KEY!,
  // optional: when using admin key, scope requests to a specific org
  orgId: "org_123",
});

const res = await client.accounts.getAccounts({ status: "setup" });

if (res.ok) {
  console.log(res.data.length);
}

Authentication

• apiKey is required.
• Standard API keys operate on their own organization.
• Admin keys can be scoped with orgId.

Overview

UGCClient groups the API into a few top-level namespaces:

• client.accounts: list, create, update, troubleshoot, quarantine/release, and manage account lifecycle
• client.posts: create video/slideshow posts, update them, retry failures, and preview schedule conflicts
• client.media: upload media, create media records, search profile-picture candidates, manage tags/names, and work with social audio
• client.stats: fetch account/post analytics, daily aggregates, top performers, and refresh stats
• client.org: manage organizations, API keys, and integration keys
• client.billing: inspect subscription state and handle account deactivation, replacements, and refunds
• client.automations: create, run, publish, export, and monitor automation workflows
• client.comments and client.tasks: manage comment jobs and account tasks

The package also exports the API request/response types plus automation/render utilities used by the product.

Common Pattern

All client methods return the same response envelope:

type ApiResponse<T> =
  | { ok: true; code: 200; message: string; data: T; nextCursor?: string | null }
  | { ok: false; code: number; message: string };

Example:

const posts = await client.posts.getPosts({ accountIds: ["acc_123"] });

if (posts.ok) {
  console.log(posts.data.length);
} else {
  console.error(posts.code, posts.message);
}

Pagination

accounts.getAccounts() and posts.getPosts() support keyset pagination via limit/cursor. Omit limit to fetch everything matching your filters (the default, unpaginated behavior); pass limit to page through results newest-first, using each response's nextCursor to fetch the next page (null/absent means there are no more pages):

let cursor: string | undefined;
const allPosts = [];

do {
  const res = await client.posts.getPosts({ limit: 100, cursor });
  if (!res.ok) break;
  allPosts.push(...res.data);
  cursor = res.nextCursor ?? undefined;
} while (cursor);

For interactive tables, posts.getPostsPage() keeps filtering and sorting on the server and returns page-scoped latest stats plus totalCount, organization-wide postTags, anyHasTitle, and matchingAccountIds. It supports caption/title/account search; platform, post type, status, account, account-tag, post-tag, social-audio, and phone-type filters; and sorting by account, status, title, caption, tag, audio presence, scheduled time, or engagement:

const page = await client.posts.getPostsPage({
  search: "launch",
  statuses: ["complete"],
  postTags: ["fall-campaign"],
  sortBy: "views",
  sortDirection: "desc",
  limit: 200,
});

if (page.ok) {
  console.log(page.data.posts, page.data.stats, page.data.totalCount);
  const next = page.data.nextCursor;
}

Caption Overlays

Video posts can carry text overlays to display on the video. Pass captionOverlays to posts.createVideo(); each CaptionOverlay is { text, x, y, fontSize }, where x/y are the overlay center as a fraction (0-1) of the video width/height and fontSize is a fraction (0-1) of the video height. Overlays are returned on the Post as caption_overlays.

await client.posts.createVideo({
  accountId: "acc_123",
  videoUrl: "https://example.com/video.mp4",
  caption: "Post description",
  captionOverlays: [{ text: "Wait for it...", x: 0.5, y: 0.2, fontSize: 0.04 }],
});

Pausing an Account

When a platform blocks an account — a human-verification prompt, a signed-out session, content strikes — quarantine it so its scheduled posts stop failing while the block is unresolved. Nothing is deleted: posts stay scheduled and become eligible again on release, which restores the account's prior status.

await client.accounts.quarantine({
  accountId,
  reason: "Platform is asking the account to verify it is human",
});

// once resolved
await client.accounts.release({ accountId });

Post Tags

Posts carry an optional custom tag for categorization (independent of account tags). Set it with the post_tag param on posts.createVideo(), posts.createSlideshow(), posts.createDraft(), and posts.updatePost(); it is returned as tag on the Post object. Note: on the create endpoints, the separate tag param filters account auto-selection by ACCOUNT tag and is not stored on the post.

await client.posts.createVideo({
  accountId: "acc_123",
  videoUrl: "https://example.com/video.mp4",
  caption: "Post description",
  post_tag: "campaign-july",
});

await client.posts.updatePost({ postId: "post_123", post_tag: "campaign-august" });

Useful Exports

• UGCClient for API access
• Request/response types for all public client methods
• Automation graph utilities and node definitions
• Render helpers and render job types

Full Reference

For the full endpoint reference, all method signatures, data structures, and workflow examples:

• Docs: https://docs.ugc.inc
• Website: https://ugc.inc

License

MIT