Social Media URLs
Evaluations
Social Media URLs
Submit social media video URLs for evaluation
Social Media URLs
Authentication
Required: API Key authentication viaX-API-Key header
Overview
This endpoint allows you to submit social media video URLs for evaluation. The system will automatically download the videos and process them through your specified judge.Request Body
The ID of the judge to use for evaluation. Must be a video-type judge.
List of social media video URLs to process.Constraints:
- Minimum 1 URL
- Maximum 20 URLs per request
- Must be valid HTTP/HTTPS URLs
Optional webhook URL to override your organization’s default webhook.If provided, this URL will receive notifications for this batch. The webhook will still use your organization’s webhook secret for request signing.
Request Example
cURL
JSON Body
Response
Unique identifier for this batch submission
Array of job information for each submitted video
Total number of videos submitted in this batch
ID of the webhook that will be used for notifications (if configured)
Response Example
Status Codes
- 202 Accepted - Request accepted and videos queued for processing
- 400 Bad Request - Invalid request parameters
- 401 Unauthorized - Missing or invalid API key
- 404 Not Found - Judge not found or not accessible
- 500 Internal Server Error - Server error
Webhook Notifications
If configured, your webhook will receive a POST request when each video completes processing: Headers:Webhook Endpoint Implementation Guidelines
Expected Response: Your webhook endpoint should return a 200 OK response. Any other status code will be considered a failure and may trigger retries. Timeout: Webhook requests timeout after 10 seconds. Ensure your endpoint responds within this time. Retries: Pique will retry failed webhook deliveries with exponential backoff. Implement idempotent processing using thejob_id.
Signing:
- Header: X-Pique-Signature: t=<unix timestamp seconds>,v1=<hex hmac>,alg=sha256
- Message for signing: message = f”.” (UTF-8 bytes)
- Algorithm: HMAC(secret, message, SHA256)
Rate Limits
- Maximum 20 videos per request
- Recommended: Batch multiple videos in a single request rather than making individual requests
Error Responses
400 Bad Request
- Judge is not of type ‘video’
- Invalid video URLs
- Too many URLs (exceeds 20)
- Empty URL list