Quickstart

Quickstart

Get from zero to your first published video in under 15 minutes.

Prerequisites

Step 1 — Get your API key

After registration, your API key is shown on the final signup step and is always accessible at Settings → Credentials in the console.

Your key looks like:

ds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep it secret — treat it like a password. Store it in an environment variable, never in source code.

export DELIVERY_API_KEY="ds_live_your_key_here"

Step 2 — Connect a YouTube channel

Open the console and navigate to Channels → Connect Channel. Select YouTube and complete the OAuth consent flow. Once connected, your channel appears in the channels list with a UUID — copy it, you'll need it next.

Alternatively, you can start the OAuth flow via API:

curl -X POST https://pharlo.io/api/v1/oauth/tickets \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "redirectUrl": "https://your-app.com/oauth/callback"
  }'

Response:

{
  "ticketId": "550e8400-e29b-41d4-a716-446655440000",
  "authUrl": "https://pharlo.io/api/v1/oauth/youtube/authorize?ticket=...",
  "expiresAt": "2026-04-23T12:05:00Z"
}

Open authUrl in a browser — after the user grants permission, the connection is created automatically.

Step 3 — Find your connection ID

Option A — Console UI (opens in a new tab): go to Channels (opens in a new tab) → click your channel → copy the UUID from the channel page. That is your connectionId.

Option B — API: for programmatic integrations, fetch the connections list:

curl https://pharlo.io/api/v1/connections \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response:

{
  "items": [
    {
      "id": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "platform": "youtube",
      "name": "My YouTube Channel",
      "isActive": true
    }
  ],
  "total": 1
}

Copy the id — this is your connectionId.

Step 4 — Publish your first video

With a connection in hand, you can now create an assignment — an instruction to deliver a video to that channel. Provide the connectionId from the previous step, the video URL, and optional metadata like title and description. The API will return an assignment ID you can use to track progress.

curl -X POST https://pharlo.io/api/v1/assignments \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "type": "video",
    "payload": {
      "title": "My First API Upload",
      "description": "Published via Pharlo",
      "privacy": "private"
    },
    "mediaUrl": "https://example.com/video.mp4",
    "callbackUrl": "https://your-server.com/webhook"
  }'

Response 201 Created:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "type": "video",
  "createdAt": "2026-04-23T10:00:00Z"
}

Privacy note: YouTube defaults to "private". To publish publicly, set "privacy": "public" in the payload.

Step 5 — Check assignment status

After creating an assignment, use its ID to poll the current status. The response includes a status field that progresses through pending → processing → completed (or failed). You can also rely on the callbackUrl you provided in the previous step to receive a webhook notification when the status changes.

curl https://pharlo.io/api/v1/assignments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "published",
  "platformPostId": "dQw4w9WgXcQ",
  "platformUrl": "https://youtu.be/dQw4w9WgXcQ",
  "publishedAt": "2026-04-23T10:02:35Z"
}

Assignment statuses: pending → uploading → uploaded → processing → published (or failed / cancelled).

Step 6 — (Optional) Receive webhook callbacks

If you provided a callbackUrl, your server will receive a POST request on each status change:

{
  "assignmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "published",
  "platformUrl": "https://youtu.be/dQw4w9WgXcQ",
  "timestamp": "2026-04-23T10:02:35Z"
}

See the Webhooks guide for signature verification.

What's next

OverviewAuthentication