Publishing Content

Deep-dive into the assignment lifecycle — from creation to monitoring to retries.

Creating an assignment

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": "Product Demo",
      "description": "See what'\''s new in v2",
      "privacy": "public"
    },
    "mediaUrl": "https://cdn.example.com/demo.mp4"
  }'

Minimal request (YouTube video)

{
  "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "type": "video",
  "payload": {
    "title": "Product Demo",
    "description": "See what's new in v2",
    "privacy": "public"
  },
  "mediaUrl": "https://cdn.example.com/demo.mp4"
}

Full request with all optional fields

{
  "connectionId": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "type": "video",
  "payload": {
    "title": "Product Demo",
    "description": "See what's new in v2",
    "privacy": "public",
    "tags": ["product", "demo", "v2"],
    "categoryId": "28"
  },
  "mediaUrl": "https://cdn.example.com/demo.mp4",
  "mediaContentType": "video/mp4",
  "mediaSizeBytes": 104857600,
  "scheduledAt": "2026-04-25T18:00:00+03:00",
  "callbackUrl": "https://your-server.com/webhook/delivery",
  "idempotencyKey": "publish-demo-2026-04-25",
  "externalId": "your-internal-id-123"
}

Response 201 Created

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

Platform-specific payloads

Always call GET /api/v1/platforms/{platform}/capabilities before building the payload — it lists every supported field, its type, constraints, and default value.

YouTube video

Facebook post (link/text)

Media URL requirements

• Must be publicly accessible (no auth required) at upload time
• Supported formats: MP4 (H.264) for video, JPEG/PNG for images
• YouTube: max 256 GB, max 12 hours
• Facebook: max 10 GB for video
• The URL is fetched by the API backend — serve it from a CDN or object storage

Scheduling

Pass an RFC 3339 timestamp with an explicit timezone offset in scheduledAt:

"scheduledAt": "2026-04-25T18:00:00+03:00"

Never pass a local time without an offset — the API stores times in UTC and the offset is used for conversion.

To reschedule a pending assignment:

curl -X PATCH https://pharlo.io/api/v1/assignments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt": "2026-04-26T18:00:00+03:00"}'

Idempotency keys

If your network request times out or you're unsure whether a request succeeded, resubmit with the same idempotencyKey. The API returns the existing assignment instead of creating a duplicate.

"idempotencyKey": "publish-demo-2026-04-25-attempt-1"

Keys are scoped to your API client.

Monitoring progress

Option A — Polling

GET /api/v1/assignments/{id}

Poll until status is published, failed, or cancelled. Recommended polling interval: 10–30 seconds.

Option B — Webhooks (recommended)

Provide a callbackUrl in the assignment. The API sends a POST to that URL on each status change. See the Webhooks guide.

Updating an assignment

Only pending and uploaded assignments can be updated:

curl -X PATCH https://pharlo.io/api/v1/assignments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-04-26T18:00:00+03:00",
    "payload": {"title": "Updated Title", "privacy": "public"}
  }'

To update metadata of an already published YouTube video:

curl -X PATCH https://pharlo.io/api/v1/assignments/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updatePublished": true,
    "payload": {
      "title": "New Title",
      "description": "Updated description",
      "privacy": "unlisted"
    }
  }'

Cancelling an assignment

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

Returns 204 No Content. Cancelled assignments cannot be restarted.

Retrying a failed assignment

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

Only failed assignments can be retried. This re-queues the assignment — it does not create a new one.

Listing assignments

curl "https://pharlo.io/api/v1/assignments?page=1&limit=20&status=failed&platform=youtube" \
  -H "Authorization: Bearer $DELIVERY_API_KEY"