# Synero for AI Agents

> Synero is an HTTP API and MCP server that asks up to four leading AI models (GPT, Claude, Gemini, Grok) the same question and returns one consensus answer plus an agreement analysis of where the models agree and split. If you are an agent deciding whether to call Synero, this document is for you.

## When to call Synero

Call Synero when a single model's answer is not enough:

- Verification or second opinion on a risky decision.
- Research questions where cross-model agreement signals confidence and disagreement surfaces blind spots.
- Multi-perspective analysis (architecture trade-offs, strategy, due diligence, code review).
- Reducing single-model bias or hallucination risk.

Do not call Synero for simple lookups, deterministic math, or tasks one model clearly handles well. It is slower and more expensive than a single-model call.

## Endpoint

POST https://synero.ai/api/query

## Authentication

Bearer token in the Authorization header. Tokens look like `sk_live_...` and are issued at https://synero.ai/app/api-keys.

    Authorization: Bearer sk_live_your_key_here

Protected-resource metadata: https://synero.ai/.well-known/oauth-protected-resource

## Minimal request

    curl -X POST https://synero.ai/api/query \
      -H "Authorization: Bearer sk_live_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{"prompt": "Is Rust or Go better for this web service?", "format": "json", "preset": "council"}'

Set `"format": "json"` for a single structured response, or omit it to stream Server-Sent Events (event types: `advisor`, `advisor-complete`, `advisor-error`, `synthesis`, `synthesis-complete`, `consensus`, `complete`, `error`). `consensus` grades agreement across the advisors (score 0-100, points they all share, and where they split, by advisor slot); JSON responses carry the same object as `consensus`, or null when grading fails. `consensus` usually arrives during synthesis but may arrive after `complete`, so read the stream until it closes; JSON responses wait for it (about 4s, up to 20s). A synthesis that fails arrives as `synthesis-complete` with an `error` field, not as a fatal `error` event.

## Key request fields

- `prompt` (string, required, max 10,000 chars): the question for the council.
- `format` ("json" | omitted): "json" returns one structured payload instead of SSE. A JSON run still going after about 60s answers 200 and sends newlines (valid leading JSON whitespace) until the object; a failure after that arrives in the body as `{ error, code }`, so check for `code`. Prefer SSE for `deep` or `web_search` runs.
- `models` (array, 1-4 model ids, one per provider) or `preset` ("solo" | "duel" | "council" | "deep" | "auto"): who answers, the same choices as the web chat (neutral prompts, so disagreements are real). "auto" lets Synero pick the preset and models per question (reported as `preset` and `routeReason` in council-meta). Without either, the legacy auto-sized council runs. `web_search` (boolean) lets each model search first; omit it and search turns on automatically for time-sensitive questions (reported as `webSearchAuto`), send false to skip it.
- `template` (string): pre-configured council for a task. Useful slugs: `code-review`, `architecture-decision`, `debugging`, `deep-research`, `due-diligence`, `strategy-brief`, `devils-advocate`.
- `context` (array): attach documents. Each item `{ name, content, type? }`. Max 50k chars per item, 100k total, at most 20 items with names up to 300 characters.
- `parent_query_id` (or `parentQueryId`): the `queryId` of an earlier query of yours; the server rebuilds the conversation for a follow-up. `thread_id` groups queries (a follow-up always joins its parent's thread). Both must be UUIDs (400 `invalid_thread_id` / `invalid_parent_query_id`). `private: true` skips saving (no `queryId`).
- `config.advisorModels` and `config.synthesizerModel`: legacy four-persona overrides, ignored when `models` or `preset` is sent.
- `config.councilTier` ("auto" | "instant" | "low" | "medium" | "high" | "custom"): the tier this query should run at. `auto` (the default) routes each question to the right size, and `instant` is a single fast model with no council. With auto or instant, setting `advisorModels` or `synthesizerModel` runs a custom council with those models instead. For flagship models (Claude Opus 5.5, GPT-6.1 Sol, Gemini 3.1 Pro, Grok 4.7) send `preset: "deep"`; an explicit `high` tier runs as medium for API callers (reported as `cappedFrom`). Use `low` for fast & cheap. The field is recorded on the saved query for analytics; agents can use it as a per-query override without affecting the user's persisted preference.
- `synthesis` (boolean, default true): set false to skip the server-side synthesizer and receive only the four advisor responses (`synthesis` is null in the JSON response). For agent callers that reconcile the advisors themselves, this cuts latency roughly in half and saves the synthesis token cost. If a requested synthesis fails (for example, the synthesizer refuses the prompt), `synthesis` is null and `synthesisError` gives the reason; the advisor responses are still returned.

Full request schema: https://synero.ai/openapi.json

## Rate limits and errors

- 60 requests per minute per API key (counted per server instance, so a guide rather than an exact quota).
- Headers on every API-key response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; 429 adds `Retry-After`.
- Errors are JSON `{ error, code, doc_url }`. 401: invalid key. 402: billing (`no_credits`, `trial_exhausted`). 404: `parent_not_found`. 429: rate limited.

## MCP

Agents using MCP can install Synero as a server. `query_council` returns the consensus answer plus the agreement analysis (score, what every model agreed on, where they split and which model said what), labeled by model name, with a `queryId` and link; it also returns `structuredContent`. Choose who answers with `models` or `preset`. `detail` ("synthesis" default | "full") controls whether each model's full answer accompanies it. Pass `synthesis: false` for a cheaper raw mode where you receive every answer plus instructions to reconcile them yourself. If a server-side synthesis fails, the tool returns the answers with the reason and asks you to synthesize them yourself. Pass a result's `queryId` as `parent_query_id` to follow up. An explicit high tier runs as medium, and every call is bounded by a server-side deadline so calls stay within client tool-call timeouts.

- Remote endpoint (Streamable HTTP, OAuth or API key): https://synero.ai/api/mcp
- Protected Resource Metadata (RFC 9728) for /api/mcp: https://synero.ai/.well-known/oauth-protected-resource/api/mcp
- Server card: https://synero.ai/.well-known/mcp-server
- Package: `@syneroai/mcp` (run via `npx -y @syneroai/mcp`), a thin proxy to the remote endpoint
- Env: `SYNERO_API_KEY=sk_live_...`
- Tool: `query_council`

## Discovery

- robots.txt: https://synero.ai/robots.txt
- Sitemap: https://synero.ai/sitemap.xml
- llms.txt: https://synero.ai/llms.txt
- llms-full.txt: https://synero.ai/llms-full.txt
- OpenAPI: https://synero.ai/openapi.json
- MCP card: https://synero.ai/.well-known/mcp-server
- Plugin manifest: https://synero.ai/.well-known/ai-plugin.json
- Protected resource metadata: https://synero.ai/.well-known/oauth-protected-resource

Public pages support Markdown content negotiation: send `Accept: text/markdown` on `/developers`, `/agent`, or `/vs/{competitor}` to receive markdown instead of HTML.