> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/specs/claudia/v1.json post /v1/playground/invoke openapi: 3.0.1 info: title: Claudia API version: 1.0.0 servers: - url: https://api.cloudhumans.com/claudia description: Production - url: https://api.cloudhumans.com/claudia/staging description: Staging security: - bearerAuth: [] tags: - name: MCP Servers description: >- The MCP servers your agents can call tools on. Registering one here is what makes its tools selectable in an agent; the credentials it needs are stored encrypted and never read back. - name: Knowledge Base Content description: Read, search and edit the content that answers your customers. - name: Content Quality description: Rewrites proposed for content that is answering your customers badly. - name: Playground description: >- Talk to one of your agents as if you were a customer, without touching a real conversation. - name: Project Settings description: >- Read and change how a ClaudIA project behaves — the settings screens of the ClaudIA app, as an API. - name: Content Improvements description: Answers Claudia proposes for questions your content does not cover yet. - name: Knowledge Bases description: The knowledge bases your account can manage. - name: Content Sources description: The sites Claudia crawls to keep a knowledge base in sync. paths: /v1/playground/invoke: post: tags: - Playground summary: Send a message to ClaudIA and read its answer description: >- 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. operationId: runPlayground requestBody: content: application/json: schema: $ref: '#/components/schemas/PlaygroundInvokeRequest' required: true responses: '200': description: The turn finished and this is what ClaudIA answered. content: application/json: schema: $ref: '#/components/schemas/PlaygroundInvokeResponse' '400': description: >- The request cannot be run as written: an empty `message`, a `conversationId` that is not a conversation id, or an `abKey` this project does not declare — listProjectAbKeys lists the ones it does. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, expired or invalid credentials. '403': description: The credentials hold no account allowed to manage this content. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The project is not one these credentials reach, or the `conversationId` names no playground conversation of it — a real customer conversation is refused here, and the two cases are deliberately indistinguishable. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit applied by the API gateway. Back off and retry. '502': description: >- The run itself failed (`RUN_FAILED`). Retrying is reasonable; the same failure twice is a problem with the project's configuration, not with the request. content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: >- ClaudIA was still working when the run budget ran out (`RUN_TIMED_OUT`). Nothing partial is returned, and the tokens the run had already spent are still spent. A prompt that reasons for minutes or a tool that hangs is the usual cause. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PlaygroundInvokeRequest: required: - message - project type: object properties: project: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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 nullable: true conversationId: type: string description: >- 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 nullable: true helpdeskId: type: string description: >- 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' nullable: true description: >- 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. PlaygroundInvokeResponse: required: - conversationId - messages - outcome - reply - usedSources type: object properties: conversationId: type: string description: >- 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 abKeyUsed: type: string description: >- The A/B variant this run actually used, or null for the live configuration. example: classification nullable: true reply: type: string description: >- 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: type: string description: >- 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. enum: - answered - forwarded_to_human - resolved example: answered tag: type: string description: >- 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 nullable: true usedSources: type: array description: >- 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. items: type: string internalNote: type: string description: >- 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. nullable: true messages: type: array description: >- 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. items: $ref: '#/components/schemas/PlaygroundMessage' description: >- 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. Error: required: - error type: object properties: error: type: string description: What went wrong. example: 'Forbidden: token holds no claim for the requested account' description: Something the caller needs to fix. PlaygroundMessage: required: - content - private - role type: object properties: role: type: string description: Who wrote it. Always `AGENT` here. example: AGENT content: type: string description: The text as it would have been sent. private: type: boolean description: >- Whether this is an internal note rather than a message to the customer. example: false description: One message ClaudIA produced during the turn. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````