Brand diagnosis API
Submit buyer questions and read the original answers, coverage, and brand mentions for your account.
Authentication
Create a revocable OpenGEO key in the workspace. Send Authorization: Bearer YOUR_OPENGEO_KEY from server-side clients.
Run your free diagnosis
POST /api/v1/diagnoses accepts a brand name, three to five distinct questions, and a funding choice.
{
"brand": "Example Brand",
"questions": [
"Which suppliers should a small warehouse evaluate?",
"What capabilities matter when choosing a supplier?",
"How does Example Brand compare with alternatives?"
],
"funding": "trial"
}
The server returns HTTP 202 with a run ID. A free run is reserved once per account per UTC day (reset 00:00 UTC / 08:00 China time). The reservation happens before sampling so concurrent requests cannot claim a second trial. Provider failures after acceptance still use the trial.
Continue with your OpenRouter key
Request another diagnosis with funding set to byok and a providerKey field holding your OpenRouter key. For Cloro targets, also supply your own cloroKey. Each key is sent only to its own provider for this run. Own-key runs do not consume the hosted trial or its monthly slots; concurrency and provider limits still apply. The key is kept out of history and reports. OpenRouter charges the account that owns it. If you need help, contact us.
Read your results
GET /api/v1/diagnoseslists your recent runs.GET /api/v1/diagnoses/IDreturns status, original answers and mention rates by model and question type. Failed and skipped attempts are excluded from the rate.GET /api/v1/mereturns trial eligibility, configured models and monthly capacity.GET /api/v1/observationsreads saved single answers.POST /api/v1/observationsaccepts a brand, one question and your ownproviderKey.
Limits and privacy
One active run per account and three service-wide. The service reserves the full question-by-model request capacity before starting. The configured operator models are used for both funding choices. Questions go to the target provider. OpenRouter model API does not request search; Cloro remote monitoring has unknown underlying model and search execution. Results keep these conditions separate.
HTTP 409 means the free run is already used. HTTP 429 means concurrency or monthly capacity is exhausted. HTTP 503 means the selected sampling path is unconfigured.
Open your workspace ↗