openapi: 3.1.0 info: title: Dialer Digital core API (v1) version: 0.151.0 summary: Compliance-first outbound dialer control plane — the authenticated /v1 surface. description: > Formal reference of the `/v1` control-plane API served by `Dialer.API.Router` (Bandit, port 4000). Source of truth: `lib/dialer/api/v1_router.ex` (tenant surface), `lib/dialer/api/admin_router.ex` (platform-admin surface), `lib/dialer/api/auth_router.ex` (dashboard login and password recovery — the only unauthenticated `/v1` surface) and `lib/dialer/api/sms_webhook_router.ex` (public SMS webhooks, described under `webhooks`). CI enforces `tools/check_openapi_drift.py`: every route in the routers must appear here (method + path) and vice versa, and `info.version` must equal the `@version` in `mix.exs`. ## Conventions - JSON in / JSON out. Request bodies above 8 MiB are rejected. - Errors always use the envelope `{"error": {"code": "...", "message": "..."}}`. Branch on `code` (machine-readable), never on `message`. - Every response carries `X-Request-ID` (yours is propagated when sane). - Timestamps are RFC 3339 / ISO-8601 (UTC). Times of day are `HH:MM:SS`. - Decimal fields (pacing ratios, thresholds) are rendered as JSON strings. ## Multi-tenancy and 404 semantics Every route runs with the tenant resolved from the bearer key; all data access flows through Postgres row-level security (RLS). The API never accepts a tenant id from path, query or body. Cross-tenant ids read as `404 not_found` because RLS returns zero rows — existence is never leaked (no 403 for foreign ids), and malformed (non-UUID) ids are the same `404`. ## Rate limits (per API key, per person) Every `dd_` API key has its own request quota on `/v1`: two keys of the same tenant never share a budget. It is a sliding allowance (GCRA), per node, with a burst of one minute's worth. The default is generous and a per-tenant operator setting (`api_key_requests_per_minute`) adjusts it. The console (`ddu_`) and agent (`ddw_`) lanes are counted too, with the same algorithm and their own setting (`session_requests_per_minute`): the bucket belongs to the person (the agent, else the user), not to the session, so logging in again does not buy a fresh budget, and another person of the same tenant is unaffected. Every response to a counted request carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; over the quota the answer is `429 rate_limited` with `Retry-After` and the request is not processed. Exempt: `POST /v1/calls/{call_id}/hangup`, webhooks and health routes. A request refused by the quota is not counted again, so waiting `Retry-After` seconds is always enough. ## Canonical errors - `401 unauthorized` — missing/unknown/revoked API key. `403 forbidden` — suspended tenant. - `404 not_found` — unknown, malformed or cross-tenant id (RLS; see above). - `422 compliance_blocked` — the compliance engine refused the operation; the body carries `gate` (which gate refused) and `decision_id` (citable against the audit chain). Do NOT retry unchanged — the block is evidence, not an error. - `429 rate_limited` — the per-API-key request quota (below), or one of the fixed-window request brakes (login, second factor, widget tokens, call control, dispositions, invitations). These carry `Retry-After`: whole seconds until a retry can succeed. The quota also carries `X-RateLimit-*`. - `429 sms_spend_cap_exceeded` — month-to-date SMS budget brake; retryable only after a cap raise or the month rollover. `429 throttled` — rate brake; retry later with backoff. Neither carries `Retry-After`: the engine does not know when capacity returns, and a made-up number is worse than none. - `502 provider_error` / `502 dial_error` / `502 sbc_error` — an upstream (SMS provider, switch, SIP edge) rejected the operation. Out of scope here (documented in `API.md`): `GET /healthz` (no auth), `GET /v1/ws` websocket live floor (upgrades before this pipeline; auth via an ephemeral one-shot `?ticket=` minted by `POST /v1/ws/ticket`, never a long-lived bearer), and `GET /metrics` (Prometheus, port 9568). contact: name: Dialer Digital license: name: Proprietary — Dialer Digital servers: - url: http://127.0.0.1:4000 description: Local development (compose stack; `API_PORT`, fallback `PORT`). - url: https://{host} description: Deployment-specific ingress in front of the core Service. variables: host: default: api.usa.dialerdigital.com security: - tenantApiKey: [] tags: - name: skip-trace description: "Skip tracing (F0): a measured vendor lookup behind a per-tenant monthly cap with a hard cut. No invoice line yet." - name: identity description: Authenticated tenant, account settings. - name: auth description: Dashboard login (email + password -> a revocable ddu_ session; sha256 at rest, plaintext shown once) and password recovery (a one-shot, expiring link — the request half never reveals whether an address has an account). - name: sso description: "SAML 2.0 single sign-on per tenant: the tenant's identity-provider configuration (loaded by an `account_admin`, audited append-only) and the service-provider metadata its IdP admin needs. SP-initiated only; a person must already exist in the tenant (no just-in-time provisioning)." - name: support-access description: "Platform-support access (ADR 225): the customer's consent (a grant with a reason and a fixed expiry, one live per tenant, revoked at will) and the append-only trail of it. `account_admin` only, except the banner." - name: users description: Dashboard user accounts (email + password; disabled, never deleted). - name: api-keys description: Per-tenant API keys (sha256 at rest; plaintext shown once). - name: widgets description: Embeddable agent-widget lifecycle — ddw_ browser tokens + the origin allowlist. - name: click-to-call description: "Click-to-call for the customer's website (ADR 220): the console mints/revokes a PUBLISHABLE `ddc_` site key, and the visitor's browser uses it to read the form's config and to leave a call request. Gated by `click_to_call_enabled`." - name: campaigns description: Campaign CRUD, lifecycle, manual dial, rewind. - name: debts description: Bulk lead import, debt detail, per-debt CDR, defense packet. - name: consumers description: "Debtor card by `consumer_ref`: debts, DNC / cease-and-desist, Reg F counter and next permitted window, derived from the append-only sources." - name: debt-lists description: "Reusable lists of debts, associated with campaigns (ADR #162)." - name: import-mappings description: CSV import templates (column -> field mapping and parse options), versioned append-only per tenant. - name: qm description: "Quality-management scoring forms (ADR #217), versioned append-only per tenant. Writes need the `qm_enabled` flag." - name: insights description: "Anomaly evidence of the insights evaluator (core#1983): contact, abandon, cost, gate-block and media-timeout series, each anomaly with its series and threshold. Always on; `insights_anomaly_k` only tunes the sensitivity." - name: product-analytics description: "Product analytics and NPS inside the console, our own and with no third party (macro-tasks#876): usage events as keys of a closed catalog, and the NPS question for account administrators. Always on; it never carries a consumer's data." - name: disclosure-scripts description: "Collection-notice script library (ADR #219): immutable versions per tenant, approved by a sealed event." - name: segment-filters description: "Saved segmentation filters (the criteria of `GET /v1/debts` with a name), versioned append-only per tenant. Behind the `debt_segmentation_enabled` flag (ADR #221)." - name: call-attempts description: Append-only CDR query + typed dispositions. - name: callbacks description: Consumer-agreed redial appointments. - name: disposition-rules description: "The tenant's retry policy by call outcome (R10): reschedule or suppress a debt after a given disposition. It can only postpone or close a debt; every dial still runs the compliance gates at originate time." - name: dispositions description: "The `dialer.v1.Disposition` contract set in REST spelling: the lowercase value, its enum name and number." - name: promises description: Promise-to-pay pipeline. - name: agents description: Seat roster, presence, softphone checkin/checkout. - name: wfm description: "Workforce management: the per-interval coverage of a day (forecast from the CDR, agents required by Erlang C against the tenant's service target, agents planned in R11 shifts). A derived read; nothing is persisted." - name: academy description: In-app Academy training records — the auditable constancia (who completed what and when), append-only and per agent. - name: supervision description: Supervisor audio (listen/whisper/barge/takeover), evidence-first. - name: calls description: Live-call control verbs (hold/unhold/mute/unmute/hangup), evidence-first. - name: transfer-destinations description: The tenant's registry of the external numbers a live call may be transferred to. - name: rewind-segments description: Named sets of rewind filters a supervisor saves per tenant and re-uses (the filters, never a list of accounts). - name: stats description: Operational counters, blocked-dial rollups, usage metering. - name: billing description: Invoiceable line items. - name: reports description: Packaged compliance artifacts. - name: compliance description: "Suppression data the tenant owns (its internal do-not-call list, uploaded as CSV into the same list the pre-dial gate reads) and the audit-chain citation: resolving a `decision_id` into its sealed link plus the integrity verdict over it." - name: dids description: DID registry, CDR-computed health, launch checklist and carrier tickets. - name: support description: Support tickets with a number and a first-response target by plan level. - name: carriers description: SIP trunk registry (BYOC/house) + SBC provisioning. - name: sms description: Gated one-off SMS send + unified ledger. - name: sms-providers description: Per-tenant/region SMS routing registry. - name: messaging description: 10DLC brand and campaign registration through the SMS provider, and the numbers of an approved campaign. Provider fees land on the balance at cost. - name: email description: Debtor email addresses with provenance, the suppression ledger (read) and the email ledger (read). - name: email-providers description: Per-tenant/region email provider registry (SMTP / log). - name: email-templates description: Per-tenant e-mail templates (static subject + body with typed variables), append-only versions, account_admin approval and retirement. - name: sms-templates description: Per-tenant SMS templates with typed variables, approval and the "templates only" setting. - name: webhooks description: "Outbound webhooks for CRMs: the tenant's endpoint registry, its subscribed events and the signing secret (shown once; rotation with a window)." - name: inbound-routes description: Inbound DID routing + SBC provisioning. - name: inbound-ivr-menus description: "The tenant's inbound IVR menus: published versions, append-only history, rendered to audio when published. An inbound route with `dest_type: ivr` runs one of them." - name: inbound-queues description: "The tenant's inbound queues: created with a name, an optional overflow to another of its queues, retired when nothing uses them. A route with `dest_type: queue` names one in `queue_id`; an inbound IVR menu names one as `queue:`." - name: recordings description: "Call-recording evidence: retention-locked metadata, signed playback, legal hold, bulk export, per-tenant policy." - name: voice-ai description: "AI voice agents: builder + versioned policy, live conversations, transcripts/outcomes, supervisor takeover, the per-tenant AI-dialing kill-switch and today's metrics." paths: /v1/me: get: operationId: getMe tags: - identity summary: Authenticated tenant, user and derived SEAT description: | Returns the tenant resolved from the bearer. When the bearer is a `ddu_` login session (email+password dashboard auth), the response also carries the `user` behind the console; for a `dd_` machine key the tenant-only shape is unchanged. Also answers "which seat am I?" (`seat` + `seat_source`, core#1059, ADR #137). A client MUST NOT let the operator PICK a seat: since core#1034 (ADR #131) `POST /v1/agents/checkin` DERIVES the seat from the bearer and answers `403 seat_mismatch` to any `sip_extension` in the body that does not match it. The seat here is derived by the same single derivation point the check-in and `GET /v1/me/scorecard` (ADR #132) use, so the two answers cannot disagree. `seat_source` is ALWAYS present — a client never has to interpret a missing field: * `token` — `seat` is the caller's own agent row, in the same projection `GET /v1/agents/{id}` returns. * `no_identity` — a `dd_` machine key: no person behind it, so there is no "own" seat. `seat` is `null`; the body is NOT consulted. * `seat_not_linked` — a `ddu_` person with no active seat (e.g. a supervisor with no dialing position). `seat` is `null`. * `seat_gone` — the bearer points at a deleted agent row. Reachable only by the `ddw_` lane, which this route denies before the handler (not on the widget allowlist); listed for completeness. All four are **200**. A person without a seat is a legitimate state and this route doubles as the SPA's bearer validator, so answering `403` there would break their login — that is the deliberate difference from `GET /v1/me/scorecard`, which IS `403` without a seat because there is no marker to show. A `dds_` support session (ADR #225) answers `seat: null`, `seat_source: no_identity` and a `support` block (`read_only` is always `true`, with the session's `expires_at` and the operator behind it) so a console can show that the session is read-only and when it ends. A `ddu_` login session answers a `session` block (core#2828) with the fixed `expires_at` of that session, so a console reloaded with only its cookie can still warn before the session ends. security: - tenantApiKey: [] - userSessionToken: [] - supportSessionToken: [] responses: "200": description: The authenticated tenant, the user (ddu_) and the derived seat. headers: X-Dialer-Support-Session: description: Present, `read-only`, on every response to a `dds_` support session. schema: type: string enum: - read-only content: application/json: schema: type: object required: - tenant - seat - seat_source - capabilities - screen_monitor properties: tenant: $ref: "#/components/schemas/Tenant" user: $ref: "#/components/schemas/User" support: type: object additionalProperties: false required: - read_only - session_id - expires_at - operator description: "Only for a `dds_` support session (ADR #225): the session is read-only and ends at `expires_at`." properties: read_only: type: boolean enum: - true session_id: type: string format: uuid expires_at: type: string format: date-time operator: type: string description: The platform operator who opened it, `operator: ()`. session: type: object additionalProperties: false required: - expires_at description: 'Only for a `ddu_` login session (core#2828): when it ends. `expires_at` is the FIXED absolute expiry set at login (it never moves, no renewal extends it) and is the same instant the login, MFA and SSO answers give as `session.expires_at`. It lets a console that reloaded with only its `HttpOnly` cookie know the end of the session. Absent for a `dd_` machine key and for a `dds_` support session (the latter has `support.expires_at`); a client MUST read a missing key as "unknown", never as "does not expire".' properties: expires_at: type: string format: date-time seat: oneOf: - $ref: "#/components/schemas/Agent" - type: "null" description: The caller's own seat, or `null` when `seat_source` is not `token`. seat_source: type: string enum: - token - no_identity - seat_not_linked - seat_gone description: How the seat was resolved (or why there is none). Always present. capabilities: type: object additionalProperties: false required: - conference description: Per-tenant UI capabilities (core#1806), a closed list. A capability that cannot be resolved reads `false`. properties: conference: type: boolean description: "`true` when the internal conference routes (`POST /v1/calls/{call_id}/conference/add|remove`) are enabled for this tenant; `false` means they answer 404." recording_pause: type: boolean description: "`true` when the tenant's `recording_pause_enabled` flag is on (core#2748): the call-recording pause and resume routes may act; `false` means they answer 404. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." email_channel: type: boolean description: "`true` when the tenant's `email_channel_enabled` flag is on (core#1925): the email sender and the `email_blast` runner may act. `false` (the default) means the channel is off: it writes no ledger row and calls no provider. It is NOT \"ready to send\": an active provider, the budget, the address provenance and every gate still apply, and core answers their typed errors. It is absent from a core that predates it, so a client MUST read a missing key as \"not published yet\" and never as `false`." click_to_call: type: boolean description: "`true` when the public click-to-call lane is ON for this tenant (core#2705): the cell ceiling is open AND the tenant's `click_to_call_enabled` override is `true`. `false` (the default) means the public routes answer 404 and write nothing, so a snippet published now would do nothing. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." widget_auth: type: boolean description: "`true` when the `ddw_` widget agent lane is ON for this tenant (core#2705): the cell ceiling is open AND the tenant's `widget_auth_enabled` override is `true`. `false` (the default) means widget agent logins and requests are refused. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." debt_segmentation: type: boolean description: "`true` when the tenant's `debt_segmentation_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." qm: type: boolean description: "`true` when the tenant's `qm_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." report_builder: type: boolean description: "`true` when the tenant's `report_builder_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." screen_monitor: type: boolean description: "`true` when the tenant's `screen_monitor_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." billing_cost: type: boolean description: "`true` when the tenant's `billing_cost_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." billing_ledger: type: boolean description: "`true` when the tenant's `billing_ledger_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." inbound_queue_stream: type: boolean description: "`true` when the tenant's `inbound_queue_stream_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." inbound_ai: type: boolean description: "`true` when the tenant's `inbound_ai_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." sms_auto_reply: type: boolean description: "`true` when the tenant's `sms_auto_reply_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." agent_session_journal: type: boolean description: "`true` when the tenant's `agent_session_journal_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." live_floor_seat_lane: type: boolean description: "`true` when the tenant's `live_floor_seat_lane` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." conference_external: type: boolean description: "`true` when the tenant's `conference_external_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." support_access: type: boolean description: "`true` when the tenant's `support_access_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." inbound_callback_offer: type: boolean description: "`true` when the tenant's `inbound_callback_offer_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." inbound_queue_skill_routing: type: boolean description: "`true` when the tenant's `inbound_queue_skill_routing_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." ai_take_payments: type: boolean description: "`true` when the tenant's `ai_take_payments_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." privacy_subject_export: type: boolean description: "`true` when the tenant's `privacy_subject_export_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." privacy_erasure: type: boolean description: "`true` when the tenant's `privacy_erasure_enabled` flag resolves on (core#2941), cell ceiling included when the key has one. `false` means the surface it governs is off for this tenant. Absent from a core that predates it: read a missing key as \"not published yet\", never as `false`." screen_monitor: $ref: "#/components/schemas/ScreenMonitorStatus" example: tenant: id: 0d4f4f9e-1f2a-4b53-9d3c-8a5e2f7b1c10 name: Acme Collections status: active synthetic: false retention_months: 84 seats: 10 tier: scale voice_ai_enabled: true ai_monthly_budget_usd: 500 ai_max_call_seconds: 600 ai_max_call_seconds_effective: 600 sms_monthly_budget_usd: 250 created_at: 2026-06-01T12:00:00Z updated_at: 2026-06-20T09:30:00Z seat: null seat_source: no_identity capabilities: conference: false recording_pause: false email_channel: false click_to_call: false widget_auth: false debt_segmentation: false qm: false report_builder: true screen_monitor: false billing_cost: false billing_ledger: false inbound_queue_stream: false inbound_ai: false sms_auto_reply: false agent_session_journal: false live_floor_seat_lane: false conference_external: false support_access: false inbound_callback_offer: false inbound_queue_skill_routing: false ai_take_payments: false privacy_subject_export: false privacy_erasure: false screen_monitor: enabled: false notice_ack_required: false notice_version: null scopes: live_monitoring: ack_current: false acked_at: null screen_recording: ack_current: false acked_at: null "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "429": $ref: "#/components/responses/ApiKeyRateLimited" /v1/me/scorecard: get: operationId: getMeScorecard tags: - identity summary: The caller's OWN shift scorecard (seat derived from the token) description: | The collector's personal marker: their calls in the window and the promises they took, for the seat the BEARER identifies. No parameter may name an agent — `agent_id` is refused by name with `400`, never ignored, so a client can never believe it read a colleague's numbers. Who gets a seat: a `ddu_` dashboard login, through the `users_agents.user_id` link (`403 seat_not_linked` when the person has no active seat). A `dd_` machine key has no person behind it and is `403`. A `ddw_` widget token is `403` before the handler — this route is not on the widget allowlist. Window: half-open `[from, to)`. Both are optional and `to` defaults to now. `from` defaults to the seat's ACTIVE check-in (`window.source: checkin`); when the seat has no active check-in — the normal state right after checkout, since `checked_in_at` is presence, not history — it defaults to `now - 12h` (`window.source: fallback_12h`). Twelve hours cover a whole collection shift without dragging in yesterday's. A client MUST surface `source`: a figure from an estimated window is shown as such, never as "the shift". `calls` counts ATTEMPTS, not CDR rows (the original plus its corrections are one call), and carries no ratios or minutes — derived occupancy is `GET /v1/agents/occupancy`, and two computations of the same thing is exactly what is avoided here. Deliberately absent: the promise `note` (free text, encrypted at rest under GLBA), phone numbers, and commission. security: - userSessionToken: [] parameters: - name: from in: query required: false schema: type: string format: date-time description: | Inclusive start (RFC 3339). Defaults to the seat's active `checked_in_at`, or to `now - 12h` when there is none — see `window.source`. - name: to in: query required: false schema: type: string format: date-time description: | Exclusive end (RFC 3339); must be after `from`. Defaults to now. responses: "200": description: The caller's own scorecard for the resolved window. content: application/json: schema: $ref: "#/components/schemas/MeScorecard" "400": description: | Malformed window, or an `agent_id` parameter — refused by name because this scorecard is always the caller's own seat. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: bad_request message: "agent_id not accepted here: this scorecard is always the caller's own seat, derived from the token — use /v1/agents/occupancy or /v1/calls for another seat" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /v1/me/evaluations: get: operationId: listMeEvaluations tags: - qm summary: The caller's OWN QM evaluations, newest first description: > The evaluations of the seat the BEARER identifies, corrections included, capped at 200. No parameter may name an agent: `agent_id`, `seat_id`, `user_id` and `sip_extension` are refused by name with `400`, never ignored, so a client can never believe it read a colleague's evaluations. The check comes AFTER the `403`, so a caller with no seat learns nothing about which parameters are read. Who gets a seat: a `ddu_` dashboard login linked to an active seat (`403 seat_not_linked` otherwise). A `dd_` machine key has no person behind it and is `403`. A `ddw_` widget token is `403` before the handler: this route is not on the widget allowlist. Each row carries the criteria answers, the score, the form version, the `comment` written for the agent, whether it is the `current` one, the state of the dispute (`dispute`, null when there is none) and `dispute_until`, the end of the `qm_dispute_window_days` window while the dispute can still be opened (null otherwise: replaced evaluation, dispute already open or resolved, fruit of a resolved dispute, window closed). The row does NOT say who evaluated, and it never carries the agent's own id. Reads work whether or not `qm_enabled` is on. security: - userSessionToken: [] responses: "200": description: The caller's evaluations. content: application/json: schema: type: object required: - evaluations properties: evaluations: type: array items: $ref: "#/components/schemas/QmAgentEvaluation" "400": description: | A parameter that names an agent (`agent_id`, `seat_id`, `user_id`, `sip_extension`), refused by name. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: bad_request message: "agent_id not accepted here: these evaluations are always the caller's own, derived from the token" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /v1/me/evaluations/{id}: get: operationId: getMeEvaluation tags: - qm summary: One of the caller's OWN QM evaluations, with its criteria and dispute thread description: > Same identity contract as `GET /v1/me/evaluations`: the seat comes from the token and the parameters that name an agent are `400`. Adds the `criteria` and `pass_threshold` of the form version the evaluation was scored against, and the `dispute_events` thread (kind, reason, note, time; no actor ids). An evaluation of another agent, of another tenant or that does not exist is the same `404`. security: - userSessionToken: [] parameters: - $ref: "#/components/parameters/PathId" responses: "200": description: The evaluation. content: application/json: schema: type: object required: - evaluation properties: evaluation: $ref: "#/components/schemas/QmAgentEvaluationDetail" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/me/evaluations/{id}/dispute: post: operationId: openMeEvaluationDispute tags: - qm summary: Open the dispute of one of the caller's OWN QM evaluations description: > The evaluated agent contests the evaluation: ONE dispute per evaluation, opened inside the `qm_dispute_window_days` window (1 to 90 days, 7 by default) counted from when the evaluation was written. Only the `ddu_` login of the agent the evaluation is about can open it, with an ACTIVE seat. A `dd_` key is a service, not a person: `403 role_forbidden`. A `ddw_` widget token is `403` before the handler: this route is not on the widget allowlist. The checks run in this order and the first one that fails writes nothing: tenant scope, `qm_enabled` (`403 qm_not_enabled`: reads continue with the flag off, writes do not), the person (`403 role_forbidden`), `404` if the id is not a UUID, `400` (the body: `reason` is one of `wrong_call`, `criterion_misjudged`, `other`, `note` is optional text, unknown fields are refused), `404` (the evaluation is not the caller's own, belongs to another tenant or does not exist: one answer for all three), then `409` when the evaluation was replaced by a newer one (dispute the current), already has its dispute or is itself the result of a resolved dispute (a resolved dispute is not reopened), or the window has closed. Answers with the evaluation as `GET /v1/me/evaluations/{id}` shows it, now with its `dispute` and the `opened` event in `dispute_events`. While the dispute is open the evaluation keeps counting: nothing hides or excludes it. security: - userSessionToken: [] parameters: - $ref: "#/components/parameters/PathId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/QmDisputeOpen" example: reason: criterion_misjudged note: Dije el aviso de grabacion en el minuto 1:10 y el criterio lo marca como omitido. responses: "201": description: The evaluation with its dispute open. content: application/json: schema: type: object required: - evaluation properties: evaluation: $ref: "#/components/schemas/QmAgentEvaluationDetail" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": description: > `code` `qm_not_enabled`: the tenant's `qm_enabled` flag is off. `code` `role_forbidden`: the caller is a `dd_` key or a login with no active agent seat. `code` `forbidden`: the tenant is suspended or the token is a widget token. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: qm_not_enabled message: QM is not enabled for this tenant "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" /v1/screen-monitor/notice: get: operationId: getScreenMonitorNotice tags: - identity summary: The current screen-monitoring notice description: | The CURRENT version of the notice a seat must acknowledge before its screen may be observed (core#1989, FASE 0 of dashboard#696). The notice is a global catalogue (no tenant) and append-only: publishing a newer `version` invalidates, without touching them, every acknowledgement of the older ones. `404 not_found` when the tenant's founder-governed flag `screen_monitor_enabled` is off, and also when no version has been published yet. Reachable by a `dd_` key and by a `ddu_` login; a `ddw_` widget token is `403` before the handler. security: - tenantApiKey: [] - userSessionToken: [] responses: "200": description: The current notice. content: application/json: schema: type: object required: - notice properties: notice: $ref: "#/components/schemas/ScreenMonitorNotice" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/screen-monitor/acks: post: operationId: acknowledgeScreenMonitorNotice tags: - identity summary: Acknowledge the current screen-monitoring notice from one's OWN seat description: > Records that the caller's OWN seat accepts `notice_version`, which must be the CURRENT version, FOR ONE `scope`: `live_monitoring` or `screen_recording`. The scopes are acknowledged separately: accepting live monitoring does not authorize recording, and a new notice version invalidates both. Idempotent: a second acknowledgement of the same version and scope returns the first (`200`, no new row). The ledger is append-only (DELETE revoked and a trigger refuses UPDATE/DELETE). The seat is derived from the bearer, never from the body. Only a `ddu_` login with a linked seat may acknowledge: a `dd_` machine key has no person behind it (`403 forbidden`), a `ddu_` with no active seat is `403 seat_not_linked`, and an `agent_id` in the body that is not the caller's own seat is `403 forbidden` — a third party never acknowledges on someone else's behalf. A `ddw_` widget token is `403` before the handler. `404 not_found` while the tenant's flag `screen_monitor_enabled` is off. With the flag on, `409 no_notice_published` when no version exists and `409 stale_notice` when `notice_version` is not the current one. security: - userSessionToken: [] requestBody: required: true content: application/json: schema: type: object required: - notice_version - scope additionalProperties: false properties: notice_version: type: integer minimum: 1 description: The version being accepted; it must be the current one. scope: type: string enum: - live_monitoring - screen_recording description: What the seat accepts with this acknowledgement. agent_id: type: string format: uuid description: Optional. If present it must be the caller's own seat; anything else is `403`. responses: "200": description: The acknowledgement (the existing one when repeated). content: application/json: schema: type: object required: - ack properties: ack: $ref: "#/components/schemas/ScreenMonitorAck" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": description: > `no_notice_published`: no notice version exists yet, so nobody can acknowledge. `stale_notice`: `notice_version` is not the current one. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: stale_notice message: that notice version is not the current one get: operationId: listScreenMonitorAcks tags: - identity summary: Acknowledgements of the tenant (supervisor/admin seat) description: | The tenant's acknowledgements, newest first, paginated by cursor. Allowed only to a seat whose template role is `supervisor` or `admin` (`403 role_forbidden` otherwise; a `dd_` key and a `ddu_` with no seat are `403`). The role is evaluated always; it does not depend on `supervision_role_enforced`. It does NOT consult `screen_monitor_enabled`: it is the record of what was accepted, and turning the function off neither deletes nor hides it. Nothing crosses tenants. security: - userSessionToken: [] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 description: Page size (a value over the ceiling is capped, not refused). - name: cursor in: query required: false schema: type: string description: Opaque keyset cursor — the `next_cursor` of the previous page. - name: agent_id in: query required: false schema: type: string format: uuid description: Only the acknowledgements of this seat. responses: "200": description: One page of acknowledgements, newest first. content: application/json: schema: type: object required: - acks - next_cursor properties: acks: type: array items: $ref: "#/components/schemas/ScreenMonitorAck" next_cursor: oneOf: - type: string - type: "null" description: Cursor of the next page; `null` on the last one. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" /v1/agent-monitoring-notice: get: operationId: getAgentMonitoringNotice tags: - identity summary: The current recording-and-supervision notice an agent accepts description: > The texts (one per language) of the CURRENT version of the notice an agent accepts at check-in (core#2323, MT-CLI-37; ADR #289). Where both parties must consent, the acceptance by agent and date is the proof the law asks for. The notice is a global catalogue (no tenant) and append-only: publishing a newer `version` invalidates, without touching them, every acceptance of the older ones. Core publishes NO legal text of its own: the catalogue is born empty and is filled by whoever migrates, with the reference of the text's approval. `404 not_found` while no version is in force. Reachable by a `dd_` key and by a `ddu_` login; a `ddw_` widget token is `403` before the handler. security: - tenantApiKey: [] - userSessionToken: [] responses: "200": description: The current version and its texts. content: application/json: schema: type: object required: - notice properties: notice: $ref: "#/components/schemas/AgentMonitoringNotice" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/agent-monitoring-acknowledgements: post: operationId: acknowledgeAgentMonitoringNotice tags: - identity summary: Accept the current recording-and-supervision notice from one's OWN seat description: > Records that the caller's OWN seat accepts `notice_version`, which must be the CURRENT version, as read in `lang` (a language the current version has a text in). The row keeps the version, the language, the hash of the text the agent saw, the date and the origin (`channel`). Idempotent: a second acceptance of the same version returns the first (`200`, no new row), even in another language. The ledger is append-only: it can neither be edited nor deleted (DELETE revoked and a trigger refuses UPDATE/DELETE); a newer notice version leaves the old acceptance on file and simply stops covering the agent. The seat is derived from the bearer, never from the body. Only a `ddu_` login with a linked seat may accept: a `dd_` machine key has no person behind it (`403 forbidden`), a `ddu_` with no active seat is `403 seat_not_linked`, and an `agent_id` in the body that is not the caller's own seat is `403 forbidden`. A `ddw_` widget token is `403` before the handler. `409 no_notice_published` when no version is in force and `409 stale_notice` when `notice_version` is not the current one; `422` when the current version has no text in `lang`. security: - userSessionToken: [] requestBody: required: true content: application/json: schema: type: object required: - notice_version - lang additionalProperties: false properties: notice_version: type: integer minimum: 1 description: The version being accepted; it must be the current one. lang: type: string description: The language of the text the agent was shown, e.g. `es` or `en`. agent_id: type: string format: uuid description: Optional. If present it must be the caller's own seat; anything else is `403`. responses: "200": description: The acceptance (the existing one when repeated). content: application/json: schema: type: object required: - acknowledgement properties: acknowledgement: $ref: "#/components/schemas/AgentMonitoringAck" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": description: > `no_notice_published`: no notice version is in force, so nobody can accept. `stale_notice`: `notice_version` is not the current one. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: stale_notice message: that notice version is not the current one "422": $ref: "#/components/responses/Unprocessable" /v1/agents/{id}/monitoring-acknowledgement: get: operationId: getAgentMonitoringAcknowledgement tags: - agents summary: The latest recording-and-supervision acceptance of one agent description: > The current notice version, whether THIS agent has accepted it (`current`) and the agent's latest acceptance of any version (`null` if none). A seat reads its own; a seat whose template role is `supervisor` or `admin` and a `dd_` tenant key read any agent of the tenant; another seat reading a colleague's is `403 forbidden`. An id from another tenant is `404`. A `ddw_` widget token is `403` before the handler. security: - tenantApiKey: [] - userSessionToken: [] parameters: - $ref: "#/components/parameters/PathId" responses: "200": description: The agent's monitoring-notice state. content: application/json: schema: type: object required: - monitoring properties: monitoring: $ref: "#/components/schemas/AgentMonitoringStatus" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/screen-recordings/{id}/chunks/{n}: put: operationId: putScreenRecordingChunk tags: - recordings summary: Upload one chunk of the OWN seat's screen recording description: > Stores chunk `n` (from 0) of the screen recording `id` of one call. The browser's `MediaRecorder` sends the chunks as they are produced; `id` is a UUID the client chooses for the whole recording, so a retry is idempotent. Everything that identifies the recording comes from core, not from the client: the seat from the bearer, the call from `call_uuid` (which must be a call of THIS seat) and the retention from the voice recording of the same call (`retained_until`). The start and end instants are those of the call and are not stored again. The chunk is sealed with the tenant's key (AES-256-GCM) before it reaches the store, bound to `id` and `n`: the object cannot be opened elsewhere. Gates, in order: only a `ddu_` login with a linked seat (`403` for a `dd_` key, a `ddu_` with no seat, and a `ddw_` token); `404 not_found` while the tenant's flag `screen_monitor_enabled` is off; `404 not_found` for a `call_uuid` that is unknown or is another agent's call (the same answer, and an audit row records which); `403 screen_recording_not_acknowledged` when the seat has no current `screen_recording` acknowledgement (nothing is stored and a `not_armed` gap is recorded). Repeating a chunk with the same bytes answers `200 duplicate`; other bytes under the same `n` are `409 chunk_conflict`; a second recording id for the same call is `409 recording_conflict`. A chunk the store did not take is `503` and records an `upload_failed` gap. Limits: 4 000 000 bytes per chunk, `n` from 0 to 1 000 000. security: - userSessionToken: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: Recording id, chosen by the client, one per call. - name: n in: path required: true schema: type: integer minimum: 0 maximum: 1000000 description: Chunk number, from 0. - name: call_uuid in: query required: true schema: type: string minLength: 1 maxLength: 128 description: The call being recorded; it must be the caller's own. requestBody: required: true content: video/webm: schema: type: string format: binary video/mp4: schema: type: string format: binary responses: "200": description: The chunk was already stored with the same bytes. content: application/json: schema: $ref: "#/components/schemas/ScreenRecordingChunkAck" "201": description: The chunk was sealed and stored. content: application/json: schema: $ref: "#/components/schemas/ScreenRecordingChunkAck" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": description: > `chunk_conflict`: that `n` already holds other bytes. `recording_conflict`: the call already has a recording under another id, or `id` belongs to another call. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: chunk_conflict message: that chunk number already holds other bytes "410": description: The screen recording was purged at the end of its retention. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" "413": description: The chunk is larger than 4 000 000 bytes. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" "415": description: The body is not `video/webm` or `video/mp4`. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" "503": description: The store did not take the chunk; retry it. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" /v1/screen-recordings/gaps: post: operationId: reportScreenRecordingGap tags: - recordings summary: Declare that a call's screen is missing, and why description: > The agent's client reports a gap it knows about: `agent_stopped` (the agent ended the capture), `upload_failed` (the chunks did not arrive) or `not_armed` (the capture was never started). Core writes its own `not_armed` gap when a chunk arrives without a current acknowledgement. Idempotent: one row per call, reason and source. The ledger is append-only. The same seat and call rules as the chunk upload apply (`404 not_found` for a call that is not the caller's; `404` while `screen_monitor_enabled` is off). No acknowledgement is needed: a gap is evidence, not content. security: - userSessionToken: [] requestBody: required: true content: application/json: schema: type: object required: - call_uuid - reason additionalProperties: false properties: call_uuid: type: string minLength: 1 maxLength: 128 reason: type: string enum: - not_armed - agent_stopped - upload_failed note: type: string maxLength: 500 responses: "200": description: The gap is on file (the first one when repeated). content: application/json: schema: type: object required: - gap properties: gap: type: object required: - call_uuid - reason - source properties: call_uuid: type: string reason: type: string enum: - not_armed - agent_stopped - upload_failed source: type: string enum: - agent "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v1/screen-recordings/{id}/pii-marks: post: operationId: postScreenRecordingPiiMarks tags: - recordings summary: Declare which stretches of the OWN seat's screen recording showed PII description: > The agent's dashboard declares the intervals during which the screen showed a surface it paints as PII, and how far it has classified the video (`covered_through_ms`). Core keeps them append-only next to the recording; the redacted copy that supervisors watch by default is built from them (core#2017, ADR #266): every mark, widened by a guard on both sides, and everything after `covered_through_ms` is blacked out. A recording with no coverage row is blacked out entirely, so a client that never reports leaves a black copy, never a clear one. `zone` is a CLOSED catalogue: `consumer_card` (the consumer's record), `full_number` (the phone number unmasked), `payment` (card, bank account, SSN, PIN) and `focus_lost` (the dashboard has no focus or is not visible, so it does not know what the screen shows). A zone outside the catalogue is `422 invalid_zone`; it is never stored as free text. A mark carries instants only, never text or values. Instants are milliseconds from the start of the recording's video, `0 <= start_ms < end_ms <= 86 400 000`. One request takes at most 200 marks and one recording holds at most 1 000 (`422 too_many_marks`, `422 mark_limit_reached`; a refused request stores nothing). `marks` may be empty: a request with only `covered_through_ms` is a heartbeat. Idempotent: a mark already on file (same `start_ms`, `end_ms`, `zone`) is counted in `duplicates` and not stored twice. `covered_through_ms` only moves forward: a lower value than the one on file is ignored, not an error (it is a retry that arrived late), and the response says the value in force. Same gates as the chunk upload, in order: only a `ddu_` login with a linked seat (`403` for a `dd_` key, a `ddu_` with no seat, and a `ddw_` token); `404 not_found` while the tenant's flag `screen_monitor_enabled` is off; `404 not_found` for a recording that is unknown or belongs to another seat or tenant (one answer for all three; the recording exists once its first chunk landed, so a client that is ahead of its upload gets `404` and retries); `403 screen_recording_not_acknowledged` when the seat has no current `screen_recording` acknowledgement; `410` once the recording was purged. security: - userSessionToken: [] parameters: - name: id in: path required: true schema: type: string format: uuid description: The recording id the client chose for the chunk upload. requestBody: required: true content: application/json: schema: type: object required: - covered_through_ms additionalProperties: false properties: marks: type: array maxItems: 200 items: type: object required: - start_ms - end_ms - zone additionalProperties: false properties: start_ms: type: integer minimum: 0 maximum: 86400000 end_ms: type: integer minimum: 1 maximum: 86400000 zone: type: string enum: - consumer_card - full_number - payment - focus_lost covered_through_ms: type: integer minimum: 0 maximum: 86400000 responses: "200": description: The marks are on file and the coverage is in force. content: application/json: schema: type: object required: - pii_marks properties: pii_marks: type: object required: - recording_id - stored - duplicates - covered_through_ms properties: recording_id: type: string format: uuid stored: type: integer minimum: 0 description: Marks written by this request. duplicates: type: integer minimum: 0 description: Marks already on file. covered_through_ms: type: integer description: The value in force, the larger of the one on file and the one sent. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "410": description: The screen recording was purged at the end of its retention. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" "422": description: > `invalid_zone`: the zone is not in the catalogue. `invalid_interval`: a mark outside `0 <= start_ms < end_ms <= 86 400 000`. `too_many_marks`: more than 200 in one request. `mark_limit_reached`: the recording would hold more than 1 000. content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" example: error: code: invalid_zone message: "zone must be one of: consumer_card, full_number, payment, focus_lost" /v1/screen-recordings/playback: post: operationId: playScreenRecording tags: - recordings summary: Ask to watch the REDACTED screen recording of a call; returns a short-lived signed URL description: > Takes a supervisor or admin seat (`403 role_forbidden` otherwise; a `dd_` key has no seat, so `403 forbidden`). It does NOT consult `screen_monitor_enabled`: switching the function off does not hide what was already recorded. What is served is the REDACTED copy: the video with every stretch the dashboard marked as PII (and every stretch it never classified) blacked out (core#2124, ADR #266). It is served only once the copy is `ready`. While it is being built, or rebuilt after a newer mark arrived, the answer is `409 redaction_pending`; if it could not be built, `409 redaction_failed`. The original is NEVER served in its place: the unmasked video is a separate route, `POST /v1/screen-recordings/original-playback`. The access row (who, which `call_uuid`, which `variant`, until when) is written in the same transaction BEFORE the URL is minted; with no row there is no URL. The chunks are stored as ciphertext, so the URL is not a store URL: it points at `GET /v1/screen-media/{token}`, which needs NO bearer (the signed token in the path is the credential, valid for `expires_at`, 5 minutes) and so can be the `src` of a `