Connections

A connection is an authorized link between your workspace and a social media channel (YouTube channel or Facebook page). Connections are created via the OAuth / Channel Connect flow and used as the target when creating Assignments.

Each connection holds an OAuth access token and a refresh token. When the access token expires the API can silently renew it using POST /refresh-token. If the refresh token itself is no longer valid, the channel must be re-authorized via the OAuth flow.

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

Endpoints

Method	Path	Description	Status
GET	`/api/v1/connections`	List connections	200
GET	`/api/v1/connections/{id}`	Connection detail	200
PATCH	`/api/v1/connections/{id}`	Update name, active state, externalId	200
POST	`/api/v1/connections/{id}/refresh-token`	Refresh OAuth token	200

`GET /api/v1/connections`

Returns a paginated list of connections visible to your API key. By default inactive connections are excluded — pass includeInactive=true to include them.

Query parameters

Parameter	Type	Description
`platform`	string	Filter by platform: `youtube` or `facebook`
`externalId`	string	Exact match on your custom identifier
`includeInactive`	bool	Include deactivated connections (default: `false`)
`organizationId`	UUID	Filter by organization. See Organizations.
`page`	int	Page number (default: 1)
`limit`	int	Items per page (default: 20)

Example request

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

Response `200 OK`

{
  "items": [
    {
      "id": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "platform": "youtube",
      "name": "My YouTube Channel",
      "thumbnailUrl": "https://yt3.ggpht.com/...",
      "isActive": true,
      "tokenExpiresAt": "2026-05-23T10:00:00Z",
      "createdAt": "2026-01-10T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Field	Type	Description
`id`	UUID	Connection ID — use this as `connectionId` in Assignments
`platform`	string	`youtube` or `facebook`
`name`	string	Display name of the channel or page
`thumbnailUrl`	string	Avatar URL from the platform
`isActive`	bool	`false` means publishing assignments to this connection will be rejected
`tokenExpiresAt`	ISO 8601	When the current access token expires. Refresh proactively using refresh-token.
`createdAt`	ISO 8601	When this connection was first authorized

`GET /api/v1/connections/{id}`

Full connection detail including OAuth token status and platform-level metadata.

Example request

curl https://pharlo.io/api/v1/connections/7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response `200 OK`

{
  "id": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "platform": "youtube",
  "name": "My YouTube Channel",
  "externalPlatformId": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "thumbnailUrl": "https://yt3.ggpht.com/...",
  "isActive": true,
  "tokenStatus": "valid",
  "tokenExpiresAt": "2026-05-23T10:00:00Z",
  "metadata": {
    "subscriberCount": 12400,
    "videoCount": 84
  },
  "createdAt": "2026-01-10T08:00:00Z"
}

Field	Type	Description
`id`	UUID	Connection ID
`platform`	string	`youtube` or `facebook`
`name`	string	Display name
`externalPlatformId`	string	Channel or page ID from the platform (e.g. `UCxxxxxx` for YouTube)
`thumbnailUrl`	string	Avatar URL
`isActive`	bool	Whether the connection accepts new assignments
`tokenStatus`	string	See token status values below
`tokenExpiresAt`	ISO 8601	Access token expiry time
`metadata`	object	Platform-level statistics (subscriber count, video count, etc.)
`createdAt`	ISO 8601	When this connection was first authorized

Token status values

Value	Meaning	Action
`valid`	Access token is current	None required
`expired`	Access token has expired but refresh token may still be valid	Call refresh-token
`missing`	No token stored — connection was never fully authorized	Re-run the OAuth flow

⚠️

Assignments submitted to a connection with tokenStatus: expired or missing will fail immediately. Resolve the token status before creating new assignments.

`PATCH /api/v1/connections/{id}`

Update connection settings. All fields are optional — include only what you want to change.

Request body

Field	Type	Description
`name`	string	Display name shown in the UI and assignment responses
`isActive`	bool	Set to `false` to deactivate the connection and prevent new assignments. Set to `true` to re-activate.
`externalId`	string	Your custom identifier — useful for correlating with your internal system

Deactivating a connection (isActive: false) does not cancel pending assignments that are already in the queue. To stop in-progress publishing, cancel the individual assignments via DELETE /api/v1/assignments/{id}.

Example request

curl -X PATCH https://pharlo.io/api/v1/connections/7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main YouTube Channel", "isActive": true}'

Response `200 OK`

{
  "id": "7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "name": "Main YouTube Channel",
  "isActive": true,
  "platform": "youtube"
}

`POST /api/v1/connections/{id}/refresh-token`

Attempt to silently renew the OAuth access token using the stored refresh token. If successful, tokenStatus becomes valid and tokenExpiresAt is updated. No user interaction required.

⚠️

If the refresh token itself has expired (Google: after 7 days of inactivity; Meta: after 60–90 days or on user revocation), this endpoint returns tokenStatus: expired and you must re-run the full OAuth flow to get a fresh token pair.

Example request

curl -X POST https://pharlo.io/api/v1/connections/7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b/refresh-token \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response `200 OK`

{
  "tokenStatus": "valid",
  "tokenExpiresAt": "2026-05-23T10:00:00Z"
}

Field	Type	Description
`tokenStatus`	string	`valid` if refresh succeeded; `expired` if the refresh token itself is no longer valid
`tokenExpiresAt`	ISO 8601	New expiry time when `tokenStatus` is `valid`; `null` when `expired`

Error responses

Status	Reason
`400`	Invalid query parameter or request body field
`401`	Missing or invalid API key
`403`	API key does not have access to this connection
`404`	Connection ID does not exist in this workspace

{
  "error": "Validation failed",
  "details": {
    "platform": ["The value 'tiktok' is not valid. Allowed: youtube, facebook."]
  }
}

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

Connections

Endpoints

GET /api/v1/connections

Query parameters

Example request

Response 200 OK

GET /api/v1/connections/{id}

Example request

Response 200 OK

Token status values

PATCH /api/v1/connections/{id}

Request body

Example request

Response 200 OK

POST /api/v1/connections/{id}/refresh-token

Example request

Response 200 OK

Error responses

See also

`GET /api/v1/connections`

Response `200 OK`

`GET /api/v1/connections/{id}`

Response `200 OK`

`PATCH /api/v1/connections/{id}`

Response `200 OK`

`POST /api/v1/connections/{id}/refresh-token`

Response `200 OK`