# Synero for AI Agents

> Synero is an HTTP API that queries a council of 4 AI models (GPT, Claude, Gemini, Grok) in parallel and returns a synthesized answer. 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"}'

Set `"format": "json"` for a single structured response, or omit it to stream Server-Sent Events (event types: `advisor`, `advisor-complete`, `synthesis`, `complete`, `error`).

## 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.
- `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.
- `threadId` + `parentQueryId`: multi-turn conversations.
- `config.advisorModels` and `config.synthesizerModel`: override the default council.
- `config.councilTier` ("low" | "medium" | "high" | "custom"): the curated tier this query should run at. Use `high` for flagship models from each provider (Opus, GPT-5.5, Gemini 3.1 Pro, Grok 4.20 Reasoning). 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.

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

## Rate limits and errors

- 60 requests per minute per API key.
- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`.
- 401: invalid key. 402: insufficient credits (or missing provider keys in BYOK mode). 429: rate limited.

## MCP

Agents using MCP can install Synero as a server. `query_council` defaults to `synthesis: false`: you receive all four advisor responses plus instructions to synthesize them yourself (roughly half the latency of a server-synthesized answer). Pass `synthesis: true` for the server-synthesized answer instead, with `detail` ("synthesis" default | "full") controlling whether advisor transcripts accompany it. The council is capped at medium tier and bounded by a server-side deadline via this API, 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`)
- 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.