App API responses

{
  "available": true,
  "slots": ["2026-08-03T10:30:00+05:30", "2026-08-03T11:00:00+05:30"],
  "clinic": "Andheri West"
}

{
  "ok": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-03T10:30:00+05:30",
    "status": "booked",
    "caller_number": "+919845012345"
  }
}

{
  "ok": true,
  "deleted": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-03T10:30:00+05:30",
    "status": "booked"
  }
}

{
  "ok": false,
  "deleted": false,
  "error": "no matching record found"
}

{
  "results": [
    {
      "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
      "data": {
        "patient_name": "Asha Rao",
        "phone": "+919845012345",
        "slot": "2026-08-03T10:30:00+05:30",
        "status": "booked",
        "caller_number": "+919845012345",
        "display_name": "Asha Rao — 3 Aug"
      },
      "created_at": "2026-07-29T09:14:22.481293Z"
    }
  ]
}

{
  "ok": true,
  "id": "7d3f9a1e-2c48-4b6a-9f10-5e8b2d4c7a63",
  "record": {
    "patient_name": "Asha Rao",
    "phone": "+919845012345",
    "slot": "2026-08-05T16:00:00+05:30",
    "status": "rescheduled",
    "caller_number": "+919845012345"
  }
}

{
  "success — the snippet's return value, verbatim; keys are whatever the app's JS snippet returned, always a JSON object, NO envelope and NO `ok` field": {
    "total": 1770,
    "currency": "INR",
    "breakdown": { "base": 1500, "tax": 270 }
  },
  "failure — platform-built envelope; `status` is one of error|timeout|oom|invalid|busy, `error` is a diagnostic of at most 512 bytes": {
    "ok": false,
    "status": "timeout",
    "error": "execution timed out"
  },
  "gated off (the DEFAULT — sandbox tools not enabled on the deployment) — a hard error, so the model sees only a flat `error`": {
    "error": "sandbox app tools are disabled (set FEATURE_APP_SANDBOX=true)"
  }
}

{
  "ok": false,
  "status": "timeout",
  "error": "execution timed out"
}

{
  "error": "app tool failed (404 Not Found): {\"message\":\"no such clinic\"}"
}

{
  "ok": false,
  "error": "app data store is full — cannot create more records"
}

{
  "ok": false,
  "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again"
}

{
  "ok": false,
  "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again (this tool normally uses the caller's own details, but this call has none — a web call, or a withheld caller ID — so ask the caller for it)"
}

{
  "no_matching_record": {
    "ok": false,
    "error": "no matching record found"
  },
  "missing_match_value - NOTE: no `ok` key": {
    "error": "missing value for match field `appointment_id` — this tool received [caller_number, notes, phone]. The `match` field must be the name of an ARGUMENT the model fills (or a `handler.map` target), not just a field of the object."
  },
  "success, for contrast": {
    "ok": true,
    "id": "9f2c1b84-3d5e-4a17-9c60-7b1e2af03d55",
    "record": {
      "appointment_id": "APT-4821",
      "phone": "+14155550111",
      "status": "cancelled",
      "updated_at": "2026-07-29T11:42:07Z"
    }
  }
}

{
  "error": "missing value for match field `candidate` — this tool received [candidate_id, notes, stage]. The `match` field must be the name of an ARGUMENT the model fills (or a `handler.map` target), not just a field of the object."
}

{
  "error": "app tool 'clinic-crm' is not available to this agent"
}

{
  "error": "unsupported app handler 'js' — supported: object.create / object.query / object.update (declarative), http (external), sandbox (gated)"
}

{ "success": true }

HTTP 404  {"success": false, "error": "record not found"}

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210", "status": "active" },
        "createdBy": "api",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ]
  }
}

HTTP 403  {"success": false, "error": "token does not include the data:read scope"}

{
  "success": true,
  "data": {
    "grants": [
      { "providerAppId": "clinic-crm", "objectType": "patient", "access": "read" },
      { "providerAppId": "clinic-crm", "objectType": "appointment", "access": "read" }
    ]
  }
}

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "5e8a1f30-7c62-4b8d-9a44-1d2e3f4a5b6c",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210" },
        "createdBy": "api",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ]
  }
}

HTTP 403  {"success": false, "error": "app 'clinic-crm' does not share 'patient' with your app"}
HTTP 403  {"success": false, "error": "your app did not declare a read dependency on 'patient' from 'clinic-crm'"}
HTTP 400  {"success": false, "error": "use the normal data API to read your own app's data"}

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "patient",
        "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
        "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ],
    "nextCursor": "2026-07-29T09:14:22.481233+00:00,c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4"
  }
}

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210", "status": "discharged" },
    "createdBy": "api",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T13:40:55.002881Z"
  }
}

HTTP 404  {"success": false, "error": "record not found"}

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210" },
    "createdBy": "api",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
}

HTTP 400  {"success": false, "error": "unknown object type 'candidates' — declare it under the manifest's objects[]"}
HTTP 413  {"success": false, "error": "app data store is full (max 100000 records per app)"}

