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": {}
    }
  ]
}
'

import requests

url = "https://api.getpique.ai/v1/judges"

payload = {
    "name": "<string>",
    "description": "<string>",
    "content_type": "<string>",
    "detectors": [
        {
            "detector_name": "<string>",
            "config": {}
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    content_type: '<string>',
    detectors: [{detector_name: '<string>', config: {}}]
  })
};

fetch('https://api.getpique.ai/v1/judges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getpique.ai/v1/judges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'content_type' => '<string>',
    'detectors' => [
        [
                'detector_name' => '<string>',
                'config' => [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getpique.ai/v1/judges"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getpique.ai/v1/judges")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getpique.ai/v1/judges")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "<string>"
}

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": {}
    }
  ]
}
'

import requests

url = "https://api.getpique.ai/v1/judges"

payload = {
    "name": "<string>",
    "description": "<string>",
    "content_type": "<string>",
    "detectors": [
        {
            "detector_name": "<string>",
            "config": {}
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    content_type: '<string>',
    detectors: [{detector_name: '<string>', config: {}}]
  })
};

fetch('https://api.getpique.ai/v1/judges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getpique.ai/v1/judges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'content_type' => '<string>',
    'detectors' => [
        [
                'detector_name' => '<string>',
                'config' => [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getpique.ai/v1/judges"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getpique.ai/v1/judges")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getpique.ai/v1/judges")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"content_type\": \"<string>\",\n  \"detectors\": [\n    {\n      \"detector_name\": \"<string>\",\n      \"config\": {}\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

detectors

array

required

An array of detector configurations. Must contain at least 1 detector.

Show Detector Configuration

detector_name

string

required

The name of the detector. Must be a valid detector name.See Detector Configuration Reference for available detectors.

config

object

required

Configuration object for the detector. Required keys depend on the detector type.See Detector Configuration Reference for detector-specific configurations.

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:

Upload reference content using /v1/judges/reference_content
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

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, podcast_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

Get Judge Create Reference Content Upload URL

​Authentication

​Request Body

​Request Example

​cURL

​JSON Body

​Example with Reference Content

​Response

​Response Example

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​500 Internal Server Error

Authentication

Request Body

Request Example

cURL

JSON Body

Example with Reference Content

Response

Response Example

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error