Skip to main content
Direct Upload
curl --request POST \
  --url https://api.getpique.ai/v1/evaluations/presigned-upload \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "judge_id": "<string>",
  "content_type": "<string>",
  "filename": "<string>",
  "file_size_bytes": 123,
  "title": "<string>",
  "description": "<string>",
  "webhook_url": "<string>"
}
'
{
  "job_id": "<string>",
  "upload_url": "<string>",
  "upload_headers": {},
  "expires_at": "<string>"
}

​
Authentication

Required: API Key authentication via X-API-Key header

​
Overview

This endpoint initiates an event-driven evaluation flow:
  1. API creates evaluation job record with status awaiting_upload
  2. API generates pre-signed GCS upload URL
  3. Client uploads content directly to GCS using PUT request
  4. Evaluation triggered on upload completion
  5. Webhook notification sent to client

​
Request Body

​
judge_id
string
required
The ID of the judge to use for evaluation
​
content_type
string
required
The type of content being uploadedAllowed values: video, image, audio
​
filename
string
required
The original filename of the content. Must be between 1-255 characters.
​
file_size_bytes
integer
required
The size of the file in bytes.
​
title
string
Optional title for the content
​
description
string
Optional description for the content
​
webhook_url
string
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

curl -X POST "https://api.getpique.ai/v1/evaluations/presigned-upload" \
  -H "X-API-Key: pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "judge_id": "judge_abc123",
    "content_type": "video",
    "filename": "safety_test_video.mp4",
    "file_size_bytes": 52428800,
    "title": "Product Demo Video",
    "description": "Marketing video for new product launch"
  }'

​
JSON Body

{
  "judge_id": "judge_abc123",
  "content_type": "video",
  "filename": "safety_test_video.mp4",
  "file_size_bytes": 52428800,
  "title": "Product Demo Video",
  "description": "Marketing video for new product launch"
}

​
Response

​
job_id
string
Unique identifier for the evaluation job. Use this to track the evaluation status.
​
upload_url
string
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
​
upload_headers
object
Headers that must be included when uploading to the upload_urlTypically includes:
  • Content-Type headers
  • Any required authentication headers
​
expires_at
string
ISO 8601 timestamp indicating when the upload URL expires (typically 1 hour from creation)

​
Response Example

{
  "job_id": "job_xKt9mNp2qRs3vWy7",
  "upload_url": "https://storage.googleapis.com/judge-content/org_123/pending/job_xKt9mNp2qRs3vWy7/safety_test_video.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&...",
  "upload_headers": {
    "Content-Type": "video/mp4"
  },
  "expires_at": "2024-01-15T11:30:00Z"
}

​
Uploading Content

After receiving the response, upload your file using the provided URL: 
curl -X PUT "<UPLOAD_URL_FROM_RESPONSE>"\
  -H "Content-Type: video/mp4" \
  --data-binary @your-video.mp4 \

​
Webhook Notifications

If your organization has configured a webhook (contact Pique to set a default webhook for your organization), you’ll receive a notification when the evaluation completes. The webhook payload will include:
  • Job ID
  • Evaluation status
  • Results (if successful)
  • Error message (if failed)

​
Error Responses

​
400 Bad Request

  • Invalid content type (must be video, image, or audio)
  • Invalid request parameters

​
401 Unauthorized

Missing or invalid API key

​
404 Not Found

Judge not found or not accessible by your organization

​
500 Internal Server Error

Failed to create upload URL due to server error