{
  "success": true,
  "data": {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210" },
    "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
}

HTTP 413  {"success": false, "error": "app data store is full (max 100000 records per app)"}

{
  "success": true,
  "data": {
    "ticket": "9c2f0a7b41d84e6cb3f5d0a19e77c412",
    "wsUrl": "wss://app.telenow.ai/ws/object-changes?ticket=9c2f0a7b41d84e6cb3f5d0a19e77c412"
  }
}

{
  "success": true,
  "data": {
    "objects": [
      {
        "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
        "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "appId": "clinic-crm",
        "objectType": "appointment",
        "data": {
          "patient_id": "5e8a1f30-7c62-4b8d-9a44-1d2e3f4a5b6c",
          "slot_start": "2026-07-30T10:30:00Z",
          "status": "booked",
          "patient_id__expanded": { "first_name": "Asha", "phone": "+919876543210" }
        },
        "createdBy": "agent:9a3d5c71-0f28-4e6b-b1a7-c8d9e0f1a2b3",
        "createdAt": "2026-07-29T09:14:22.481233Z",
        "updatedAt": "2026-07-29T09:14:22.481233Z"
      }
    ],
    "nextCursor": null
  }
}

HTTP 400  {"success": false, "error": "unknown object type 'patients'"}
HTTP 404  {"success": false, "error": "app is not installed"}

{ "success": true, "data": { "count": 42 } }

{
  "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
  "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "appId": "clinic-crm",
  "objectType": "patient",
  "data": {
    "first_name": "Asha",
    "last_name": "Rao",
    "phone": "+919876543210",
    "status": "active",
    "doctor_id": "a71c04e8-92b5-4d3f-8e10-6b2f9c4d7a55",
    "display_name": "Asha Rao",
    "doctor_id__expanded": { "name": "Dr. Mehta", "dept": "cardiology" }
  },
  "createdBy": "api",
  "createdAt": "2026-07-29T09:14:22.481233Z",
  "updatedAt": "2026-07-29T11:02:07.930114Z"
}

{ "event": "created", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": { "first_name": "Asha", "phone": "+919876543210" } }

{ "event": "deleted", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": null }

// object.create and object.update (success):
{ "ok": true, "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "record": { "first_name": "Asha", "phone": "+919876543210", "status": "active", "caller_number": "+919876543210" } }

// object.delete (success):
{ "ok": true, "deleted": true, "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "record": { "first_name": "Asha", "phone": "+919876543210" } }

{ "ok": false, "error": "no matching record found" }                      // object.update miss
{ "ok": false, "deleted": false, "error": "no matching record found" }     // object.delete miss
{ "ok": false, "error": "app data store is full — cannot create more records" }  // object.create at the row cap

{
  "results": [
    {
      "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
      "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
      "created_at": "2026-07-29T09:14:22.481233Z"
    }
  ]
}

{ "ok": false, "error": "no lookup value was provided — ask the caller for the detail this lookup needs (e.g. their phone number) and try again" }

{ "count": 42 }

{
  "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
  "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "appId": "clinic-crm",
  "objectType": "patient",
  "data": { "first_name": "Asha", "phone": "+919876543210" },
  "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
  "createdAt": "2026-07-29T09:14:22.481233Z",
  "updatedAt": "2026-07-29T09:14:22.481233Z"
}

the Promise REJECTS with the server's error string — for a viewer/member that is `new Error("this action requires one of: owner, admin, developer")`; the bridge does not role-check data writes itself

[
  {
    "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4",
    "orgId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "appId": "clinic-crm",
    "objectType": "patient",
    "data": { "first_name": "Asha", "phone": "+919876543210", "display_name": "Asha Rao" },
    "createdBy": "7d1e6c90-3b48-4f2a-8c55-9e0a1b2c3d4e",
    "createdAt": "2026-07-29T09:14:22.481233Z",
    "updatedAt": "2026-07-29T09:14:22.481233Z"
  }
]

{ "ok": true }

// resolves to an unsubscribe function:
const off = await telenow.data.subscribe('patient', (f) => { /* f is the frame below */ });
// each onChange call receives, verbatim:
{ "event": "updated", "objectType": "patient", "id": "c3f1b8a2-6d4e-4a91-b2f7-0e5a9c81d3f4", "data": { "first_name": "Asha", "status": "discharged" } }

HTTP 429
{ "success": false, "error": "Data API rate limit reached — slow down", "retryAfter": 1 }

HTTP 413
{ "success": false, "error": "app data store is full (max 100000 records per app)" }

{
  "title": "Standard REST error envelope (app object routes)",
  "envelope_shape": { "success": false, "error": "<message string>" },
  "notes": "Flat, exactly two keys. The wire string is the bare message - it never carries a `not found: ` / `bad request: ` prefix.",
  "dashboard_proxy_object_routes": {
    "route_prefix": "/api/orgs/:orgId/apps/:appId/objects/:objectType",
    "404_record_not_found": {
      "status": 404,
      "from": "update / delete",
      "body": { "success": false, "error": "record not found" }
    },
    "404_app_not_installed": {
      "status": 404,
      "from": "query / change-ticket / create / update / delete (install and object-type check)",
      "body": { "success": false, "error": "app is not installed" }
    },
    "400_body_not_object": {
      "status": 400,
      "from": "create / update",
      "body": { "success": false, "error": "body must be a JSON object" }
    },
    "400_unknown_object_type": {
      "status": 400,
      "from": "query / change-ticket / create / update / delete (install and object-type check)",
      "body": { "success": false, "error": "unknown object type 'patient'" }
    },
    "403_write_role_gate": {
      "status": 403,
      "from": "the org role check",
      "applies_to": "create / update / delete",
      "body": { "success": false, "error": "this action requires one of: owner, admin, developer" }
    },
    "403_not_a_member": {
      "status": 403,
      "from": "the org membership check",
      "applies_to": "query / count / change-ticket",
      "body": { "success": false, "error": "not a member of this organization" }
    },
    "no_objects_scope_403": "There is no `objects:<type>` scope check on any object route. No route checks an `objects:*` scope, and the UI bridge treats object CRUD as 'always allowed'. `objects:patient` is install-consent metadata only."
  },
  "app_key_data_api_object_routes": {
    "route_prefix": "/api/app-data/:objectType",
    "403_oauth_token_scope": {
      "status": 403,
      "from": "the Data API scope check (OAuth Bearer tokens only)",
      "body": { "success": false, "error": "token does not include the data:read scope" }
    },
    "403_static_key_scope": {
      "status": 403,
      "from": "the app-files routes, which check a static key against the install's granted scopes",
      "body": { "success": false, "error": "app did not declare the files:read scope" }
    },
    "429_rate_limited": {
      "status": 429,
      "from": "the per-(org, app) Data API rate limit",
      "note": "Extra camelCase `retryAfter` key on top of the standard envelope.",
      "body": { "success": false, "error": "Data API rate limit reached — slow down", "retryAfter": 1 }
    }
  },
  "scope_denial_403_actual_wording_and_routes": {
    "status": 403,
    "from": "the dashboard proxy's install-scope check",
    "reachable_from": "ai:llm, files:read, links:write/read, agents:read, agents:write, agent-config read, kb:read, calls:transcribe:live, members:read, user:profile - NOT from object routes",
    "body": { "success": false, "error": "this install has not granted the kb:read scope. If the app's current manifest declares it, the org is still on an older installed version — upgrade the app in Settings → Apps to grant the new scopes" }
  },
  "envelope_variants_that_add_a_key": {
    "401_jwt": {
      "from": "an expired or invalid dashboard session token",
      "body": { "success": false, "error": "Access token expired", "code": "token_expired" }
    },
    "403_with_code": {
      "from": "a write attempted while a support admin is viewing the account read-only",
      "body": { "success": false, "error": "Read-only view: this account is being viewed by an admin and cannot be modified. Ask the customer to grant temporary write access.", "code": "impersonation_write_denied" }
    },
    "502_provider": {
      "from": "an upstream carrier or vendor rejecting the request",
      "body": { "success": false, "error": "callback_method requires a valid URL", "code": "provider_error" }
    }
  },
  "ui_bridge_reprojection": {
    "from": "the dashboard host that runs your app page",
    "note": "An app running inside the sandboxed iframe NEVER sees the REST envelope. The host catches the failed request, takes the response body's `error` string, and posts back a different shape - `success` is replaced by `ok` and the HTTP status is dropped.",
    "rest_shape": { "success": false, "error": "record not found" },
    "bridge_shape": { "source": "telenow-host", "id": "4f2c1e90-9a3c-4b21-8f77-1d0a6b5e2c31", "ok": false, "error": "record not found" },
    "bridge_success_shape_for_contrast": { "source": "telenow-host", "id": "4f2c1e90-9a3c-4b21-8f77-1d0a6b5e2c31", "ok": true, "data": {} }
  }
}

// wire frame the host posts back into the iframe:
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "record not found" }

// what your code sees: the Promise rejects
try { await telenow.data.update('patient', id, { status: 'x' }); }
catch (e) { e.message === 'record not found'; }

{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
        "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
        "agentName": "Clinic Reception",
        "status": "ended",
        "callMode": "agent",
        "channel": "telephony",
        "direction": "inbound",
        "startTime": "2026-07-29T09:14:02.331245Z",
        "endTime": "2026-07-29T09:16:11.884012Z",
        "durationSec": 129,
        "fromNumber": "+919845012345",
        "toNumber": "+918031138113",
        "answeredBy": "human",
        "disposition": "answered",
        "wrapupDisposition": null,
        "hasRecording": true,
        "latency": {
          "sttMsAvg": 312,
          "turnHoldMsAvg": 420,
          "llmMsAvg": 688,
          "ttsMsAvg": 241,
          "netRttMsAvg": null,
          "flowMsAvg": null,
          "respMsAvg": 1104,
          "respMsMax": 1980,
          "respSamples": 8,
          "audioGapCount": 0
        },
        "createdAt": "2026-07-29T09:14:02.331245Z",
        "analysis": {
          "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
          "orgId": "b1d0a4c7-2e56-4d90-8f3a-6c17e9b25a08",
          "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
          "status": "done",
          "summary": "Caller rescheduled a dermatology appointment from Thursday to Monday morning and confirmed the SMS reminder.",
          "sentiment": "positive",
          "sentimentScore": 0.62,
          "disposition": "appointment_rescheduled",
          "actionItems": ["Send updated confirmation SMS for Mon 10:30"],
          "customData": { "patient_id": "P-40182", "department": "dermatology" },
          "evidence": { "patient_id": "my patient number is four zero one eight two" },
          "qa": [{ "key": "verified_identity", "met": true, "evidence": "Can you confirm your date of birth?" }],
          "objections": ["Thursday slot was too late in the day"],
          "score": 88,
          "coaching": [{ "issue": "Did not offer the earlier 9:15 slot", "suggestion": "Read the two nearest openings before confirming", "severity": "low" }],
          "hallucinations": [],
          "cx": { "rating": "good", "friction": ["hold while checking the calendar"], "highlights": ["confirmed the new time twice"] },
          "topics": ["appointment_rescheduling", "sms_reminder"],
          "keywords": ["dermatology", "monday", "reminder"],
          "agentWords": 214,
          "customerWords": 96,
          "agentTurns": 9,
          "customerTurns": 8,
          "model": "gpt-4.1-mini",
          "error": null,
          "createdAt": "2026-07-29T09:21:44.120388Z",
          "updatedAt": "2026-07-29T09:21:44.120388Z"
        },
        "analysisEnabled": true,
        "cost": {
          "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
          "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
          "agentName": "Clinic Reception",
          "callType": "agent_voice",
          "startTime": "2026-07-29T09:14:02.331245Z",
          "llmUsd": "0.001842",
          "sttUsd": "0.000930",
          "ttsUsd": "0.002105",
          "telephonyUsd": "0.006450",
          "platformAiUsd": "0",
          "postCallAnalysisUsd": "0.000410",
          "simulationUsd": "0",
          "embeddingUsd": "0",
          "platformFeeUsd": "0.004500",
          "featureSurchargeUsd": "0",
          "totalChargeUsd": "0.016237",
          "hasEstimates": false,
          "breakdown": {
            "billedMinutes": "2.15",
            "feePercent": "10",
            "feePerMinUsd": "0.002",
            "softphoneFee": false,
            "feeOverridden": false,
            "durationSecs": 129,
            "telephonyBilledSecs": 129,
            "demo": false,
            "featureSurchargeUsd": "0",
            "featureSurcharges": [],
            "feeRule": null
          },
          "ratedAt": "2026-07-29T09:21:00.004881Z"
        }
      }
    ],
    "total": 412,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

// 403 — neither calls scope granted
{ "success": false, "error": "requires the calls:read or calls:read:org scope" }

{
  "success": true,
  "data": {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agentName": "Clinic Reception",
    "status": "ended",
    "callMode": "agent",
    "channel": "telephony",
    "direction": "inbound",
    "startTime": "2026-07-29T09:14:02.331245Z",
    "endTime": "2026-07-29T09:16:11.884012Z",
    "durationSec": 129,
    "fromNumber": "+919845012345",
    "toNumber": "+918031138113",
    "answeredBy": "human",
    "disposition": "answered",
    "wrapupDisposition": null,
    "hasRecording": true,
    "latency": {
      "sttMsAvg": 312,
      "turnHoldMsAvg": 420,
      "llmMsAvg": 688,
      "ttsMsAvg": 241,
      "netRttMsAvg": null,
      "flowMsAvg": null,
      "respMsAvg": 1104,
      "respMsMax": 1980,
      "respSamples": 8,
      "audioGapCount": 0
    },
    "createdAt": "2026-07-29T09:14:02.331245Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "5c8b2d41-6e70-4a92-b1f3-2a7d90e4c815",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a Tuesday cleaning to the 4th at 11:00.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "resolved",
      "actionItems": ["Send the caller an SMS confirmation for Aug 4, 11:00"],
      "customData": { "appointment_type": "cleaning", "patient_id": "PT-40912" },
      "evidence": { "sentiment": "Sure — I can do Tuesday the fourth at eleven." },
      "qa": [
        { "key": "verified_identity", "met": true, "evidence": "Can I confirm your date of birth?" },
        { "key": "offered_reminder", "met": false, "evidence": "" }
      ],
      "objections": [],
      "score": 88,
      "coaching": [
        { "issue": "Did not offer an SMS reminder", "suggestion": "Close by offering a reminder text", "severity": "low" }
      ],
      "hallucinations": [],
      "cx": { "rating": "good", "friction": [], "highlights": ["Rebooked in under a minute"] },
      "topics": ["appointment rescheduling", "dental cleaning"],
      "keywords": ["Tuesday", "cleaning", "reschedule"],
      "agentWords": 96,
      "customerWords": 41,
      "agentTurns": 6,
      "customerTurns": 5,
      "model": "claude-sonnet-4-5",
      "error": null,
      "createdAt": "2026-07-29T09:16:20.104553Z",
      "updatedAt": "2026-07-29T09:16:38.772910Z"
    },
    "analysisEnabled": true,
    "transcript": [
      { "role": "assistant", "text": "Thanks for calling Smile Dental, how can I help?", "at": "2026-07-29T09:14:04.102331Z", "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" },
      { "role": "user", "text": "I need to move my Tuesday cleaning.", "at": "2026-07-29T09:14:09.774210Z", "agentId": null },
      { "role": "assistant", "text": "Sure — I can do Tuesday the fourth at eleven.", "at": "2026-07-29T09:14:15.310884Z", "agentId": "7b0e4c22-1a9f-4d55-8e30-cc61b9a7d248" }
    ],
    "participants": {
      "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception",
      "7b0e4c22-1a9f-4d55-8e30-cc61b9a7d248": "Scheduling Specialist"
    }
  }
}

// 404 — not this org's call
{ "success": false, "error": "call not found" }
// 403 — org owns it but the install isn't bound to its agent, and no :org scope
{ "success": false, "error": "app is not bound to this call's agent" }

// GET /orgs/{orgId}/apps/{appId}/calls?limit=50&includeAnalysis=true
{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
        "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
        "agentName": "Clinic Reception",
        "status": "ended",
        "callMode": "agent",
        "channel": "telephony",
        "direction": "inbound",
        "startTime": "2026-07-29T09:14:02.331245Z",
        "endTime": "2026-07-29T09:16:11.884012Z",
        "durationSec": 129,
        "fromNumber": "+919845012345",
        "toNumber": "+918031138113",
        "answeredBy": "human",
        "disposition": "answered",
        "wrapupDisposition": null,
        "hasRecording": true,
        "latency": { "sttMsAvg": 312, "turnHoldMsAvg": 420, "llmMsAvg": 688, "ttsMsAvg": 241, "netRttMsAvg": null, "flowMsAvg": null, "respMsAvg": 1104, "respMsMax": 1980, "respSamples": 8, "audioGapCount": 0 },
        "createdAt": "2026-07-29T09:14:02.331245Z",
        "analysis": { /* the full analysis object, or null */ },
        "analysisEnabled": true
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agentName": "Clinic Reception",
    "status": "ended",
    "callMode": "agent",
    "channel": "telephony",
    "direction": "inbound",
    "startTime": "2026-07-29T09:14:02.331245Z",
    "endTime": "2026-07-29T09:16:11.884012Z",
    "durationSec": 129,
    "fromNumber": "+919845012345",
    "toNumber": "+918031138113",
    "answeredBy": "human",
    "disposition": "answered",
    "wrapupDisposition": null,
    "hasRecording": true,
    "latency": {
      "sttMsAvg": 312,
      "turnHoldMsAvg": 420,
      "llmMsAvg": 688,
      "ttsMsAvg": 241,
      "netRttMsAvg": null,
      "flowMsAvg": null,
      "respMsAvg": 1104,
      "respMsMax": 1980,
      "respSamples": 8,
      "audioGapCount": 0
    },
    "createdAt": "2026-07-29T09:14:02.331245Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "6b0d4c11-9e57-4a02-8f3c-2d71b5e9a084",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a Tuesday cleaning to Thursday 4pm and confirmed the SMS reminder.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "appointment_rescheduled",
      "actionItems": ["Send confirmation SMS for Thu 4:00pm"],
      "customData": { "patient_name": "Anita Rao", "new_slot": "2026-08-06T16:00:00+05:30" },
      "evidence": { "new_slot": "Thursday at four in the afternoon works" },
      "qa": [{ "key": "verified_identity", "met": true, "evidence": "Can I have your date of birth?" }],
      "objections": ["Did not want a Monday slot"],
      "score": 86,
      "coaching": [{ "issue": "Did not offer the earlier cancellation slot", "suggestion": "Read the waitlist openings before proposing a new day", "severity": "low" }],
      "hallucinations": [],
      "cx": { "rating": 4, "friction": ["Repeated the phone number twice"], "highlights": ["Confirmed the new time back to the caller"] },
      "topics": ["appointment_rescheduling"],
      "keywords": ["cleaning", "Tuesday", "Thursday", "reminder"],
      "agentWords": 143,
      "customerWords": 61,
      "agentTurns": 7,
      "customerTurns": 6,
      "model": "gpt-4.1-mini",
      "error": null,
      "createdAt": "2026-07-29T09:16:44.512907Z",
      "updatedAt": "2026-07-29T09:16:44.512907Z"
    },
    "analysisEnabled": true,
    "transcript": [
      { "role": "assistant", "text": "Thanks for calling Smile Dental, how can I help?", "at": "2026-07-29T09:14:04.102331Z", "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" },
      { "role": "user", "text": "I need to move my Tuesday cleaning.", "at": "2026-07-29T09:14:09.774210Z", "agent_id": null }
    ],
    "participants": {
      "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception"
    }
  }
}

