Quickstart

You’ll send one finished conversation to Midwater and read back its outcome and check results. It takes about five minutes.

Early access

Your API base URL comes with your key. During early access, Midwater sends you both when your workspace is set up; set them as MIDWATER_API_KEY and MIDWATER_BASE_URL. Questions: hello@midwater.ai.

1. Make a test key. In the Midwater app, open Developers and create a key in the Test environment. It starts mw_test_ and is shown once, so copy it now. Test keys keep practice calls out of your live reports and alerts.

2. Set two environment variables.

   export MIDWATER_API_KEY="mw_test_..."
   export MIDWATER_BASE_URL="<the base URL for your Midwater environment>"

   Every example in these docs reads the key and the base URL from these variables. The base URL has no default: use the one for your Midwater environment.

3. Send a conversation. When a call or chat ends, send its transcript, the agent that handled it, and what the agent did.

   curl

   curl -X POST "$MIDWATER_BASE_URL/v1/conversations" \
     -H "Authorization: Bearer $MIDWATER_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: call_8f2a91" \
     -d '{
       "external_id": "call_8f2a91",
       "channel": "voice",
       "ended_by": "caller",
       "agent": { "id": "front-desk", "name": "Front desk", "version": "1.0.0" },
       "transcript": [
         { "speaker": "agent", "text": "Thanks for calling, this call may be recorded. How can I help?" },
         { "speaker": "user", "text": "I need to move my appointment to Thursday." },
         { "speaker": "agent", "text": "Sure, I have Thursday at 10 AM. Does that work?" },
         { "speaker": "user", "text": "Yes, that is perfect." },
         { "speaker": "agent", "text": "Great, you are all set for Thursday at 10 AM." }
       ],
       "events": [
         { "type": "tool_call", "name": "reschedule_appointment", "status": "success" }
       ]
     }'

   JavaScript

   import { Midwater } from "@midwater/sdk";
   
   const midwater = new Midwater(); // reads MIDWATER_API_KEY and MIDWATER_BASE_URL
   
   const { id, status } = await midwater.conversations.create({
     external_id: "call_8f2a91",
     channel: "voice",
     ended_by: "caller",
     agent: { id: "front-desk", name: "Front desk", version: "1.0.0" },
     transcript: [
       { speaker: "agent", text: "Thanks for calling, this call may be recorded. How can I help?" },
       { speaker: "user", text: "I need to move my appointment to Thursday." },
       { speaker: "agent", text: "Sure, I have Thursday at 10 AM. Does that work?" },
       { speaker: "user", text: "Yes, that is perfect." },
       { speaker: "agent", text: "Great, you are all set for Thursday at 10 AM." },
     ],
     events: [{ type: "tool_call", name: "reschedule_appointment", status: "success" }],
   });

   Python

   from midwater import Midwater
   
   client = Midwater()  # reads MIDWATER_API_KEY and MIDWATER_BASE_URL
   
   accepted = client.conversations.create({
       "external_id": "call_8f2a91",
       "channel": "voice",
       "ended_by": "caller",
       "agent": {"id": "front-desk", "name": "Front desk", "version": "1.0.0"},
       "transcript": [
           {"speaker": "agent", "text": "Thanks for calling, this call may be recorded. How can I help?"},
           {"speaker": "user", "text": "I need to move my appointment to Thursday."},
           {"speaker": "agent", "text": "Sure, I have Thursday at 10 AM. Does that work?"},
           {"speaker": "user", "text": "Yes, that is perfect."},
           {"speaker": "agent", "text": "Great, you are all set for Thursday at 10 AM."},
       ],
       "events": [{"type": "tool_call", "name": "reschedule_appointment", "status": "success"}],
   })

   Midwater answers 202 Accepted with { "id": "…", "status": "queued" }. The conversation is stored; scoring runs in the background.

4. Read the result. Scoring usually takes a few seconds. Fetch the conversation by Midwater’s id or by your external_id:

   curl

   curl "$MIDWATER_BASE_URL/v1/conversations/call_8f2a91" \
     -H "Authorization: Bearer $MIDWATER_API_KEY"

   JavaScript

   const conversation = await midwater.conversations.wait(id); // polls until scoring finishes
   console.log(conversation.outcome);
   for (const r of conversation.results) console.log(r.check_name, r.verdict, r.reason);

   Python

   conversation = client.conversations.wait(accepted.id)  # polls until scoring finishes
   print(conversation.outcome)
   for r in conversation.results:
       print(r.check_name, r.verdict, r.reason)

   When status is done, you get the outcome (for example resolved) and one entry in results per check, each with its result, a likelihood score, how it was decided, and a one-sentence reason. The dashboard_url opens the conversation in the app.

Next

Send real conversations from where your agent’s calls end: your voice platform’s end-of-call webhook, or your chat backend. Read Sending conversations for the full payload, then set up webhooks so results come to you instead of polling. When you’re ready for production, make a live key: see Authentication and environments.