PorticoDocs

Handoffs

Generated handoffs operations.

POST/v1/handoffsManage shared playback for the signed-in profileplayback
Audience
Clients · Native API
Authorization
API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID
social_post_v1_handoffs
Max body
256 KiB

Request body application/json · required

Example
{
  "expectedPlaybackRevision": "r12",
  "grantId": "id_8h2k4q",
  "protocolVersion": "string",
  "receiverId": "id_8h2k4q",
  "requestId": "id_8h2k4q",
  "sourcePlaybackId": "id_8h2k4q",
  "startPositionUs": "string"
}
Schema
  • expectedPlaybackRevisionstring
  • grantIdstringrequired
  • protocolVersionstringrequired
  • receiverIdstringrequired
  • requestIdstringrequired
  • sourcePlaybackIdstringrequired
  • startPositionUsstring

Responses

201Successapplication/json

Example
{
  "handoff": {
    "committedPositionUs": "string",
    "createdAt": "2026-10-18T19:30:00Z",
    "expiresAt": "2026-10-18T19:30:00Z",
    "grantId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "itemId": "id_8h2k4q",
    "outcome": "string",
    "readyPositionUs": "string",
    "reason": "string",
    "receiverId": "id_8h2k4q",
    "receiverPlaybackId": "id_8h2k4q",
    "requestId": "id_8h2k4q",
    "requestedPositionUs": "string",
    "revision": "r12",
    "settledAt": "2026-10-18T19:30:00Z",
    "sourcePlaybackId": "id_8h2k4q",
    "sourceRetired": true,
    "state": "string"
  },
  "protocolVersion": "string",
  "serverTime": "2026-10-18T19:30:00Z"
}
Schema
  • handoffobjectrequired
    • committedPositionUsstringrequired
    • createdAtstringrequired
    • expiresAtstringrequired
    • grantIdstringrequired
    • idstringrequired
    • itemIdstringrequired
    • outcomestringrequired
    • readyPositionUsstringrequired
    • reasonstringrequired
    • receiverIdstringrequired
    • receiverPlaybackIdstringrequired
    • requestIdstringrequired
    • requestedPositionUsstringrequired
    • revisionstringrequired
    • settledAtstring | any | nullrequired
    • sourcePlaybackIdstringrequired
    • sourceRetiredbooleanrequired
    • statestringrequired
  • protocolVersionstringrequired
  • serverTimestringrequired

defaultRequest refused or unavailableapplication/json

Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Schema
  • errorobjectrequired
    • codestringrequired
    • messagestringrequired

Error codesunauthorizednot_permittedinternalreceiver_requiredcapacity_reachedcast_access_endedcast_code_consumedcast_code_expiredcast_code_not_foundcast_code_revokedcast_device_expiredcast_device_not_foundcast_device_revokedcast_unavailabledevice_requiredentry_not_foundgrant_not_acceptedgrant_not_pendinggroup_endedgroup_fullhandoff_expiredhandoff_in_progresshandoff_not_readyhandoff_source_conflicthandoff_source_revision_conflicthandoff_state_conflicthost_requiredidempotency_key_reusedinvalid_requestinvite_consumedinvite_expiredinvite_not_foundinvite_revokedinvite_wrong_recipientmedia_no_longer_accessiblemember_not_foundmembership_revokednot_foundparticipant_incompatibleplayback_authority_unavailablequeue_fullrate_limitedreceiver_key_mismatchrevision_conflicttarget_unavailabledatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/handoffs" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedPlaybackRevision": "r12",
  "grantId": "id_8h2k4q",
  "protocolVersion": "string",
  "receiverId": "id_8h2k4q",
  "requestId": "id_8h2k4q",
  "sourcePlaybackId": "id_8h2k4q",
  "startPositionUs": "string"
}'
GET/v1/handoffs/{id}Manage shared playback for the signed-in profileread
Audience
Clients · Native API
Authorization
API key or personal access token with the read scope, or a signed-in session
OpenAPI operation ID
social_get_v1_handoffs_id

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200Successapplication/json