{
  "success": true,
  "data": {
    "armed": true,
    "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42"
  }
}

// 400 — not a softphone call
{ "success": false, "error": "live assist is only available on manual softphone calls" }
// 409 — not live right now
{ "success": false, "error": "call is not live" }

{
  "success": true,
  "data": {
    "ticket": "5b81a3c74f6e4d2ab0973e1c8f4d2266",
    "wsUrl": "wss://app.telenow.ai/ws/live-call-stream?ticket=5b81a3c74f6e4d2ab0973e1c8f4d2266"
  }
}

// 409 — call is not live on this node
{ "success": false, "error": "call is not live" }

// telenow.calls.arm(sessionId, { language: 'en-IN', sttModel: 'nova-2' })
{ "armed": true, "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42" }

// telenow.calls.open(sessionId) — NAVIGATES the dashboard away, unmounting your page
{ "ok": true }

// telenow.stream.subscribe(sessionId, onEvent) — the RPC resolves to an unsubscribe function;
// internally the host replies with just:
{ "streamId": "a2c4e6f8-1b3d-4a5c-9e7f-0d2b4c6a8e10" }
// then pushes each socket frame to the iframe as:
{ "source": "telenow-host", "stream": "a2c4e6f8-…", "data": { "topic": "call.turn", "sessionId": "9f1c…", "data": { "corr": "t3:n=greet:g=1", "text": "I need to move my Tuesday cleaning." } } }

