Assignments

An assignment is a publishing job that sends content to a connected social media channel. Each assignment moves through a lifecycle from pending to published (or failed).

Before creating an assignment you need a connectionId — get one from Connections. The payload structure depends on the target platform; see Platform Capabilities for the full schema per platform.

Base URL: https://pharlo.io
Auth: Authorization: Bearer ds_live_...

Endpoints

POST /api/v1/assignments

Create a new publishing job.

Request body

Example request

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 is new in v2",
      "privacy": "public"
    },
    "mediaUrl": "https://cdn.example.com/demo.mp4",
    "scheduledAt": "2026-04-25T18:00:00+03:00",
    "callbackUrl": "https://your-server.com/webhook"
  }'

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"
}

GET /api/v1/assignments

Paginated list of assignments. Use filters to narrow results by status, platform, or date range.

Query parameters

Example request

curl "https://pharlo.io/api/v1/assignments?status=published&limit=10" \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response 200 OK

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "published",
      "platform": "youtube",
      "type": "video",
      "platformUrl": "https://youtu.be/dQw4w9WgXcQ",
      "publishedAt": "2026-04-25T15:02:35Z",
      "createdAt": "2026-04-23T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

GET /api/v1/assignments/{id}

Full assignment detail including status, errors, platform URL, and payload.

Assignment lifecycle

Assignments progress through the following statuses in order. Once published, the platformUrl field is populated with the live URL.

Example request

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

Response 200 OK — published

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "published",
  "platform": "youtube",
  "type": "video",
  "platformPostId": "dQw4w9WgXcQ",
  "platformUrl": "https://youtu.be/dQw4w9WgXcQ",
  "publishedAt": "2026-04-25T15:02:35Z",
  "payload": {
    "title": "Product Demo",
    "privacy": "public"
  }
}

Response 200 OK — failed

When status is failed, the errors array contains one or more platform error codes with human-readable messages. Use these to diagnose the issue before retrying.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "platform": "youtube",
  "type": "video",
  "errors": [
    {
      "code": "QUOTA_EXCEEDED",
      "message": "YouTube daily upload quota exceeded for this channel."
    }
  ],
  "payload": {
    "title": "Product Demo",
    "privacy": "public"
  },
  "createdAt": "2026-04-23T10:00:00Z"
}

PATCH /api/v1/assignments/{id}

Update a pending or uploaded assignment before it is processed. You can change the payload (title, description, privacy, etc.) or reschedule with a new scheduledAt.

To update metadata of an already published YouTube video (e.g. change the title or description), include "updatePublished": true. This sends the updated payload to the platform directly without changing the assignment status.

Example — reschedule and update title

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"
    }
  }'

Example — update 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": "Product Demo — Final Cut",
      "description": "Updated description with corrected links.",
      "privacy": "public"
    }
  }'

Response 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "scheduledAt": "2026-04-26T15:00:00Z",
  "payload": {
    "title": "Updated Title",
    "privacy": "public"
  }
}

POST /api/v1/assignments/{id}/retry

Re-queue a failed assignment without creating a new one. The assignment status resets to pending and it re-enters the processing queue.

Example request

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

Response 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending"
}

DELETE /api/v1/assignments/{id}

Cancel a pending or scheduled assignment. Cancellation is permanent — cancelled assignments cannot be restarted. To publish the same content again, create a new assignment.

Example request

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

Returns 204 No Content on success. No response body.

Error responses

{
  "error": "Validation failed",
  "details": {
    "connectionId": ["This value should not be blank."],
    "type": ["The value 'clip' is not a valid content type."]
  }
}

For a full guide on handling errors and retries, see Error Handling.

See also

• Publishing guide — end-to-end walkthrough of the assignment lifecycle
• Connections — list your channel connections and get connectionId values
• Platform Capabilities — accepted payload fields per platform and content type
• Webhooks guide — how to receive and verify status-change callbacks
• Webhook deliveries — inspect delivery history for your callbackUrl