Skip to main content

Prepare Upload

POST 
/v1/:slug/assets/upload_prepare

Step 1 of 4-Step Asset Upload Process

This endpoint prepares a signed URL for uploading assets to Google Cloud Storage using resumable uploads.

Complete Upload Flow:​

Step 1: Prepare Upload (this endpoint)​

POST /v1/{org_slug}/assets/upload_prepare
Headers:
  Authorization: Bearer {your_access_token}
  Content-Type: application/json
Body:
  {
    "asset": {
      "title": "my-image.jpg",
      "media_type": "image/jpeg",
      "size": 1048576
    }
  }

Returns: upload_url, signed_gcs_id, encrypted_organization_metadata, file_extension

Step 2: Initialize Resumable Upload Session​

POST {upload_url_from_step_1}
Headers:
  Content-Type: {media_type_from_step_1}
  x-goog-resumable: start
  x-goog-meta-encrypted-organization-metadata: {value_from_step_1}
  x-goog-meta-extension: {file_extension_from_step_1} (if present)
Body: EMPTY (no data)

Returns: HTTP 200 with Location header containing session URL

Step 3: Upload File Data​

PUT {session_url_from_step_2_location_header}
Headers:
  Content-Type: {media_type}
Body: {binary_file_data}

Returns: HTTP 200 OK when upload completes

Step 4: Complete Upload in Playbook​

POST /v1/{org_slug}/assets/upload_complete
Headers:
  Authorization: Bearer {your_access_token}
  Content-Type: application/json
Body:
  {
    "asset": {
      "signed_gcs_id": "{value_from_step_1}",
      "title": "my-image.jpg"
    }
  }

Returns: Complete Asset object with ID, URLs, thumbnails, etc.

Important Notes:​

  • Steps 2 & 3 are Google Cloud Storage API calls (not Playbook API)
  • Step 4 is required to create the Asset in Playbook's database
  • Do not include Authorization header in steps 2 & 3 (signed URL handles auth)
  • The upload_url uses V4 signing with resumable upload protocol
  • Without Step 4, the file exists in GCS but not in Playbook's system

Error Handling:​

  • If any step fails, restart from Step 1 with a new upload_prepare call
  • The signed URL expires after 24 hours
  • Session URLs from Step 2 have shorter expiration times

Request​

Responses​

Upload preparation successful