// resolves to the REST `data` object VERBATIM — camelCase, snake_case transcript
{
  "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
  "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
  "agentName": "Clinic Reception",
  "status": "ended",
  "callMode": "agent",
  "channel": "telephony",
  "direction": "inbound",
  "startTime": "2026-07-29T09:14:02.331245Z",
  "endTime": "2026-07-29T09:16:11.884012Z",
  "durationSec": 129,
  "fromNumber": "+919845012345",
  "toNumber": "+918031138113",
  "answeredBy": "human",
  "disposition": "answered",
  "wrapupDisposition": null,
  "hasRecording": true,
  "latency": { "sttMsAvg": 312, "turnHoldMsAvg": 420, "llmMsAvg": 688, "ttsMsAvg": 241, "netRttMsAvg": null, "flowMsAvg": null, "respMsAvg": 1104, "respMsMax": 1980, "respSamples": 8, "audioGapCount": 0 },
  "createdAt": "2026-07-29T09:14:02.331245Z",
  "analysis": { /* the full analysis object, or null */ },
  "analysisEnabled": true,
  "transcript": [
    { "role": "assistant", "text": "Thanks for calling Smile Dental.", "at": "2026-07-29T09:14:04.102331Z", "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35" }
  ],
  "participants": { "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35": "Clinic Reception" }
}

