Send a message to ClaudIA and read its answer

curl --request POST \
  --url https://api.cloudhumans.com/claudia/v1/playground/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project": "acme_support",
  "message": "meu pedido 12345 ainda não chegou, o que houve?",
  "abKey": "classification",
  "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
  "helpdeskId": "84213"
}
'

import requests

url = "https://api.cloudhumans.com/claudia/v1/playground/invoke"

payload = {
    "project": "acme_support",
    "message": "meu pedido 12345 ainda não chegou, o que houve?",
    "abKey": "classification",
    "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
    "helpdeskId": "84213"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project: 'acme_support',
    message: 'meu pedido 12345 ainda não chegou, o que houve?',
    abKey: 'classification',
    conversationId: '6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d',
    helpdeskId: '84213'
  })
};

fetch('https://api.cloudhumans.com/claudia/v1/playground/invoke', 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.cloudhumans.com/claudia/v1/playground/invoke",
  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([
    'project' => 'acme_support',
    'message' => 'meu pedido 12345 ainda não chegou, o que houve?',
    'abKey' => 'classification',
    'conversationId' => '6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d',
    'helpdeskId' => '84213'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.cloudhumans.com/claudia/v1/playground/invoke"

	payload := strings.NewReader("{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.cloudhumans.com/claudia/v1/playground/invoke")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloudhumans.com/claudia/v1/playground/invoke")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}"

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

{
  "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
  "reply": "Seu pedido 12345 saiu para entrega ontem e chega até amanhã.",
  "outcome": "answered",
  "usedSources": [
    "<string>"
  ],
  "messages": [
    {
      "role": "AGENT",
      "content": "<string>",
      "private": false
    }
  ],
  "abKeyUsed": "classification",
  "tag": "n2_unansweredbyclaudia",
  "internalNote": "Cliente pergunta sobre atraso do pedido 12345; base não cobre prazo para a região."
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

Playground

Send a message to ClaudIA and read its answer

Runs your ClaudIA for real against a message you write — the live project your customers are served by, with its own prompts, knowledge base, tools, model, classification and hand-off rules — and answers with what the customer would have received and where the ticket would have gone. Nothing reaches a customer and no production ticket is created; the run is mirrored into your CloudChat playground inbox, so it leaves a trace you can open. The run is a real one: it spends LLM tokens you are billed for and it calls the project’s tools for real, which may touch external systems. Treat every call as costly and deliberate — ask the question a customer would ask, read the answer, and change something before asking again; never loop on it to see whether the reply changes. Pass abKey to run an A/B variant of the configuration instead of the live one, which is how two configurations are compared without editing the project. The call blocks until ClaudIA is done, which is seconds to a couple of minutes; a run that outlives its budget answers 504 rather than a partial reply.

POST

playground

invoke

curl --request POST \
  --url https://api.cloudhumans.com/claudia/v1/playground/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project": "acme_support",
  "message": "meu pedido 12345 ainda não chegou, o que houve?",
  "abKey": "classification",
  "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
  "helpdeskId": "84213"
}
'

import requests

url = "https://api.cloudhumans.com/claudia/v1/playground/invoke"

payload = {
    "project": "acme_support",
    "message": "meu pedido 12345 ainda não chegou, o que houve?",
    "abKey": "classification",
    "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
    "helpdeskId": "84213"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project: 'acme_support',
    message: 'meu pedido 12345 ainda não chegou, o que houve?',
    abKey: 'classification',
    conversationId: '6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d',
    helpdeskId: '84213'
  })
};

fetch('https://api.cloudhumans.com/claudia/v1/playground/invoke', 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.cloudhumans.com/claudia/v1/playground/invoke",
  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([
    'project' => 'acme_support',
    'message' => 'meu pedido 12345 ainda não chegou, o que houve?',
    'abKey' => 'classification',
    'conversationId' => '6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d',
    'helpdeskId' => '84213'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.cloudhumans.com/claudia/v1/playground/invoke"

	payload := strings.NewReader("{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.cloudhumans.com/claudia/v1/playground/invoke")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloudhumans.com/claudia/v1/playground/invoke")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project\": \"acme_support\",\n  \"message\": \"meu pedido 12345 ainda não chegou, o que houve?\",\n  \"abKey\": \"classification\",\n  \"conversationId\": \"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d\",\n  \"helpdeskId\": \"84213\"\n}"

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

{
  "conversationId": "6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d",
  "reply": "Seu pedido 12345 saiu para entrega ontem e chega até amanhã.",
  "outcome": "answered",
  "usedSources": [
    "<string>"
  ],
  "messages": [
    {
      "role": "AGENT",
      "content": "<string>",
      "private": false
    }
  ],
  "abKeyUsed": "classification",
  "tag": "n2_unansweredbyclaudia",
  "internalNote": "Cliente pergunta sobre atraso do pedido 12345; base não cobre prazo para a região."
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

{
  "error": "Forbidden: token holds no claim for the requested account"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

One customer turn to send to ClaudIA. Everything else about the run — which knowledge base, which prompts, which tools, which model — comes from the project's own configuration, so a reply here is the reply a real customer would have received.

project

string

required

Project to talk to, e.g. acme_support, as listed by listMyClaudiaProjects. Project names are unique across all customers, so this alone identifies the environment — you never supply an account, an instance or a tenant. A project these credentials cannot reach answers 404, indistinguishable from one that does not exist.

Example:

"acme_support"

message

string

required

What the customer says this turn, verbatim and in the customer's own language. Write it the way a real person would open a ticket — the reply is only as representative as the message that provoked it. One turn per call: to continue a conversation, send the next message with the conversationId you got back.

Example:

"meu pedido 12345 ainda não chegou, o que houve?"

abKey

string | null

Run this turn through an A/B variant of the project's configuration instead of the live one, by its key. The variant replaces the settings it declares for this run only, and the key travels to the trace so the run is comparable afterwards. Get the keys from listProjectAbKeys; a key the project does not declare is refused. Omit to run the live configuration.

Example:

"classification"

conversationId

string | null

Continue an existing playground conversation instead of starting a new one. Pass the conversationId from a previous response and ClaudIA sees everything already said in it. Omit it to start fresh. A conversation that belongs to another project, or that is a real customer conversation rather than a playground one, answers 404.

Example:

"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d"

helpdeskId

string | null

Ticket ClaudIA should behave as if it were answering, by its id in the helpdesk. Use it to reproduce what happened on a specific real ticket: the run reads that conversation's context, so tools and prompts that depend on it behave as they did there. Omit it — the normal case — and the run carries no ticket context at all.

Example:

"84213"

Response

The turn finished and this is what ClaudIA answered.

The finished turn: what the customer would have received, and where the ticket would have gone. Returned only once ClaudIA is done — a run takes as long as the pipeline takes to classify, search, answer and decide.

conversationId

string

required

The playground conversation this turn belongs to. Send it back as conversationId on the next call to keep talking with the same history. The same conversation is mirrored into your CloudChat playground inbox under this id.

Example:

"6c7b1f2e-3a4d-4f5b-8c9d-0e1f2a3b4c5d"

string

required

The reply the customer would have received, whole. A project that splits long answers sends it as several messages, and they are joined here with a line break — read messages to see how it was actually delivered. Empty only when the turn produced no public message, which is what happens on a silent hand-off.

Example:

"Seu pedido 12345 saiu para entrega ontem e chega até amanhã."

outcome

enum<string>

required

What ClaudIA decided to do with the ticket. answered kept it; forwarded_to_human handed it to a human queue, and internalNote then carries the note the human reads; resolved closed it.

Available options:

answered,

forwarded_to_human,

resolved

Example:

"answered"

usedSources

string[]

required

Names of the knowledge base entries the answer was built from, in the order they were used. Empty when the reply came from a prompt rather than from content — which is itself the finding when you expected content to be used.

messages

object[]

required

Every message this turn produced, in order, including the internal notes. A turn can produce more than one message when the project splits long replies or writes a note before handing off.

Show child attributes

abKeyUsed

string | null

The A/B variant this run actually used, or null for the live configuration.

Example:

"classification"

tag

string | null

Tag applied to the ticket this turn, if any. This is what a routing rule in CloudChat would key on, so it says more about where the ticket ends up than the reply does.

Example:

"n2_unansweredbyclaudia"

internalNote

string | null

The internal note written for the human taking over, when this turn handed the ticket off. Null otherwise. Customers never see it.

Example:

"Cliente pergunta sobre atraso do pedido 12345; base não cobre prazo para a região."

Getting Started

Authentication

Knowledge Bases

Knowledge Base Content

Content Quality

Content Improvements

Content Sources

MCP Servers

Playground

Project Settings

Send a message to ClaudIA and read its answer

Authorizations

Body

Response