Skip to main content
Create Judge
curl --request POST \
  --url https://api.getpique.ai/v1/judges \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "content_type": "<string>",
  "detectors": [
    {
      "detector_name": "<string>",
      "config": {}
    }
  ]
}
'
{
  "id": "<string>",
  "status": "<string>"
}

​
Authentication

  • API Key: Organization API key in the X-API-Key header

​
Request Body

​
name
string
required
The name of the judge. Must be between 1-200 characters.
​
description
string
required
A description of what this judge evaluates. Must be between 1-2000 characters.
​
content_type
string
required
The type of content this judge will evaluate.Allowed values: video, image, audio, text
​
detectors
array
required
An array of detector configurations. Must contain at least 1 detector.

​
Request Example

​
cURL

curl -X POST "https://api.getpique.ai/v1/judges" \
  -H "X-API-Key: pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Video Quality Judge",
    "description": "Evaluates video technical quality and content",
    "content_type": "video",
    "detectors": [
      {
        "detector_name": "video_specs",
        "config": {
          "min_width": 1920,
          "min_height": 1080,
          "min_duration_sec": 15,
          "max_duration_sec": 60,
          "min_fps": 24
        }
      },
      {
        "detector_name": "audio_noise",
        "config": {}
      },
      {
        "detector_name": "pronunciation",
        "config": {
          "brand_name": "pique",
          "brand_cue": "pronounced like peak"
        }
      }
    ]
  }'

​
JSON Body

{
  "name": "Video Quality Judge",
  "description": "Evaluates video technical quality and content",
  "content_type": "video",
  "detectors": [
    {
      "detector_name": "video_specs",
      "config": {
        "min_width": 1920,
        "min_height": 1080,
        "min_duration_sec": 15,
        "max_duration_sec": 60,
        "min_fps": 24
      }
    },
    {
      "detector_name": "audio_noise",
      "config": {}
    },
    {
      "detector_name": "pronunciation",
      "config": {
        "brand_name": "pique",
        "brand_cue": "pronounced like peak"
      }
    }
  ]
}

​
Example with Reference Content

For detectors that require reference content (like video_matching), first upload the reference content:
  1. Upload reference content using /v1/judges/reference_content
  2. Use the returned reference_content_uri in the detector config:
{
  "name": "Content Matching Judge",
  "description": "Matches videos against reference content",
  "content_type": "video",
  "detectors": [
    {
      "detector_name": "video_matching",
      "config": {
        "reference_videos": [
          "gs://judge-artifacts/org_123/reference_uploads/abc/reference.mp4"
        ]
      }
    },
    {
      "detector_name": "audio_matching",
      "config": {
        "reference_audio": "gs://judge-artifacts/org_123/reference_uploads/def/audio.mp3"
      }
    }
  ]
}

​
Response

​
id
string
The unique identifier of the created judge
​
status
string
The current status of the judgePossible values:
  • pending - Judge is being prepared (reference content preprocessing)
  • ready - Judge is ready to use
  • failed - Judge creation failed

​
Response Example

{
  "id": "judge_abc123",
  "status": "ready"
}
Note: If the judge includes detectors that require preprocessing (like video_matching or audio_matching), the status will be pending until preprocessing completes.

​
Error Responses

​
400 Bad Request

Invalid request body or validation errors

​
401 Unauthorized

Missing or invalid authentication

​
403 Forbidden

Insufficient permissions

​
500 Internal Server Error

Failed to create judge due to server error