[
  {
    "id": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
    "agent_id": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
    "agent_name": "Clinic Reception",
    "channel": "telephony",
    "direction": "inbound",
    "from_number": "+919845012345",
    "to_number": "+918031138113",
    "status": "ended",
    "duration_sec": 129,
    "start_time": "2026-07-29T09:14:02.331245Z",
    "end_time": "2026-07-29T09:16:11.884012Z",
    "analysis": {
      "sessionId": "9f1c2b8e-4a3d-4f26-9b71-0c5ad83e1f42",
      "orgId": "c81b4f27-6e0a-4d33-8f52-2a7c9b1d6e04",
      "agentId": "3d5a1f90-7c2e-4b18-a6d4-91e2f0c74b35",
      "status": "done",
      "summary": "Caller rescheduled a dermatology appointment from Thursday to Saturday morning and asked whether the clinic bills their insurer directly.",
      "sentiment": "positive",
      "sentimentScore": 0.62,
      "disposition": "resolved",
      "actionItems": [
        "Send the Saturday 11:00 confirmation SMS",
        "Email the insurance pre-authorisation form"
      ],
      "customData": { "department": "dermatology", "reschedule": true },
      "evidence": {
        "disposition": "great, Saturday at eleven works for me",
        "department": "I need to move my skin appointment"
      },
      "qa": [
        { "key": "verified_identity", "met": true, "evidence": "can I confirm your date of birth?" },
        { "key": "offered_callback", "met": false, "evidence": null }
      ],
      "objections": ["Thursday slot was too early"],
      "score": 84,
      "coaching": [
        { "issue": "Did not offer a callback number", "suggestion": "Close by confirming the best number to reach them on.", "severity": "low" }
      ],
      "hallucinations": [],
      "cx": { "rating": 4, "friction": ["Two attempts to hear the date"], "highlights": ["Reschedule handled in one turn"] },
      "topics": ["appointment_reschedule", "insurance"],
      "keywords": ["dermatology", "Saturday", "pre-authorisation"],
      "agentWords": 142,
      "customerWords": 96,
      "agentTurns": 9,
      "customerTurns": 8,
      "model": "gpt-4o-mini",
      "error": null,
      "createdAt": "2026-07-29T09:16:44.010982Z",
      "updatedAt": "2026-07-29T09:16:51.447203Z"
    },
    "analysis_enabled": true
  },
  {
    "id": "b7e0d413-52c8-4a90-9f6b-1d84c7a2e550",
    "agent_id": "5c9e7a02-13bd-4c77-8e41-6fa03b9d2c18",
    "agent_name": null,
    "channel": "web_call",
    "direction": "web",
    "from_number": null,
    "to_number": null,
    "status": "active",
    "duration_sec": null,
    "start_time": "2026-07-29T09:22:18.664301Z",
    "end_time": null,
    "analysis": null,
    "analysis_enabled": false
  }
]

