Core Concepts

Understanding the Pharlo domain model makes every other guide easier to follow.

Assignments

An assignment is a publishing job. When you want to post a video to YouTube or publish a post to Facebook, you create an assignment.

Assignment lifecycle

`pending`

Created and queued — waiting to be picked up for processing.

`uploading`

Media file is being transferred to the platform.

`uploaded`

Upload complete — metadata and settings are being applied.

`processing`

Platform is processing the content (transcoding, moderation, etc.).

`published`

Live on the platform. The platformUrl field is now set.

⚠️

Terminal states — published and cancelled are final and cannot change. Failed assignments can be retried, which moves them back to pending.

Status	Meaning
`pending`	Created, waiting to be processed
`uploading`	Media file is being transferred to the platform
`uploaded`	Media uploaded, metadata being applied
`processing`	Platform is processing the content
`published`	Live on the platform — `platformUrl` is set
`failed`	Processing failed — `errors` array has details
`cancelled`	Manually cancelled before publishing

Once an assignment reaches published or cancelled, it cannot change status. Failed assignments can be retried, which moves them back to pending.

Assignment fields

Field	Description
`id`	UUID — use this to check status or cancel
`connectionId`	Which channel to publish to
`type`	Content type: `video`, `image`, `link`, `text`, `reel`, `short`, `story`, `carousel`
`payload`	Platform-specific fields (title, description, privacy, tags, etc.)
`mediaUrl`	URL to the media file (required for video/image types)
`scheduledAt`	RFC 3339 timestamp with timezone offset — omit for immediate publishing
`callbackUrl`	Your server URL — receives status change notifications
`idempotencyKey`	Unique string to prevent duplicate submissions
`platformPostId`	Platform's own ID (set after publishing)
`platformUrl`	Direct link to the published content
`externalId`	Optional custom ID from your system

Connections

A connection is an authorized link to a social media channel — a YouTube channel or a Facebook page. Connections are created via OAuth; the API holds the OAuth tokens on your behalf.

Connection states

State	Meaning
`isActive: true`	Can publish; token is valid
`isActive: false`	Deactivated — assignments to this connection will be rejected
Token expired	Token needs refreshing — re-run the OAuth flow

What a connection holds

Platform slug (youtube or facebook)
Channel name, thumbnail URL, metadata
OAuth access + refresh tokens (managed internally)
Reference to which OAuth app config was used

Platforms & Content Types

A platform is a social network. Currently supported: youtube, facebook.

Each platform has a set of content types (e.g., video, short, reel) and capabilities — field definitions, limits, and defaults. Always call GET /api/v1/platforms/{platform}/capabilities (or get_platform_capabilities in MCP) before creating an assignment to learn what the platform accepts.

Organizations

Users belong to organizations. An organization groups members under a shared workspace, with a single API client (key) and a shared credit wallet.

Roles

Role	Permissions
`owner`	Full access; can delete the organization
`admin`	Manage members, channels, billing
`member`	Create and view content

Members are invited by email. An invitation token is emailed to the invitee; they accept via POST /api/v1/auth/invitations/{token}/accept.

Webhooks

Webhooks are outbound HTTP callbacks sent to your server on assignment status changes. Configure a callbackUrl per assignment, or set a global URL via your API client settings.

Each delivery is logged and retried on failure. You can inspect the delivery log at GET /api/v1/webhooks/deliveries.

Webhook payloads are signed with HMAC-SHA256. See the Webhooks guide for verification instructions.

Credits

Operations consume credits from your wallet. Credits are reserved before an operation starts and returned if it fails.

Free operations (auth, OAuth, org management, health checks, platform discovery) never cost credits.

See the Billing & Credits guide for plan details and operation costs.

Entity relationships

ApiClient (your API key)
 ├── Connection[]              (YouTube channels / Facebook pages)
 │    └── Assignment[]         (publishing jobs)
 │
 ├── Organization (optional)
 │    ├── OrganizationMember[] (users with roles)
 │    └── OrganizationInvitation[]
 │
 └── BillingAccount
      └── CreditWallet

The ApiClient is the root tenant. Every connection, assignment, and billing transaction is scoped to it.

Authentication Publishing Content