{"openapi":"3.0.0","paths":{"/users/me":{"get":{"operationId":"getProfile","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserProfileResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get current user profile","tags":["users"]}},"/users/me/contacts/sync":{"post":{"description":"Bulk upsert of contacts from the device address book, keyed on `userId + phoneNumber`. Existing contacts are updated with the most recent values, new ones are created. Rows missing `phoneNumber` or missing BOTH `firstName` AND `companyName` are silently skipped and counted. Phone numbers are normalized (strips `()`, `-`, spaces) so formatting variations don't create duplicates. Does NOT emit timeline activity — this is a silent sync.","operationId":"syncContacts","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncContactsDto"}}}},"responses":{"200":{"description":"Contacts synced successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Sync contacts from mobile device","tags":["users"]}},"/users/me/contacts":{"delete":{"description":"When `id` query param is provided, deletes only that contact. When omitted, deletes ALL of the user's contacts and requires request body `{\"confirmation\":\"delete all\"}`. The cleanup runs in one transaction: contact-only rows are removed, and calls/SMS/tasks/follow-ups/appointments are retained with `contactId` cleared.","operationId":"deleteAllContacts","parameters":[{"name":"id","required":false,"in":"query","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteContactsDto"}}}},"responses":{"200":{"description":"All contacts deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Delete all contacts","tags":["users"]},"get":{"description":"Paginated list of non-deleted contacts with per-contact stats (call counts, last interaction date) and aggregations (unique company count + list). `sort` accepts `lastInteraction`, `created`, or `name` — invalid values silently fall back to `created`. Sorting by `lastInteraction` is indexed but can get slow above ~10k contacts; prefer `created` for the default list view.","operationId":"getContacts","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort contacts by: lastInteraction, created, or name","schema":{"enum":["lastInteraction","created","name"],"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get all contacts","tags":["users"]}},"/users/me/contacts/{id}":{"patch":{"description":"Partial update of a single contact's fields: name, email, company, avatar, tags, `isFavorite`, `lifecycleStage`, `doNotCall`, `doNotSms`. Changing `phoneNumber` resets the contact's identity key — avoid unless intentional. `doNotCall` and `doNotSms` act as outbound suppression flags; enforcement happens at send time, not in this endpoint.","operationId":"updateContact","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactItemResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update contact","tags":["users"]},"get":{"description":"Returns contact details enriched with totalIncomingCalls, totalOutboundCalls, totalSmsMessages, lastCallDate, upcomingAppointments","operationId":"getContact","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactItemResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get a single contact with stats","tags":["users"]}},"/users/me/contacts/duplicates":{"get":{"description":"Returns candidate duplicate pairs grouped by either phone (last 10 digits of the normalized number match) or name (fuzzy similarity > 0.8, Levenshtein-like). Each group carries a `matchType` and a `confidence` hint. Run this after large imports before calling `/merge` — phone matches are high-confidence, name matches produce false positives for common names and should always be reviewed by a human.","operationId":"getDuplicateContacts","parameters":[],"responses":{"200":{"description":"List of potential duplicate contact pairs"}},"security":[{"bearer":[]}],"summary":"Find duplicate contacts","tags":["users"]}},"/users/me/contacts/merge":{"post":{"description":"Keeps the primary contact and reassigns all linked records (calls, SMS, notes, tasks, appointments) from secondary to primary, then soft-deletes the secondary. Field conflicts are resolved by `mergedData` — whatever you pass wins, so the client must decide ahead of time which values to keep. Irreversible: the secondary's `deletedAt` is set, history is preserved under the primary.","operationId":"mergeContacts","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeContactsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Merge two duplicate contacts","tags":["users"]}},"/users/me/contacts/search":{"post":{"description":"Full-text, typo-tolerant search across name, phone, company, and tags. Results are ranked by similarity then recency. If the query contains digits, also matches against the normalized (digits-only, last 10) phone so `555-123` and `(555) 123` find the same contact. With `injectCalls=true`, recent matching calls are returned as synthetic contacts (source `WEB`, max 5) — useful for surfacing numbers that aren't saved yet.","operationId":"searchContacts","parameters":[{"name":"query","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","schema":{"type":"number"}},{"name":"injectCalls","required":false,"in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Search contacts","tags":["users"]}},"/users/me/contacts/import":{"post":{"description":"Bulk import from arbitrary CSV or JSON. An AI pass reads the first 10 lines / 500 chars and auto-maps unknown column names to canonical contact fields (`firstName`, `lastName`, `phoneNumber`, `email`, `address`, `companyName`, `notes`, `tags`). If mapping fails, sensible defaults are used. Rows missing a valid phone, or missing BOTH `firstName` and `companyName`, are rejected with per-row errors; valid rows merge by phone rather than creating duplicates. Comma-separated tag strings are split into arrays.","operationId":"importContacts","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportContactsDto"}}}},"responses":{"200":{"description":"Contacts imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportContactsResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Import contacts from CSV or JSON file","tags":["users"]}},"/users/me/contacts/tags":{"get":{"description":"Returns all tags used across the user's contacts with occurrence counts, sorted by count DESC. Feeds frontend tag autocomplete and tag-cloud widgets. Only contacts with non-empty `tags` arrays contribute — newly-invented tags that aren't yet assigned to any contact won't appear. Tag matching is case-sensitive, so \"VIP\" and \"vip\" count as separate tags.","operationId":"getTagStats","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagStatsResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get tag statistics for autocomplete","tags":["users"]}},"/users/me/contacts/advanced-search":{"post":{"description":"Multi-criteria filter with AND between groups and OR within a group: `name` is split on spaces and matched against `firstName`/`lastName`/`companyName` (and `phoneNumber` if it contains digits, with phone normalization), `companies` matches any in the array, `tags` matches any in the array. Supports custom `sortBy` and `sortOrder`. Tag filtering is case-sensitive — keep tag naming consistent across the app. Combining many filters narrows results aggressively.","operationId":"advancedSearch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvancedSearchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Advanced search in contacts by name, company, and tags","tags":["users"]}},"/users/me/contacts/{id}/notes":{"get":{"description":"Returns all notes attached to the contact, ordered by `createdAt DESC`. Notes are user-scoped by default: team members only see their own notes unless `isPublic: true` was set when the note was created (team accounts feature). Use this for a dedicated notes tab; the same notes also appear in the contact timeline.","operationId":"getCustomerNotes","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List notes for a customer (newest first)","tags":["users"]},"post":{"description":"Attaches a free-text note to the contact and records the activity in its timeline. `isPublic` controls team visibility — defaults to private (visible only to the author). Notes are a human-authored layer separate from AI-generated summaries: keep them for context that the agent can't infer from transcripts (deal notes, manual follow-ups, offline context).","operationId":"addCustomerNote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCustomerNoteDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Add a note to a customer","tags":["users"]}},"/users/me/contacts/{id}/timeline":{"get":{"description":"Paginated, unified activity feed — inbound/outbound calls, SMS, notes, tasks, appointments, file uploads, custom field changes — sorted newest-first. This endpoint is read-only; to create activity, hit the specific endpoints (`/notes`, `/schedule-call`, `/send-sms`, etc.) and the timeline entry is written automatically. Aggregation is capped at ~1000 activities per contact; use `limit`/`offset` pagination for very active contacts to avoid slow loads.","operationId":"getCustomerTimeline","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get unified timeline for a customer","tags":["users"]}},"/users/me/contacts/{id}/notes/{noteId}":{"patch":{"description":"Updates note content and/or toggles the `isPublic` flag. The note ID is scoped to the caller's user ID and the current contact, so you can't edit someone else's note or a note from another customer.","operationId":"updateCustomerNote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"noteId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerNoteDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update a customer note","tags":["users"]},"delete":{"description":"Removes a note from the contact. The timeline entry for the note remains unless separately removed.","operationId":"deleteCustomerNote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"noteId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete a customer note","tags":["users"]}},"/users/me/contacts/{id}/custom-fields":{"patch":{"description":"Sets values for one or more user-defined custom fields on a contact. Each key must match an existing custom field definition — unknown keys are silently ignored. Values are validated against the field's type and (for `SELECT`/`MULTI_SELECT`) its options. Passing `null` clears the field; clearing a field marked `isRequired` returns a validation error. The change is recorded on the contact timeline.","operationId":"updateCustomerFields","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update custom fields on a customer","tags":["users"]}},"/calendars/appointments":{"get":{"description":"Returns appointments booked via calls or imported from connected calendars (Google, Outlook, Calendly, Square, Cal.com, GHL). Supports pagination (1-indexed `page`, max 100 per page — different from the 0-indexed offset used by `/calls`), plus filters by `period` ('upcoming' | 'past' | 'all'), `agentId`, `calendarId`, and free-text `search` across phone/email/title. Appointments only appear if at least one calendar is connected and enabled.","operationId":"listAppointments","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":20,"type":"number"}},{"name":"period","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["upcoming","past","all"]}},{"name":"agentId","required":false,"in":"query","schema":{"type":"string"}},{"name":"calendarId","required":false,"in":"query","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by phone, email, or title","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Filter from date (ISO string)","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Filter to date (ISO string)","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentsListResponseDto"}}}}},"summary":"List booked appointments","tags":["Calendars"]}},"/calendars/appointments/upcoming":{"get":{"description":"Lightweight endpoint for dashboard/widget UIs — returns the next N confirmed appointments sorted by `startTime` ascending (nearest first), default limit 5. Tentative appointments are excluded. Use `/calendars/appointments` with `period='upcoming'` when you need full pagination, filtering, or the unabridged appointment payload.","operationId":"getUpcomingAppointments","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AppointmentResponseDto"}}}}}},"summary":"Get upcoming appointments for widget","tags":["Calendars"]}},"/calendars/appointments/stats":{"get":{"description":"Returns count buckets for dashboard summary cards: total `upcoming`, `thisWeek`, `thisMonth`, and all-time `total`. \"This week\" and \"this month\" are relative to today in the user's timezone. Aggregates across every connected calendar provider (Google, Outlook, Calendly, Square, Cal.com, GHL) — no way to scope to a single calendar from this endpoint.","operationId":"getAppointmentStats","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentStatsDto"}}}}},"summary":"Get appointment statistics","tags":["Calendars"]}},"/calendars/appointments/{id}":{"get":{"description":"Returns the full appointment record including the external calendar event URL (`externalEventUrl` — deep link to Google Calendar, Calendly, etc.), the creating call reference (`callId` + `callDetailsUrl`), and whether it came from an inbound or outbound call (`isIncoming`). Useful for building detail views after `/calendars/appointments` or `/calendars/appointments/upcoming`.","operationId":"getAppointment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentResponseDto"}}}}},"summary":"Get a single appointment","tags":["Calendars"]},"delete":{"description":"Soft-deletes the appointment from SkipCalls only. The event REMAINS in the external calendar provider (Google, Outlook, Calendly, Square, Cal.com, GHL) — this endpoint does NOT cancel the booking with the customer. To fully cancel, also delete the event from the provider UI or via the `cancel_event` LLM tool during a call. There is no restore endpoint.","operationId":"deleteAppointment","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Hide/delete an appointment from the list","tags":["Calendars"]}},"/calls/transcribe":{"post":{"description":"Converts base64-encoded audio into text. Used for voice input in the chat UI so users can speak instead of typing. Accepts common formats (webm, mp3, wav, m4a, ogg). Audio must be a base64 data URL. Not intended for call transcription — call transcripts are generated automatically during the call lifecycle.","operationId":"transcribe","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscribeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscribeResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Transcribe audio (for chat)","tags":["calls"]}},"/calls/schedule":{"post":{"description":"Queues an outbound call. Creates the record in QUEUED status (or NOT_STARTED if scheduled for a future time). Runs validation: phone format and country checks (rejects VOIP/premium/shared-cost numbers for US/CA), destination-country restriction (your phone numbers must match the destination country), rate limits, balance check against `maxDurationMinutes`, and a content safety review. If the goal is ambiguous, the response may be `NEEDS_CLARIFICATION` with a follow-up question instead of a scheduled call — set `force: true` to skip clarification.","operationId":"scheduleCall","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleCallDto"}}}},"responses":{"201":{"description":"Call scheduled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseCallResponseDto"}}}},"400":{"description":"Invalid input data, needs clarification, insufficient credits, or call request denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseUnsuccessfulCallResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Schedule a new call","tags":["calls"]}},"/calls/{id}":{"delete":{"description":"Transitions a call from NOT_STARTED or QUEUED to CANCELLED. The record is retained for history and analytics. Only not-yet-started calls can be cancelled here — for IN_PROGRESS calls use `POST /calls/:id/drop`, and for finished calls use `DELETE /calls/:id/full`. Reserved minutes are released back to the user's balance.","operationId":"cancelScheduledCall","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Cancel a scheduled call by ID","tags":["calls"]},"get":{"description":"Returns the full call record with all relations loaded: transactions (billing), agent, voicemails, dataCollections, evaluations, tasks, analysis, followUps, plus computed fields `isFavorite`, `shareHash`, and a plain-text `transcription` rendered from `roleplayTranscript`. For in-progress calls some fields (finalSummary, minutesUsed) may be partial.","operationId":"getCallDetails","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Get call details","tags":["calls"]}},"/calls/copy/{id}":{"post":{"description":"Duplicates an existing call for a retry with optional overrides (new `scheduledAt`, different `phoneNumber`, revised goal/context). The new call's `copyOfCallId` points to the source, forming a retry chain. `cronSchedule` is intentionally NOT copied to prevent runaway recurring retries. Runs the same validation as `/schedule`, so a copy can still be denied. Primarily used when a call failed or the customer was unavailable.","operationId":"copyCall","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyCallDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseCallResponseDto"}}}},"400":{"description":"Invalid input data, needs clarification, insufficient credits, or call request denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseUnsuccessfulCallResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Copy a call","tags":["calls"]}},"/calls":{"get":{"description":"Lists outbound calls for the current user with status/date/phone filters, pagination, and aggregated stats (totals by status, minutes used). When `raw=true` the response is a plain array without stats. `transcription` is rendered on-the-fly from `roleplayTranscript` and may be empty for in-progress calls. Use `favorites=true` to filter to pinned calls only.","operationId":"getCallHistory","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["QUEUED","IN_PROGRESS","AWAITING_CONNECTION","SUCCESS","FAILED","NOT_STARTED","CANCELLED","CALL_TRANSFERRED"]}}},{"name":"startDate","required":false,"in":"query","description":"Start date for filtering calls (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for filtering calls (ISO 8601)","schema":{"type":"string"}},{"name":"phoneNumber","required":false,"in":"query","description":"Filter by phone number","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records to return","schema":{"minimum":1,"default":10,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"raw","required":false,"in":"query","description":"In Raw mode","schema":{"default":"false","type":"string"}},{"name":"favorites","required":false,"in":"query","description":"Filter only favorite calls","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallHistoryResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get call history","tags":["calls"]}},"/calls/search":{"get":{"description":"Full-text search across BOTH outbound and incoming calls in one query. Matches against transcripts, finalSummary, title, phoneNumber/phoneNumberFrom, goal, and callerName (case-insensitive). Results carry a `callType: 'outgoing' | 'incoming'` discriminator plus `matchedFields` showing which columns hit. For outbound-only results use `/calls/search/outgoing`; for incoming-only use `/incoming-calls/search`. Soft-deleted calls are excluded.","operationId":"searchCalls","parameters":[{"name":"query","required":true,"in":"query","description":"Search query string","schema":{"minLength":1,"example":"appointment","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records to return","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"minimum":0,"default":0,"type":"number"}}],"responses":{"200":{"description":"Search results including both outgoing and incoming calls","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCallsResponseDto"}}}},"400":{"description":"Invalid search query"}},"security":[{"bearer":[]}],"summary":"Search calls","tags":["calls"]}},"/calls/search/outgoing":{"get":{"description":"Same search semantics as `/calls/search` but scoped to outbound calls — faster because it skips the incoming-calls merge step. Matches transcripts, summaries, titles, goals, and phone numbers case-insensitively, returning `matchedFields` for each result. Use this when you know you only care about outbound history (e.g., a campaign follow-up list).","operationId":"searchOutgoingCalls","parameters":[{"name":"query","required":true,"in":"query","description":"Search query string","schema":{"minLength":1,"example":"appointment","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records to return","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"minimum":0,"default":0,"type":"number"}}],"responses":{"200":{"description":"Search results for outgoing calls only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallHistoryResponseDto"}}}},"400":{"description":"Invalid search query"}},"security":[{"bearer":[]}],"summary":"Search outgoing calls only","tags":["calls"]}},"/calls/{id}/rate":{"post":{"description":"Records a thumbs-up/thumbs-down rating plus optional comment on a completed call. Set `isIncomingCall=true` to rate an inbound call instead of outbound. A call can only be rated once — a second call returns 400. Ratings are generally only meaningful for SUCCESS/FAILED calls; rating an in-progress call is allowed but discouraged.","operationId":"rateCall","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateCallDto"}}}},"responses":{"200":{"description":"Call rated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"400":{"description":"Call already rated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Rate a call","tags":["calls"]}},"/calls/{id}/drop":{"post":{"description":"Best-effort termination of an IN_PROGRESS or AWAITING_CONNECTION call. The endpoint returns success even if the call is already ending. Minutes consumed up to the drop are billed, and the call is finalized with status FAILED and reason DROPPED_BY_USER. No-op if the call is already finished.","operationId":"dropCall","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Drop a call immediately by ID","tags":["calls"]}},"/calls/{id}/favorite":{"post":{"description":"Pins an outbound call for quick access via the `favorites=true` filter on history/search. A second call returns 400 — check `isFavorite` first or catch the error. Favoriting does not affect call behavior, retention, or billing; it is purely a UI concern.","operationId":"addToFavorites","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"400":{"description":"Call already in favorites"},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Add call to favorites","tags":["calls"]},"delete":{"description":"Unpins an outbound call. Returns 400 if the call was not previously favorited — check `isFavorite` first if you want idempotent behavior. Does not modify the call record itself.","operationId":"removeFromFavorites","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"400":{"description":"Call not in favorites"}},"security":[{"bearer":[]}],"summary":"Remove call from favorites","tags":["calls"]}},"/calls/{id}/notes":{"patch":{"description":"Attaches or replaces free-form plain-text notes on a call — pass `isIncomingCall=true` to target an inbound call instead. Typically used to record follow-up actions, context the agent missed, or personal observations after reviewing the transcript. Can be called on both in-progress and completed calls; there is no formatting support (plain text only).","operationId":"updateCallNotes","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID (outbound or inbound)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCallNotesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Update call notes","tags":["calls"]}},"/incoming-calls":{"get":{"description":"Lists inbound calls received on the user's agent numbers with status/date/phone filters and pagination. Unlike outbound calls, inbound calls only appear here once their status is FINISHED or PROCESSED (they go IN_PROGRESS → FINISHED → PROCESSED). Soft-deleted/hidden calls are excluded. Use `hideTrashCalls=true` to exclude spam and calls that ended immediately after the greeting before pagination and totals are calculated. Use `favorites=true` for pinned calls only, `raw=true` to skip the stats block. Each call still consumes minutes from the user's subscription balance.","operationId":"getCallHistory","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["FINISHED","PROCESSED","FAILED","IN_PROGRESS"]}}},{"name":"startDate","required":false,"in":"query","description":"Start date for filtering calls (ISO 8601)","schema":{"type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date for filtering calls (ISO 8601)","schema":{"type":"string"}},{"name":"phoneNumber","required":false,"in":"query","description":"Filter by phone number","schema":{"type":"string"}},{"name":"agentId","required":false,"in":"query","description":"Filter by receptionist ID","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records to return","schema":{"minimum":1,"default":10,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"raw","required":false,"in":"query","description":"In Raw mode","schema":{"default":"false","type":"string"}},{"name":"favorites","required":false,"in":"query","description":"Filter only favorite calls","schema":{"default":false,"type":"boolean"}},{"name":"hideTrashCalls","required":false,"in":"query","description":"Hide spam and calls that ended immediately after the greeting","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingCallHistoryResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get incoming call history","tags":["incoming-calls"]}},"/incoming-calls/search":{"get":{"description":"Full-text search scoped to inbound calls — matches caller name, phone number, transcript, summary, and title case-insensitively. Faster than `/calls/search` which also scans outbound calls. Returns `matchedFields` per result showing which columns hit the query. Soft-deleted calls are excluded.","operationId":"searchIncomingCalls","parameters":[{"name":"query","required":true,"in":"query","description":"Search query string","schema":{"minLength":1,"example":"appointment","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records to return","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of records to skip","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"agentId","required":false,"in":"query","description":"Filter by receptionist ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results for incoming calls only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingCallHistoryResponseDto"}}}},"400":{"description":"Invalid search query"}},"security":[{"bearer":[]}],"summary":"Search incoming calls only","tags":["incoming-calls"]}},"/incoming-calls/{id}":{"get":{"description":"Returns the full inbound call record with all relations: transcript, finalSummary, agent config used, `dataCollections` (structured data extracted by the AI), `followUps` and `tasks` created during the call (both filtered to non-deleted and sorted newest first). If the call is still IN_PROGRESS some fields may be partial.","operationId":"getCallDetails","parameters":[{"name":"id","required":true,"in":"path","description":"Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingCallDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Get incoming call details","tags":["incoming-calls"]},"delete":{"description":"Soft-deletes an inbound call by setting `deletedAt`, hiding it from history and search. The record stays in the DB for analytics and audit; there is no restore endpoint. Does not affect transactions/billing or delete any booked appointments created during the call.","operationId":"deleteCall","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Delete an incoming call","tags":["incoming-calls"]}},"/incoming-calls/{id}/block":{"post":{"description":"Adds the call's `phoneNumberFrom` to the user's blocklist so future calls from that number are rejected by ALL the user's agents globally. Typical use: spam, harassment, or competitors. Blocks the exact number only (not the caller name/account). Use `POST /incoming-calls/:id/unblock` with the same call ID to reverse.","operationId":"blockCaller","parameters":[{"name":"id","required":true,"in":"path","description":"Incoming Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number blocked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockCallerResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Block the caller phone number from this incoming call","tags":["incoming-calls"]}},"/incoming-calls/{id}/unblock":{"post":{"description":"Removes `phoneNumberFrom` of the referenced call from the user's blocklist — effective immediately, the next call from that number will ring through to the agent again. Pass the incoming call ID that was originally used to block, not the phone number directly.","operationId":"unblockCaller","parameters":[{"name":"id","required":true,"in":"path","description":"Incoming Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Phone number unblocked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockCallerResponseDto"}}}},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Unblock the caller phone number from this incoming call","tags":["incoming-calls"]}},"/incoming-calls/{id}/drop":{"post":{"description":"Terminates an IN_PROGRESS inbound call. Best-effort: returns success even if termination fails (the call may already be ending). Minutes consumed up to the drop are billed.","operationId":"dropIncomingCall","parameters":[{"name":"id","required":true,"in":"path","description":"Incoming Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"404":{"description":"Incoming call not found"}},"security":[{"bearer":[]}],"summary":"Drop an incoming call immediately by ID","tags":["incoming-calls"]}},"/incoming-calls/{id}/favorite":{"post":{"description":"Pins an inbound call for quick access via the `favorites=true` filter on history/search. A second call returns 400 — check `isFavorite` first or catch the error. Purely a UI concern — does not change call behavior or retention.","operationId":"addToFavorites","parameters":[{"name":"id","required":true,"in":"path","description":"Incoming Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"400":{"description":"Call already in favorites"},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Add incoming call to favorites","tags":["incoming-calls"]},"delete":{"description":"Unpins an inbound call. Returns 400 if the call was not previously favorited — check `isFavorite` first if you want idempotent behavior. Does not modify the call record itself.","operationId":"removeFromFavorites","parameters":[{"name":"id","required":true,"in":"path","description":"Incoming Call ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallSimpleResponseDto"}}}},"400":{"description":"Call not in favorites"},"404":{"description":"Call not found"}},"security":[{"bearer":[]}],"summary":"Remove incoming call from favorites","tags":["incoming-calls"]}},"/agents":{"post":{"description":"Creates a voice AI agent with the provided configuration. The agent won't receive calls until a phone number is assigned, but it can be tested immediately. Instructions are validated by an LLM and rejected if vague or off-topic. Subscription agent-count limits are enforced. Mobile users auto-get isVoiceMailAgent=true; avatar is auto-generated from name.","operationId":"create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentDto"}}}},"responses":{"201":{"description":"The agent has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"400":{"description":"Invalid agent instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentValidationDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a new agent","tags":["agents"]},"get":{"description":"Returns all non-deleted agents you own, ordered by newest first, with nested phone numbers (test numbers excluded), tools, evaluations, and data collections plus their results. Use for the dashboard agent list, external sync, or audits. Soft-deleted agents are filtered out.","operationId":"findAll","parameters":[],"responses":{"200":{"description":"Returns an array of agents.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentDto"}}}}}},"security":[{"bearer":[]}],"summary":"Get all not deleted agents for the current user","tags":["agents"]}},"/agents/public":{"get":{"description":"Returns curated public template agents visible to all users — useful as starting points, examples, or for a template gallery. Response excludes userId and sensitive config fields. No authentication data is required beyond standard JWT.","operationId":"findPublic","parameters":[],"responses":{"200":{"description":"Returns an array of public agents.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentDto"}}}}}},"security":[{"bearer":[]}],"summary":"Get all public agents","tags":["agents"]}},"/agents/{id}":{"get":{"description":"Retrieves the full agent configuration including instructions, voice, evaluations, data collections, linked calendars, transfer numbers, and tasks. Use for edit form pre-population, detail views, or config audits. Returns 404 if the agent doesn't belong to the authenticated user or was soft-deleted.","operationId":"findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the agent if found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"404":{"description":"Agent not found."}},"security":[{"bearer":[]}],"summary":"Get a specific agent by ID","tags":["agents"]},"patch":{"description":"Partial update — only fields sent in the body are changed. If instructions change they're re-validated and rejected if invalid. If toolIds is sent, ALL existing tool links are replaced. SMS-capable setting changes reconcile Messaging Service registration for assigned US Twilio numbers.","operationId":"update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentDto"}}}},"responses":{"200":{"description":"The agent has been successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"400":{"description":"Invalid agent instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentValidationDto"}}}},"404":{"description":"Agent not found."}},"security":[{"bearer":[]}],"summary":"Update an agent","tags":["agents"]},"delete":{"description":"Deletes the agent and its evaluations, data collections, and transfer numbers. Phone numbers become unassigned and can be reused.","operationId":"remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The agent has been successfully deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"404":{"description":"Agent not found."}},"security":[{"bearer":[]}],"summary":"Delete an agent","tags":["agents"]}},"/agents/{id}/toggle":{"patch":{"description":"Flips the agent's isActive flag to quickly pause or resume it without losing configuration. Inactive agents don't receive calls. Use for off-hours pause, maintenance windows, or a single-click enable/disable control in the UI.","operationId":"toggle","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The agent has been successfully toggled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}}},"security":[{"bearer":[]}],"summary":"Toggle an agent active status","tags":["agents"]}},"/agents/{id}/reset-to-defaults":{"post":{"description":"Resets the agent's editable dashboard configuration to the default new-receptionist settings while preserving the agent record and linked resources. The reset is recorded in agent audit history.","operationId":"resetToDefaults","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The agent has been reset to defaults.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDto"}}}},"404":{"description":"Agent not found."}},"security":[{"bearer":[]}],"summary":"Reset an agent to dashboard defaults","tags":["agents"]}},"/agents/{id}/audit-history":{"get":{"description":"Returns paginated audit log of every config change on this agent (instructions, voice, settings, etc.) with old/new values and source attribution. Use for compliance reports, debugging unexpected changes, or rollback planning. Defaults: limit=50, offset=0.","operationId":"getAuditHistory","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max entries to return","schema":{"default":50,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Offset for pagination","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"Returns paginated audit log entries for the agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAuditHistoryResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get agent change history","tags":["agents"]}},"/agents/{id}/evaluations":{"post":{"description":"Defines a new call-quality criterion (yes/no question like \"Did the agent mention pricing?\"). After every call, the LLM evaluates the transcript and returns SUCCESS/FAILURE/UNKNOWN with a rationale. Use to track agent performance metrics and build quality dashboards.","operationId":"createEvaluation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentEvaluationDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create agent evaluation","tags":["agents"]},"get":{"description":"Returns all evaluation criteria defined for this agent with their execution results (SUCCESS/FAILURE/UNKNOWN + rationale per call). Use for quality dashboards, trend analysis, or listing tracked metrics. Soft-deleted evaluations are filtered out.","operationId":"getEvaluations","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get agent evaluations","tags":["agents"]}},"/agents/evaluations/{id}":{"patch":{"description":"Modifies the name or prompt of an evaluation criterion. Past results are preserved — only future evaluations use the new prompt. Use to refine criteria or clarify what you're measuring. Ownership verified via the nested agent.userId.","operationId":"updateEvaluation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentEvaluationDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update agent evaluation","tags":["agents"]},"delete":{"description":"Soft-deletes the evaluation (sets deletedAt). Past results stay archived and queryable; no new evaluations run on future calls. Use when retiring outdated metrics or simplifying dashboards.","operationId":"deleteEvaluation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete agent evaluation","tags":["agents"]}},"/agents/{id}/data-collections":{"post":{"description":"Defines a structured field (customer_name, budget, appointment_time, etc.) auto-extracted from every call transcript. Specify dataType (STRING/NUMBER/INTEGER/BOOLEAN/DATE) to enforce the expected type on the extracted value. Use for CRM sync, analytics, or integrations.","operationId":"createDataCollection","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentDataCollectionDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create agent data collection","tags":["agents"]},"get":{"description":"Returns all extraction fields configured for this agent plus the values extracted from recent calls. Use for CRM sync settings, reviewing captured data, or auditing extraction setup. Soft-deleted fields are filtered out.","operationId":"getDataCollections","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get agent data collections","tags":["agents"]}},"/agents/data-collections/{id}":{"patch":{"description":"Modifies the description or dataType of an extraction field. Past results remain untouched; future calls use the new config. Use to clarify extraction instructions or change the expected data type.","operationId":"updateDataCollection","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentDataCollectionDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update agent data collection","tags":["agents"]},"delete":{"description":"Soft-deletes the extraction field. Past extracted values are preserved and queryable; no new extractions run on future calls. Use to remove unused fields or consolidate data capture.","operationId":"deleteDataCollection","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete agent data collection","tags":["agents"]}},"/agents/{id}/calendars":{"post":{"description":"Links a calendar (Google/Outlook/Apple) to the agent so it can check availability and auto-book appointments during calls. Specify work hours per day (HHMM format), timezone, default duration, buffer minutes. The calendar must already belong to the user.","operationId":"connectCalendar","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentCalendarDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Connect calendar to agent","tags":["agents"]},"get":{"description":"Returns all calendars linked to this agent with their booking config (work hours, timezone, duration, buffer, active flag). Use to view integrations, verify booking setup, or audit access.","operationId":"getConnectedCalendars","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get agent connected calendars","tags":["agents"]}},"/agents/{id}/calendars/{agentCalendarId}/duplicate":{"post":{"description":"Creates a second AgentCalendar row pointing at the same underlying calendar but with independent duration/description. Use this to expose multiple \"virtual\" variants of one Google/Outlook/Apple calendar to the AI — e.g., \"New patient — 40 min\" and \"Follow-up — 10 min\" on the same physical calendar. The AI sees them as distinct options and picks one per appointment type. Only allowed for self-managed providers (GOOGLE, OUTLOOK, APPLE); external booking engines (Calendly, Cal.com, Square, GHL) dictate duration from their own system, so cloning is rejected. :agentCalendarId is the AgentCalendar primary key (not the underlying calendar's ID).","operationId":"duplicateCalendar","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"agentCalendarId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateAgentCalendarDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Duplicate an agent-calendar link (virtual calendar)","tags":["agents"]}},"/agents/{id}/calendars/{calendarId}":{"patch":{"description":"Partial update of a calendar link — work hours, timezone, default duration, buffer minutes, active flag, double-booking permission. Use for seasonal schedule changes, timezone updates after relocation, or enabling/disabling booking temporarily.","operationId":"updateCalendarSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"calendarId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentCalendarDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update calendar settings","tags":["agents"]},"delete":{"description":"Removes the link between the agent and the calendar. Agent stops checking availability or booking events on this calendar. The underlying calendar itself is preserved. Use when replacing calendars or removing booking capability.","operationId":"disconnectCalendar","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"calendarId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Disconnect calendar from agent","tags":["agents"]}},"/agents/{id}/embed":{"post":{"description":"Creates or updates the widget config for embedding this agent on a website as a voice button. Requires at least one allowed domain (exact \"example.com\" or wildcard \"*.example.com\"). Embed key is generated on first create and preserved on updates. Customize position, autoConnect, primaryColor, callButtonText.","operationId":"createOrUpdateEmbed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWidgetConfigDto"}}}},"responses":{"200":{"description":"Widget configuration created/updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetConfigResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create or update widget embed configuration","tags":["agents"]},"get":{"description":"Returns the widget's embedKey (pk_embed_*), isEnabled flag, allowed domains, styling options, and usage stats (totalConnections, lastUsedAt). Use to display the embed code snippet in settings or verify current config.","operationId":"getEmbed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns widget configuration"}},"security":[{"bearer":[]}],"summary":"Get widget embed configuration","tags":["agents"]},"delete":{"description":"Sets isEnabled=false on the widget config — the embed stops working on all websites immediately, but config (domains, styling, embed key) is preserved for quick re-enable. Use for maintenance, temporarily pausing, or removing from production.","operationId":"disableEmbed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Disable widget embed","tags":["agents"]}},"/agents/{id}/embed/regenerate-key":{"post":{"description":"Invalidates the current embed key and generates a new pk_embed_* value. The old key stops working immediately — any deployed