// the bridge rejects the Promise with an Error; the raw postMessage is
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "calls.history: unsupported filter(s) [phone] — this app plane supports agentId, callMode, status, from, to, sort, limit, offset" }

// Every REST route on both planes (app-key and dashboard proxy):
{ "success": false, "error": "call not found" }                         // 404
{ "success": false, "error": "requires the calls:read or calls:read:org scope" }  // 403
{ "success": false, "error": "app is not bound to this call's agent" }   // 403
{ "success": false, "error": "call is not live" }                       // 409
{ "success": false, "error": "live assist is only available on manual softphone calls" } // 400
{ "success": false, "error": "Something went wrong" }                   // 500, message is always this literal

// Rate limited (extra field):
{ "success": false, "error": "Too many requests, please try again later", "retryAfter": 30 }  // 429

// Expired/invalid JWT (extra machine-readable code):
{ "success": false, "error": "Access token expired", "code": "token_expired" }  // 401

// UI BRIDGE — a different shape entirely, over postMessage:
{ "source": "telenow-host", "id": "r7", "ok": false, "error": "this app didn't request the \"calls:read\" capability" }

{ "success": true }

403 when the agent exists but this app did not create it:
{ "success": false, "error": "agent was not created by this app" }
404 for missing/cross-org: { "success": false, "error": "agent not found" }

{
  "success": true,
  "data": {
    "agents": [
      { "id": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77", "name": "Front Desk", "kind": "single" },
      { "id": "b41d9a02-5e67-4c8a-8f13-9d0e6a2c5b90", "name": "Collections", "kind": "flow" }
    ]
  }
}

{
  "success": true,
  "data": {
    "agentId": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77",
    "name": "Front Desk",
    "description": "Books and reschedules appointments",
    "kind": "flow",
    "updatedAt": "2026-07-29T09:14:22.481930Z",
    "prompt": { "systemPrompt": "You are the front desk for Acme Dental. Be brief." },
    "model": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "temperature": 0.7,
      "maxTokens": 300,
      "config": { "provider": "openai", "model": "gpt-4o-mini", "temperature": 0.7, "maxTokens": 300 }
    },
    "voice": {
      "provider": "elevenlabs",
      "voice": "21m00Tcm4TlvDq8ikWAM",
      "config": { "provider": "elevenlabs", "voice": "21m00Tcm4TlvDq8ikWAM", "speed": 1.0 }
    },
    "stt": {
      "provider": "deepgram",
      "config": { "provider": "deepgram", "language": "en-IN", "punctuation": true }
    },
    "behavior": {
      "memoryType": "ephemeral",
      "maxDuration": 600,
      "contextMode": "window",
      "silenceHangupSecs": 30,
      "bargeInSensitivity": 0.5,
      "debugTrace": true
    },
    "telephony": {
      "provider": "twilio",
      "config": {
        "phoneNumber": "+918031138113",
        "firstResponse": "agent",
        "agentMsg": "Thanks for calling Acme Dental.",
        "recording": true
      }
    },
    "flow": {
      "schema": 1,
      "startNodeId": "greet",
      "nodes": [
        {
          "id": "greet",
          "kind": "conversation",
          "name": "Greeting",
          "position": { "x": 0, "y": 0 },
          "prompt": "Greet the caller and find out what they need.",
          "promptMode": "append",
          "toolCount": 0,
          "precallLookupCount": 0
        },
        {
          "id": "book",
          "kind": "tool",
          "name": "Book slot",
          "config": {},
          "toolCount": 2,
          "precallLookupCount": 1
        }
      ],
      "edges": [
        { "id": "e1", "source": "greet", "target": "book", "condition": { "kind": "ai", "describe": "caller wants to book" } }
      ]
    },
    "analysis": {
      "enabled": false,
      "customFields": [],
      "qaCriteria": [],
      "minDurationSec": 20,
      "minCustomerTurns": 2,
      "language": "en",
      "sections": { "summary": true, "sentiment": true, "disposition": true, "actionItems": true, "objections": true, "evidence": true, "topics": true, "judge": true },
      "basePrompt": "You are writing the notes the owner of this AI agent reads after each call. The owner is the business or person the agent answers for. …"
    },
    "objectives": { "enabled": false, "askCap": 2, "slots": [], "actions": [], "dispositions": [], "fallbackDisposition": null },
    "tools": [
      { "name": "book_appointment", "description": "Book a slot in the clinic calendar", "kind": "http" }
    ],
    "realtimeEngine": null
  }
}

{
  "success": true,
  "data": {
    "isPublic": false,
    "slug": "a3f19c0d4b72",
    "publicUrl": "https://app.telenow.ai/p/a3f19c0d4b72",
    "embedSnippet": "<script src=\"https://api.telenow.ai/widget.js\" data-slug=\"a3f19c0d4b72\"></script>"
  }
}

