Direct Upload
Evaluations
Direct Upload
Request a pre-signed upload URL for content evaluation
Direct Upload
Authentication
Required: API Key authentication viaX-API-Key header
Overview
This endpoint initiates an event-driven evaluation flow:- API creates evaluation job record with status
awaiting_upload - API generates pre-signed GCS upload URL
- Client uploads content directly to GCS using PUT request
- Evaluation triggered on upload completion
- Webhook notification sent to client
Request Body
The ID of the judge to use for evaluation
The type of content being uploadedAllowed values:
video, image, audioThe original filename of the content. Must be between 1-255 characters.
The size of the file in bytes.
Optional title for the content
Optional description for the content
Optional webhook URL to override your organization’s default webhook. Intended for easier sandbox testingIf 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 the evaluation job. Use this to track the evaluation status.
Pre-signed GCS upload URL. Use this URL with a PUT request to upload your content.Important: This URL expires after the time specified in
expires_at (15 minutes from creation)Headers that must be included when uploading to the
upload_urlTypically includes:- Content-Type headers
- Any required authentication headers
ISO 8601 timestamp indicating when the upload URL expires (15 minutes from creation)
Response Example
Uploading Content
After receiving the response, upload your file using the provided URL:Webhook Notifications
If configured, your webhook will receive a POST request when content processing completes: 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)
Error Responses
400 Bad Request
- Invalid content type (must be video, image, or audio)
- Invalid request parameters