Submit external feedback
curl --request POST \
--url https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"payload": {},
"source": "unknown",
"external_id": "<string>",
"conversation_id": "<string>"
}
'import requests
url = "https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback"
payload = {
"payload": {},
"source": "unknown",
"external_id": "<string>",
"conversation_id": "<string>"
}
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({
payload: {},
source: 'unknown',
external_id: '<string>',
conversation_id: '<string>'
})
};
fetch('https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback', 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.clarityq.ai/api/v1/products/{product_id}/external-feedback",
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([
'payload' => [
],
'source' => 'unknown',
'external_id' => '<string>',
'conversation_id' => '<string>'
]),
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.clarityq.ai/api/v1/products/{product_id}/external-feedback"
payload := strings.NewReader("{\n \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\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.clarityq.ai/api/v1/products/{product_id}/external-feedback")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback")
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 \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}API Reference
Submit External Feedback
Store an arbitrary evaluation/feedback JSON payload from an external system. The payload is stored as-is without validation. The optional external_id and conversation_id are sender-side identifiers kept as opaque strings for later correlation.
POST
/
api
/
v1
/
products
/
{product_id}
/
external-feedback
Submit external feedback
curl --request POST \
--url https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"payload": {},
"source": "unknown",
"external_id": "<string>",
"conversation_id": "<string>"
}
'import requests
url = "https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback"
payload = {
"payload": {},
"source": "unknown",
"external_id": "<string>",
"conversation_id": "<string>"
}
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({
payload: {},
source: 'unknown',
external_id: '<string>',
conversation_id: '<string>'
})
};
fetch('https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback', 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.clarityq.ai/api/v1/products/{product_id}/external-feedback",
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([
'payload' => [
],
'source' => 'unknown',
'external_id' => '<string>',
'conversation_id' => '<string>'
]),
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.clarityq.ai/api/v1/products/{product_id}/external-feedback"
payload := strings.NewReader("{\n \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\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.clarityq.ai/api/v1/products/{product_id}/external-feedback")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.clarityq.ai/api/v1/products/{product_id}/external-feedback")
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 \"payload\": {},\n \"source\": \"unknown\",\n \"external_id\": \"<string>\",\n \"conversation_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Store an evaluation or feedback payload produced by your own tooling — for example a
pipeline that scores ClarityQ’s answers against your reference data.
The
payload field accepts any JSON and is stored exactly as sent, without validation,
so your format can evolve freely without breaking the integration. The optional source,
external_id, and conversation_id fields are kept as opaque strings you can use to
correlate feedback records with your own systems later.
Example request
POST /api/v1/products/{product_id}/external-feedback
Content-Type: application/json
{
"source": "my-eval-pipeline",
"external_id": "QUESTION_42",
"conversation_id": "your-conversation-reference",
"payload": {
"passed": true,
"overall_score": 95,
"strengths": ["Accurate metric calculations"],
"weaknesses": ["Could present SQL more explicitly"]
}
}
Example response
{
"id": "811918ff-2dd0-4106-8afd-b26a1f18f461",
"created_at": "2026-08-13T09:54:58Z"
}
Authorizations
API key obtained from the ClarityQ dashboard.
Path Parameters
Body
application/json
An external evaluation/feedback payload, stored as-is.
Arbitrary feedback JSON, stored without validation.
Optional identifier of the sending system, e.g. 'my-eval-pipeline'.
Maximum string length:
200Sender-side identifier for this feedback item, e.g. a question id.
Maximum string length:
500Conversation identifier as known to the sender. Stored as an opaque string; it may or may not be a ClarityQ conversation id.
Maximum string length:
500