{
  "success": true,
  "data": {
    "teams": [
      {
        "id": "front-desk-team",
        "name": "Front Desk Team",
        "description": "Reception plus billing",
        "memberCount": 2,
        "members": [
          { "ref": "receptionist", "name": "Receptionist", "kind": "flow" },
          { "ref": "billing", "name": "billing", "kind": "single" }
        ]
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "templates": [
      { "id": "front-desk", "name": "Front Desk", "description": "Answers and books", "kind": "flow" },
      { "id": "after-hours", "name": "after-hours", "description": null, "kind": "single" }
    ]
  }
}

{
  "GET /api/orgs/{orgId}/apps/{appId}/agents/{agentId}/config": {
    "success": true,
    "data": {
      "agentId": "9f1c2a84-7b3e-4d51-a0c6-2e58d43f1b90",
      "name": "Clinic Front Desk",
      "description": "Books and reschedules appointments",
      "kind": "single",
      "updatedAt": "2026-07-29T09:14:52.183042Z",
      "prompt": { "systemPrompt": "You are Asha, the front desk assistant for Sunrise Clinic." },
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "temperature": 0.4,
        "maxTokens": 400,
        "config": { "temperature": 0.4, "maxTokens": 400 }
      },
      "voice": { "provider": "telenow", "voice": "asha", "config": { "language": "hi-IN", "speed": 1.0 } },
      "stt": { "provider": "deepgram", "config": { "model": "nova-2", "language": "en-IN" } },
      "behavior": {
        "memoryType": "short-term",
        "maxDuration": 600,
        "contextMode": "window",
        "contextWindow": 10,
        "silenceHangupSecs": 30
      },
      "telephony": {
        "provider": "plivo",
        "config": {
          "phoneNumber": "+918031138113",
          "firstResponse": "agent",
          "agentMsg": "Hi, this is Asha from Sunrise Clinic.",
          "recording": true
        }
      },
      "flow": null,
      "analysis": {
        "enabled": false,
        "customFields": [],
        "qaCriteria": [],
        "minDurationSec": 20,
        "minCustomerTurns": 2,
        "language": "en",
        "sections": { "summary": true, "sentiment": true, "disposition": true, "actionItems": true, "objections": true, "evidence": true, "topics": true, "judge": true },
        "basePrompt": "You are writing the notes the owner of this AI agent reads after each call. The owner is the business or person the agent answers for. …"
      },
      "objectives": { "enabled": false, "askCap": 2, "slots": [], "actions": [], "dispositions": [], "fallbackDisposition": null },
      "tools": [
        { "name": "book_appointment", "description": "Book a slot in the clinic calendar", "kind": "custom" }
      ],
      "realtimeEngine": null
    }
  },
  "PATCH /api/orgs/{orgId}/apps/{appId}/agents/{agentId}/config": {
    "success": true,
    "data": {
      "updated": ["prompt", "model"],
      "config": {
        "agentId": "9f1c2a84-7b3e-4d51-a0c6-2e58d43f1b90",
        "name": "Clinic Front Desk",
        "description": "Books and reschedules appointments",
        "kind": "single",
        "updatedAt": "2026-07-29T09:21:07.664118Z",
        "prompt": { "systemPrompt": "You are Asha. Confirm the patient's name before booking." },
        "model": {
          "provider": "openai",
          "model": "gpt-4o",
          "temperature": 0.2,
          "maxTokens": 400,
          "config": { "temperature": 0.2, "maxTokens": 400 }
        },
        "voice": { "provider": "telenow", "voice": "asha", "config": { "language": "hi-IN", "speed": 1.0 } },
        "stt": { "provider": "deepgram", "config": { "model": "nova-2", "language": "en-IN" } },
        "behavior": {
          "memoryType": "short-term",
          "maxDuration": 600,
          "contextMode": "window",
          "contextWindow": 10,
          "silenceHangupSecs": 30
        },
        "telephony": {
          "provider": "plivo",
          "config": {
            "phoneNumber": "+918031138113",
            "firstResponse": "agent",
            "agentMsg": "Hi, this is Asha from Sunrise Clinic.",
            "recording": true
          }
        },
        "flow": null,
        "analysis": {
          "enabled": false,
          "customFields": [],
          "qaCriteria": [],
          "minDurationSec": 20,
          "minCustomerTurns": 2,
          "language": "en",
          "sections": { "summary": true, "sentiment": true, "disposition": true, "actionItems": true, "objections": true, "evidence": true, "topics": true, "judge": true },
          "basePrompt": "You are writing the notes the owner of this AI agent reads after each call. The owner is the business or person the agent answers for. …"
        },
        "objectives": { "enabled": false, "askCap": 2, "slots": [], "actions": [], "dispositions": [], "fallbackDisposition": null },
        "tools": [
          { "name": "book_appointment", "description": "Book a slot in the clinic calendar", "kind": "custom" }
        ],
        "realtimeEngine": null
      }
    }
  },
  "flow agent - same document, data.flow is non-null (nodes re-projected: tools/precallLookups become toolCount/precallLookupCount)": {
    "schema": 1,
    "startNodeId": "greet",
    "nodes": [
      {
        "id": "greet",
        "kind": "conversation",
        "name": "Greeting",
        "position": { "x": 120, "y": 80 },
        "prompt": "Greet the caller and ask what they need.",
        "promptMode": "append",
        "toolCount": 2,
        "precallLookupCount": 0
      }
    ],
    "edges": [
      {
        "id": "e1",
        "source": "greet",
        "target": "book",
        "label": "wants appointment",
        "priority": 0,
        "condition": { "kind": "ai", "describe": "caller wants to book an appointment" }
      }
    ]
  },
  "UI bridge (telenow.agents.getConfig / updateConfig) - envelope STRIPPED": {
    "getConfig resolves to": "the data object above, verbatim - no { success } wrapper",
    "updateConfig resolves to": { "updated": ["prompt"], "config": "same object as data.config above" },
    "on failure": "the promise REJECTS with Error(message); the host->iframe frame is { ok: false, error }"
  },
  "error (HTTP 409 - ifUnmodifiedSince mismatch)": {
    "success": false,
    "error": "agent changed since you read it (now 2026-07-29T09:21:07.664118+00:00) — re-read the config and re-apply"
  }
}

403 with the upgrade hint the app-key plane does NOT emit:
{ "success": false, "error": "this install has not granted the agents:config:write:prompt scope. If the app's current manifest declares it, the org is still on an older installed version — upgrade the app in Settings → Apps to grant the new scopes" }

{
  "success": true,
  "data": {
    "isPublic": true,
    "slug": "a3f19c0d4b72",
    "publicUrl": "https://app.telenow.ai/p/a3f19c0d4b72",
    "embedSnippet": "<script src=\"https://api.telenow.ai/widget.js\" data-slug=\"a3f19c0d4b72\"></script>"
  }
}

403 (not connected): { "success": false, "error": "app is not connected to this agent" }  — note the wording differs from the app-key plane's "app is not bound to this agent" for the identical condition.

{
  "success": true,
  "data": {
    "updated": ["prompt", "voice"],
    "config": {
      "agentId": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77",
      "name": "Front Desk",
      "description": "Answers inbound clinic calls and books appointments",
      "kind": "flow",
      "updatedAt": "2026-07-29T09:31:07.220114Z",
      "prompt": { "systemPrompt": "You are Riya at Sunrise Clinic. Be brief and warm." },
      "model": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "temperature": 0.6,
        "maxTokens": 512,
        "config": { "temperature": 0.6, "maxTokens": 512 }
      },
      "voice": { "provider": "telenow", "voice": "aarohi", "config": { "speed": 1.0, "language": "en-IN" } },
      "stt": { "provider": "deepgram", "config": { "model": "nova-3", "language": "en-IN" } },
      "behavior": {
        "opener": "Thanks for calling Sunrise Clinic, how can I help?",
        "bargeIn": true,
        "bargeInSensitivity": 0.5,
        "silenceSecs": 8,
        "debugTrace": true
      },
      "telephony": { "provider": "twilio", "config": { "phoneNumber": "+919876543210", "recording": true } },
      "flow": {
        "startNodeId": "greeting",
        "nodes": [
          {
            "id": "greeting",
            "kind": "conversation",
            "name": "Greeting",
            "prompt": "Greet the caller and find out what they need.",
            "position": { "x": 120, "y": 80 },
            "toolCount": 0,
            "precallLookupCount": 0
          },
          {
            "id": "book",
            "kind": "conversation",
            "name": "Book appointment",
            "prompt": "Collect the preferred slot and confirm it back.",
            "position": { "x": 420, "y": 80 },
            "knowledgeBaseIds": ["1f4b7a02-6c19-4e83-9a55-cc0f2d7e1b34"],
            "toolCount": 2,
            "precallLookupCount": 1
          }
        ],
        "edges": [
          {
            "id": "e1",
            "source": "greeting",
            "target": "book",
            "label": "wants an appointment",
            "priority": 0,
            "condition": { "kind": "ai", "describe": "the caller wants to book an appointment" }
          }
        ]
      },
      "analysis": {
        "enabled": false,
        "customFields": [],
        "qaCriteria": [],
        "minDurationSec": 20,
        "minCustomerTurns": 2,
        "language": "en",
        "sections": { "summary": true, "sentiment": true, "disposition": true, "actionItems": true, "objections": true, "evidence": true, "topics": true, "judge": true },
        "basePrompt": "You are writing the notes the owner of this AI agent reads after each call. The owner is the business or person the agent answers for. …"
      },
      "objectives": { "enabled": false, "askCap": 2, "slots": [], "actions": [], "dispositions": [], "fallbackDisposition": null },
      "tools": [
        { "name": "book_slot", "description": "Book a clinic appointment slot", "kind": "custom" },
        { "name": "check_availability", "description": "List free slots for a date", "kind": "custom" }
      ],
      "realtimeEngine": null
    }
  }
}

