> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # Get a call > Call details including the transcript, the AI summary, provider-neutral failure guidance, the chronological event log, and a signed `recording_url` (valid 1 hour) if a recording exists. Failed transfer events expose the same safe failure shape without raw SIP or SDK diagnostics. **Required scope:** `calls:read` (keys without scope restrictions have full access). Removed conversations are excluded. Their detail IDs return not found. Includes measured call insights. Unavailable measurements are null. Transcript recognition confidence is a score, not a correctness guarantee. Recording playback is limited to available consent-permitted audio. ## OpenAPI ````yaml /api-reference/openapi.json get /calls/{id} openapi: 3.1.0 info: title: Famulor API version: 1.0.0 description: >- REST API for Famulor. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token. Every response uses a consistent envelope: `{ "data": ... , "meta": { ... } }` on success and `{ "error": { "code", "message" } }` on failure. List endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`; `meta.pagination.total` carries the total match count. REST operations require API Access through the workspace plan or a recurring add-on. Without it, regular operations return `403 api_access_required`. The invoice-payment and billing-portal operations remain available with a valid `billing:write` credential after a failed plan payment so an authorized owner, admin, or billing member can recover billing. The same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access. servers: - url: https://app.famulor.io/api/v1 description: Hosted platform. - url: https://{domain}/api/v1 description: White-label tenant domain — same paths, tenant branding. variables: domain: default: app.famulor.io description: Your white-label tenant domain. security: - bearerAuth: [] tags: - name: Account description: Self-inspection of the calling credential. - name: Migrations description: Preview and import data from supported legacy platforms. - name: Assistants description: Create and manage voice assistants. - name: Tools description: >- Reusable tools (HTTP APIs and external MCP servers) assistants can call mid-conversation. - name: Voices description: Browse the text-to-speech voice library. - name: Calls description: Start outbound calls and read call history, transcripts and recordings. - name: History description: Unified conversation history across calls, messaging and assistant emails. - name: Campaigns description: Outbound calling campaigns with a compliant power dialer. - name: Leads description: Manage Audience contacts across campaigns, channels and Call QA metrics. - name: Segments description: >- Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment. - name: Suppression description: Cross-channel marketing opt-outs and active workspace suppression records. - name: Callbacks description: >- Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email. - name: Phone Numbers description: Marketplace numbers and customer-provided numbers. - name: Famulor Loop description: >- Personal business-phone access, directory, presence, devices, and Loop call recents. - name: SIP Trunks description: Bring your own SIP provider and numbers. - name: Carrier Connections description: Connect a supported carrier account and import its existing phone numbers. - name: Knowledge Bases description: RAG knowledge bases and documents for assistants. - name: Settings description: Workspace-level settings such as caller-memory defaults. - name: Billing description: Balance and transaction ledger of the API key's workspace. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan. - name: Milian Missions description: Recurring jobs that Milian runs unattended on schedule. - name: Integrations description: >- Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling. - name: Bookings description: >- Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce. - name: Dashboards description: >- Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires Custom dashboards in the workspace plan. - name: Catalog description: >- Read-only platform catalogs — available models, supported assistant languages, and prompt templates. - name: Simulations description: Assistant simulation tests (plan-gated). - name: Versions description: Assistant configuration version history. - name: Caller IDs description: Outbound caller ID verification. - name: Widgets description: Web widget connectors. - name: Messaging description: >- Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks. - name: QA description: Cohort AI Quality Assurance runs over call transcripts. - name: White Label description: >- Manage white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility. - name: API Keys description: >- Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own. - name: Workspaces description: >- List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace. - name: SMS description: Outbound SMS from workspace phone numbers. - name: Milian description: >- Ask Milian, the AI co-worker in your workspace, and start voice sessions with it. - name: Translation description: >- Live translation sessions that interpret a conversation between two languages. paths: /calls/{id}: parameters: - name: id in: path required: true schema: type: string format: uuid description: Call ID. get: tags: - Calls summary: Get a call description: >- Call details including the transcript, the AI summary, provider-neutral failure guidance, the chronological event log, and a signed `recording_url` (valid 1 hour) if a recording exists. Failed transfer events expose the same safe failure shape without raw SIP or SDK diagnostics. **Required scope:** `calls:read` (keys without scope restrictions have full access). Removed conversations are excluded. Their detail IDs return not found. Includes measured call insights. Unavailable measurements are null. Transcript recognition confidence is a score, not a correctness guarantee. Recording playback is limited to available consent-permitted audio. operationId: getCall responses: '200': description: The call with events and recording URL. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/CallDetail' example: data: id: c1b2c3d4-0000-4000-8000-000000000010 assistant_id: a1b2c3d4-0000-4000-8000-000000000001 phone_number_id: p1b2c3d4-0000-4000-8000-000000000020 direction: outbound from_number: '+4930123456' to_number: '+4915123456789' status: completed started_at: '2026-07-01T10:00:00Z' answered_at: '2026-07-01T10:00:05Z' ended_at: '2026-07-01T10:03:25Z' duration_sec: 200 transcript: items: - type: message role: assistant content: - Hi! How can I help you today? - type: message role: user content: - Please book Friday afternoon. - type: function_call name: book_appointment call_id: tool-1 arguments: '{"day":"Friday","period":"afternoon"}' created_at: 1782900005.25 - type: function_call_output name: book_appointment call_id: tool-1 output: '{"booked":true}' is_error: false created_at: 1782900006.5 structured_transcript: |- ai: Hi! How can I help you today? human: Please book Friday afternoon. summary: Caller rescheduled their appointment to Friday. evaluation: null metadata: {} created_at: '2026-07-01T10:00:00Z' updated_at: '2026-07-01T10:03:30Z' recording_url: https://storage.example.com/recordings/signed-url events: - id: e1 call_id: c1b2c3d4-0000-4000-8000-000000000010 type: state_changed payload: status: in_progress created_at: '2026-07-01T10:00:05Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/RequestProtectionUnavailable' components: schemas: CallDetail: allOf: - $ref: '#/components/schemas/Call' - type: object properties: recording_url: type: - string - 'null' description: >- Signed recording download URL (valid 1 hour), or `null` if the call has no recording. billing: $ref: '#/components/schemas/CallBilling' structured_transcript: type: string description: >- The `transcript` flattened to one line per turn, formatted as `ai: …` / `human: …` (assistant/user), in chronological order. Convenience string for prompts, emails or webhooks that don't want to parse the raw transcript items. events: type: array items: $ref: '#/components/schemas/CallEvent' description: Call events in chronological order. insights: oneOf: - $ref: '#/components/schemas/CallInsights' - type: 'null' description: >- Measured call insights, or null if insights cannot currently be loaded. Call details remain available. transcript_display: type: array items: $ref: '#/components/schemas/CallTranscriptDisplayEntry' description: >- Customer-safe display timeline with paired tool calls and merged conversational fragments. Insight transcript_index values refer to this array. Internal message identity and raw telemetry are excluded. Call: type: object properties: id: type: string format: uuid assistant_id: type: - string - 'null' format: uuid phone_number_id: type: - string - 'null' format: uuid direction: type: string enum: - inbound - outbound - web from_number: type: - string - 'null' to_number: type: - string - 'null' status: type: string enum: - queued - ringing - in_progress - completed - failed - no_answer - busy failure: $ref: '#/components/schemas/PublicCallFailure' description: >- Provider-neutral failure guidance. Present when a call has a normalized failure reason (telephony, billing, runtime, …). started_at: type: - string - 'null' format: date-time answered_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time duration_sec: type: - integer - 'null' transcript: $ref: '#/components/schemas/CallTranscript' description: >- Public-safe session history. `items` contains messages and typed function_call/function_call_output entries linked by call_id. Provider metrics, request IDs and model-specific metadata are omitted. `timeline_seq`, `logical_turn_id` and `started_at` provide stable ordering when present. Null while no transcript is available. summary: type: - string - 'null' description: AI-generated post-call summary. evaluation: description: AI post-call evaluation, or `null`. analysis: type: - object - 'null' additionalProperties: true description: >- Post-call analysis result produced by the LLM judge after the call ends (only when the assistant has `analysis_config` enabled). Shape: `{ sentiment, success, success_reason, data, model, analyzed_at }`. `data` holds the structured fields defined in the assistant's `analysis_config.fields`. `null` until analysis has run. properties: sentiment: type: - string - 'null' enum: - positive - neutral - negative - null success: type: - boolean - 'null' success_reason: type: - string - 'null' data: type: object additionalProperties: true model: type: - string - 'null' analyzed_at: type: - string - 'null' format: date-time sentiment: type: - string - 'null' enum: - positive - neutral - negative - null description: >- Denormalized copy of `analysis.sentiment` for filtering. Use `?sentiment=` on `GET /calls`. success: type: - boolean - 'null' description: >- Denormalized copy of `analysis.success` for filtering. Use `?success=` on `GET /calls`. metadata: type: object additionalProperties: true description: Includes `campaign_id`/`lead_id` for campaign dialer calls. created_at: type: string format: date-time updated_at: type: string format: date-time qa_scorecard: type: - object - 'null' additionalProperties: true description: >- AI-QA scorecard result. Shape: `{ score, passed, pass_threshold, criteria[], scored_at }`. `null` until scored. qa_score: type: - number - 'null' description: Denormalized overall QA score 0–100. qa_passed: type: - boolean - 'null' description: Denormalized pass/fail against the configured threshold. amd_result: type: - string - 'null' description: >- Answering-machine detection result when available, including human, machine-vm, machine-ivr, machine-unavailable, or uncertain. A detected phone menu is an answered call, not a ringing timeout. required: - id - direction - status - created_at - updated_at CallBilling: type: object description: >- Actual workspace credit debits posted for one call. total_credits_charged includes the primary call and linked additional services, net of refunds. Later phone adjustments may update the amounts. The primary-call fields and hold calculations remain separate from additional services. properties: credits_charged: type: - number - 'null' description: >- Primary-call credits, including posted primary phone adjustments. Excludes separately booked transfer, recording and other linked services. Use total_credits_charged for the combined posted amount. total_credits_charged: type: - number - 'null' description: >- Primary-call credits plus additional_credits, net of posted refunds. Null when a complete ledger summary is unavailable; not an estimate or a guaranteed final amount before later adjustments. additional_credits: type: - number - 'null' description: >- Net credits for linked transfer, recording and other call services. Already included in total_credits_charged. Null if the linked ledger could not be fully read. recording_credits: type: - number - 'null' description: >- Recording subset of additional_credits, net of posted refunds. Do not add it again to the total. Zero means no net recording debit was found; null means unavailable. telephony_credits: type: - number - 'null' description: >- Final telephony credits at the workspace rate. Null until the live carrier price is billed. Not the hold estimate. credits_reserved: type: - number - 'null' description: Credits held at call start for the maximum talk time. credits_released: type: - number - 'null' description: >- Unused hold returned after the call (reserved minus billed, or the full hold when the call was skipped). credits_per_min: type: - number - 'null' description: Workspace credit rate used to size the hold (talk plus telephony). max_duration_sec: type: - integer - 'null' description: Maximum talk time the hold was sized for. reservation_status: type: - string - 'null' enum: - active - settled - released - failed - null hold_reason: type: - string - 'null' description: Why credits were held and how billed/telephony relate to the hold. CallEvent: type: object properties: id: type: string format: uuid call_id: type: string format: uuid type: type: string description: >- E.g. `state_changed`, `transcript_delta`, `tool_called`, `call_transfer_failed`, or `warm_transfer_failed`. payload: type: object additionalProperties: true description: >- Failure events expose a safe `failure` object. Raw SIP status, connection diagnostics and SDK errors are omitted. created_at: type: string format: date-time required: - id - call_id - type - created_at CallInsights: type: object additionalProperties: false required: - version - coverage - recording_origin - summary - timing - replies - events properties: version: type: integer const: 1 coverage: type: string enum: - complete - partial description: >- Coverage of the available observation data. Individual missing measurements remain null. recording_origin: type: - string - 'null' format: date-time description: >- Start of the available recording. Playback remains subject to recording and consent settings. summary: type: object additionalProperties: false required: - reply_count - measured_reply_count - response_median_ms - response_p95_ms - interruptions - backchannels - resumed - overlap_ms - overlap_coverage - connection_quality properties: reply_count: type: integer minimum: 0 measured_reply_count: type: integer minimum: 0 response_median_ms: type: - number - 'null' minimum: 0 description: >- Median measured response time. Missing measurements are null, never zero-filled. response_p95_ms: type: - number - 'null' minimum: 0 description: >- 95th percentile measured response time. Missing measurements are null, never zero-filled. interruptions: type: - integer - 'null' minimum: 0 backchannels: type: - integer - 'null' minimum: 0 description: >- Caller overlaps classified as non-interrupting speech, when observed. resumed: type: - integer - 'null' minimum: 0 overlap_ms: type: - number - 'null' minimum: 0 description: >- Observed duration of simultaneous caller and assistant speech. Missing measurements are null, never zero-filled. overlap_coverage: type: string enum: - complete - partial - unavailable connection_quality: type: string enum: - good - degraded - poor - unknown timing: type: object additionalProperties: false required: - recognition_ms - turn_detection_ms - response_generation_ms - speech_generation_ms - playback_ms properties: recognition_ms: type: object additionalProperties: false required: - average_ms - samples properties: average_ms: type: - number - 'null' minimum: 0 description: >- Mean of available measurements. Missing measurements are null, never zero-filled. samples: type: integer minimum: 0 turn_detection_ms: type: object additionalProperties: false required: - average_ms - samples properties: average_ms: type: - number - 'null' minimum: 0 description: >- Mean of available measurements. Missing measurements are null, never zero-filled. samples: type: integer minimum: 0 response_generation_ms: type: object additionalProperties: false required: - average_ms - samples properties: average_ms: type: - number - 'null' minimum: 0 description: >- Mean of available measurements. Missing measurements are null, never zero-filled. samples: type: integer minimum: 0 speech_generation_ms: type: object additionalProperties: false required: - average_ms - samples properties: average_ms: type: - number - 'null' minimum: 0 description: >- Mean of available measurements. Missing measurements are null, never zero-filled. samples: type: integer minimum: 0 playback_ms: type: object additionalProperties: false required: - average_ms - samples properties: average_ms: type: - number - 'null' minimum: 0 description: >- Mean of available measurements. Missing measurements are null, never zero-filled. samples: type: integer minimum: 0 replies: type: array items: $ref: '#/components/schemas/CallInsightReply' events: type: array items: $ref: '#/components/schemas/CallInsightEvent' description: >- Customer-facing measured conversation insights. Missing data remains unavailable. Recording positions only refer to audio that was recorded under the conversation recording and consent settings. CallTranscriptDisplayEntry: oneOf: - type: object additionalProperties: false properties: kind: const: message role: type: string enum: - user - assistant text: type: string interrupted: type: boolean ended_at: type: string format: date-time attachments: type: array items: type: object timestamp: type: string format: date-time required: - kind - role - text - type: object additionalProperties: false properties: kind: const: tool_pair call: type: object additionalProperties: false properties: kind: const: tool_call name: type: string call_id: type: string args: type: string timestamp: type: string format: date-time required: - kind - name - call_id - args output: type: object additionalProperties: false properties: kind: const: tool_output name: type: string call_id: type: string output: type: string is_error: type: boolean timestamp: type: string format: date-time required: - kind - name - call_id - output - is_error required: - kind - call - type: object additionalProperties: false properties: kind: const: tool_output name: type: string call_id: type: string output: type: string is_error: type: boolean timestamp: type: string format: date-time required: - kind - name - call_id - output - is_error ErrorEnvelope: type: object description: Error envelope returned by every /api/v1 endpoint on failure. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - api_access_required - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - destination_forbidden - internal_error - service_unavailable description: >- Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable). message: type: string description: Human-readable description of the error. PublicCallFailure: type: object additionalProperties: false required: - domain - code - message - retryable - action description: >- Provider-neutral failure guidance for calls. Telephony failures also set operation. properties: domain: type: string enum: - telephony - billing - admission - runtime - config - dispatch - workspace operation: type: string enum: - outbound_call - cold_transfer - warm_transfer description: Present when domain is telephony. code: type: string enum: - busy - declined - no_answer - temporarily_unavailable - cancelled_before_answer - invalid_destination - destination_not_found - authentication_failed - destination_forbidden - caller_blocked - call_redirected - invalid_call_request - phone_account_payment_required - destination_gone - media_not_supported - connection_timeout - request_too_large - calling_feature_unsupported - call_timer_rejected - caller_identity_rejected - phone_connection_failed - routing_limit_reached - call_permission_required - call_session_not_found - destination_ambiguous - call_request_pending - call_security_rejected - phone_network_timeout - call_requirements_not_met - call_unwanted - call_blocked_by_network - routing_loop - routing_conflict - method_not_allowed - trunk_unavailable - no_outbound_trunk - transfer_unavailable - unknown - insufficient_credits - reservation_failed - outbound_quota_reservation_failed - integrated_outbound_limit_reached - quiet_hours - budget_service_unavailable - workspace_concurrency_limit - campaign_concurrency_limit - platform_unavailable - region_unavailable - capability_unavailable - capacity_exhausted - admission_unavailable - voice_unavailable - speech_unavailable - assistant_unavailable - call_runtime_failed - workspace_suspended - dispatch_failed - missing_destination - ivr_detected - voicemail_detected - mailbox_unavailable message: type: string description: Stable, provider-neutral English explanation. retryable: type: boolean description: >- Informational retry guidance. It does not change campaign retry policy. action: type: string enum: - retry_later - do_not_retry - check_destination - check_trunk_credentials - check_trunk_configuration - connect_outbound_number - continue_call - contact_support - top_up - check_assistant - check_campaign_schedule CallTranscript: oneOf: - type: 'null' - type: object required: - items additionalProperties: false properties: items: type: array items: oneOf: - $ref: '#/components/schemas/CallTranscriptMessage' - $ref: '#/components/schemas/CallTranscriptFunctionCall' - $ref: '#/components/schemas/CallTranscriptFunctionOutput' - type: array description: Legacy role/content transcript format. items: type: object required: - role - content additionalProperties: false properties: role: type: string enum: - user - assistant content: {} CallInsightReply: type: object additionalProperties: false required: - transcript_index - at - audio_offset_sec - before_recording - number - response_ms - recognition_ms - turn_detection_ms - response_generation_ms - speech_generation_ms - playback_ms properties: transcript_index: type: - integer - 'null' minimum: 0 description: >- Index in transcript_display when a unique displayed turn match is available; otherwise null. at: type: - string - 'null' format: date-time audio_offset_sec: type: - number - 'null' minimum: 0 description: >- Position in the permitted recording in seconds, or null when unavailable. before_recording: type: boolean description: >- True when the spoken turn precedes the available recording. Such speech cannot be played. number: type: integer minimum: 1 response_ms: type: - number - 'null' minimum: 0 description: >- Measured response time in milliseconds. Missing measurements are null, never zero-filled. recognition_ms: type: - number - 'null' minimum: 0 description: >- Time from the caller finishing speech until the transcript arrives. Missing measurements are null, never zero-filled. turn_detection_ms: type: - number - 'null' minimum: 0 description: >- Additional wait from transcript arrival until the caller turn is committed; recognition time is excluded. Missing measurements are null, never zero-filled. response_generation_ms: type: - number - 'null' minimum: 0 description: >- Time until response generation begins returning text. Missing measurements are null, never zero-filled. speech_generation_ms: type: - number - 'null' minimum: 0 description: >- Time until speech generation begins returning audio. Missing measurements are null, never zero-filled. playback_ms: type: - number - 'null' minimum: 0 description: >- Delay before the generated speech starts playing. Missing measurements are null, never zero-filled. CallInsightEvent: type: object additionalProperties: false required: - transcript_index - at - audio_offset_sec - before_recording - id - kind - duration_ms - confidence properties: transcript_index: type: - integer - 'null' minimum: 0 description: >- Index in transcript_display when a unique displayed turn match is available; otherwise null. at: type: - string - 'null' format: date-time audio_offset_sec: type: - number - 'null' minimum: 0 description: >- Position in the permitted recording in seconds, or null when unavailable. before_recording: type: boolean description: >- True when the spoken turn precedes the available recording. Such speech cannot be played. id: type: string description: Identifier within this insights response. kind: type: string enum: - interruption - backchannel - resumed - review_transcript - late_transcript - overlap - playback duration_ms: type: - number - 'null' minimum: 0 description: >- Measured duration where applicable. Missing measurements are null, never zero-filled. confidence: type: - number - 'null' minimum: 0 maximum: 1 description: >- Recorded recognition score when available. This is not a probability that the sentence is correct. CallTranscriptMessage: type: object required: - type - role - content additionalProperties: false properties: id: type: string description: Stable history item identifier. type: type: string const: message role: type: string enum: - user - assistant content: type: array items: oneOf: - type: string - type: object additionalProperties: true interrupted: type: boolean description: Whether assistant speech for this message was interrupted. attachments: type: array description: >- Files or images the visitor uploaded with this chat turn (web widget chat, chat preview). Only present on user messages that carried uploads. `url` is a temporary signed link valid for about one hour. items: type: object properties: id: type: string type: type: string enum: - image - file filename: type: string mime_type: type: string nullable: true size: type: integer nullable: true description: Bytes. description: type: string nullable: true description: Short vision caption for images, when available. url: type: string nullable: true description: Temporary signed download URL. timeline_seq: type: integer minimum: 1 description: Monotonic ordering key assigned when the turn started. logical_turn_id: type: string description: >- Stable turn identifier used to merge interim and final transcript updates. started_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time created_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time CallTranscriptFunctionCall: type: object required: - type - name - call_id - arguments additionalProperties: false properties: id: type: string description: Stable history item identifier. type: type: string const: function_call name: type: string call_id: type: string arguments: type: string description: JSON-encoded, public-safe tool arguments. timeline_seq: type: integer minimum: 1 description: Monotonic ordering key assigned when tool execution started. logical_turn_id: type: string description: Stable lifecycle identifier; equal to call_id for tool events. started_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time created_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time CallTranscriptFunctionOutput: type: object required: - type - name - call_id - output - is_error additionalProperties: false properties: id: type: string description: Stable history item identifier. type: type: string const: function_call_output name: type: string call_id: type: string output: type: string description: JSON-encoded or plain-text, public-safe tool result. is_error: type: boolean timeline_seq: type: integer minimum: 1 description: Monotonic ordering key assigned when tool execution ended. logical_turn_id: type: string description: Stable lifecycle identifier; equal to call_id for tool events. started_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time created_at: oneOf: - type: number description: Unix epoch seconds. - type: string format: date-time responses: Unauthorized: description: Missing, invalid, expired or revoked API key / access token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Invalid API key. Forbidden: description: >- The credential lacks the required scope or role, or the workspace does not have the required capability. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: scopeDenied: summary: Required scope is missing value: error: code: forbidden message: >- This API key is missing the required scope "assistants:write". apiAccessRequired: summary: API Access is not available value: error: code: api_access_required message: >- API Access is not available for this workspace. Review Settings → Plan. NotFound: description: Resource not found (or it belongs to another workspace). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: Assistant not found RateLimited: description: Too many requests. Retry after the indicated delay. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Too many requests. Retry after the indicated delay. RequestProtectionUnavailable: description: Request protection is temporarily unavailable. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Request protection is temporarily unavailable. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `billing:write`, `settings:write`, `platform:read`, `platform:write`; a `*:write` scope implies the matching `*:read`. Automation and dashboard endpoints also accept the legacy `calls:*` scope. Keys without scope restrictions have full access within the workspace's available capabilities. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.