API Reference › Making requests › Synchronous requests

Synchronous requests

A synchronous call sends your prompt to an AI provider and holds the connection open until the finished answer comes back in a single response — no polling, no callbacks.

POST https://api.cloro.cloud/v1/monitor/<provider>

Overview

Almost every monitoring endpoint in the cloro API accepts the same request body and returns the same envelope, so once you have integrated one provider the rest behave identically. The Google Search endpoint is the notable exception: because it is built around search queries rather than conversational prompts, it expects a query field where the other endpoints expect prompt. The remainder of this page describes the shared contract.

Request parameters

Send a JSON body with the fields below. Only prompt is mandatory.

Field	Type	Description
`prompt`	string	Required. The text sent to the AI provider, between 1 and 10,000 characters. (On the Google Search endpoint this field is named `query`.)
`country`	string	Optional. An ISO 3166-1 alpha-2 code such as `US` or `GB` that localizes the result. When omitted, it falls back to `US`.
`include`	object	Optional. A set of boolean flags that request extra representations of the answer. Supported keys are `html` and `markdown`, both defaulting to `false`. Neither carries an additional charge.

For the full catalogue of accepted country codes, query the Countries endpoint.

Request example

curl -X POST "https://api.cloro.cloud/v1/monitor/chatgpt" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What do you know about Acme Corp?",
    "country": "US",
    "include": { "markdown": true, "html": true }
  }'

Response structure

A successful call returns an envelope with a success flag and a result object. The provider's answer lives in result.text, while any citations appear in result.sources. Requesting extra formats adds sibling fields such as html or markdown alongside them.

Field	Type	Description
`success`	boolean	Always `true` on a successful response.
`result.text`	string	The answer text produced by the AI provider.
`result.sources`	array	The list of references the provider drew on. See below for the per-item shape.
`result.html`	string	Present only when `include.html` is `true`. A link to the full rendered HTML of the answer; the link stops working 24 hours after it is issued.
`result.markdown`	string	Present only when `include.markdown` is `true`. The answer re-rendered as Markdown.

Response example

{
  "success": true,
  "result": {
    "text": "Acme Corp is a manufacturer of industrial hardware...",
    "sources": [
      {
        "position": 1,
        "url": "https://example.com/article",
        "label": "Article Title Here",
        "description": "A short snippet summarizing the referenced page..."
      }
    ],
    "html": "https://storage.cloro.cloud/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html"
  }
}

Sources array

Each entry in result.sources shares the same base fields. Some providers attach extra keys, which are documented on their individual endpoint pages.

Field	Type	Description
`position`	number	The ranking index of the source within the answer.
`url`	string	The address of the referenced page.
`label`	string	The title of the referenced article.
`description`	string	A brief excerpt or summary of the source.

Notes

Every response carries an X-Request-Id header holding a unique identifier for the call, for example X-Request-Id: b0864943-5d45-4796-bc64-f052661256f0. Keep it with your logs — quoting it lets our team trace a specific request quickly if you contact [email protected].

Rate-limit, concurrency, and credit details are reported through separate headers, covered under Credits & limits. Both the html and markdown formats are free to request, but the hosted HTML link is temporary and expires 24 hours after generation, so download it promptly if you need to retain it.