409 (stale read):
{ "success": false, "error": "agent changed since you read it (now 2026-07-29T09:31:07.220114+00:00) — re-read the config and re-apply" }
400 (bad precondition FORMAT, deliberately distinct from the conflict):
{ "success": false, "error": "`ifUnmodifiedSince` must be an RFC-3339 timestamp (echo the `updatedAt` you read); got `last tuesday`" }
403 (missing group scope, names the exact scope):
{ "success": false, "error": "app did not declare the agents:config:write:voice scope" }
403 (never-writable): { "success": false, "error": "`tools` cannot be changed by an app — an app may rewrite what an agent says, never what it can do" }
400 (typo, names the offender): { "success": false, "error": "unknown config group `prompts` — expected one of: prompt, model, voice, stt, behavior, flow, telephony, analysis, objectives" }
400 (no-op patch): { "success": false, "error": "this patch changes nothing — send at least one setting inside a group" }
400 (graph regression): { "success": false, "error": "this change would make the flow graph invalid: … It would be discarded at call time and the agent would silently run single-context." }

{
  "success": true,
  "data": {
    "agentId": "7c1f0b8e-3a24-4d51-9f6e-2b8c0d1a4e77",
    "kind": "single"
  }
}

413 when the per-app cap (100 agents) is hit:
{ "success": false, "error": "this app has reached its agent limit (100) for this org" }

{
  "success": true,
  "data": {
    "results": [
      {
        "name": "reschedule request",
        "passed": true,
        "score": 88,
        "reasoning": "Agent confirmed the existing slot and offered two alternatives.",
        "turns": 4,
        "errored": false
      },
      {
        "name": "scenario 2",
        "passed": false,
        "reasoning": "simulation failed: no LLM provider configured",
        "turns": 0,
        "errored": true
      }
    ],
    "passed": 1,
    "total": 2,
    "allPassed": false
  }
}

400 on timeout: { "success": false, "error": "eval timed out — try fewer scenarios or turns" }
400 when sim is off: { "success": false, "error": "agent simulation is not configured on this platform" }
403: { "success": false, "error": "app is not bound to this agent" }