Example
{
  "handoff": {
    "committedPositionUs": "string",
    "createdAt": "2026-10-18T19:30:00Z",
    "expiresAt": "2026-10-18T19:30:00Z",
    "grantId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "itemId": "id_8h2k4q",
    "outcome": "string",
    "readyPositionUs": "string",
    "reason": "string",
    "receiverId": "id_8h2k4q",
    "receiverPlaybackId": "id_8h2k4q",
    "requestId": "id_8h2k4q",
    "requestedPositionUs": "string",
    "revision": "r12",
    "settledAt": "2026-10-18T19:30:00Z",
    "sourcePlaybackId": "id_8h2k4q",
    "sourceRetired": true,
    "state": "string"
  },
  "protocolVersion": "string",
  "serverTime": "2026-10-18T19:30:00Z"
}
Schema
  • handoffobjectrequired
    • committedPositionUsstringrequired
    • createdAtstringrequired
    • expiresAtstringrequired
    • grantIdstringrequired
    • idstringrequired
    • itemIdstringrequired
    • outcomestringrequired
    • readyPositionUsstringrequired
    • reasonstringrequired
    • receiverIdstringrequired
    • receiverPlaybackIdstringrequired
    • requestIdstringrequired
    • requestedPositionUsstringrequired
    • revisionstringrequired
    • settledAtstring | any | nullrequired
    • sourcePlaybackIdstringrequired
    • sourceRetiredbooleanrequired
    • statestringrequired
  • protocolVersionstringrequired
  • serverTimestringrequired

defaultRequest refused or unavailableapplication/json

Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Schema
  • errorobjectrequired
    • codestringrequired
    • messagestringrequired

Error codesunauthorizednot_permittedinternalreceiver_requiredcapacity_reachedcast_access_endedcast_code_consumedcast_code_expiredcast_code_not_foundcast_code_revokedcast_device_expiredcast_device_not_foundcast_device_revokedcast_unavailabledevice_requiredentry_not_foundgrant_not_acceptedgrant_not_pendinggroup_endedgroup_fullhandoff_expiredhandoff_in_progresshandoff_not_readyhandoff_source_conflicthandoff_source_revision_conflicthandoff_state_conflicthost_requiredidempotency_key_reusedinvalid_requestinvite_consumedinvite_expiredinvite_not_foundinvite_revokedinvite_wrong_recipientmedia_no_longer_accessiblemember_not_foundmembership_revokednot_foundparticipant_incompatibleplayback_authority_unavailablequeue_fullrate_limitedreceiver_key_mismatchrevision_conflicttarget_unavailabledatabase_busy

Example request

curl -X GET "http://127.0.0.1:32500/v1/handoffs/{id}" \
  -H "Authorization: Bearer $PORTICO_API_KEY"
POST/v1/handoffs/{id}/commitManage shared playback for the signed-in profileplayback
Audience
Clients · Native API
Authorization
API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID
social_post_v1_handoffs_id_commit
Max body
256 KiB

Parameters

NameInTypeDescription
idrequiredpathstring

Request body application/json · required

Example
{
  "expectedRevision": "r12",
  "protocolVersion": "string"
}
Schema
  • expectedRevisionstringrequired
  • protocolVersionstringrequired

Responses

200Successapplication/json

Example
{
  "handoff": {
    "committedPositionUs": "string",
    "createdAt": "2026-10-18T19:30:00Z",
    "expiresAt": "2026-10-18T19:30:00Z",
    "grantId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "itemId": "id_8h2k4q",
    "outcome": "string",
    "readyPositionUs": "string",
    "reason": "string",
    "receiverId": "id_8h2k4q",
    "receiverPlaybackId": "id_8h2k4q",
    "requestId": "id_8h2k4q",
    "requestedPositionUs": "string",
    "revision": "r12",
    "settledAt": "2026-10-18T19:30:00Z",
    "sourcePlaybackId": "id_8h2k4q",
    "sourceRetired": true,
    "state": "string"
  },
  "protocolVersion": "string",
  "serverTime": "2026-10-18T19:30:00Z"
}
Schema
  • handoffobjectrequired
    • committedPositionUsstringrequired
    • createdAtstringrequired
    • expiresAtstringrequired
    • grantIdstringrequired
    • idstringrequired
    • itemIdstringrequired
    • outcomestringrequired
    • readyPositionUsstringrequired
    • reasonstringrequired
    • receiverIdstringrequired
    • receiverPlaybackIdstringrequired
    • requestIdstringrequired
    • requestedPositionUsstringrequired
    • revisionstringrequired
    • settledAtstring | any | nullrequired
    • sourcePlaybackIdstringrequired
    • sourceRetiredbooleanrequired
    • statestringrequired
  • protocolVersionstringrequired
  • serverTimestringrequired

