Search

Consumer-facing guide to POST /search — the fast lane: one blocking call that returns data now, no agent run. It is the low-latency counterpart to Chat. Where Chat opens a conversation and runs a multi-step Master agent turn server-side (always async, handles only), Search blocks for a single answer: it turns your ask into SQL over your interactions warehouse and runs it, and in blended mode adds a quick web + news citation pass.

Search or Chat?

Search settles in seconds (a ~15s hard ceiling). Chat can take minutes. If an ask is too open-ended for the fast lane, Search says so — the response carries escalate_to_chat: true and a plain-language message.

Call it

curl -X POST https://api.amdahl.com/api/platform/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "objection-tagged calls in the last 30 days",
    "mode": "internal"
  }'

Parameters

Unknown fields are stripped; a bad mode / limit surfaces as one invalid_argument error rather than a silent clamp gone wrong.

internal vs blended

• internal (default) writes SQL over your interactions warehouse and runs it through the same query gate the rest of the platform uses — your tenant scope, your data-access policy, the truncation guard, and the 1-hour query cache all apply, and one self-repair round re-writes the SQL if the first attempt fails.
• blended does everything internal does and fans out a quick web + news citation pass under a tight deadline. There is deliberately no rerank and no fusion here — that heavier market synthesis (and the divergence map) is Chat / the external_search tool. Blended needs the external_search:execute scope; without it the call quietly degrades to internal-only and sets external_omitted: "missing_scope" — it never fails for the missing scope.

The result shape

Search never hands back a raw error or stack. Past parameter validation it always returns success: true; every failure mode is a typed field on the result, and a partial answer always beats a 500.

{
  "success": true,
  "query": "objection-tagged calls in the last 30 days",
  "mode": "blended",
  "internal": {
    "status": "ok",
    "sql": "SELECT objection, COUNT(*) AS n FROM interactions WHERE …",
    "explanation": "Counts objection-tagged interactions in the last 30 days.",
    "rows": [{ "objection": "pricing", "n": 42 }],
    "row_count": 1,
    "truncated": false,
    "cached": false,
    "repaired": false,
    "note": null
  },
  "external": {
    "citations": [
      { "title": "…", "url": "https://…", "snippet": "…", "source": "web" }
    ],
    "sources_timed_out": []
  },
  "external_omitted": null,
  "synthesis": null,
  "message": "Found 1 result over your interactions.",
  "escalate_to_chat": false
}

Reading it

• internal.status is the warehouse leg's outcome:
  • ok — SQL ran and returned rows (in internal.rows).
  • empty — SQL ran, zero rows matched. The ask is answerable; nothing fit. internal.note explains, and internal.sql shows what ran.
  • unsupported — the ask does not fit a single SELECT over the interactions surface, so no SQL was written. escalate_to_chat is true.
  • failed — SQL was written but execution failed after one self-repair round (or the phase ran out of time). internal.note is a plain-language explanation — never the raw database error.
• internal.sql is the SQL that ran (or the last attempt). Re-run it yourself via data.query for live numbers, or show internal.rows as the snapshot.
• internal.truncated is true when the row set was capped at limit; cached is true when the 1-hour cache served it; repaired is true when the self-repair round rewrote the SQL.
• external is present only on the blended path when the external leg ran (null otherwise). Any source that missed its deadline is listed by id in external.sources_timed_out — a slow source loses a citation, never the whole call.
• external_omitted is "missing_scope" when you asked for blended but lack external_search:execute; null otherwise.
• synthesis is the opt-in one-paragraph headline (only when you passed synthesize: true and it succeeded; null otherwise).
• escalate_to_chat is true when the ask is out of the fast lane's reach and Chat is the better door.

The only success: false shape is a parameter-validation failure:

{ "success": false, "error": { "code": "invalid_argument", "message": "Invalid search request: …" } }

Over MCP

The same fast lane is the search tool on the Amdahl MCP server — one action, run, with the same parameters:

{ "action": "run", "query": "top objections this quarter", "mode": "blended" }

Use search when you want data back in one call; use the agents tool's Chat actions (start_chat / chat_status / respond / cancel_chat) when you want Amdahl to run a multi-step investigation server-side. The result is data only — no directive text.

Scopes

data:read is all internal needs, so a read-only key can call it. The blended leg additionally checks external_search:execute and degrades to internal-only when it is absent. Both scopes are on the customer-agent key bundle.