defaultRequest refused or unavailableapplication/json

Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Schema
  • errorobjectrequired
    • codestringrequired
    • messagestringrequired

Error codesunauthorizednot_permittedinternalreceiver_requiredcapacity_reachedcast_access_endedcast_code_consumedcast_code_expiredcast_code_not_foundcast_code_revokedcast_device_expiredcast_device_not_foundcast_device_revokedcast_unavailabledevice_requiredentry_not_foundgrant_not_acceptedgrant_not_pendinggroup_endedgroup_fullhandoff_expiredhandoff_in_progresshandoff_not_readyhandoff_source_conflicthandoff_source_revision_conflicthandoff_state_conflicthost_requiredidempotency_key_reusedinvalid_requestinvite_consumedinvite_expiredinvite_not_foundinvite_revokedinvite_wrong_recipientmedia_no_longer_accessiblemember_not_foundmembership_revokednot_foundparticipant_incompatibleplayback_authority_unavailablequeue_fullrate_limitedreceiver_key_mismatchrevision_conflicttarget_unavailabledatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/handoffs/{id}/commit" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":"r12","protocolVersion":"string"}'
POST/v1/handoffs/{id}/readinessManage shared playback for the signed-in profileplayback
Audience
Clients · Native API
Authorization
API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID
social_post_v1_handoffs_id_readiness
Max body
256 KiB

Parameters

NameInTypeDescription
idrequiredpathstring

Request body application/json · required

Example
{
  "expectedRevision": "r12",
  "positionUs": "string",
  "protocolVersion": "string",
  "readiness": "string",
  "receiverPlaybackId": "id_8h2k4q"
}
Schema
  • expectedRevisionstring
  • positionUsstringrequired
  • protocolVersionstringrequired
  • readinessstringrequired
  • receiverPlaybackIdstringrequired

Responses

200Successapplication/json

Example
{
  "handoff": {
    "committedPositionUs": "string",
    "createdAt": "2026-10-18T19:30:00Z",
    "expiresAt": "2026-10-18T19:30:00Z",
    "grantId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "itemId": "id_8h2k4q",
    "outcome": "string",
    "readyPositionUs": "string",
    "reason": "string",
    "receiverId": "id_8h2k4q",
    "receiverPlaybackId": "id_8h2k4q",
    "requestId": "id_8h2k4q",
    "requestedPositionUs": "string",
    "revision": "r12",
    "settledAt": "2026-10-18T19:30:00Z",
    "sourcePlaybackId": "id_8h2k4q",
    "sourceRetired": true,
    "state": "string"
  },
  "protocolVersion": "string",
  "serverTime": "2026-10-18T19:30:00Z"
}
Schema
  • handoffobjectrequired
    • committedPositionUsstringrequired
    • createdAtstringrequired
    • expiresAtstringrequired
    • grantIdstringrequired
    • idstringrequired
    • itemIdstringrequired
    • outcomestringrequired
    • readyPositionUsstringrequired
    • reasonstringrequired
    • receiverIdstringrequired
    • receiverPlaybackIdstringrequired
    • requestIdstringrequired
    • requestedPositionUsstringrequired
    • revisionstringrequired
    • settledAtstring | any | nullrequired
    • sourcePlaybackIdstringrequired
    • sourceRetiredbooleanrequired
    • statestringrequired
  • protocolVersionstringrequired
  • serverTimestringrequired

defaultRequest refused or unavailableapplication/json

Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Schema
  • errorobjectrequired
    • codestringrequired
    • messagestringrequired

Error codesunauthorizednot_permittedinternalreceiver_requiredcapacity_reachedcast_access_endedcast_code_consumedcast_code_expiredcast_code_not_foundcast_code_revokedcast_device_expiredcast_device_not_foundcast_device_revokedcast_unavailabledevice_requiredentry_not_foundgrant_not_acceptedgrant_not_pendinggroup_endedgroup_fullhandoff_expiredhandoff_in_progresshandoff_not_readyhandoff_source_conflicthandoff_source_revision_conflicthandoff_state_conflicthost_requiredidempotency_key_reusedinvalid_requestinvite_consumedinvite_expiredinvite_not_foundinvite_revokedinvite_wrong_recipientmedia_no_longer_accessiblemember_not_foundmembership_revokednot_foundparticipant_incompatibleplayback_authority_unavailablequeue_fullrate_limitedreceiver_key_mismatchrevision_conflicttarget_unavailabledatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/handoffs/{id}/readiness" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":"r12","positionUs":"string","protocolVersion":"string","readiness":"string","receiverPlaybackId":"id_8h2k4q"}'
POST/v1/handoffs/{id}/rollbackManage shared playback for the signed-in profileplayback
Audience
Clients · Native API
Authorization
API key or personal access token with the playback scope, or a signed-in session
OpenAPI operation ID
social_post_v1_handoffs_id_rollback
Max body
256 KiB

Parameters

NameInTypeDescription
idrequiredpathstring

Request body application/json · required

Example
{
  "expectedRevision": "r12",
  "protocolVersion": "string",
  "reason": "string"
}
Schema
  • expectedRevisionstring
  • protocolVersionstringrequired
  • reasonstring

Responses

200Successapplication/json

Example
{
  "handoff": {
    "committedPositionUs": "string",
    "createdAt": "2026-10-18T19:30:00Z",
    "expiresAt": "2026-10-18T19:30:00Z",
    "grantId": "id_8h2k4q",
    "id": "id_8h2k4q",
    "itemId": "id_8h2k4q",
    "outcome": "string",
    "readyPositionUs": "string",
    "reason": "string",
    "receiverId": "id_8h2k4q",
    "receiverPlaybackId": "id_8h2k4q",
    "requestId": "id_8h2k4q",
    "requestedPositionUs": "string",
    "revision": "r12",
    "settledAt": "2026-10-18T19:30:00Z",
    "sourcePlaybackId": "id_8h2k4q",
    "sourceRetired": true,
    "state": "string"
  },
  "protocolVersion": "string",
  "serverTime": "2026-10-18T19:30:00Z"
}
Schema
  • handoffobjectrequired
    • committedPositionUsstringrequired
    • createdAtstringrequired
    • expiresAtstringrequired
    • grantIdstringrequired
    • idstringrequired
    • itemIdstringrequired
    • outcomestringrequired
    • readyPositionUsstringrequired
    • reasonstringrequired
    • receiverIdstringrequired
    • receiverPlaybackIdstringrequired
    • requestIdstringrequired
    • requestedPositionUsstringrequired
    • revisionstringrequired
    • settledAtstring | any | nullrequired
    • sourcePlaybackIdstringrequired
    • sourceRetiredbooleanrequired
    • statestringrequired
  • protocolVersionstringrequired
  • serverTimestringrequired

defaultRequest refused or unavailableapplication/json

Example
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
Schema
  • errorobjectrequired
    • codestringrequired
    • messagestringrequired

Error codesunauthorizednot_permittedinternalreceiver_requiredcapacity_reachedcast_access_endedcast_code_consumedcast_code_expiredcast_code_not_foundcast_code_revokedcast_device_expiredcast_device_not_foundcast_device_revokedcast_unavailabledevice_requiredentry_not_foundgrant_not_acceptedgrant_not_pendinggroup_endedgroup_fullhandoff_expiredhandoff_in_progresshandoff_not_readyhandoff_source_conflicthandoff_source_revision_conflicthandoff_state_conflicthost_requiredidempotency_key_reusedinvalid_requestinvite_consumedinvite_expiredinvite_not_foundinvite_revokedinvite_wrong_recipientmedia_no_longer_accessiblemember_not_foundmembership_revokednot_foundparticipant_incompatibleplayback_authority_unavailablequeue_fullrate_limitedreceiver_key_mismatchrevision_conflicttarget_unavailabledatabase_busywriter_capacity

Example request

curl -X POST "http://127.0.0.1:32500/v1/handoffs/{id}/rollback" \
  -H "Authorization: Bearer $PORTICO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":"r12","protocolVersion":"string","reason":"string"}'