{"openapi":"3.1.0","info":{"title":"yourang.ai External API V1","description":"\n# yourang.ai External API V1\n\nWelcome to the yourang.ai External API! This RESTful API provides secure programmatic access to your yourang.ai platform data and functionality, enabling seamless integration with your applications and workflows.\n\n## Getting Started\n\n### API Endpoint\nAll API requests should be made to:\n```\nhttps://api.yourang.ai/v1\n```\n\n### Authentication\nTo authenticate your requests, include your API key in the Authorization header of every request:\n\n```http\nAuthorization: Bearer your_api_key_here\n```\n\n**Important Notes:**\n- Your API key is unique to your organization and should be kept secure\n- API keys begin with the prefix `yk_`\n- Never expose your API key in client-side code or public repositories\n\n### Response Format\nAll responses are returned in JSON format with consistent structure for error handling and data presentation.\n\n## Need Help?\n- **Interactive Documentation:** Explore and test endpoints at [https://developers.yourang.ai](https://developers.yourang.ai)\n- **Support:** Contact our technical support team for assistance with integration\n\n# Changelog\n\nEvery change to v1, newest first. Entries are additive unless a line says BREAKING — the `/v1` URL is unaffected by them.\n\n## v1.23.0 - Call History: AI Provider That Served the Call\n\n*2026-09-28 - feature*\n\n- Added ai_provider to call history list and detail responses — the provider that actually served the call (openai, gemini, elevenlabs, amazon_nova, grok)\n- Added ai_provider_fallback_used: true when the agent's configured provider failed to connect and a fallback served the call instead\n- Both fields are null for calls that were not measured (pre-feature rows, or an AI leg that never completed)\n- Sourced from the per-call metrics blob, not from the configured-provider column — the two differ exactly when the fallback chain fires\n- Additive and backward compatible — existing fields and types are unchanged\n\n## v1.22.0 - Agent Gemini Backend Selection\n\n*2026-09-25 - feature*\n\n- Agent PATCH supports gemini_backend (vertex_ai/google_ai_studio)\n- vertex_ai is the platform default (EU-resident, best phone transcription); google_ai_studio is gemini-3.8-live\n- Omitted gemini_backend is unchanged. Explicit null follows the platform default\n- Inactive when another model is selected; parity with the dashboard Voice section and the admin MCP/CLI\n\n## v1.21.0 - Vertical Portal Subscription Access\n\n*2026-09-24 - feature*\n\n- Added GET /v1/portal-access/{portal_type} for Food, Beauty and Real Estate\n- Returns the authenticated organization's matching marketplace product, purchased variant and operational access decision\n- Responses include checked_at, valid_until and an effective entitlement expiry when applicable; decisions must be refreshed within 60 seconds\n- Preserves renewal grace periods, scheduled cancellations and manual grants until their effective expiry\n- No subscription is required to check access; API keys require READ or READ_WRITE and OAuth callers require a current persisted offline_access grant\n- Missing entitlements return HTTP 200 with operational_access=false; verification failures return HTTP 503\n- Returns an organization-specific purchase link on the platform or reseller frontend; subscription access does not grant additional role permissions\n\n## v1.20.0\n\n*2026-09-22 - feature*\n\n- Agent PATCH live_conversation_settings accepts pronunciations (reference term/say_as pairs, up to 20).\n- Within live_conversation_settings, omitting or nulling pronunciations preserves the agent's current list; an empty list clears it.\n\n## v1.19.0\n\n*2026-09-18 - feature*\n\n- Agent PATCH supports live_reasoning_effort (low/medium/high) and Grok reasoning_effort (none/high).\n- Model discovery includes the effective reasoning model, allowed levels and null-reset default.\n- Omitted effort is unchanged. Explicit null follows the platform default. Legacy GPT Live agents retain low.\n\n## v1.18.0 - Agent Voice Catalogue and GPT Live Settings\n\n*2026-09-18 - feature*\n\n- Added GET /v1/agents/models for organization-visible voice model availability\n- Added GET /v1/agents/voices with model filtering and pagination\n- Extended PATCH /v1/agents/{agent_id} with model, voice, language, conversation style and GPT Live listening settings\n- Voice/model writes reuse the existing provider compatibility and GPT Live rollout checks\n- No lifecycle, reasoning, cost or provider-account integration fields are exposed\n\n## v1.17.0 - Agent Updates (Prompt & First Message)\n\n*2026-07-31 - feature*\n\n- Added PATCH /v1/agents/{agent_id} to update an agent's conversation copy\n- Updatable fields: prompt_instructions and first_message (partial update)\n- Explicit null or a blank string clears the field and restores default behaviour\n- Empty request bodies, unknown fields and read-only fields are rejected with 400\n- Service failures preserve their status: 404 agent gone, 409 conflict, 500 write failed\n- New OAuth scopes agents:read / agents:write; agents:write gates this endpoint so a generic *:write consent cannot rewrite an agent prompt\n- agents:read is enforced on GET /v1/agents and GET /v1/agents/{id} — OAuth clients reading agents must request it (implied by agents:write); API keys unaffected\n- Requires an API key with READ_WRITE permission; other organizations' agents return 404\n- Call-routing fields (voice, provider, phone numbers, agent type) remain read-only by design\n\n## v1.16.0 - Contacts Secondary Phone\n\n*2026-07-24 - feature*\n\n- Added optional secondary_phone_number to contacts\n- Accepted on POST /v1/contacts and PUT /v1/contacts/by-phone/{phone_number}\n- Returned on all contact responses (list, detail, by-phone)\n- Searchable via search and filter (secondary_phone_number column)\n- Additive and backward compatible — field is optional and nullable\n\n## v1.15.0 - Usage API (Read-Only)\n\n*2026-07-20 - feature*\n\n- Added read-only Usage API for plan consumption monitoring\n- Implemented GET /v1/usage - Plan minutes summary for the current billing period\n- Response includes minutes_included, minutes_used, minutes_remaining, extra_minutes_used, and the billing period bounds\n- Same data that powers the dashboard usage bar, exposed in partner-safe minutes (no internal credit rates or pricing)\n- New OAuth scope usage:read gates the endpoint for OAuth tokens; API keys with READ/READ_WRITE hold it implicitly\n- 404 returned when the organization has no active plan\n\n## v1.14.0 - Call History Transfer Time & Status Filter\n\n*2026-07-02 - improvement*\n\n- Added transfer_time to GET /v1/call-history/{call_id} - timestamp of handoff to a human operator or external number (new optional field, non-breaking)\n- Fixed call_status filter on GET /v1/call-history to accept every real call status (Completed, Not Answered, Rejected, Failed, Busy, Voicemail, Ended In Queue)\n- BREAKING (minor): 'In Progress' and 'Cancelled' are no longer accepted by the call_status filter and now return 400 - these statuses never existed in call records, so previous requests using them always returned an empty list\n\n## v1.13.0 - Webhook Token Auth, Sorting & Polling Cursors\n\n*2026-06-12 - improvement*\n\n- WhatsApp webhook receiver now validates a per-organization secret URL token\n- Requests with invalid or missing tokens rejected with 401\n- Automatic migration of existing webhook registrations to tokenized URLs\n- Added sort (name, created_at) and search (name) to GET /v1/catalogues\n- Added sort (name, created_at, price) and search (name/SKU/description) to GET /v1/catalogues/items\n- Added sort (created_at, status, total_amount) with id tiebreaker to GET /v1/orders\n- Added created_after incremental polling cursor to GET /v1/orders\n- Documented the orders response envelope (prefer meta for pagination)\n- Added standard limit/offset pagination and meta object to GET /v1/events (grouped)\n- Added deterministic id tiebreaker to flat event list sorting\n- No breaking changes — all new query parameters are optional and response keys unchanged\n\n## v1.12.0 - Contact Lists, Wallet & Campaigns APIs\n\n*2026-06-12 - feature*\n\n- Added Contact Lists API for programmatic list management\n- Implemented GET /v1/contact-lists - List contact lists with pagination and search\n- Implemented GET /v1/contact-lists/{contact_list_id} - Get contact list details\n- Implemented GET /v1/contact-lists/{contact_list_id}/contacts - Paginated list members\n- Implemented POST /v1/contact-lists/{contact_list_id}/contacts - Add contacts to a list\n- Implemented DELETE /v1/contact-lists/{contact_list_id}/contacts - Remove contacts from a list\n- Contacts identifiable by contact_ids (UUID) and/or phone_numbers (E.164)\n- Optional auto_create flag creates contacts for unknown phone numbers in one call\n- Unknown identifiers reported in the response instead of failing the request\n- Added read-only Wallet API for credit monitoring\n- Implemented GET /v1/wallet - Balance, currency, and auto-topup status\n- Implemented GET /v1/wallet/transactions - Paginated transaction history\n- Transaction filters: transaction_type (ADD/CONSUME) and created_after (ISO-8601)\n- Added Campaigns API for outbound campaign orchestration\n- Implemented GET /v1/campaigns - List campaigns with status filter and search\n- Implemented GET /v1/campaigns/{campaign_id} - Campaign details with progress counters\n- Implemented GET /v1/campaigns/{campaign_id}/stats - Campaign statistics\n- Implemented POST /v1/campaigns/{campaign_id}/start|pause|resume|stop - Lifecycle management\n- Lifecycle validation errors surfaced as 400 with descriptive messages\n- Organization ownership validation on all new endpoints\n- READ permission for GET endpoints, READ_WRITE for membership and lifecycle operations\n- External-safe schemas expose only partner-relevant fields\n\n## v1.11.0\n\n*2026-05-25 - fix*\n\n- Fixed Call History list endpoint missing calls in polling integrations (Zapier)\n- Added deterministic default ordering (created_at DESC, id DESC) when sort is omitted\n- Added `id` tiebreaker to all explicit sorts for stable pagination across pages\n- Added `created_after` query parameter for incremental polling cursors\n- Recommended polling pattern: ?sort=-created_at&created_after=<last_seen>\n- Added composite index idx_call_history_org_created_id (organization_id, created_at, id) to keep the new query path cheap on high-volume orgs\n- No breaking changes — existing clients that pass `sort` see no behavioral difference beyond the id tiebreaker\n\n## v1.10.0\n\n*2026-03-31 - feature*\n\n- Added Orders Management API for external consumers\n- Implemented GET /v1/orders - List orders with pagination and status filtering\n- Implemented GET /v1/orders/{order_id} - Get order details with line items\n- Implemented PATCH /v1/orders/{order_id} - Update order status and notes\n- Status filtering: pending, confirmed, completed, cancelled, refused\n- Status transitions: pending → confirmed → completed, pending → refused\n- Requires status_reason when refusing orders\n- Cancellation restricted to customers via public order link\n- Automatic SMS notifications on status changes when configured\n- Order responses include line items with name, SKU, quantity, prices\n- Organization ownership validation on all order endpoints\n- READ permission for GET, READ_WRITE for PATCH\n- Added place_order tool endpoints to Agent Tools API\n- Implemented GET /v1/agents/{agent_id}/tools/place-order - Get config\n- Implemented PATCH /v1/agents/{agent_id}/tools/place-order - Update config\n- Added PlaceOrderConfigUpdate schema with type-safe validation\n- Changed Events update endpoint from PUT to PATCH for partial updates\n- Added extras field support to event updates for custom field values\n- Created ExternalEventUpdateRequest schema (separate from internal)\n- Added translate() to all Events API error messages for i18n compliance\n- Extracted tool config schemas to dedicated external schemas module\n- Moved schedule validation helpers to shared schema validators\n- Added translate() to all Agent Tools error messages for i18n compliance\n- Rich OpenAPI documentation for all new order endpoints\n- Request examples for all order status transitions\n- Complete error response documentation (400, 401, 403, 404)\n- Follows same auth/security patterns as existing external APIs\n\n## v1.9.0\n\n*2026-01-14 - feature*\n\n- Added Agents Management API for programmatic agent access\n- Implemented GET /v1/agents - List organization agents with pagination\n- Implemented GET /v1/agents/{agent_id} - Get complete agent configuration\n- Added agent type filtering (inbound/outbound) to list endpoint\n- Added pagination support (limit/offset) for agents list\n- Agent responses include AI provider, voice details, language config, prompts\n- Organization ownership validation on all agent endpoints\n- Added System Tools Management API with tool-specific endpoints\n- Implemented GET /v1/agents/{agent_id}/tools - List all tools for agent\n- Implemented 4 tool-specific GET endpoints for configuration details:\n- - GET /v1/agents/{agent_id}/tools/end-the-call (core tool)\n- - GET /v1/agents/{agent_id}/tools/make-reservation (8 config fields)\n- - GET /v1/agents/{agent_id}/tools/transfer-to-operator (2 config fields)\n- - GET /v1/agents/{agent_id}/tools/transfer-to-phone (2 config fields)\n- Implemented 3 tool-specific PATCH endpoints with simplified body requests:\n- - PATCH /v1/agents/{agent_id}/tools/make-reservation\n- - PATCH /v1/agents/{agent_id}/tools/transfer-to-operator\n- - PATCH /v1/agents/{agent_id}/tools/transfer-to-phone\n- Simplified request body: direct fields without configuration wrapper\n- Type-safe Pydantic schemas for each tool (MakeReservationConfigUpdate, etc.)\n- Tools automatically filtered by agent type (inbound/outbound)\n- Tools automatically filtered by organization business type\n- Tool configuration fields dynamically filtered by business type\n- Hotel-only fields (check-in/out times) filtered for non-hotel organizations\n- Security filtering prevents unauthorized config field updates\n- Mutual exclusivity checks prevent enabling conflicting tools\n- Phone number validation (E.164 format) for transfer_to_phone\n- WorkingHours/schedule format validation for all time-based fields\n- Config fields include metadata: type, required, default_value, current_value\n- All agent endpoints require API key authentication\n- READ permission for all GET endpoints (agents and tools)\n- READ_WRITE permission required for PATCH tool configuration\n- Organization ownership validated on all operations\n- 404 returned for both 'not found' and 'not owned' (prevents info disclosure)\n- Comprehensive logging with organization_id and api_key_id context\n- Rich OpenAPI documentation for all 10 new endpoints\n- Tool-specific documentation with precise field descriptions\n- Simplified body examples without configuration wrapper\n- Multiple request examples for each PATCH endpoint\n- Complete error response documentation (400, 401, 403, 404)\n- Example responses for all success and error scenarios\n- Mutual exclusivity documented in tool descriptions\n- Schedule/WorkingHours format examples in documentation\n- Follows same auth/security patterns as existing external APIs\n\n## v1.8.0\n\n*2025-12-04 - feature*\n\n- Added advanced filtering with OR (|) and AND (&) logic support\n- Implemented new 'filter' query parameter for Contacts API\n- Added custom fields support to Contacts API responses\n- Unified filtering system across internal and external APIs\n- Enhanced apply_sort_filter core function with OR groups support\n- Added _build_filter_condition helper for centralized filter logic\n- Updated parse_sort_filter_params to support | separator\n- Migrated contact selectors to use unified filtering system\n- Filter parameter takes precedence over search parameter\n- Backward compatible - existing 'search' parameter still works\n- Supports all operators: ~=, ==, !=, >, <, >=, <=, in\n- Comprehensive OpenAPI documentation with filter examples\n- Custom fields automatically included in all contact list responses\n\n## v1.7.0\n\n*2025-11-26 - feature*\n\n- Added Call History Summary endpoint for retrieving AI-generated call summaries\n- Implemented GET /v1/call-history/{call_id}/summary endpoint\n- Lightweight response returns only call ID and summary text\n- Follows existing call history API patterns and authorization\n- Proper organization ownership validation\n- Updated API documentation to v1.7.0\n- Updated OpenAPI specification to v1.7.0\n\n## v1.6.0\n\n*2025-11-04 - feature*\n\n- Added Playground Test Call API for testing outbound agent configurations\n- Implemented POST /v1/playground/test-call endpoint\n- Test calls require API key with WRITE and MAKE_OUTBOUND_CALLS permissions\n- Phone number verification ensures test calls only go to verified numbers\n- Agent validation checks for OUTBOUND type and required field configuration\n- Returns task ID for tracking asynchronous call execution\n- Comprehensive error handling with clear validation messages\n- Uses is_playground flag to distinguish test calls from production calls\n- Supports agent testing workflow before production deployment\n- Updated API documentation to v1.6.0\n- Updated OpenAPI specification to v1.6.0\n\n## v1.4.0\n\n*2025-09-24 - feature*\n\n- Added comprehensive Catalogues API with full CRUD operations\n- Implemented GET /v1/catalogues - List catalogues\n- Implemented POST /v1/catalogues - Create catalogue\n- Implemented GET /v1/catalogues/{catalogue_id} - Get catalogue\n- Implemented PUT /v1/catalogues/{catalogue_id} - Update catalogue\n- Implemented DELETE /v1/catalogues/{catalogue_id} - Delete catalogue\n- Implemented GET /v1/catalogues/items - List items with flexible filtering\n- Implemented POST /v1/catalogues/items - Create item (standalone or in catalogue)\n- Implemented GET /v1/catalogues/items/{item_id} - Get item by ID\n- Implemented PUT /v1/catalogues/items/{item_id} - Update item\n- Implemented DELETE /v1/catalogues/items/{item_id} - Delete item\n- Implemented POST /v1/catalogues/items/assign - Assign/unassign items to catalogues\n- Added support for standalone items (items not assigned to any catalogue)\n- Added automatic SKU generation for items when not provided\n- Added comprehensive pagination support for all list endpoints\n- Added organization-level access control and data isolation\n- Added rich item data model with SKU, price, currency, quantity, category\n- Added detailed OpenAPI documentation with examples for all endpoints\n- Added proper HTTP status codes and error handling\n- Maintained backward compatibility with existing API endpoints\n\n## v1.3.0\n\n*2025-09-22 - feature*\n\n- Added phone number-based endpoints for Contacts API\n- Implemented GET /v1/contacts/by-phone/{phone_number}\n- Implemented PUT /v1/contacts/by-phone/{phone_number}\n- Implemented DELETE /v1/contacts/by-phone/{phone_number}\n- Added support for using phone numbers as unique identifiers\n- Added call transcript endpoint to Call History API\n- Implemented GET /v1/call-history/{call_id}/transcript\n- Added ExternalCallTranscriptResponse schema for structured transcript data\n- Maintained backward compatibility with existing UUID-based endpoints\n- Maintained consistent authentication and authorization patterns\n- Added proper error handling for missing calls and insufficient permissions\n\n## v1.2.0\n\n*2025-09-15 - feature*\n\n- Added comprehensive Events API endpoints\n- Implemented events CRUD operations (GET, PUT, DELETE, PATCH)\n- Added events grouped by date functionality\n- Added event status management (approve/reject/confirm)\n- Integrated calendar services (Google/Apple Calendar)\n- Added proper organization-level access control for events\n- Updated external API documentation with events section\n\n## v1.1.0\n\n*2025-08-08 - improvement*\n\n- Clarified pagination and filtering behavior\n- Aligned response examples with actual payloads\n\n## v1.0.0\n\n*2024-07-31 - release*\n\n- Initial release of External API v1\n- Added health check endpoint\n- Added contacts CRUD operations\n- Implemented authentication system\n\n\n---\n**API Version:** v1 | **Documentation Version:** 1.23.0\n- **Release Date:** 2026-09-28","version":"1.23.0"},"servers":[{"url":"https://api.yourang.ai/v1","description":"yourang.ai Production API Server - Version V1 (Documentation v1.23.0)"}],"paths":{"/agents/models":{"get":{"tags":["Agent Catalogue"],"summary":"List available agent voice models","description":"List voice models available to the authenticated organization.","operationId":"list_agent_models_agents_models_get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of models to return.","default":50,"title":"Limit"},"description":"Maximum number of models to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of models to skip.","default":0,"title":"Offset"},"description":"Number of models to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"items":{"properties":{"value":{"type":"string","title":"Value","description":"Stable public model selector."},"label":{"type":"string","title":"Label","description":"Human-readable model name."},"description":{"type":"string","title":"Description","description":"Localized model description."},"disabled":{"type":"boolean","title":"Disabled","description":"Whether this model is unavailable."},"reasoning":{"anyOf":[{"properties":{"field":{"type":"string","title":"Field","description":"Agent configuration field to update."},"model":{"type":"string","title":"Model","description":"Effective backend model identifier."},"levels":{"items":{"type":"string"},"type":"array","title":"Levels","description":"Supported wire values, ordered by depth."},"default":{"type":"string","title":"Default","description":"Effective value when the setting is null."},"delegated":{"type":"boolean","title":"Delegated","description":"Whether reasoning runs in a delegated backend."}},"type":"object","required":["field","model","levels","default","delegated"]},{"type":"null"}]},"capabilities":{"additionalProperties":{"type":"string"},"type":"object","title":"Capabilities","description":"Supported configuration controls for this model."}},"type":"object","required":["value","label","description","disabled"],"description":"A model configuration and its organization-specific availability."},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/agents/voices":{"get":{"tags":["Agent Catalogue"],"summary":"List available agent voices","description":"List organization-visible voices with pagination.","operationId":"list_agent_voices_agents_voices_get","security":[{"API Key":[]}],"parameters":[{"name":"model_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by public model selector, for example 'base' or 'zeta'.","title":"Model Name"},"description":"Filter by public model selector, for example 'base' or 'zeta'."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of voices to return.","default":50,"title":"Limit"},"description":"Maximum number of voices to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of voices to skip.","default":0,"title":"Offset"},"description":"Number of voices to skip."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"items":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Voice identifier used by agent configuration."},"custom_name":{"type":"string","title":"Custom Name","description":"Display name of the voice."},"description":{"type":"string","title":"Description","description":"Localized voice description."},"file":{"properties":{"file_name":{"type":"string","title":"File Name","description":"Audio preview filename."},"content_size":{"type":"integer","title":"Content Size","description":"Audio preview size in bytes."},"content_type":{"type":"string","title":"Content Type","description":"Audio preview MIME type."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Signed or public preview URL."}},"type":"object","required":["file_name","content_size","content_type"],"description":"Audio preview metadata."},"ai_provider":{"type":"string","title":"Ai Provider","description":"Public model selector associated with this voice."},"provider_voice_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Voice Key","description":"Stable provider voice identifier."},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Voice gender classification."},"language_characterization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language Characterization","description":"Localized language or regional characterization."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 voice language tag."},"generation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Generation","description":"'legacy' for a superseded provider voice generation kept for continuity, 'current' for the generation the provider ships today; null when the provider makes no such distinction."},"recommended_for":{"items":{"type":"string"},"type":"array","title":"Recommended For","description":"ISO 639-1 codes a listening test cleared for this voice. Empty means not evaluated yet, never unsupported."}},"type":"object","required":["id","custom_name","description","file","ai_provider"],"description":"A voice that can be assigned to an agent."},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/agents/":{"get":{"tags":["Agents"],"summary":"List organization agents","description":"Retrieve all agents for the authenticated organization.\n\n    Returns a paginated list of agents with basic information including:\n    - Agent ID and name\n    - Agent type (inbound/outbound)\n    - Active status\n    - AI provider information\n    - First message configuration\n    - Created/updated timestamps\n\n    Filtering and pagination:\n    - Optional filter by agent type (inbound or outbound)\n    - Sorted by newest agent first (created_at DESC)\n    - Default limit: 50 agents per page (max 100)\n    - Use offset for pagination\n\n    Authentication:\n    - API key with READ or READ_WRITE permission, or\n    - OAuth access token granted the `agents:read` scope","operationId":"list_agents_agents__get","security":[{"API Key":[]}],"parameters":[{"name":"agent_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(inbound|outbound|meta)$"},{"type":"null"}],"description":"Filter agents by type (inbound, outbound or meta)","title":"Agent Type"},"description":"Filter agents by type (inbound, outbound or meta)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of agents to return (max 100)","default":50,"title":"Limit"},"description":"Maximum number of agents to return (max 100)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of agents to skip for pagination","default":0,"title":"Offset"},"description":"Number of agents to skip for pagination"}],"responses":{"200":{"description":"Successfully retrieved agents list","content":{"application/json":{"schema":{"title":"Response List Agents Agents  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"agent_type":{"type":"string"},"agent_type_display_name":{"type":"string"},"is_active":{"type":"boolean"},"ai_provider":{"type":"string","nullable":true},"ai_provider_display_name":{"type":"string","nullable":true},"first_message":{"type":"string","nullable":true},"disable_first_message_interruptions":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"550e8400-e29b-41d4-a716-446655440000","name":"Reception Assistant","agent_type":"inbound","agent_type_display_name":"Inbound","is_active":true,"ai_provider":"openai","ai_provider_display_name":"OpenAI","disable_first_message_interruptions":false,"created_at":"2024-01-15T10:00:00Z","updated_at":"2024-01-20T12:30:00Z"}],"meta":{"limit":50,"offset":0,"total_items":3}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/agents/{agent_id}":{"get":{"tags":["Agents"],"summary":"Get agent details","description":"Retrieve detailed information for a specific agent.\n\n    Returns complete agent configuration including:\n    - Agent ID and name\n    - Agent type (inbound/outbound) and active status\n    - AI provider and selected voice details\n    - Prompt instructions and first message settings\n    - Language configuration (default and supported languages)\n    - Verified caller ID (for outbound agents)\n    - Created/updated timestamps\n\n    The agent must belong to your organization. Attempting to access an agent\n    from another organization will return 404.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission, or\n    - OAuth access token granted the `agents:read` scope","operationId":"get_agent_agents__agent_id__get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved agent details","content":{"application/json":{"schema":{"title":"Response Get Agent Agents  Agent Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"agent_type":{"type":"string"},"agent_type_display_name":{"type":"string"},"is_active":{"type":"boolean"},"ai_provider":{"type":"string","nullable":true},"ai_provider_display_name":{"type":"string","nullable":true},"first_message":{"type":"string","nullable":true},"disable_first_message_interruptions":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","organization_id":"660e9500-f39c-52e5-b827-557766550001","name":"Reception Assistant","agent_type":"inbound","agent_type_display_name":"Inbound","is_active":true,"ai_provider":"openai","ai_provider_display_name":"OpenAI","ai_provider_model_name":"base","selected_voice":"770e9611-g49d-63f6-c938-668877661112","voice":{"id":"770e9611-g49d-63f6-c938-668877661112","custom_name":"Sarah - Professional","ai_provider":"openai"},"prompt_instructions":"Be polite and professional. Help guests with check-in, check-out, and general inquiries.","disable_first_message_interruptions":false,"default_language":"en","supported_languages":["en","it","fr"],"created_at":"2024-01-15T10:00:00Z","updated_at":"2024-01-20T12:30:00Z"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Agents"],"summary":"Update agent conversation and voice settings","description":"Update the conversation and voice configuration of a specific agent.\n\n    Updatable fields (partial update — only the fields you send are changed):\n    - `prompt_instructions`: the custom instructions driving the agent behaviour\n    - `first_message`: the message the agent says when the conversation starts\n    - `ai_provider`: public voice model selector, including `zeta` for GPT Live 1\n    - `selected_voice`: compatible voice ID; the provider is validated from the voice\n    - `default_language` and `supported_languages`: language configuration\n    - `conversation_style`: tone, formality, response length and pace\n    - `live_conversation_settings`: GPT Live backchannels, pauses and reference\n      pronunciations. Within this object, omitting or nulling `pronunciations`\n      keeps the agent's current list; sending an empty list clears it\n    - `live_reasoning_effort`: GPT Live delegated backend, low/medium/high; null follows medium\n    - `reasoning_effort`: Grok only, none/high; null follows the platform default\n    - `gemini_backend`: Gemini only, vertex_ai/google_ai_studio; null follows the platform default\n\n    Effort preferences and the Gemini backend remain stored but inactive when another model is selected.\n    Read `/agents/models` for supported effort levels and the effective backend model.\n\n    Sending an explicit `null` clears nullable configuration fields. A blank\n    string clears only `prompt_instructions` and `first_message`; blank model,\n    voice, language, style or Live settings values are rejected. Omitting a\n    field leaves it untouched. An empty body is rejected with 400.\n\n    Phone routing, caller IDs, and agent type remain internal lifecycle settings.\n    Voice/model writes use the same provider compatibility and GPT Live rollout\n    checks as the dashboard.\n\n    Unknown fields are rejected with 400, so a typo (or an attempt to change a\n    read-only field) never looks like a successful update.\n\n    The agent must belong to your organization. Attempting to update an agent\n    from another organization will return 404.\n\n    Authentication:\n    - API key with READ_WRITE permission, or\n    - OAuth access token granted the `agents:write` scope","operationId":"update_agent_endpoint_agents__agent_id__patch","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prompt_instructions":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Prompt Instructions","description":"Custom prompt instructions driving the agent's behaviour during a call. Send null to clear them and fall back to the default prompt."},"first_message":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"First Message","description":"Initial message the agent says when the conversation starts. Send null to clear it (the agent opens the conversation on its own)."},"ai_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Provider","description":"Voice model selector, such as 'base' (OpenAI), 'beta' (Gemini), or 'zeta' (GPT Live 1). Availability is validated by the service."},"selected_voice":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Selected Voice","description":"ID of the voice to use; its provider is validated automatically."},"default_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Language","description":"ISO 639-1 default language for the agent."},"supported_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Supported Languages","description":"ISO 639-1 languages supported by the agent."},"conversation_style":{"anyOf":[{"properties":{"tone":{"type":"string","enum":["friendly","warm","professional","direct"],"description":"Conversation tone."},"formality":{"type":"string","enum":["informal","balanced","formal"],"description":"Conversation formality."},"response_length":{"type":"string","enum":["concise","balanced","detailed"],"description":"Preferred response length."},"pace":{"type":"string","enum":["relaxed","natural","brisk"],"description":"Conversation pace."},"custom_note":{"type":"string","maxLength":500,"title":"Custom Note","description":"Optional style note.","default":""}},"additionalProperties":false,"type":"object","required":["tone","formality","response_length","pace"],"description":"Public conversation style controls."},{"type":"null"}],"description":"Conversation tone, formality, response length and pace preferences."},"live_reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Live Reasoning Effort","description":"GPT Live delegated reasoning. Omit to preserve; null resets to medium. Inactive on other models."},"reasoning_effort":{"anyOf":[{"type":"string","enum":["none","high"]},{"type":"null"}],"title":"Reasoning Effort","description":"Grok reasoning. Omit to preserve; null follows the platform default. Inactive on other models."},"gemini_backend":{"anyOf":[{"type":"string","enum":["vertex_ai","google_ai_studio"]},{"type":"null"}],"title":"Gemini Backend","description":"Gemini Live backend: 'vertex_ai' (EU-resident, best phone transcription, platform default) or 'google_ai_studio' (gemini-3.8-live, newest model). Omit to preserve; null follows the platform default. Inactive on other models."},"live_conversation_settings":{"anyOf":[{"properties":{"backchannels":{"type":"string","enum":["off","subtle","natural","expressive"],"description":"Backchannel level."},"pauses":{"type":"string","enum":["natural","patient"],"description":"Pause behavior."},"pronunciations":{"anyOf":[{"items":{"properties":{"term":{"type":"string","maxLength":60,"minLength":1,"title":"Term","description":"Word or phrase as it is written (a brand, a dish, a surname)."},"say_as":{"type":"string","maxLength":120,"minLength":1,"title":"Say As","description":"How to say it, spelled phonetically (for example \"NYOK-kee\")."}},"additionalProperties":false,"type":"object","required":["term","say_as"],"description":"One spoken form for a word the voice model mispronounces."},"type":"array","maxItems":20},{"type":"null"}],"title":"Pronunciations","description":"Reference pronunciations read out in the voice session instructions. Omit or send null to keep the agent's current pronunciations unchanged; send an empty list to clear them."}},"additionalProperties":false,"type":"object","required":["backchannels","pauses"],"description":"Public GPT Live listening controls."},{"type":"null"}],"description":"GPT Live backchannel, pause and reference pronunciation preferences. Within this object, omitting or nulling `pronunciations` keeps the agent's current list; an empty list clears it."}},"additionalProperties":false,"type":"object","description":"Partial update of an agent's conversation copy.\n\nOnly the fields present in the request body are changed. Sending an\nexplicit ``null`` clears the field (the agent falls back to its default\nbehaviour); omitting the field leaves it untouched.","example":{"ai_provider":"zeta","conversation_style":{"custom_note":"","formality":"balanced","pace":"natural","response_length":"concise","tone":"warm"},"default_language":"it","first_message":"Hello! How can I help you today?","live_conversation_settings":{"backchannels":"natural","pauses":"patient"},"prompt_instructions":"You are the reception assistant. Be polite and concise. Help guests with check-in, check-out and general inquiries.","selected_voice":"770e9611-49d6-3f6c-9386-688776611112","supported_languages":["it","en"]}}}}},"responses":{"200":{"description":"Successfully updated the agent","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"organization_id":{"type":"string","format":"uuid","title":"Organization Id"},"name":{"type":"string","title":"Name"},"agent_type":{"type":"string","enum":["inbound","outbound","meta","whatsapp"],"description":"Dynamically generated from the Agent model's AgentTypeEnum."},"is_active":{"type":"boolean","title":"Is Active"},"selected_voice":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Selected Voice"},"verified_caller_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Verified Caller Id"},"inbound_phone_number_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Inbound Phone Number Id","description":"Organization phone number bound as the inbound number for this agent (inbound agents only)"},"outbound_phone_number_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Outbound Phone Number Id","description":"Organization phone number bound as the outbound number for this agent (outbound agents only)"},"prompt_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt Instructions"},"conversation_style":{"anyOf":[{"properties":{"tone":{"type":"string","enum":["friendly","warm","professional","direct"]},"formality":{"type":"string","enum":["informal","balanced","formal"]},"response_length":{"type":"string","enum":["concise","balanced","detailed"]},"pace":{"type":"string","enum":["relaxed","natural","brisk"]},"custom_note":{"type":"string","maxLength":500,"title":"Custom Note","default":""}},"additionalProperties":false,"type":"object","required":["tone","formality","response_length","pace"]},{"type":"null"}]},"live_reasoning_effort":{"anyOf":[{"type":"string","enum":["low","medium","high"]},{"type":"null"}],"title":"Live Reasoning Effort","description":"GPT Live delegated reasoning: low, medium or high. Omitted updates preserve the value; null follows medium. New agents default to medium; legacy agents retain low."},"live_conversation_settings":{"anyOf":[{"properties":{"backchannels":{"type":"string","enum":["off","subtle","natural","expressive"]},"pauses":{"type":"string","enum":["natural","patient"]},"pronunciations":{"items":{"properties":{"term":{"type":"string","maxLength":60,"minLength":1,"title":"Term","description":"Word or phrase as it is written (a brand, a dish, a surname)"},"say_as":{"type":"string","maxLength":120,"minLength":1,"title":"Say As","description":"How to say it, spelled phonetically (for example \"NYOK-kee\")"}},"additionalProperties":false,"type":"object","required":["term","say_as"],"description":"One spoken form for a word the voice model mispronounces."},"type":"array","maxItems":20,"title":"Pronunciations","description":"Reference pronunciations read out in the voice session instructions; keep the list short and add a term only when you hear it mispronounced"}},"additionalProperties":false,"type":"object","required":["backchannels","pauses"]},{"type":"null"}]},"first_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Message"},"disable_first_message_interruptions":{"type":"boolean","title":"Disable First Message Interruptions"},"first_message_delay_seconds":{"type":"number","title":"First Message Delay Seconds"},"max_call_duration_minutes":{"type":"integer","title":"Max Call Duration Minutes"},"is_call_recording_enabled":{"type":"boolean","title":"Is Call Recording Enabled"},"is_transcript_saving_enabled":{"type":"boolean","title":"Is Transcript Saving Enabled","description":"Whether to save call transcripts for this agent"},"include_past_calls_in_context":{"type":"boolean","title":"Include Past Calls In Context","description":"Whether to inject summaries of the caller's recent past calls into the AI context","default":false},"past_calls_count":{"type":"integer","title":"Past Calls Count","description":"How many of the caller's most recent past calls to include in context (1-5)","default":3},"auto_hide_abusive_comments":{"type":"boolean","title":"Auto Hide Abusive Comments","description":"Meta agents only: automatically hide clearly-abusive/spam comments instead of replying."},"comment_moderation_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Moderation Instructions","description":"Meta agents only: business-specific rules describing which comments to hide vs keep."},"comment_reply_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Reply Instructions","description":"Meta agents only: custom prompt instructions for PUBLIC comment replies. Falls back to prompt_instructions (the DM prompt) when empty."},"dm_reply_mode":{"type":"string","enum":["agent","workflow","off"],"description":"Meta agents only: who answers inbound DMs — 'agent' (always-on auto-reply), 'workflow' (a Meta DM workflow owns replies), or 'off' (no DM auto-reply).","default":"agent"},"dm_debounce_seconds":{"type":"integer","title":"Dm Debounce Seconds","description":"Meta and WhatsApp agents only: seconds to wait after the customer's last DM before replying once to the whole burst (0-1800, 0 = instant per-message reply).","default":0},"whatsapp_handoff_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp Handoff Instructions","description":"WhatsApp agents only: business-specific rules for when to hand a conversation off to a human team member."},"whatsapp_greeting_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp Greeting Text","description":"WhatsApp agents only: fixed greeting line prepended to the agent's first reply in a conversation."},"whatsapp_no_reply_rules":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Whatsapp No Reply Rules","description":"WhatsApp agents only: business rules describing messages the agent must leave unanswered (fed to the model next to the built-in no-reply guidance: empty/emoji-only messages, acknowledgements after our reply, goodbyes)."},"user_silence_warning_seconds":{"type":"integer","title":"User Silence Warning Seconds"},"user_silence_hangup_seconds":{"type":"integer","title":"User Silence Hangup Seconds"},"user_silence_prompt_message":{"type":"string","title":"User Silence Prompt Message"},"amd_enabled":{"type":"boolean","title":"Amd Enabled"},"amd_action":{"type":"string","enum":["hangup","leave_message"]},"amd_voicemail_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amd Voicemail Message"},"default_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Language"},"supported_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Supported Languages"},"ai_temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Temperature","description":"AI model temperature (0.0-2.0)"},"ai_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Speed","description":"AI speech speed multiplier (0.25-1.5)"},"turn_detection_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Turn Detection Mode","description":"Turn detection mode: 'semantic_vad' or 'server_vad'"},"vad_eagerness":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vad Eagerness","description":"VAD eagerness level: 'auto', 'low', 'medium', 'high'"},"vad_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vad Threshold","description":"VAD activation threshold (0.0-1.0)"},"vad_silence_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Vad Silence Duration Ms","description":"Duration of silence in ms to detect end of speech (100-2000)"},"min_speech_duration_ms":{"type":"integer","title":"Min Speech Duration Ms","description":"Platform-side barge-in noise gate: while the agent speaks, interruptions shorter than this many ms never reach the AI (0-1000, 0 = off).","default":250},"reasoning_effort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning Effort","description":"Reasoning effort: 'none' (fast) or 'high' (thinks before replying). Grok-only."},"call_summary_custom_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Summary Custom Prompt","description":"The agent's post-call summary instructions; null keeps the standard default (call_summary_default_prompt)"},"call_summary_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Summary Language","description":"ISO 639-1 language the post-call summary is written in (falls back to the agent's default language)"},"call_summary_default_prompt":{"type":"string","title":"Call Summary Default Prompt","description":"The standard post-call summary instructions, pre-filled into the editor; edit to customize, or leave as-is to keep using the live default. Read-only (same for every agent).","default":"Write a concise business summary of the call.\n\n- For outbound calls, the first sentence MUST state that the agent called the customer (never the reverse).\n- For inbound calls, the first sentence MUST state that the customer called (never the reverse).\n- Describe what the agent did: actions taken, information provided, limitations, and any transfers or escalations.\n- State the resolution, the next steps, or the lack thereof.\n- Be specific about products, policies, constraints, contact methods and time frames when they are present.\n- If the caller spoke another language, note that explicitly.\n- Keep a professional, neutral tone: no emojis, no bullet points, no generic fillers (e.g. \"great service\", \"positive experience\").\n- Focus on the actual content and interaction; ignore small talk, repetitions and obvious transcription noise."},"gemini_backend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemini Backend","description":"Gemini backend: 'vertex_ai' (default) or 'google_ai_studio' (gemini-3.8-live)"},"ai_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Provider"},"ai_provider_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ai Provider Display Name"},"agent_type_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Type Display Name"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"voice":{"anyOf":[{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"custom_name":{"type":"string","title":"Custom Name"},"description":{"type":"string","title":"Description"},"file":{"properties":{"file_name":{"type":"string","title":"File Name"},"content_size":{"type":"integer","title":"Content Size"},"content_type":{"type":"string","title":"Content Type"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","readOnly":true}},"type":"object","required":["file_name","content_size","content_type","url"],"description":"Response model for retrieving file details.","example":{"content_size":2048,"content_type":"text/plain","file_name":"example.txt","url":"https://s3.example.com/some-generated-id"}},"ai_provider":{"type":"string","title":"Ai Provider"},"provider_voice_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Voice Key","description":"Stable provider voice identifier used on the wire; custom_name is presentation-only."},"gender":{"anyOf":[{"type":"string","enum":["male","female","neutral"]},{"type":"null"}],"title":"Gender","description":"Explicit catalogue metadata; null means the product has no classification."},"language_characterization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language Characterization","description":"Localized regional or primary-language characterization; not a hard language restriction."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 language tag of the voice (e.g. 'it', 'ar'); null if multilingual"},"generation":{"anyOf":[{"type":"string","enum":["legacy","current"]},{"type":"null"}],"title":"Generation","description":"'legacy' for a superseded provider generation kept for continuity, 'current' for the generation the provider ships today; null when the provider makes no such distinction."},"recommended_for":{"items":{"type":"string"},"type":"array","title":"Recommended For","description":"ISO 639-1 codes a listening test cleared for this voice. Empty means not evaluated yet, never unsupported."}},"type":"object","required":["id","custom_name","description","file","ai_provider"],"example":{"ai_provider":"base","custom_name":"Marco","description":"Una voce equilibrata e versatile adatta alla maggior parte delle applicazioni","file":{"content_size":1024,"content_type":"audio/mpeg","file_name":"voice.mp3","id":"aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f","url":"https://s3.example.com/some-generated-id/logo.png"},"id":"aaaabf4b-0c8d-4e2b-9c3f-1a2b3c4d5e6f","language":"it","recommended_for":[]}},{"type":"null"}]}},"type":"object","required":["id","organization_id","name","agent_type","is_active","selected_voice","verified_caller_id","prompt_instructions","first_message","disable_first_message_interruptions","first_message_delay_seconds","max_call_duration_minutes","is_call_recording_enabled","is_transcript_saving_enabled","auto_hide_abusive_comments","user_silence_warning_seconds","user_silence_hangup_seconds","user_silence_prompt_message","amd_enabled","amd_action","amd_voicemail_message","default_language","supported_languages","ai_provider","ai_provider_display_name","agent_type_display_name","created_at","updated_at"],"description":"Schema for agent response."},{"type":"null"}]},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}},"409":{"description":"The update conflicts with another agent"},"500":{"description":"The update could not be persisted"}}}},"/agents/{agent_id}/tools":{"get":{"tags":["Agent Tools"],"summary":"List agent tools","description":"Retrieve all tools available for a specific agent.\n\n    Returns a list of tools with their configuration status including:\n    - Tool name and display name\n    - Tool description and category\n    - Whether the tool is enabled for this agent\n    - Whether the tool is configured (has required configuration)\n    - Tool scope (system or organization)\n    - Whether the tool can be disabled\n\n    Tools are automatically filtered based on:\n    - Agent type (inbound vs outbound)\n    - Organization business type (hotel, restaurant, rental, etc.)\n    - Beta access features\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_agent_tools_agents__agent_id__tools_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved tools list","content":{"application/json":{"schema":{"title":"Response List Agent Tools Agents  Agent Id  Tools Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"}}}}}},"example":{"ok":true,"data":[{"name":"end_the_call","display_name":"End The Call","description":"End the conversation professionally","category":"core","category_display_name":"Core Functions","scope":"system","enabled":true,"is_configured":true,"can_disable":false,"icon_url":"","version":"1.0.0"},{"name":"make_reservation","display_name":"Make Reservation","description":"Create reservations and send confirmation SMS","category":"reservation","category_display_name":"Reservation Management","scope":"system","enabled":false,"is_configured":true,"can_disable":true,"icon_url":"","version":"1.0.0"}]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/agents/{agent_id}/tools/end-the-call":{"get":{"tags":["Agent Tools"],"summary":"Get end_the_call tool configuration","description":"Retrieve configuration for the end_the_call tool.\n\n    This is a core tool that allows the agent to end conversations professionally.\n    It is always enabled and cannot be disabled or configured.\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_end_the_call_config_agents__agent_id__tools_end_the_call_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved end_the_call configuration","content":{"application/json":{"schema":{"title":"Response Get End The Call Config Agents  Agent Id  Tools End The Call Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"end_the_call","display_name":"End The Call","description":"End the conversation professionally","category":"core","enabled":true,"is_configured":true,"can_disable":false,"config_fields":[]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/agents/{agent_id}/tools/make-reservation":{"get":{"tags":["Agent Tools"],"summary":"Get make_reservation tool configuration","description":"Retrieve configuration for the make_reservation tool.\n\n    Returns complete configuration including:\n    - SMS notification settings\n    - Reservation duration and hours\n    - Guest information requirements\n    - Check-in/check-out times (hotel only)\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_make_reservation_config_agents__agent_id__tools_make_reservation_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved make_reservation configuration","content":{"application/json":{"schema":{"title":"Response Get Make Reservation Config Agents  Agent Id  Tools Make Reservation Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"make_reservation","display_name":"Make Reservation","enabled":false,"is_configured":true,"config_fields":[{"name":"send_sms","current_value":true},{"name":"reservation_hours","current_value":{"monday":["09:00 - 18:00"],"tuesday":["09:00 - 18:00"]}}]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Agent Tools"],"summary":"Update make_reservation tool configuration","description":"Update configuration for the make_reservation tool.\n\n    Allows you to configure:\n    - Enable/disable the tool\n    - SMS notification settings (send_sms, sms_text template)\n    - Reservation duration and hours\n    - Guest information requirements\n    - Check-in/check-out times (hotel only)\n\n    All fields are optional - only provide the fields you want to update.\n\n    Schedule format for reservation_hours:\n    ```json\n    {\n      \"monday\": [\"09:00 - 12:00\", \"14:00 - 18:00\"],\n      \"tuesday\": [\"09:00 - 18:00\"],\n      \"wednesday\": [],\n      ...\n    }\n    ```\n\n    SMS template placeholders — all optional, use any subset:\n    - {nome_cliente}, {data_inizio}, {data_fine}\n    - {link} (edit/cancel reservation link), {numero_ospiti} (party size)\n\n    An unknown placeholder is left as-is in the delivered message.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_make_reservation_config_agents__agent_id__tools_make_reservation_patch","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Enabled","description":"Enable or disable the tool"},"send_sms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send Sms","description":"Send SMS confirmation when reservation is made"},"allow_overlapping_reservations":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allow Overlapping Reservations","description":"Allow overlapping reservations"},"include_guests":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Guests","description":"Request number of guests in the reservation"},"sms_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms Text","description":"SMS template. All placeholders are optional: {nome_cliente}, {data_inizio}, {data_fine}, {link}, {numero_ospiti}. Unknown placeholders are left as-is in the delivered message"},"reservation_duration_minutes":{"anyOf":[{"type":"integer","maximum":480.0,"minimum":15.0},{"type":"null"}],"title":"Reservation Duration Minutes","description":"Default reservation duration in minutes (15-480)"},"reservation_hours":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Reservation Hours","description":"Working hours for accepting reservations (schedule format: {monday: ['09:00 - 18:00'], ...})"},"default_checkin_time":{"anyOf":[{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},{"type":"null"}],"title":"Default Checkin Time","description":"Default check-in time in HH:MM format (hotel only)"},"default_checkout_time":{"anyOf":[{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},{"type":"null"}],"title":"Default Checkout Time","description":"Default check-out time in HH:MM format (hotel only)"},"custom_fields":{"anyOf":[{"items":{"properties":{"field_name":{"type":"string","maxLength":100,"minLength":1,"title":"Field Name","description":"Internal field identifier (snake_case, e.g., 'allergies', 'room_preference')"},"display_name":{"type":"string","maxLength":200,"minLength":1,"title":"Display Name","description":"Human-readable label shown to the user (e.g., 'Food Allergies')"},"field_type":{"type":"string","title":"Field Type","description":"Data type: string, number, boolean, date, email, phone, url","default":"string"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Description of the field, used as instruction for the AI agent"},"is_required":{"type":"boolean","title":"Is Required","description":"Whether the AI must collect this field before making the reservation","default":false}},"type":"object","required":["field_name","display_name"],"description":"Schema for a single custom field definition in make_reservation tool."},"type":"array"},{"type":"null"}],"title":"Custom Fields","description":"Custom fields the AI will collect during reservations. Each field defines a piece of information to gather from the customer."}},"type":"object","description":"Schema for updating make_reservation tool configuration."},"examples":{"enable_tool":{"summary":"Enable tool with basic config","value":{"is_enabled":true,"send_sms":true}},"update_hours":{"summary":"Update reservation hours","value":{"reservation_hours":{"monday":["09:00 - 18:00"],"tuesday":["09:00 - 18:00"],"wednesday":["09:00 - 18:00"],"thursday":["09:00 - 18:00"],"friday":["09:00 - 18:00"],"saturday":"Close all day","sunday":"Close all day"}}},"complete_configuration":{"summary":"All available configuration fields","value":{"is_enabled":true,"send_sms":true,"allow_overlapping_reservations":true,"include_guests":false,"sms_text":"Gentile {nome_cliente}, la sua prenotazione è stata confermata dal {data_inizio} al {data_fine}. Può modificarla o cancellarla cliccando: {link}","reservation_duration_minutes":60,"reservation_hours":{"monday":"Open all day","tuesday":"Open all day","wednesday":"Open all day","thursday":"Open all day","friday":"Open all day","saturday":"Close all day","sunday":"Close all day"},"default_checkin_time":"15:00","default_checkout_time":"11:00"}}}}}},"responses":{"200":{"description":"Successfully updated configuration","content":{"application/json":{"schema":{"title":"Response Update Make Reservation Config Agents  Agent Id  Tools Make Reservation Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"make_reservation","enabled":true,"config_fields":[{"name":"send_sms","current_value":true}]}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/agents/{agent_id}/tools/place-order":{"get":{"tags":["Agent Tools"],"summary":"Get place_order tool configuration","description":"Retrieve configuration for the place_order tool.\n\n    Returns complete configuration including:\n    - SMS notification settings (creation, confirmation, refusal, cancellation)\n    - SMS templates with placeholder support\n    - Default currency\n    - Stock management settings\n    - Auto-accept configuration\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_place_order_config_agents__agent_id__tools_place_order_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved place_order configuration","content":{"application/json":{"schema":{"title":"Response Get Place Order Config Agents  Agent Id  Tools Place Order Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"place_order","display_name":"Place Order","enabled":false,"is_configured":true,"config_fields":[{"name":"send_sms","current_value":true},{"name":"default_currency","current_value":"EUR"},{"name":"auto_accept","current_value":false}]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Agent Tools"],"summary":"Update place_order tool configuration","description":"Update configuration for the place_order tool.\n\n    Allows you to configure:\n    - Enable/disable the tool\n    - SMS notification settings (creation, confirmation, refusal, cancellation)\n    - SMS templates with placeholders\n    - Default currency (3-letter ISO code)\n    - Stock management (ignore_stock)\n    - Auto-accept orders without manual approval\n\n    SMS template placeholders:\n    - Creation: {customer_name}, {customer_surname}, {order_id}, {link}\n    - Refusal: additionally {reason}\n\n    All fields are optional - only provide the fields you want to update.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_place_order_config_agents__agent_id__tools_place_order_patch","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Enabled","description":"Enable or disable the tool"},"send_sms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send Sms","description":"Send SMS when an order is created"},"sms_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms Template","description":"SMS template for order creation. Must include {customer_name} and {order_id}. Optional placeholders: {customer_surname}, {link}"},"default_currency":{"anyOf":[{"type":"string","maxLength":3,"minLength":3},{"type":"null"}],"title":"Default Currency","description":"Default currency as 3-letter ISO code (e.g., EUR, USD)"},"ignore_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Ignore Stock","description":"If enabled, orders are placed without checking stock availability"},"auto_accept":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Auto Accept","description":"If enabled, orders are automatically confirmed without manual approval"},"send_sms_on_confirmation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send Sms On Confirmation","description":"Send SMS when an order is confirmed"},"sms_confirmation_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms Confirmation Template","description":"SMS template for order confirmation. Placeholders: {customer_name}, {customer_surname}, {order_id}, {link}"},"send_sms_on_refusal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send Sms On Refusal","description":"Send SMS when an order is refused"},"sms_refusal_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms Refusal Template","description":"SMS template for order refusal. Placeholders: {customer_name}, {customer_surname}, {order_id}, {link}, {reason}"},"send_sms_on_cancellation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send Sms On Cancellation","description":"Send SMS when an order is cancelled"},"sms_cancellation_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sms Cancellation Template","description":"SMS template for order cancellation. Placeholders: {customer_name}, {customer_surname}, {order_id}, {link}"}},"type":"object","description":"Schema for updating place_order tool configuration."},"examples":{"enable_tool":{"summary":"Enable tool with basic config","value":{"is_enabled":true,"send_sms":true}},"update_currency":{"summary":"Update default currency","value":{"default_currency":"USD"}},"complete_configuration":{"summary":"All available configuration fields","value":{"is_enabled":true,"send_sms":true,"sms_template":"Gentile {customer_name} {customer_surname}, il tuo ordine #{order_id} è stato creato!\n\nVisualizza il tuo ordine: {link}","default_currency":"EUR","ignore_stock":false,"auto_accept":false,"send_sms_on_confirmation":true,"sms_confirmation_template":"Gentile {customer_name}, il tuo ordine #{order_id} è stato confermato!","send_sms_on_refusal":true,"sms_refusal_template":"Gentile {customer_name}, il tuo ordine #{order_id} è stato rifiutato. Motivo: {reason}","send_sms_on_cancellation":false,"sms_cancellation_template":"Gentile {customer_name}, il tuo ordine #{order_id} è stato annullato."}}}}}},"responses":{"200":{"description":"Successfully updated configuration","content":{"application/json":{"schema":{"title":"Response Update Place Order Config Agents  Agent Id  Tools Place Order Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"place_order","enabled":true,"config_fields":[{"name":"send_sms","current_value":true},{"name":"default_currency","current_value":"EUR"}]}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/agents/{agent_id}/tools/transfer-to-operator":{"get":{"tags":["Agent Tools"],"summary":"Get transfer_to_mobile_operator tool configuration","description":"Retrieve configuration for the transfer_to_mobile_operator tool.\n\n    This tool transfers calls to human operators. Configuration includes:\n    - Operator availability hours\n    - Enabled departments (which departments can receive transfers)\n\n    Note: This tool is mutually exclusive with transfer_to_phone.\n    Only one can be enabled at a time.\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_transfer_to_mobile_operator_config_agents__agent_id__tools_transfer_to_operator_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved transfer_to_mobile_operator configuration","content":{"application/json":{"schema":{"title":"Response Get Transfer To Mobile Operator Config Agents  Agent Id  Tools Transfer To Operator Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"transfer_to_mobile_operator","display_name":"Transfer to Operator","enabled":false,"is_configured":true,"config_fields":[{"name":"available_hours","current_value":{"monday":["09:00 - 18:00"],"tuesday":["09:00 - 18:00"]}}]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Agent Tools"],"summary":"Update transfer_to_mobile_operator tool configuration","description":"Update configuration for the transfer_to_mobile_operator tool.\n\n    Allows you to configure:\n    - Enable/disable the tool\n    - Operator availability hours\n    - Enabled departments (which departments can receive transfers)\n\n    Schedule format for available_hours:\n    ```json\n    {\n      \"monday\": [\"09:00 - 18:00\"],\n      \"tuesday\": [\"09:00 - 18:00\"],\n      ...\n    }\n    ```\n\n    Note: This tool is mutually exclusive with transfer_to_phone.\n    Attempting to enable this while transfer_to_phone is enabled will fail.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_transfer_to_mobile_operator_config_agents__agent_id__tools_transfer_to_operator_patch","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Enabled","description":"Enable or disable the tool"},"available_hours":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Available Hours","description":"Operator availability hours (schedule format: {monday: ['09:00 - 18:00'], ...})"},"enabled_departments":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Enabled Departments","description":"List of enabled department UUIDs (empty list = all departments available)"}},"type":"object","description":"Schema for updating transfer_to_mobile_operator tool configuration."},"examples":{"enable_tool":{"summary":"Enable tool","value":{"is_enabled":true}},"set_hours":{"summary":"Set availability hours","value":{"is_enabled":true,"available_hours":{"monday":["09:00 - 18:00"],"tuesday":["09:00 - 18:00"],"wednesday":["09:00 - 18:00"],"thursday":["09:00 - 18:00"],"friday":["09:00 - 18:00"],"saturday":"Close all day","sunday":"Close all day"}}},"complete_configuration":{"summary":"All available configuration fields","value":{"is_enabled":true,"available_hours":{"monday":"Open all day","tuesday":"Open all day","wednesday":"Open all day","thursday":"Open all day","friday":"Open all day","saturday":"Close all day","sunday":"Close all day"},"enabled_departments":[]}}}}}},"responses":{"200":{"description":"Successfully updated configuration","content":{"application/json":{"schema":{"title":"Response Update Transfer To Mobile Operator Config Agents  Agent Id  Tools Transfer To Operator Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"transfer_to_mobile_operator","enabled":true}}}}},"400":{"description":"Invalid configuration or mutual exclusivity violation","content":{"application/json":{"examples":{"mutual_exclusivity":{"summary":"Mutual exclusivity error","value":{"detail":"Cannot enable 'transfer_to_mobile_operator' while 'transfer_to_phone' is enabled"}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/agents/{agent_id}/tools/transfer-to-phone":{"get":{"tags":["Agent Tools"],"summary":"Get transfer_to_phone tool configuration","description":"Retrieve configuration for the transfer_to_phone tool.\n\n    This tool transfers calls to specific phone numbers. Configuration includes:\n    - List of phone destinations (each with phone number, name, availability hours)\n    - Transfer message (what the agent says before transferring)\n\n    Note: This tool is mutually exclusive with transfer_to_mobile_operator.\n    Only one can be enabled at a time.\n\n    The agent must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_transfer_to_phone_config_agents__agent_id__tools_transfer_to_phone_get","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successfully retrieved transfer_to_phone configuration","content":{"application/json":{"schema":{"title":"Response Get Transfer To Phone Config Agents  Agent Id  Tools Transfer To Phone Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"transfer_to_phone","display_name":"Transfer to Phone","enabled":false,"is_configured":false,"config_fields":[{"name":"phone_destinations","current_value":[]},{"name":"transfer_message","current_value":"Transferring your call..."}]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Agent Tools"],"summary":"Update transfer_to_phone tool configuration","description":"Update configuration for the transfer_to_phone tool.\n\n    Allows you to configure:\n    - Enable/disable the tool\n    - Phone destinations (list of phone numbers with names and availability)\n    - Transfer message\n\n    Phone destinations structure:\n    ```json\n    {\n      \"phone_number\": \"+393471234567\",  // E.164 format\n      \"name\": \"Reception\",\n      \"description\": \"Main reception desk\",\n      \"available_hours\": {  // Optional schedule\n        \"monday\": [\"09:00 - 18:00\"],\n        ...\n      }\n    }\n    ```\n\n    Important:\n    - phone_destinations is REQUIRED when enabling the tool (is_enabled=true)\n    - Phone numbers must be in E.164 format\n    - Phone numbers must be unique within destinations\n    - This tool is mutually exclusive with transfer_to_mobile_operator\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_transfer_to_phone_config_agents__agent_id__tools_transfer_to_phone_patch","security":[{"API Key":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Enabled","description":"Enable or disable the tool"},"phone_destinations":{"anyOf":[{"items":{"properties":{"phone_number":{"type":"string","pattern":"^\\+?[1-9]\\d{1,14}$","title":"Phone Number","description":"Phone number in E.164 format (e.g., +393471234567)"},"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name","description":"Destination name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Destination description"},"available_hours":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Available Hours","description":"Availability hours for this destination (schedule format: {monday: ['09:00 - 18:00'], ...})"}},"type":"object","required":["phone_number","name"],"description":"Phone destination configuration for transfer_to_phone tool."},"type":"array"},{"type":"null"}],"title":"Phone Destinations","description":"List of phone destinations (REQUIRED when enabling the tool)"},"transfer_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transfer Message","description":"Message said before transferring the call"}},"type":"object","description":"Schema for updating transfer_to_phone tool configuration."},"examples":{"enable_single_destination":{"summary":"Enable with single destination","value":{"is_enabled":true,"phone_destinations":[{"phone_number":"+393471234567","name":"Reception","description":"Main reception desk"}]}},"multiple_destinations":{"summary":"Multiple destinations with schedules","value":{"is_enabled":true,"phone_destinations":[{"phone_number":"+393471234567","name":"Reception","description":"Main reception desk during business hours","available_hours":{"monday":["09:00 - 18:00"],"tuesday":["09:00 - 18:00"],"wednesday":["09:00 - 18:00"],"thursday":["09:00 - 18:00"],"friday":["09:00 - 18:00"],"saturday":"Open all day","sunday":"Close all day"}},{"phone_number":"+393479876543","name":"Emergency","description":"24/7 emergency line"}],"transfer_message":"Transferring your call to an operator"}},"complete_configuration":{"summary":"All available configuration fields","value":{"is_enabled":true,"phone_destinations":[{"phone_number":"+393471234567","name":"Reception","description":"Main reception desk","available_hours":{"monday":"Open all day","tuesday":"Open all day","wednesday":"Open all day","thursday":"Open all day","friday":"Open all day","saturday":"Close all day","sunday":"Close all day"}}],"transfer_message":"Sto trasferendo la tua chiamata. Un momento per favore."}}}}}},"responses":{"200":{"description":"Successfully updated configuration","content":{"application/json":{"schema":{"title":"Response Update Transfer To Phone Config Agents  Agent Id  Tools Transfer To Phone Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"category_display_name":{"type":"string"},"scope":{"type":"string"},"enabled":{"type":"boolean"},"is_configured":{"type":"boolean"},"can_disable":{"type":"boolean"},"icon_url":{"type":"string"},"version":{"type":"string"},"config_fields":{"type":"array","items":{"type":"object"}}}}}},"example":{"ok":true,"data":{"name":"transfer_to_phone","enabled":true}}}}},"400":{"description":"Invalid configuration or mutual exclusivity violation","content":{"application/json":{"examples":{"missing_destinations":{"summary":"Missing phone_destinations when enabling","value":{"detail":"phone_destinations is required when enabling transfer_to_phone"}},"mutual_exclusivity":{"summary":"Mutual exclusivity error","value":{"detail":"Cannot enable 'transfer_to_phone' while 'transfer_to_mobile_operator' is enabled"}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns":{"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Retrieve a paginated list of dialer campaigns for your organization.\n\n    Supports optional filtering by campaign status:\n    - `draft` — Campaign is being configured\n    - `scheduled` — Campaign is scheduled to start\n    - `running` — Campaign is actively placing calls\n    - `paused` — Campaign has been paused\n    - `completed` — All contacts have been processed\n    - `stopped` — Campaign was manually stopped\n    - `failed` — Campaign encountered a fatal error\n\n    Supports optional search by campaign name (case-insensitive substring match).\n\n    Campaigns are returned in reverse chronological order (newest first).\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_campaigns_campaigns_get","security":[{"API Key":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by campaign status (draft, scheduled, running, paused, completed, stopped, failed)","title":"Status"},"description":"Filter by campaign status (draft, scheduled, running, paused, completed, stopped, failed)"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive substring search on campaign name","title":"Search"},"description":"Case-insensitive substring search on campaign name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Number of items to return","default":50,"title":"Limit"},"description":"Number of items to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Successfully retrieved campaign list","content":{"application/json":{"schema":{"title":"Response List Campaigns Campaigns Get"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/campaigns/{campaign_id}":{"get":{"tags":["Campaigns"],"summary":"Get campaign details","description":"Retrieve details for a specific campaign.\n\n    Returns a safe, consumer-facing subset of campaign fields. Internal\n    configuration such as caller-ID lists, operator assignments, retry rules,\n    schedule windows, and workflow IDs are not exposed.\n\n    The campaign must belong to your organization. Campaigns belonging to other\n    organizations return 404.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_campaign_campaigns__campaign_id__get","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Successfully retrieved campaign","content":{"application/json":{"schema":{"title":"Response Get Campaign Campaigns  Campaign Id  Get"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns/{campaign_id}/stats":{"get":{"tags":["Campaigns"],"summary":"Get campaign statistics","description":"Retrieve aggregated statistics for a specific campaign.\n\n    Returns contact-level counts (total, completed, failed, pending, in-progress,\n    skipped, retry-scheduled), call-attempt totals, success rate, answer rate,\n    drop-off rate, average call duration, and time-series breakdowns.\n\n    The campaign must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_campaign_statistics_campaigns__campaign_id__stats_get","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Successfully retrieved campaign statistics","content":{"application/json":{"schema":{"title":"Response Get Campaign Statistics Campaigns  Campaign Id  Stats Get"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns/{campaign_id}/start":{"post":{"tags":["Campaigns"],"summary":"Start a campaign","description":"Start a campaign, transitioning it from DRAFT to RUNNING.\n\n    Prerequisites checked by the service:\n    - The campaign must have contacts assigned\n    - The campaign must have at least one verified caller ID configured\n    - AI-based strategies require an agent to be assigned\n    - Human strategies require operators to be assigned and online\n    - The organization wallet must have sufficient balance\n\n    Returns the campaign ID and new status on success.\n    Validation failures (missing contacts, missing caller IDs, invalid state\n    transition, insufficient balance, etc.) are returned as 400 errors with\n    the service message.\n\n    Authentication:\n    - API key with READ_WRITE permission AND the outbound-call entitlement\n      (starting a campaign places outbound calls)","operationId":"start_campaign_campaigns__campaign_id__start_post","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Campaign started successfully","content":{"application/json":{"schema":{"title":"Response Start Campaign Campaigns  Campaign Id  Start Post"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns/{campaign_id}/pause":{"post":{"tags":["Campaigns"],"summary":"Pause a campaign","description":"Pause a running campaign, transitioning it from RUNNING to PAUSED.\n\n    Only campaigns in RUNNING status can be paused. Attempting to pause a\n    campaign in any other status (e.g. DRAFT) returns 400.\n\n    Returns the campaign ID and new status on success.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"pause_campaign_campaigns__campaign_id__pause_post","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Campaign paused successfully","content":{"application/json":{"schema":{"title":"Response Pause Campaign Campaigns  Campaign Id  Pause Post"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns/{campaign_id}/resume":{"post":{"tags":["Campaigns"],"summary":"Resume a campaign","description":"Resume a paused campaign, transitioning it from PAUSED to RUNNING.\n\n    Only campaigns in PAUSED status can be resumed. For human-only strategies,\n    at least one operator must be online when resuming.\n\n    Returns the campaign ID and new status on success.\n\n    Authentication:\n    - API key with READ_WRITE permission AND the outbound-call entitlement\n      (resuming a campaign places more outbound calls)","operationId":"resume_campaign_campaigns__campaign_id__resume_post","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Campaign resumed successfully","content":{"application/json":{"schema":{"title":"Response Resume Campaign Campaigns  Campaign Id  Resume Post"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/campaigns/{campaign_id}/stop":{"post":{"tags":["Campaigns"],"summary":"Stop a campaign","description":"Stop a running or paused campaign, transitioning it to STOPPED.\n\n    Only campaigns in RUNNING or PAUSED status can be stopped. Stopping is\n    irreversible — a stopped campaign cannot be restarted.\n\n    Returns the campaign ID and new status on success.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"stop_campaign_campaigns__campaign_id__stop_post","security":[{"API Key":[]}],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Campaign Id"}}],"responses":{"200":{"description":"Campaign stopped successfully","content":{"application/json":{"schema":{"title":"Response Stop Campaign Campaigns  Campaign Id  Stop Post"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/catalogues":{"get":{"tags":["Catalogues"],"summary":"List catalogues","description":"Retrieve a paginated list of catalogues for the authenticated organization.","operationId":"list_catalogues_catalogues_get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of catalogues to return","default":50,"title":"Limit"},"description":"Maximum number of catalogues to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of catalogues to skip for pagination","default":0,"title":"Offset"},"description":"Number of catalogues to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^-?(name|created_at)$"},{"type":"null"}],"description":"Sort field. Prefix with '-' for descending order. Available: name, created_at. Example: 'name' (A→Z), '-created_at' (newest first).","title":"Sort"},"description":"Sort field. Prefix with '-' for descending order. Available: name, created_at. Example: 'name' (A→Z), '-created_at' (newest first)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Filter catalogues by name (case-insensitive substring match).","title":"Search"},"description":"Filter catalogues by name (case-insensitive substring match)."}],"responses":{"200":{"description":"Successfully retrieved catalogues","content":{"application/json":{"schema":{"title":"Response List Catalogues Catalogues Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"file_key":{"type":"string","nullable":true},"status":{"type":"string"},"total_items":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","organization_id":"456e7890-e89b-12d3-a456-426614174001","name":"Spring 2024 Collection","description":"Our latest spring collection","status":"ready","total_items":42,"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T12:00:00"}],"meta":{"limit":10,"offset":0,"total_items":5}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}},"post":{"tags":["Catalogues"],"summary":"Create catalogue","description":"Create a new catalogue in your organization.","operationId":"create_catalogue_catalogues_post","security":[{"API Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","description":"Catalogue name","example":"Spring 2024 Collection"},"description":{"type":"string","description":"Catalogue description (optional)","example":"Our latest spring collection items"},"items":{"type":"array","description":"Initial items to add to the catalogue (optional)","items":{"type":"object","properties":{"sku":{"type":"string","description":"Product SKU (optional - auto-generated if not provided)","example":"PROD-001"},"name":{"type":"string","description":"Product name","example":"Premium Widget"},"description":{"type":"string","description":"Product description (optional)","example":"High-quality widget for professional use"},"price":{"type":"string","description":"Product price (optional)","example":"29.99"},"currency":{"type":"string","description":"Currency code (optional)","example":"EUR"},"quantity":{"type":"integer","description":"Available quantity (optional)","example":100},"category":{"type":"string","description":"Product category (optional)","example":"Widgets"}},"required":["name"]}}},"type":"object","required":["name"],"description":"Unified schema for creating a catalogue (manually or from preview).","example":{"description":"Our latest spring collection","is_active":true,"items":[],"name":"Spring 2024 Collection"}},"examples":{"basic_catalogue":{"summary":"Basic catalogue with name only","description":"Create a catalogue with just the required name field","value":{"name":"Winter Collection"}},"complete_catalogue":{"summary":"Complete catalogue with items","description":"Create a catalogue with description and initial items","value":{"name":"Spring 2024 Collection","description":"Our latest spring collection items","items":[{"name":"Premium Widget","description":"High-quality widget for professional use","price":"29.99","currency":"EUR","quantity":100,"category":"Widgets"}]}}}}}},"responses":{"201":{"description":"Catalogue created successfully","content":{"application/json":{"schema":{"title":"Response Create Catalogue Catalogues Post","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"file_key":{"type":"string","nullable":true},"status":{"type":"string"},"total_items":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","organization_id":"456e7890-e89b-12d3-a456-426614174001","name":"Spring 2024 Collection","description":"Our latest spring collection","status":"ready","total_items":0,"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T10:00:00"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/catalogues/items/assign":{"post":{"tags":["Catalogues"],"summary":"Assign or unassign items to/from a catalogue","description":"Assign items to a catalogue or unassign them to make them standalone.","operationId":"assign_or_unassign_items_catalogues_items_assign_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"catalogue_id":{"type":"string","format":"uuid","description":"Catalogue ID to assign items to (null or omit to unassign)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"item_ids":{"items":{"type":"string","format":"uuid"},"type":"array","description":"List of item IDs to assign/unassign","example":["789e0123-e89b-12d3-a456-426614174002","890e0123-e89b-12d3-a456-426614174003"]}},"type":"object","required":["item_ids"],"description":"Schema for assigning/unassigning items to/from a catalogue.","example":{"catalogue_id":"123e4567-e89b-12d3-a456-426614174000","item_ids":["789e0123-e89b-12d3-a456-426614174002","890e0123-e89b-12d3-a456-426614174003"]}},"examples":{"assign_items":{"summary":"Assign items to a catalogue","value":{"catalogue_id":"123e4567-e89b-12d3-a456-426614174000","item_ids":["789e0123-e89b-12d3-a456-426614174002","890e0123-e89b-12d3-a456-426614174003"]}},"unassign_items":{"summary":"Unassign items (make standalone)","value":{"item_ids":["789e0123-e89b-12d3-a456-426614174002","890e0123-e89b-12d3-a456-426614174003"]}}}}},"required":true},"responses":{"200":{"description":"Items assigned/unassigned successfully","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"properties":{"message":{"type":"string"}},"type":"object"}},"type":"object","title":"Response Assign Or Unassign Items Catalogues Items Assign Post"},"example":{"ok":true,"data":{"message":"Items assigned to catalogue successfully"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}},"security":[{"API Key":[]}]}},"/catalogues/items":{"get":{"tags":["Catalogues"],"summary":"List items","description":"Retrieve a paginated list of items with optional filtering by catalogue or standalone status.","operationId":"list_items_catalogues_items_get","security":[{"API Key":[]}],"parameters":[{"name":"catalogue_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by catalogue ID","title":"Catalogue Id"},"description":"Filter by catalogue ID"},{"name":"standalone_only","in":"query","required":false,"schema":{"type":"boolean","description":"Get only standalone items","default":false,"title":"Standalone Only"},"description":"Get only standalone items"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of items to return","default":50,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^-?(name|created_at|price)$"},{"type":"null"}],"description":"Sort field. Prefix with '-' for descending order. Available: name, created_at, price. Example: 'name' (A→Z), '-price' (highest first).","title":"Sort"},"description":"Sort field. Prefix with '-' for descending order. Available: name, created_at, price. Example: 'name' (A→Z), '-price' (highest first)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Search items by name, SKU, or description (case-insensitive substring match). Applies to all items unless catalogue_id or standalone_only is also set.","title":"Search"},"description":"Search items by name, SKU, or description (case-insensitive substring match). Applies to all items unless catalogue_id or standalone_only is also set."}],"responses":{"200":{"description":"Successfully retrieved items","content":{"application/json":{"schema":{"title":"Response List Items Catalogues Items Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"catalogue_id":{"type":"string","format":"uuid","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"789e0123-e89b-12d3-a456-426614174002","catalogue_id":"123e4567-e89b-12d3-a456-426614174000","sku":"PROD-001","name":"Premium Widget","description":"High-quality widget for professional use","price":"29.99","currency":"EUR","quantity":100,"category":"Widgets","created_at":"2024-01-30T12:00:00","updated_at":"2024-01-30T12:00:00"}],"meta":{"limit":10,"offset":0,"total_items":42}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}},"post":{"tags":["Catalogues"],"summary":"Create item","description":"Create an item either as standalone or directly in a catalogue.","operationId":"create_item_catalogues_items_post","security":[{"API Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sku":{"type":"string","description":"Product SKU (optional - auto-generated if not provided)","example":"STAND-001"},"name":{"type":"string","description":"Product name","example":"Standalone Product"},"description":{"type":"string","description":"Product description (optional)","example":"A product not yet assigned to any catalogue"},"price":{"type":"string","description":"Product price (optional)","example":"19.99"},"currency":{"type":"string","description":"Currency code (optional)","example":"EUR"},"quantity":{"type":"integer","description":"Available quantity (optional)","example":50},"category":{"type":"string","description":"Product category (optional)","example":"Standalone"},"catalogue_id":{"type":"string","format":"uuid","description":"Catalogue ID to add the item to (optional - creates standalone if not provided)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true}},"type":"object","required":["name"],"description":"Schema for creating a catalogue item.","example":{"catalogue_id":"123e4567-e89b-12d3-a456-426614174000","category":"Widgets","currency":"EUR","description":"High-quality widget for professional use","ignore_stock":false,"is_available":true,"name":"Premium Widget","price":"29.99","quantity":100,"sku":"PROD-001"}},"examples":{"basic_standalone":{"summary":"Basic standalone item","value":{"name":"Standalone Product"}},"item_with_catalogue":{"summary":"Item added directly to catalogue","value":{"name":"Catalogue Product","description":"A product added directly to a catalogue","catalogue_id":"123e4567-e89b-12d3-a456-426614174000","price":"29.99","currency":"EUR"}},"complete_standalone":{"summary":"Complete standalone item","value":{"name":"Standalone Product","description":"A product not yet assigned to any catalogue","price":"19.99","currency":"EUR","quantity":50,"category":"Standalone"}}}}}},"responses":{"201":{"description":"Item created successfully","content":{"application/json":{"schema":{"title":"Response Create Item Catalogues Items Post","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"catalogue_id":{"type":"string","format":"uuid","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"789e0123-e89b-12d3-a456-426614174002","sku":"STAND-001","name":"Standalone Product","description":"A product not yet assigned to any catalogue","price":"19.99","currency":"EUR","quantity":50,"category":"Standalone","created_at":"2024-01-30T12:00:00","updated_at":"2024-01-30T12:00:00"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/catalogues/items/{item_id}":{"get":{"tags":["Catalogues"],"summary":"Get item","description":"Retrieve a specific item by its ID, whether standalone or in a catalogue.","operationId":"get_item_by_id_catalogues_items__item_id__get","security":[{"API Key":[]}],"parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Item retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Item By Id Catalogues Items  Item Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"catalogue_id":{"type":"string","format":"uuid","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"789e0123-e89b-12d3-a456-426614174002","catalogue_id":"123e4567-e89b-12d3-a456-426614174000","sku":"PROD-001","name":"Premium Widget","description":"High-quality widget for professional use","price":"29.99","currency":"EUR","quantity":100,"category":"Widgets","created_at":"2024-01-30T12:00:00","updated_at":"2024-01-30T12:00:00"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"put":{"tags":["Catalogues"],"summary":"Update item","description":"Update an item, whether standalone or in a catalogue.","operationId":"update_item_catalogues_items__item_id__put","security":[{"API Key":[]}],"parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sku":{"type":"string","description":"Product SKU (optional)","example":"PROD-001"},"name":{"type":"string","description":"Product name (optional)","example":"Updated Premium Widget"},"description":{"type":"string","description":"Product description (optional)","example":"Updated description"},"price":{"type":"string","description":"Product price (optional)","example":"34.99"},"currency":{"type":"string","description":"Currency code (optional)","example":"EUR"},"quantity":{"type":"integer","description":"Available quantity (optional)","example":85},"category":{"type":"string","description":"Product category (optional)","example":"Widgets"}},"type":"object","description":"Schema for updating a catalogue item.","example":{"ignore_stock":false,"is_available":true,"name":"Updated Premium Widget","price":"34.99","quantity":85},"additionalProperties":false},"examples":{"price_update":{"summary":"Update price and quantity","value":{"price":"34.99","quantity":85}},"description_update":{"summary":"Update name and description","value":{"name":"Updated Premium Widget","description":"Updated description for the widget"}}}}}},"responses":{"200":{"description":"Item updated successfully","content":{"application/json":{"schema":{"title":"Response Update Item Catalogues Items  Item Id  Put","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"catalogue_id":{"type":"string","format":"uuid","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"quantity":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"789e0123-e89b-12d3-a456-426614174002","catalogue_id":"123e4567-e89b-12d3-a456-426614174000","sku":"PROD-001","name":"Updated Premium Widget","description":"Updated high-quality widget for professional use","price":"34.99","currency":"EUR","quantity":85,"category":"Widgets","created_at":"2024-01-30T12:00:00","updated_at":"2024-01-30T15:30:00"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Catalogues"],"summary":"Delete item","description":"Delete an item, whether standalone or in a catalogue.","operationId":"delete_item_catalogues_items__item_id__delete","security":[{"API Key":[]}],"parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Item Id"}}],"responses":{"200":{"description":"Item deleted successfully","content":{"application/json":{"schema":{"title":"Response Delete Item Catalogues Items  Item Id  Delete","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"deleted_id":{"type":"string","format":"uuid"}}}}},"example":{"ok":true,"data":{"message":"Item deleted successfully","deleted_id":"789e0123-e89b-12d3-a456-426614174002"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/catalogues/{catalogue_id}":{"get":{"tags":["Catalogues"],"summary":"Get catalogue","description":"Retrieve a specific catalogue by ID.","operationId":"get_catalogue_catalogues__catalogue_id__get","security":[{"API Key":[]}],"parameters":[{"name":"catalogue_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Catalogue Id"}}],"responses":{"200":{"description":"Catalogue retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Catalogue Catalogues  Catalogue Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"file_key":{"type":"string","nullable":true},"status":{"type":"string"},"total_items":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","organization_id":"456e7890-e89b-12d3-a456-426614174001","name":"Spring 2024 Collection","description":"Our latest spring collection","status":"ready","total_items":42,"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T12:00:00"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"put":{"tags":["Catalogues"],"summary":"Update catalogue","description":"Update a specific catalogue by ID.","operationId":"update_catalogue_catalogues__catalogue_id__put","security":[{"API Key":[]}],"parameters":[{"name":"catalogue_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Catalogue Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"type":"string","description":"Catalogue name (optional)","example":"Updated Spring Collection"},"description":{"type":"string","description":"Catalogue description (optional)","example":"Updated description for our spring collection"}},"type":"object","description":"Schema for updating a catalogue.","example":{"description":"Updated description for spring collection","is_active":true,"name":"Spring 2024 Collection Updated"},"additionalProperties":false},"examples":{"name_update":{"summary":"Update name only","description":"Change just the catalogue's name","value":{"name":"Updated Spring Collection"}},"full_update":{"summary":"Update name and description","description":"Update both name and description","value":{"name":"Updated Spring Collection","description":"Updated description for our spring collection"}}}}}},"responses":{"200":{"description":"Catalogue updated successfully","content":{"application/json":{"schema":{"title":"Response Update Catalogue Catalogues  Catalogue Id  Put","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"file_key":{"type":"string","nullable":true},"status":{"type":"string"},"total_items":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","organization_id":"456e7890-e89b-12d3-a456-426614174001","name":"Updated Spring Collection","description":"Updated description for spring collection","status":"ready","total_items":42,"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T15:30:00"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Catalogues"],"summary":"Delete catalogue","description":"Delete a specific catalogue by ID.","operationId":"delete_catalogue_catalogues__catalogue_id__delete","security":[{"API Key":[]}],"parameters":[{"name":"catalogue_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Catalogue Id"}},{"name":"preserve_items","in":"query","required":false,"schema":{"type":"boolean","description":"If true, items will become standalone instead of being deleted","default":false,"title":"Preserve Items"},"description":"If true, items will become standalone instead of being deleted"}],"responses":{"200":{"description":"Catalogue deleted successfully","content":{"application/json":{"schema":{"title":"Response Delete Catalogue Catalogues  Catalogue Id  Delete","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"deleted_id":{"type":"string","format":"uuid"}}}}},"example":{"ok":true,"data":{"message":"Catalogue deleted successfully","deleted_id":"123e4567-e89b-12d3-a456-426614174000"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/contact-lists":{"get":{"tags":["Contact Lists"],"summary":"List contact lists","description":"Retrieve a paginated list of contact lists for your organisation.\n\n    Supports optional name search via the ``search`` query parameter.\n    Lists are returned in reverse chronological order (newest first).\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_contact_lists_contact_lists_get","security":[{"API Key":[]}],"parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Filter lists by name (partial, case-insensitive match)","title":"Search"},"description":"Filter lists by name (partial, case-insensitive match)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of lists to return","default":50,"title":"Limit"},"description":"Maximum number of lists to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of lists to skip for pagination","default":0,"title":"Offset"},"description":"Number of lists to skip for pagination"}],"responses":{"200":{"description":"Successfully retrieved contact lists","content":{"application/json":{"schema":{"title":"Response List Contact Lists Contact Lists Get"},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","name":"VIP Customers","description":"High-value customers","contact_count":42,"created_at":"2024-01-30T10:00:00"}],"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/contact-lists/{contact_list_id}":{"get":{"tags":["Contact Lists"],"summary":"Get contact list","description":"Retrieve a specific contact list by ID.\n\n    The list must belong to your organisation; requesting a list owned by another\n    organisation returns 404 (no information disclosure).\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_contact_list_contact_lists__contact_list_id__get","security":[{"API Key":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact List Id"}}],"responses":{"200":{"description":"Successfully retrieved contact list","content":{"application/json":{"schema":{"title":"Response Get Contact List Contact Lists  Contact List Id  Get"},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","name":"VIP Customers","description":"High-value customers","contact_count":42,"created_at":"2024-01-30T10:00:00"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/contact-lists/{contact_list_id}/contacts":{"get":{"tags":["Contact Lists"],"summary":"List contacts in a contact list","description":"Retrieve a paginated list of contacts belonging to a specific contact list.\n\n    Returns external-safe contact fields: id, first_name, last_name, email, phone_number.\n    The list must belong to your organisation.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_contacts_in_list_contact_lists__contact_list_id__contacts_get","security":[{"API Key":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact List Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of contacts to return","default":50,"title":"Limit"},"description":"Maximum number of contacts to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of contacts to skip for pagination","default":0,"title":"Offset"},"description":"Number of contacts to skip for pagination"}],"responses":{"200":{"description":"Successfully retrieved contacts in list","content":{"application/json":{"schema":{"title":"Response List Contacts In List Contact Lists  Contact List Id  Contacts Get"},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890"}],"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"post":{"tags":["Contact Lists"],"summary":"Add contacts to a contact list","description":"Add contacts to a contact list by contact ID and/or phone number.\n\n    At least one of ``contact_ids`` or ``phone_numbers`` is required.\n\n    **Phone number resolution:**\n    Each phone number is matched to an existing contact in your organisation.\n    - ``auto_create=false`` (default): unrecognised numbers are reported in\n      ``not_found_phone_numbers`` and no error is raised.\n    - ``auto_create=true``: unrecognised numbers are used to create new contacts\n      automatically. The new contact's ``first_name`` is set to the phone number string.\n      The newly created contact IDs are reported in ``created_contact_ids``.\n\n    Contacts already in the list are counted silently (idempotent operation).\n    ``added_count`` reflects only newly added contacts.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"add_contacts_to_list_contact_lists__contact_list_id__contacts_post","security":[{"API Key":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500},{"type":"null"}],"title":"Contact Ids","description":"List of contact UUIDs to add to the list (max 500 per request)"},"phone_numbers":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Phone Numbers","description":"List of phone numbers in E.164 format to add to the list (max 500 per request). Each number is resolved to an existing contact in your organisation."},"auto_create":{"type":"boolean","title":"Auto Create","description":"When True, phone numbers that do not match any existing contact are automatically created as new contacts (first_name set to the phone number). When False, unrecognised phone numbers are reported in not_found_phone_numbers without raising an error.","default":false}},"type":"object","description":"Request schema for adding contacts to a contact list.\n\nSpecify at least one of ``contact_ids`` or ``phone_numbers``.\n\nWhen ``auto_create`` is ``True``, phone numbers that do not match any existing\ncontact in the organization are automatically created as new contacts. The new\ncontact's ``first_name`` is set to the phone number string. When ``auto_create``\nis ``False`` (the default), unrecognised phone numbers are reported in the\n``not_found_phone_numbers`` field of the response and no error is raised."}}}},"responses":{"200":{"description":"Contacts added successfully","content":{"application/json":{"schema":{"title":"Response Add Contacts To List Contact Lists  Contact List Id  Contacts Post"},"example":{"ok":true,"data":{"added_count":3,"created_contact_ids":[],"not_found_phone_numbers":["+39000000000"],"not_found_contact_ids":[]}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Contact Lists"],"summary":"Remove contacts from a contact list","description":"Remove contacts from a contact list by contact ID and/or phone number.\n\n    At least one of ``contact_ids`` or ``phone_numbers`` is required.\n\n    Contacts not currently in the list are silently ignored (idempotent).\n    Phone numbers that cannot be resolved to a contact in your organisation are\n    reported in ``not_found_phone_numbers`` without raising an error.\n\n    **Note:** This operation removes contacts from the list only.\n    Contacts are never deleted from your organisation.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"remove_contacts_from_list_contact_lists__contact_list_id__contacts_delete","security":[{"API Key":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":500},{"type":"null"}],"title":"Contact Ids","description":"List of contact UUIDs to remove from the list (max 500 per request)"},"phone_numbers":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":500},{"type":"null"}],"title":"Phone Numbers","description":"List of phone numbers in E.164 format to remove from the list (max 500 per request)"}},"type":"object","description":"Request schema for removing contacts from a contact list.\n\nSpecify at least one of ``contact_ids`` or ``phone_numbers``.\nPhone numbers are resolved to existing contacts; unrecognised numbers are\nreported in ``not_found_phone_numbers`` without raising an error."}}}},"responses":{"200":{"description":"Contacts removed successfully","content":{"application/json":{"schema":{"title":"Response Remove Contacts From List Contact Lists  Contact List Id  Contacts Delete"},"example":{"ok":true,"data":{"removed_count":2,"not_found_phone_numbers":[],"not_found_contact_ids":[]}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Retrieve a paginated list of contacts for the authenticated organization.","operationId":"list_contacts_contacts_get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of contacts to return","default":50,"title":"Limit"},"description":"Maximum number of contacts to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of contacts to skip for pagination","default":0,"title":"Offset"},"description":"Number of contacts to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^-?(first_name|last_name|email|created_at)$"},{"type":"null"}],"description":"Sort field. Prefix with '-' for descending order. Available: first_name, last_name, email, created_at","title":"Sort"},"description":"Sort field. Prefix with '-' for descending order. Available: first_name, last_name, email, created_at"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Search in first_name, last_name, email, or phone_number (finds contacts with search term in ANY of these fields)","title":"Search"},"description":"Search in first_name, last_name, email, or phone_number (finds contacts with search term in ANY of these fields)"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Advanced filter with AND (&) and OR (|) logic. Format: 'column:value' or 'column:operator:value'. Limits: max 50 conditions, max 20 groups, max 100 items in 'in' operator, max 1000 chars per value. Examples: 'first_name:Mario|last_name:Mario' (OR), 'first_name:Mario&email:gmail.com' (AND). ","title":"Filter"},"description":"Advanced filter with AND (&) and OR (|) logic. Format: 'column:value' or 'column:operator:value'. Limits: max 50 conditions, max 20 groups, max 100 items in 'in' operator, max 1000 chars per value. Examples: 'first_name:Mario|last_name:Mario' (OR), 'first_name:Mario&email:gmail.com' (AND). "}],"responses":{"200":{"description":"Successfully retrieved contacts with custom fields","content":{"application/json":{"schema":{"title":"Response List Contacts Contacts Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890","address":"123 Main St, City, State","last_call_time":"2024-01-15T10:30:00Z","custom_fields":{"department":"Sales"}}],"meta":{"limit":10,"offset":0,"total_items":25}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}},"post":{"tags":["Contacts"],"summary":"Create contact","description":"Create a new contact in your organization.","operationId":"create_contact_api_contacts_post","security":[{"API Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first_name":{"type":"string","description":"Contact's first name","example":"John"},"last_name":{"type":"string","description":"Contact's last name (optional)","example":"Doe"},"email":{"type":"string","format":"email","description":"Contact's email address (optional)","example":"john.doe@example.com"},"phone_number":{"type":"string","description":"Contact's phone number in E.164 format","pattern":"^\\+[1-9]\\d{1,14}$","example":"+1234567890"},"address":{"type":"string","description":"Contact's address (optional)","example":"123 Main St, City, State 12345"},"custom_fields":{"type":"object","description":"Custom fields as key-value pairs. Unknown fields are auto-created with type inferred from the value. Supported value types: string, number, boolean.","additionalProperties":true,"example":{"hair_color":"brown","department":"Engineering","is_vip":true}}},"type":"object","required":["first_name","phone_number"],"example":{"address":"123 Main St, City, State","custom_fields":{"department":"Engineering","hair_color":"brown"},"email":"john.doe@example.com","first_name":"John","last_name":"Doe","phone_number":"+1234567890"}},"examples":{"basic_contact":{"summary":"Basic contact with required fields","description":"A contact with just the required fields","value":{"first_name":"Jane","phone_number":"+1987654321"}},"complete_contact":{"summary":"Complete contact information","description":"A contact with all available fields","value":{"first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890","address":"123 Main St, Anytown, State 12345"}},"with_custom_fields":{"summary":"Contact with custom fields","description":"Custom fields are auto-created if they don't exist. Type is inferred from the value: string, number, boolean (true/false), email, phone, url, date.","value":{"first_name":"Alice","last_name":"Smith","phone_number":"+1555123456","email":"alice.smith@example.com","custom_fields":{"hair_color":"brown","department":"Engineering","employee_id":"EMP001","is_vip":true,"years_experience":5}}}}}}},"responses":{"201":{"description":"Contact created successfully","content":{"application/json":{"schema":{"title":"Response Create Contact Api Contacts Post","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time","nullable":true}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890","address":"123 Main St, City, State"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/contacts/{contact_id}":{"get":{"tags":["Contacts"],"summary":"Get contact","description":"Retrieve a specific contact by ID.","operationId":"get_contact_contacts__contact_id__get","security":[{"API Key":[]}],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact Id"}}],"responses":{"200":{"description":"Contact retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Contact Contacts  Contact Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890","address":"123 Main St, City, State","last_call_time":"2024-01-15T10:30:00Z","custom_fields":{"company":"Acme Corp"}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Contacts"],"summary":"Update contact","description":"Partially update a specific contact by ID. Supports custom field auto-creation and null semantics.","operationId":"update_contact_api_contacts__contact_id__patch","security":[{"API Key":[]}],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first_name":{"type":"string","description":"Contact's first name (optional)","example":"Johnny"},"last_name":{"type":"string","description":"Contact's last name (optional)","example":"Smith"},"email":{"type":"string","format":"email","description":"Contact's email address (optional)","example":"new.email@example.com"},"phone_number":{"type":"string","description":"Contact's phone number in E.164 format (optional)","pattern":"^\\+[1-9]\\d{1,14}$","example":"+1555123456"},"address":{"type":"string","description":"Contact's address (optional)","example":"789 Updated Ave, New City, State 54321"},"custom_fields":{"type":"object","nullable":true,"description":"Custom fields as key-value pairs. Unknown fields are auto-created with type inferred from the value (string, number, boolean, email, phone, url, date). Set to null to remove ALL custom field values. Set a field's value to null to remove that specific field value. Omit the key entirely to leave custom fields unchanged.","additionalProperties":true,"example":{"hair_color":"blonde","department":"Marketing","is_vip":true}}},"type":"object","example":{"address":"456 New St, City, State","custom_fields":{"department":"Marketing","hair_color":"blonde"},"email":"john.smith@example.com","first_name":"John","last_name":"Smith"},"additionalProperties":false},"examples":{"name_change":{"summary":"Update name only","description":"Change just the contact's name","value":{"first_name":"Johnny","last_name":"Smith"}},"contact_info_change":{"summary":"Update contact information","description":"Update email and address","value":{"email":"new.email@example.com","address":"789 Updated Ave, New City, State 54321"}},"update_custom_fields":{"summary":"Update custom fields","description":"Set or update custom field values. Unknown fields are auto-created. Boolean values (true/false) create boolean-type fields.","value":{"custom_fields":{"hair_color":"blonde","department":"Marketing","years_experience":5,"is_vip":true}}},"remove_specific_field":{"summary":"Remove a specific custom field value","description":"Set a field to null to remove its value.","value":{"custom_fields":{}}},"remove_all_custom_fields":{"summary":"Remove all custom field values","description":"Set custom_fields to null to remove all values.","value":{}}}}}},"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"title":"Response Update Contact Api Contacts  Contact Id  Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Smith","email":"john.smith@example.com","phone_number":"+1234567890","address":"456 New St, City, State","last_call_time":"2024-01-15T10:30:00Z"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"put":{"tags":["Contacts"],"summary":"Update contact (deprecated, use PATCH)","description":"Deprecated: Use PATCH instead. Updates a specific contact by ID.","operationId":"update_contact_api_contacts__contact_id__put","deprecated":true,"security":[{"API Key":[]}],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first_name":{"type":"string","description":"Contact's first name (optional)","example":"Johnny"},"last_name":{"type":"string","description":"Contact's last name (optional)","example":"Smith"},"email":{"type":"string","format":"email","description":"Contact's email address (optional)","example":"new.email@example.com"},"phone_number":{"type":"string","description":"Contact's phone number in E.164 format (optional)","pattern":"^\\+[1-9]\\d{1,14}$","example":"+1555123456"},"address":{"type":"string","description":"Contact's address (optional)","example":"789 Updated Ave, New City, State 54321"},"custom_fields":{"type":"object","nullable":true,"description":"Custom fields as key-value pairs. Unknown fields are auto-created with type inferred from the value (string, number, boolean, email, phone, url, date). Set to null to remove ALL custom field values. Set a field's value to null to remove that specific field value. Omit the key entirely to leave custom fields unchanged.","additionalProperties":true,"example":{"hair_color":"blonde","department":"Marketing","is_vip":true}}},"type":"object","example":{"address":"456 New St, City, State","custom_fields":{"department":"Marketing","hair_color":"blonde"},"email":"john.smith@example.com","first_name":"John","last_name":"Smith"},"additionalProperties":false},"examples":{"name_change":{"summary":"Update name only","description":"Change just the contact's name","value":{"first_name":"Johnny","last_name":"Smith"}},"contact_info_change":{"summary":"Update contact information","description":"Update email and address","value":{"email":"new.email@example.com","address":"789 Updated Ave, New City, State 54321"}},"update_custom_fields":{"summary":"Update custom fields","description":"Set or update custom field values. Unknown fields are auto-created. Boolean values (true/false) create boolean-type fields.","value":{"custom_fields":{"hair_color":"blonde","department":"Marketing","years_experience":5,"is_vip":true}}},"remove_specific_field":{"summary":"Remove a specific custom field value","description":"Set a field to null to remove its value.","value":{"custom_fields":{}}},"remove_all_custom_fields":{"summary":"Remove all custom field values","description":"Set custom_fields to null to remove all values.","value":{}}}}}},"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"title":"Response Update Contact Api Contacts  Contact Id  Put","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Smith","email":"john.smith@example.com","phone_number":"+1234567890","address":"456 New St, City, State","last_call_time":"2024-01-15T10:30:00Z"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Contacts"],"summary":"Delete contact","description":"Delete a specific contact by ID.","operationId":"delete_contact_contacts__contact_id__delete","security":[{"API Key":[]}],"parameters":[{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contact Id"}}],"responses":{"200":{"description":"Contact deleted successfully","content":{"application/json":{"schema":{"title":"Response Delete Contact Contacts  Contact Id  Delete","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"deleted_id":{"type":"string","format":"uuid"}}}}},"example":{"ok":true,"data":{"message":"Contact deleted successfully","deleted_id":"123e4567-e89b-12d3-a456-426614174000"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/contacts/by-phone/{phone_number}":{"get":{"tags":["Contacts"],"summary":"Get contact by phone number","description":"Retrieve a specific contact by phone number.","operationId":"get_contact_by_phone_contacts_by_phone__phone_number__get","security":[{"API Key":[]}],"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string","title":"Phone Number"}}],"responses":{"200":{"description":"Contact retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Contact By Phone Contacts By Phone  Phone Number  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"},"custom_fields":{"type":"object","additionalProperties":true}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Doe","email":"john.doe@example.com","phone_number":"+1234567890","address":"123 Main St, City, State","last_call_time":"2024-01-15T10:30:00Z","custom_fields":{"company":"Acme Corp"}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Contacts"],"summary":"Update contact by phone number","description":"Partially update a specific contact by phone number. Supports custom field auto-creation and null semantics.","operationId":"update_contact_by_phone_contacts_by_phone__phone_number__patch","security":[{"API Key":[]}],"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string","title":"Phone Number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"first_name":{"type":"string","description":"Contact's first name (optional)","example":"Johnny"},"last_name":{"type":"string","description":"Contact's last name (optional)","example":"Smith"},"email":{"type":"string","format":"email","description":"Contact's email address (optional)","example":"new.email@example.com"},"phone_number":{"type":"string","description":"Contact's new phone number in E.164 format (optional)","pattern":"^\\+[1-9]\\d{1,14}$","example":"+1555123456"},"address":{"type":"string","description":"Contact's address (optional)","example":"789 Updated Ave, New City, State 54321"},"custom_fields":{"type":"object","nullable":true,"description":"Custom fields as key-value pairs. Unknown fields are auto-created with type inferred from the value. Set to null to remove ALL custom field values. Set a field's value to null to remove that specific field value.","additionalProperties":true,"example":{"department":"Engineering","is_vip":true}}},"type":"object","example":{"address":"456 New St, City, State","custom_fields":{"department":"Marketing","hair_color":"blonde"},"email":"john.smith@example.com","first_name":"John","last_name":"Smith"},"additionalProperties":false},"examples":{"name_change":{"summary":"Update name only","description":"Change just the contact's name","value":{"first_name":"Johnny","last_name":"Smith"}},"with_custom_fields":{"summary":"Update with custom fields","description":"Update contact and set custom field values","value":{"first_name":"Johnny","custom_fields":{"department":"Engineering","is_vip":true}}}}}}},"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"title":"Response Update Contact By Phone Contacts By Phone  Phone Number  Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number":{"type":"string"},"address":{"type":"string"},"last_call_time":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","first_name":"John","last_name":"Smith","email":"john.smith@example.com","phone_number":"+1234567890","address":"456 New St, City, State","last_call_time":"2024-01-15T10:30:00Z"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Contacts"],"summary":"Delete contact by phone number","description":"Delete a specific contact by phone number.","operationId":"delete_contact_by_phone_contacts_by_phone__phone_number__delete","security":[{"API Key":[]}],"parameters":[{"name":"phone_number","in":"path","required":true,"schema":{"type":"string","title":"Phone Number"}}],"responses":{"200":{"description":"Contact deleted successfully","content":{"application/json":{"schema":{"title":"Response Delete Contact By Phone Contacts By Phone  Phone Number  Delete","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"deleted_phone_number":{"type":"string"}}}}},"example":{"ok":true,"data":{"message":"Contact deleted successfully","deleted_phone_number":"+1234567890"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/call-history":{"get":{"tags":["Call History"],"summary":"List call history","description":"Retrieve a paginated list of call history records for the authenticated organization.\n\n**Polling integrations (e.g. Zapier):** to avoid missing calls during high-volume windows, poll with `sort=-created_at&created_after=<bookmark>`, where `<bookmark>` is the highest `created_at` value seen in the previous batch. Results are returned in `created_at DESC, id DESC` order by default, so pagination is deterministic.","operationId":"list_call_history_call_history_get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of call records to return","default":50,"title":"Limit"},"description":"Maximum number of call records to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of call records to skip for pagination","default":0,"title":"Offset"},"description":"Number of call records to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^-?(start_time|end_time|duration|created_at)$"},{"type":"null"}],"description":"Sort field. Prefix with '-' for descending order. Available: start_time, end_time, duration, created_at","title":"Sort"},"description":"Sort field. Prefix with '-' for descending order. Available: start_time, end_time, duration, created_at"},{"name":"call_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(Completed|Not\\ Answered|Rejected|Failed|Busy|Voicemail|Ended\\ In\\ Queue)$"},{"type":"null"}],"description":"Filter by call status. Accepted values: Completed, Not Answered, Rejected, Failed, Busy, Voicemail, Ended In Queue","title":"Call Status"},"description":"Filter by call status. Accepted values: Completed, Not Answered, Rejected, Failed, Busy, Voicemail, Ended In Queue"},{"name":"is_outbound","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by call direction (true for outbound, false for inbound)","title":"Is Outbound"},"description":"Filter by call direction (true for outbound, false for inbound)"},{"name":"from_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Filter by caller phone number","title":"From Number"},"description":"Filter by caller phone number"},{"name":"to_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Filter by called phone number","title":"To Number"},"description":"Filter by called phone number"},{"name":"phone_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Filter by any phone number (from_number or to_number)","title":"Phone Number"},"description":"Filter by any phone number (from_number or to_number)"},{"name":"contact_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by contact ID","title":"Contact Id"},"description":"Filter by contact ID"},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Return only calls created strictly after this ISO-8601 timestamp. Intended for polling integrations: bookmark the highest `created_at` from the previous response and pass it back on the next request to fetch only new calls.","title":"Created After"},"description":"Return only calls created strictly after this ISO-8601 timestamp. Intended for polling integrations: bookmark the highest `created_at` from the previous response and pass it back on the next request to fetch only new calls."}],"responses":{"200":{"description":"Successfully retrieved call history","content":{"application/json":{"schema":{"title":"Response List Call History Call History Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_outbound":{"type":"boolean"},"status":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"from_number":{"type":"string"},"to_number":{"type":"string"},"duration":{"type":"integer"},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"reason":{"type":"string"},"hangup_reason":{"type":"string"},"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"agent_type":{"type":"string"}}},"criteria_status":{"type":"string"},"ai_provider":{"type":"string","nullable":true},"ai_provider_fallback_used":{"type":"boolean","nullable":true},"customer_contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone_number":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"}}},"recording_url":{"type":"string"},"recording_file_id":{"type":"string","format":"uuid"},"recording_duration":{"type":"integer"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"550e8400-e29b-41d4-a716-446655440000","created_at":"2024-01-15T10:33:05Z","is_outbound":false,"status":"Completed","user_id":"550e8400-e29b-41d4-a716-446655440002","from_number":"+1987654321","to_number":"+1234567890","duration":180,"start_time":"2024-01-15T10:30:00Z","end_time":"2024-01-15T10:33:00Z","reason":"INFO","hangup_reason":"user_hangup","agent":{"id":"550e8400-e29b-41d4-a716-446655440004","name":"Customer Service Agent","agent_type":"INBOUND"},"criteria_status":"evaluated","ai_provider":"openai","ai_provider_fallback_used":false,"customer_contact":{"id":"550e8400-e29b-41d4-a716-446655440001","first_name":"John","last_name":"Doe","phone_number":"+1987654321","email":"john.doe@example.com","address":"123 Main St, City, State"},"recording_url":"https://s3.amazonaws.com/bucket/recording.mp3?...","recording_file_id":"550e8400-e29b-41d4-a716-446655440003","recording_duration":180}],"meta":{"limit":10,"offset":0,"total_items":50}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/call-history/{call_id}":{"get":{"tags":["Call History"],"summary":"Get call history details","description":"Retrieve detailed information about a specific call, including transcript.","operationId":"get_call_history_detail_call_history__call_id__get","security":[{"API Key":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"Call history retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Call History Detail Call History  Call Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_outbound":{"type":"boolean"},"status":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"from_number":{"type":"string"},"to_number":{"type":"string"},"duration":{"type":"integer"},"start_time":{"type":"string","format":"date-time"},"end_time":{"type":"string","format":"date-time"},"reason":{"type":"string"},"hangup_reason":{"type":"string"},"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"agent_type":{"type":"string"}}},"criteria_status":{"type":"string"},"ai_provider":{"type":"string","nullable":true},"ai_provider_fallback_used":{"type":"boolean","nullable":true},"customer_contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone_number":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"}}},"transcript":{"type":"array","items":{"type":"string"}},"transfer_time":{"type":"string","format":"date-time"},"recording_url":{"type":"string"},"recording_file_id":{"type":"string","format":"uuid"},"recording_duration":{"type":"integer"}}}}},"example":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","created_at":"2024-01-15T10:33:05Z","is_outbound":false,"status":"Completed","user_id":"550e8400-e29b-41d4-a716-446655440002","from_number":"+1987654321","to_number":"+1234567890","duration":180,"start_time":"2024-01-15T10:30:00Z","end_time":"2024-01-15T10:33:00Z","reason":"INFO","hangup_reason":"user_hangup","agent":{"id":"550e8400-e29b-41d4-a716-446655440004","name":"Customer Service Agent","agent_type":"INBOUND"},"criteria_status":"evaluated","ai_provider":"openai","ai_provider_fallback_used":false,"customer_contact":{"id":"550e8400-e29b-41d4-a716-446655440001","first_name":"John","last_name":"Doe","phone_number":"+1987654321","email":"john.doe@example.com","address":"123 Main St, City, State"},"transcript":["ai: Hello there! I am an AI voice assistant. How can I help you?","user: I need help with my account","ai: I'd be happy to help you with your account. Let me connect you with someone who can assist."],"transfer_time":"2024-01-15T10:32:00Z","recording_url":"https://s3.amazonaws.com/bucket/recording.mp3?...","recording_file_id":"550e8400-e29b-41d4-a716-446655440003","recording_duration":180}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/call-history/{call_id}/transcript":{"get":{"tags":["Call History"],"summary":"Get call transcript","description":"Retrieve the transcript for a specific call.","operationId":"get_call_transcript_call_history__call_id__transcript_get","security":[{"API Key":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"Call transcript retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Call Transcript Call History  Call Id  Transcript Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"transcript":{"type":"array","items":{"type":"string"}}}}}},"example":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","transcript":["ai: Hello there! I am an AI voice assistant. How can I help you?","user: I need help with my account","ai: I'd be happy to help you with your account. Let me connect you with someone who can assist."]}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/call-history/{call_id}/summary":{"get":{"tags":["Call History"],"summary":"Get call summary","description":"Retrieve the AI-generated summary for a specific call.","operationId":"get_call_summary_call_history__call_id__summary_get","security":[{"API Key":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Call Id"}}],"responses":{"200":{"description":"Call summary retrieved successfully","content":{"application/json":{"schema":{"title":"Response Get Call Summary Call History  Call Id  Summary Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"summary":{"type":"string"}}}}},"example":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","summary":"The customer called to inquire about their account status. The AI assistant provided information and offered to connect them with a human representative for further assistance."}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/events":{"get":{"tags":["Events"],"summary":"List events grouped by date","description":"Retrieve events grouped by date with limited events per day.\n\n**Pagination model:** `limit` and `offset` paginate across the total event pool (i.e. across all days in the requested range). `events_per_day` then caps how many events are shown inside each day bucket. `meta.total_items` reflects the total number of matching events (not days). `remaining_count` on each day group indicates how many additional events exist beyond `events_per_day` for that day.\n\nExisting response keys (`date`, `events`, `remaining_count`) are unchanged.","operationId":"list_events_grouped_by_date_events_get","security":[{"API Key":[]}],"parameters":[{"name":"events_per_day","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of events to show per day","default":50,"title":"Events Per Day"},"description":"Maximum number of events to show per day"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum total number of events to include across all day groups. Controls how many events are fetched before grouping by date.","default":50,"title":"Limit"},"description":"Maximum total number of events to include across all day groups. Controls how many events are fetched before grouping by date."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of events to skip before applying the day grouping.","default":0,"title":"Offset"},"description":"Number of events to skip before applying the day grouping."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date for event range (YYYY-MM-DD)","title":"Start Date"},"description":"Start date for event range (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date for event range (YYYY-MM-DD)","title":"End Date"},"description":"End date for event range (YYYY-MM-DD)"}],"responses":{"200":{"description":"Successfully retrieved events grouped by date","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client_full_name":{"type":"string"},"client_email":{"type":"string","format":"email"},"client_phone_number":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"},"starting_date":{"type":"string","format":"date-time"},"ending_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"remaining_count":{"type":"integer"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}},"type":"object","required":["ok"]},"examples":{"successful_response":{"summary":"Successful response with events","description":"Example of successful events grouped by date","value":{"ok":true,"data":[{"date":"2024-01-15","events":[{"id":"550e8400-e29b-41d4-a716-446655440000","client_full_name":"John Doe","client_email":"john.doe@example.com","client_phone_number":"+1234567890","status":"PENDING","details":"Business meeting","starting_date":"2024-01-15T10:00:00Z","ending_date":"2024-01-15T11:00:00Z","created_at":"2024-01-14T15:30:00Z"}],"remaining_count":5}],"meta":{"limit":50,"offset":0,"total_items":6}}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/events/date":{"get":{"tags":["Events"],"summary":"Get events for specific date","description":"Retrieve events for a specific date with pagination support.","operationId":"get_events_by_specific_date_events_date_get","security":[{"API Key":[]}],"parameters":[{"name":"target_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Target date to get events for (YYYY-MM-DD format)","title":"Target Date"},"description":"Target date to get events for (YYYY-MM-DD format)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":-1,"description":"Maximum number of events to return. Set to -1 for all events","default":50,"title":"Limit"},"description":"Maximum number of events to return. Set to -1 for all events"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of events to skip","default":0,"title":"Offset"},"description":"Number of events to skip"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"& separated list of columns for sorting (prefix with '-' for descending)","default":"starting_date","title":"Sort"},"description":"& separated list of columns for sorting (prefix with '-' for descending)"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"& separated list of filters in format 'column:value'","title":"Filter"},"description":"& separated list of filters in format 'column:value'"}],"responses":{"200":{"description":"Successfully retrieved events for the specified date","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client_full_name":{"type":"string"},"client_email":{"type":"string","format":"email"},"client_phone_number":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"},"starting_date":{"type":"string","format":"date-time"},"ending_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}},"type":"object","required":["ok"]},"examples":{"successful_response":{"summary":"Events for specific date","description":"Example response with events for a specific date","value":{"ok":true,"data":[{"id":"550e8400-e29b-41d4-a716-446655440000","client_full_name":"John Doe","client_email":"john.doe@example.com","client_phone_number":"+1234567890","status":"PENDING","details":"Business meeting","starting_date":"2024-01-15T10:00:00Z","ending_date":"2024-01-15T11:00:00Z","created_at":"2024-01-14T15:30:00Z"}],"meta":{"limit":10,"offset":0,"total_items":1}}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/events/{event_id}":{"get":{"tags":["Events"],"summary":"Get event by ID","description":"Retrieve a specific event by its ID.","operationId":"get_event_by_id_events__event_id__get","security":[{"API Key":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Event retrieved successfully","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client_full_name":{"type":"string"},"client_email":{"type":"string","format":"email"},"client_phone_number":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"},"starting_date":{"type":"string","format":"date-time"},"ending_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"type":"object","required":["ok"]},"examples":{"successful_response":{"summary":"Single event details","description":"Example of a single event retrieved by ID","value":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","client_full_name":"John Doe","client_email":"john.doe@example.com","client_phone_number":"+1234567890","status":"PENDING","details":"Business meeting","starting_date":"2024-01-15T10:00:00Z","ending_date":"2024-01-15T11:00:00Z","created_at":"2024-01-14T15:30:00Z"}}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Events"],"summary":"Update event","description":"Update a specific event by ID. All fields in the request body are optional - only include fields you want to change.","operationId":"update_event_endpoint_events__event_id__patch","security":[{"API Key":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"client_full_name":{"type":"string","description":"Client's full name (optional)","example":"Jane Smith"},"client_email":{"type":"string","format":"email","description":"Client's email address (optional)","example":"jane.smith@example.com"},"client_phone_number":{"type":"string","description":"Client's phone number (optional)","example":"+1987654321"},"details":{"type":"string","description":"Event details (optional)","example":"Updated meeting details"},"starting_date":{"type":"string","format":"date-time","description":"Event start date and time (optional)","example":"2024-01-15T14:00:00Z"},"ending_date":{"type":"string","format":"date-time","description":"Event end date and time (optional)","example":"2024-01-15T15:00:00Z"},"status":{"type":"string","enum":["PENDING","CONFIRMED","APPROVED","REJECTED","PENDING_DELETION"],"description":"Event status (optional)","example":"APPROVED"},"extras":{"type":"object","description":"Additional metadata including custom field values (optional)","example":{"custom_field_values":{"room_type":"suite"}}}},"type":"object","description":"External API request for updating an event.\n\nAll fields are optional for true PATCH semantics.\nUnlike UpdateEventRequest, this is for external API use only.","example":{"client_email":"mario@example.com","client_full_name":"Mario Rossi","details":"Updated suite room","extras":{"custom_field_values":{"room_type":"deluxe"}}},"additionalProperties":false},"examples":{"update_client_info":{"summary":"Update client information","description":"Update client name and email","value":{"client_full_name":"Jane Smith","client_email":"jane.smith@example.com"}},"reschedule_event":{"summary":"Reschedule event","description":"Update event times","value":{"starting_date":"2024-01-16T10:00:00Z","ending_date":"2024-01-16T11:00:00Z"}},"update_details":{"summary":"Update event details","description":"Change event description","value":{"details":"Updated meeting with additional agenda items"}},"confirm_event":{"summary":"Confirm event","description":"Set event status to approved (confirmed)","value":{"status":"APPROVED"}}}}}},"responses":{"200":{"description":"Event updated successfully","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client_full_name":{"type":"string"},"client_email":{"type":"string","format":"email"},"client_phone_number":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"},"starting_date":{"type":"string","format":"date-time"},"ending_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"type":"object","required":["ok"]},"examples":{"successful_update":{"summary":"Event updated successfully","description":"Example of successfully updated event","value":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","client_full_name":"John Smith","client_email":"john.smith@example.com","client_phone_number":"+1234567890","status":"APPROVED","details":"Updated business meeting","starting_date":"2024-01-15T14:00:00Z","ending_date":"2024-01-15T15:00:00Z","created_at":"2024-01-14T15:30:00Z"}}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Events"],"summary":"Delete event","description":"Delete a specific event by ID.","operationId":"delete_event_endpoint_events__event_id__delete","security":[{"API Key":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Event deleted successfully","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"},"deleted_id":{"type":"string","format":"uuid"}}}},"type":"object","required":["ok"]},"examples":{"successful_deletion":{"summary":"Event deleted successfully","description":"Example of successful event deletion","value":{"ok":true,"data":{"message":"Event deleted successfully","deleted_id":"550e8400-e29b-41d4-a716-446655440000"}}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}},"500":{"description":"Failed to delete event","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"}}}}},"examples":{"internal_error":{"summary":"Internal server error","description":"Example when server fails to process request","value":{"ok":false,"error":{"code":"INTERNAL_ERROR","details":"Failed to delete event"}}}}}}}}}},"/events/{event_id}/status":{"patch":{"tags":["Events"],"summary":"Update event status","description":"Update event status to approved or rejected.","operationId":"update_event_status_endpoint_events__event_id__status_patch","security":[{"API Key":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}},{"name":"is_approved","in":"query","required":true,"schema":{"type":"boolean","description":"True to approve, False to reject","title":"Is Approved"},"description":"True to approve, False to reject"}],"responses":{"200":{"description":"Event status updated successfully","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"client_full_name":{"type":"string"},"client_email":{"type":"string","format":"email"},"client_phone_number":{"type":"string"},"status":{"type":"string"},"details":{"type":"string"},"starting_date":{"type":"string","format":"date-time"},"ending_date":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"type":"object","required":["ok"]},"examples":{"status_updated":{"summary":"Event status updated","description":"Example of event with updated status","value":{"ok":true,"data":{"id":"550e8400-e29b-41d4-a716-446655440000","client_full_name":"John Doe","client_email":"john.doe@example.com","client_phone_number":"+1234567890","status":"APPROVED","details":"Business meeting","starting_date":"2024-01-15T10:00:00Z","ending_date":"2024-01-15T11:00:00Z","created_at":"2024-01-14T15:30:00Z"}}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}},"500":{"description":"Failed to update event status","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"}}}}},"examples":{"internal_error":{"summary":"Internal server error","description":"Example when server fails to update event status","value":{"ok":false,"error":{"code":"INTERNAL_ERROR","details":"Failed to update event status"}}}}}}}}}},"/status":{"get":{"tags":["Health"],"summary":"Simple Status Check","description":"Simple status endpoint that returns a basic OK status. This endpoint does not require authentication.","operationId":"get_status_status_get","responses":{"200":{"description":"API is operational","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}},"additionalProperties":{"type":"string"},"type":"object","title":"Response Get Status Status Get"},"example":{"status":"ok"}}}}}}},"/lead-form":{"get":{"tags":["Lead Form"],"summary":"Get the organization's public lead-form link","description":"Return the public URL a portal should link visitors to.\n\nLeads captured through it become contacts in this organization and are\ndelivered to subscribed portals as a `contact.created` webhook.","operationId":"get_lead_form_link_lead_form_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"properties":{"url":{"type":"string","title":"Url","description":"Public URL of the organization's lead form"},"is_enabled":{"type":"boolean","title":"Is Enabled","description":"False when the form is currently not accepting leads"}},"type":"object","required":["url","is_enabled"],"description":"Public lead-form link exposed to connected portals.\n\nExternal-only schema: it deliberately shares nothing with the internal\n``LeadFormResponse`` and exposes no internal identifiers."},{"type":"null"}]},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}},"security":[{"API Key":[]}]}},"/orders":{"get":{"tags":["Orders"],"summary":"List orders","description":"Retrieve a paginated list of orders for your organization.\n\n    Supports filtering by order status:\n    - `pending` - Awaiting approval\n    - `confirmed` - Approved and in progress\n    - `completed` - Fulfilled\n    - `cancelled` - Cancelled by customer\n    - `refused` - Refused by organization\n\n    The `created_after` parameter (ISO-8601 datetime) enables incremental polling:\n    pass the `created_at` of the last order you received to get only newer ones.\n\n    Orders are returned in reverse chronological order (newest first) by default.\n\n    **Response shape note:** `data` is an object `{items, total, limit, offset}` for\n    backward compatibility. The top-level `meta` object `{limit, offset, total_items}`\n    is the standard pagination envelope and is always present.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_orders_orders_get","security":[{"API Key":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(pending|confirmed|completed|cancelled|refused)$"},{"type":"null"}],"description":"Filter by order status","title":"Status"},"description":"Filter by order status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Number of items to return","default":50,"title":"Limit"},"description":"Number of items to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","default":0,"title":"Offset"},"description":"Number of items to skip"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^-?(created_at|status|total_amount)$"},{"type":"null"}],"description":"Sort field. Prefix with '-' for descending order. Available: created_at, status, total_amount. A deterministic id tiebreaker is always appended. Example: '-created_at' (newest first, default), 'total_amount' (cheapest first).","title":"Sort"},"description":"Sort field. Prefix with '-' for descending order. Available: created_at, status, total_amount. A deterministic id tiebreaker is always appended. Example: '-created_at' (newest first, default), 'total_amount' (cheapest first)."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Return only orders created strictly after this ISO-8601 datetime (exclusive). Useful for incremental polling: pass the created_at of the last received order. Example: '2024-01-30T10:00:00Z'.","title":"Created After"},"description":"Return only orders created strictly after this ISO-8601 datetime (exclusive). Useful for incremental polling: pass the created_at of the last received order. Example: '2024-01-30T10:00:00Z'."}],"responses":{"200":{"description":"Successfully retrieved orders list","content":{"application/json":{"schema":{"title":"Response List Orders Orders Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","description":"Backward-compatible wrapper. Use top-level meta for pagination.","properties":{"items":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":{"items":[{"id":"123e4567-e89b-12d3-a456-426614174000","customer_name":"Mario","customer_surname":"Rossi","customer_phone":"+39123456789","total_amount":"45.50","currency":"EUR","status":"pending","sms_sent":true,"items":[],"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T10:00:00"}],"total":1,"limit":50,"offset":0},"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Get order details","description":"Retrieve details for a specific order.\n\n    Returns complete order information including line items,\n    status, customer details, and SMS notification status.\n\n    The order must belong to your organization.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_order_orders__order_id__get","security":[{"API Key":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successfully retrieved order","content":{"application/json":{"schema":{"title":"Response Get Order Orders  Order Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","customer_name":"Mario","customer_surname":"Rossi","customer_phone":"+39123456789","total_amount":"45.50","currency":"EUR","status":"pending","notes":"Extra napkins please","sms_sent":true,"items":[{"id":"789e0123-e89b-12d3-a456-426614174002","item_name":"Pizza Margherita","item_sku":"PIZ-001","quantity":2,"unit_price":"12.50","total_price":"25.00"}],"created_at":"2024-01-30T10:00:00","updated_at":"2024-01-30T10:00:00"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Orders"],"summary":"Update order","description":"Update an order's status or notes.\n\n    Available status transitions:\n    - `confirmed` - Approve a pending order\n    - `completed` - Mark a confirmed order as fulfilled\n    - `refused` - Refuse a pending order (requires status_reason)\n\n    Note: Orders cannot be cancelled via this endpoint.\n    Cancellation is only available to customers via the public order link.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_order_orders__order_id__patch","security":[{"API Key":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"type":"string","pattern":"^(confirmed|completed|refused)$"},{"type":"null"}],"title":"Status","description":"Order status (confirmed, completed, refused)"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Additional notes"},"status_reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Status Reason","description":"Reason for refusing the order (required when status is 'refused')"}},"type":"object","description":"Schema for updating an order via external API.","example":{"notes":"Customer requested extra napkins","status":"confirmed"}},"examples":{"confirm_order":{"summary":"Confirm a pending order","value":{"status":"confirmed"}},"complete_order":{"summary":"Mark order as completed","value":{"status":"completed"}},"refuse_order":{"summary":"Refuse a pending order","value":{"status":"refused","status_reason":"Item out of stock"}},"update_notes":{"summary":"Update order notes only","value":{"notes":"Customer called to add extra items"}}}}}},"responses":{"200":{"description":"Successfully updated order","content":{"application/json":{"schema":{"title":"Response Update Order Orders  Order Id  Patch","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","customer_name":"Mario","customer_surname":"Rossi","status":"confirmed"}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/playground/test-call":{"post":{"tags":["Playground"],"summary":"Make a test outbound call","description":"Make a test outbound call to a verified phone number for your organization.\n\n    This endpoint is designed for testing your agent configuration before\n    deploying to production. The call will be made to one of your organization's\n    verified phone numbers.\n\n    ## Requirements\n    - API Key with WRITE permission and MAKE_OUTBOUND_CALLS tier permission\n    - Agent must be of type OUTBOUND\n    - Agent must have all required fields configured (voice, language, etc.)\n    - Target phone number must be in your organization's verified phone numbers list\n\n    ## Use Cases\n    - Test agent configuration before going live\n    - Verify agent voice and conversation flow\n    - Test custom context and prompts\n    - Quality assurance for agent updates\n\n    ## Response\n    Returns a task ID that can be used to track the call execution status.\n    The call will be initiated asynchronously, and you should receive the call shortly.","operationId":"make_test_call_playground_test_call_post","requestBody":{"content":{"application/json":{"schema":{"properties":{"agent_id":{"type":"string","format":"uuid","description":"ID of the outbound agent to use for the test call","example":"550e8400-e29b-41d4-a716-446655440000"},"to_number":{"type":"string","description":"Phone number to call (must be in your organization's verified phone numbers list)","example":"+1234567890"}},"type":"object","required":["agent_id","to_number"],"description":"Request model for making a test outbound call via External API.","example":{"agent_id":"550e8400-e29b-41d4-a716-446655440000","to_number":"+1234567890"}},"example":{"agent_id":"550e8400-e29b-41d4-a716-446655440000","to_number":"+1234567890"}}},"required":true},"responses":{"201":{"description":"Test call successfully queued","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"properties":{"status":{"type":"string","title":"Status","description":"Status of the test call request"},"message":{"type":"string","title":"Message","description":"Human readable message about the test call"},"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id","description":"Celery task ID for tracking the call execution"},"agent_id":{"type":"string","title":"Agent Id","description":"ID of the agent used for the call"},"from_number":{"type":"string","title":"From Number","description":"Phone number the call was initiated from"},"to_number":{"type":"string","title":"To Number","description":"Phone number being called"}},"type":"object","required":["status","message","agent_id","from_number","to_number"],"description":"Response model for test outbound call request.","example":{"agent_id":"550e8400-e29b-41d4-a716-446655440000","from_number":"+1987654321","message":"Test call initiated from +1987654321 to +1234567890","status":"queued","task_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","to_number":"+1234567890"}},{"type":"null"}]},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]},"example":{"ok":true,"data":{"status":"queued","message":"Test call initiated from +1987654321 to +1234567890","task_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","agent_id":"550e8400-e29b-41d4-a716-446655440000","from_number":"+1987654321","to_number":"+1234567890"}}}}},"400":{"description":"Bad request - agent is not OUTBOUND type or other validation error"},"403":{"description":"Forbidden - organization lacks permissions or agent has missing required fields"},"404":{"description":"Not found - agent not found or phone number not in verified list"},"500":{"description":"Internal server error - failed to enqueue call"}},"security":[{"API Key":[]}]}},"/portal-access/{portal_type}":{"get":{"tags":["Portal access"],"summary":"Check operational access to a vertical portal","description":"Read the authenticated organization's matching marketplace entitlement. No paid plan is required to check access. OAuth callers must have a live persisted offline_access grant; API keys require READ or READ_WRITE. Recheck by valid_until and on organization changes. Verification failure is HTTP 503; a successful unpaid decision is HTTP 200 with operational_access=false. This decision never grants role permissions.","operationId":"portal_access_portal_access__portal_type__get","security":[{"API Key":[]}],"parameters":[{"name":"portal_type","in":"path","required":true,"schema":{"type":"string","enum":["food","beauty","real_estate"],"description":"The vertical CRM portals a provisioned organization can belong to."}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"properties":{"organization_id":{"type":"string","format":"uuid","title":"Organization Id","description":"Organization from verified credentials"},"portal_type":{"type":"string","enum":["food","beauty","real_estate"],"description":"Requested vertical portal"},"module_type":{"type":"string","title":"Module Type","description":"Marketplace product required by this portal"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant","description":"Entitled product variant, or null"},"operational_access":{"type":"boolean","title":"Operational Access","description":"Subscription allows business actions; role permissions still apply"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Hard entitlement deadline for a cancellation or manual grant; null for renewing subscriptions, including renewal grace periods"},"checked_at":{"type":"string","format":"date-time","title":"Checked At","description":"Time the authoritative check began"},"valid_until":{"type":"string","format":"date-time","title":"Valid Until","description":"Recheck by this instant; at most 60 seconds after checked_at and never beyond expires_at"},"purchase_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purchase Url","description":"Existing purchase flow on the configured reseller dashboard"}},"type":"object","required":["organization_id","portal_type","module_type","variant","operational_access","expires_at","checked_at","valid_until"]},{"type":"null"}]},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"503":{"description":"Subscription verification unavailable"}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Get plan usage summary","description":"Retrieve the organization's plan minutes consumption for the current\n    billing period — the same numbers shown by the dashboard usage bar.\n\n    Returns the minutes included in the plan, the minutes already used,\n    the minutes remaining from the quota, the extra minutes consumed beyond\n    the quota, and the billing period bounds. Internal credit rates and\n    pricing details are intentionally omitted.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission, or\n    - OAuth access token granted the `usage:read` scope","operationId":"get_usage_summary_usage_get","responses":{"200":{"description":"Successfully retrieved plan usage summary","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object"}},"type":"object","title":"Response Get Usage Summary Usage Get"},"example":{"ok":true,"data":{"minutes_included":"500.00","minutes_used":"123.45","minutes_remaining":"376.55","extra_minutes_used":"0.00","period_start":"2026-07-01T00:00:00Z","period_end":"2026-08-01T00:00:00Z"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}},"security":[{"API Key":[]}]}},"/wallet":{"get":{"tags":["Wallet"],"summary":"Get wallet snapshot","description":"Retrieve a read-only snapshot of the organization's wallet.\n\n    Returns the current balance, currency, active status, and auto top-up\n    configuration. Stripe IDs, payment-method details, and internal flags\n    are intentionally omitted.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_wallet_snapshot_wallet_get","responses":{"200":{"description":"Successfully retrieved wallet snapshot","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"data":{"type":"object"}},"type":"object","title":"Response Get Wallet Snapshot Wallet Get"},"example":{"ok":true,"data":{"balance":"87.50","currency":"EUR","is_active":true,"has_auto_topup":true,"topup_threshold":"10.00","topup_amount":"50.00"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}},"security":[{"API Key":[]}]}},"/wallet/transactions":{"get":{"tags":["Wallet"],"summary":"List wallet transactions","description":"Retrieve a paginated list of wallet transactions for the organization.\n\n    Optional query filters:\n    - `transaction_type` — filter by `ADD` or `CONSUME`\n    - `created_after` — return only transactions on or after this ISO-8601 datetime\n\n    Transactions are returned newest-first. Stripe references and internal\n    balance snapshots are intentionally omitted.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_wallet_transactions_wallet_transactions_get","security":[{"API Key":[]}],"parameters":[{"name":"transaction_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(ADD|CONSUME)$"},{"type":"null"}],"description":"Filter by transaction direction: 'ADD' or 'CONSUME'.","title":"Transaction Type"},"description":"Filter by transaction direction: 'ADD' or 'CONSUME'."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Return only transactions created on or after this datetime (ISO-8601, e.g. '2025-01-01T00:00:00'). Invalid values are rejected with a 400 error.","title":"Created After"},"description":"Return only transactions created on or after this datetime (ISO-8601, e.g. '2025-01-01T00:00:00'). Invalid values are rejected with a 400 error."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of transactions to return.","default":50,"title":"Limit"},"description":"Maximum number of transactions to return."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of transactions to skip.","default":0,"title":"Offset"},"description":"Number of transactions to skip."}],"responses":{"200":{"description":"Successfully retrieved wallet transactions","content":{"application/json":{"schema":{"title":"Response List Wallet Transactions Wallet Transactions Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174001","amount":"50.00","currency":"EUR","transaction_type":"ADD","source":"TOPUP","description":"Topup","created_at":"2025-06-01T14:30:00"}],"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/webhook-subscription":{"put":{"tags":["Webhooks"],"summary":"Self-register this portal's webhook","description":"Subscribe the calling portal's webhook for the authenticated organization.\n\nOAuth-token only: the client is resolved from the token (not the body), the\norg from the token's ``org`` claim — a portal can only ever register its own\nwebhook, for orgs that consented to it.","operationId":"register_webhook_subscription_webhook_subscription_put","requestBody":{"content":{"application/json":{"schema":{"properties":{"target_url":{"type":"string","title":"Target Url","description":"HTTPS receiver yourang POSTs signed event notifications to"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Event-type patterns to subscribe to (e.g. event.*, contact.*)"}},"type":"object","required":["target_url"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean","title":"Ok"},"data":{"anyOf":[{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Webhook endpoint identifier"},"target_url":{"type":"string","title":"Target Url","description":"Where deliveries are POSTed"},"event_types":{"items":{"type":"string"},"type":"array","title":"Event Types","description":"Subscribed event-type patterns"},"signing_secret":{"type":"string","title":"Signing Secret","description":"HMAC-SHA256 secret to verify X-Yourang-Signature"}},"type":"object","required":["id","target_url","event_types","signing_secret"]},{"type":"null"}]},"meta":{"anyOf":[{"properties":{"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"total_items":{"type":"integer","title":"Total Items"}},"type":"object","required":["limit","offset","total_items"]},{"type":"null"}]},"error":{"anyOf":[{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"object"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"]},{"type":"null"}]}},"type":"object","required":["ok"]}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"properties":{"ok":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}},"security":[{"API Key":[]}]}},"/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","description":"Register a destination URL to receive push deliveries for the selected\n    events.\n\n    Supported events:\n    - `call.ended` — a call finished (status, duration, transcript reference)\n    - `call.summary_ready` — the AI summary for a call is available\n    - `appointment.booked` — a reservation was confirmed\n    - `appointment.updated` — a reservation was rescheduled or its status changed\n    - `appointment.cancelled` — a reservation was cancelled\n    - `contact.created` — a new contact was created\n\n    The response includes a one-time `secret`. Store it securely: every delivery\n    is signed with it via the `X-Webhook-Signature: sha256=<hmac>` header. The\n    secret is never retrievable again.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"create_webhook_webhooks_post","security":[{"API Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"webhook_url":{"type":"string","maxLength":2000,"title":"Webhook Url","description":"HTTPS endpoint that will receive event deliveries."},"events":{"items":{"type":"string"},"type":"array","title":"Events","description":"Event types to subscribe to. Valid values: call.ended, call.summary_ready, call.transcript_ready, appointment.booked, appointment.updated, appointment.cancelled, contact.created, order.created, order.status_changed, dialer.contact.completed, dialer.campaign.completed."},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description","description":"Optional human-readable label for this subscription."}},"type":"object","required":["webhook_url","events"],"description":"Request body to register a new webhook subscription.","example":{"description":"n8n production workflow","events":["call.ended","appointment.booked"],"webhook_url":"https://example.com/hooks/inbound"}}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"schema":{"title":"Response Create Webhook Webhooks Post"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Retrieve a paginated list of your organization's webhook subscriptions,\n    newest first. Secrets are never included.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"list_webhooks_webhooks_get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Number of items to return","default":50,"title":"Limit"},"description":"Number of items to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Subscriptions retrieved","content":{"application/json":{"schema":{"title":"Response List Webhooks Webhooks Get"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/webhooks/{webhook_id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook subscription","description":"Retrieve a single webhook subscription by ID. The secret is never returned.\n\n    Authentication:\n    - API key with READ or READ_WRITE permission","operationId":"get_webhook_webhooks__webhook_id__get","security":[{"API Key":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Subscription retrieved","content":{"application/json":{"schema":{"title":"Response Get Webhook Webhooks  Webhook Id  Get"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook subscription","description":"Update a subscription's URL, subscribed events, label, or active state.\n    Only the provided fields are changed. The secret cannot be changed or\n    retrieved — delete and recreate to rotate it.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"update_webhook_webhooks__webhook_id__patch","security":[{"API Key":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"webhook_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Webhook Url","description":"New destination URL."},"events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Events","description":"Replacement set of subscribed event types."},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description","description":"New human-readable label."},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active","description":"Enable or disable deliveries to this subscription."}},"type":"object","description":"Request body to update an existing webhook subscription.\n\nAll fields are optional; only the provided fields are changed."}}}},"responses":{"200":{"description":"Subscription updated","content":{"application/json":{"schema":{"title":"Response Update Webhook Webhooks  Webhook Id  Patch"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook subscription","description":"Remove a webhook subscription. Deliveries stop immediately. The n8n trigger\n    node calls this on deactivate.\n\n    Authentication:\n    - API key with READ_WRITE permission","operationId":"delete_webhook_webhooks__webhook_id__delete","security":[{"API Key":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Webhook Id"}}],"responses":{"200":{"description":"Subscription deleted","content":{"application/json":{"schema":{"title":"Response Delete Webhook Webhooks  Webhook Id  Delete"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INVALID_REQUEST","details":"Invalid request data provided","message":"Invalid request data"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/workflows/":{"get":{"tags":["Workflows"],"summary":"List all workflows","description":"Retrieve a paginated list of workflows for the authenticated organization with optional filtering and sorting.","operationId":"list_workflows_workflows__get","security":[{"API Key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of workflows to return (1-100)","default":50,"title":"Limit"},"description":"Maximum number of workflows to return (1-100)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of workflows to skip for pagination","default":0,"title":"Offset"},"description":"Number of workflows to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort by field (prefix with '-' for descending). Options: display_name, created_at, version","title":"Sort"},"description":"Sort by field (prefix with '-' for descending). Options: display_name, created_at, version"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter workflows. Format: 'field:value'. Supported: display_name (substring match), is_enabled (true/false)","title":"Filter"},"description":"Filter workflows. Format: 'field:value'. Supported: display_name (substring match), is_enabled (true/false)"}],"responses":{"200":{"description":"Successfully retrieved workflows","content":{"application/json":{"schema":{"title":"Response List Workflows Workflows  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"is_enabled":{"type":"boolean"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"nodes_count":{"type":"integer"},"connections_count":{"type":"integer"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"123e4567-e89b-12d3-a456-426614174000","display_name":"Customer Outreach Workflow","is_enabled":true,"version":3,"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-20T14:45:00Z","nodes_count":5,"connections_count":4}],"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}}}}},"/workflows/{workflow_id}":{"get":{"tags":["Workflows"],"summary":"Get workflow details","description":"Retrieve detailed information about a specific workflow including its nodes and connections.","operationId":"get_workflow_workflows__workflow_id__get","security":[{"API Key":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}}],"responses":{"200":{"description":"Successfully retrieved workflow details","content":{"application/json":{"schema":{"title":"Response Get Workflow Workflows  Workflow Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"is_enabled":{"type":"boolean"},"nodes":{"type":"object"},"connections":{"type":"object"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"123e4567-e89b-12d3-a456-426614174000","display_name":"Customer Outreach Workflow","is_enabled":true,"nodes":{"0":{"type":"core-start","position":{"x":0,"y":0}},"1":{"type":"trigger-manual","position":{"x":100,"y":100}},"2":{"type":"agent-outbound-call","position":{"x":300,"y":100},"parameters":{"agent_id":"456e7890-e89b-12d3-a456-426614174000"}}},"connections":{"#1#trigger_data#0#input":{"transformations":[]},"#0#output#2#input_data":{"transformations":[]}},"version":3,"created_at":"2024-01-15T10:30:00Z","updated_at":"2024-01-20T14:45:00Z"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/workflows/{workflow_id}/execute":{"post":{"tags":["Workflows"],"summary":"Execute a workflow","description":"Trigger the execution of a workflow with optional input data. The workflow must be enabled.","operationId":"execute_workflow_workflows__workflow_id__execute_post","security":[{"API Key":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Optional input data for workflow execution","default":{},"title":"Input Data","additionalProperties":true},"examples":{"empty":{"summary":"No input data","value":{}},"with_data":{"summary":"With input data","value":{"phone_number":"+1234567890","customer_name":"John Doe","booking_id":"BK-12345"}}}}}},"responses":{"201":{"description":"Workflow execution started successfully","content":{"application/json":{"schema":{"title":"Response Execute Workflow Workflows  Workflow Id  Execute Post","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"execution_id":{"type":"string","format":"uuid"},"workflow_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"temporal_workflow_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"execution_id":"789e0123-e89b-12d3-a456-426614174000","workflow_id":"123e4567-e89b-12d3-a456-426614174000","status":"pending","temporal_workflow_id":"workflow-789e0123-e89b-12d3-a456-426614174000","created_at":"2024-01-25T15:30:00Z"}}}}},"400":{"description":"Workflow is disabled or invalid input","content":{"application/json":{"example":{"detail":"Workflow is disabled and cannot be executed"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/workflows/{workflow_id}/executions":{"get":{"tags":["Workflows"],"summary":"List workflow executions","description":"Retrieve a paginated list of executions for a specific workflow with optional filtering and sorting.","operationId":"list_workflow_executions_workflows__workflow_id__executions_get","security":[{"API Key":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of executions to return (1-100)","default":50,"title":"Limit"},"description":"Maximum number of executions to return (1-100)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of executions to skip for pagination","default":0,"title":"Offset"},"description":"Number of executions to skip for pagination"},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort by field (prefix with '-' for descending). Options: created_at, started_at, completed_at, status","title":"Sort"},"description":"Sort by field (prefix with '-' for descending). Options: created_at, started_at, completed_at, status"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter executions. Format: 'field:value'. Supported: status (pending/running/completed/failed/cancelled/timed_out), type (manual/api/scheduled/triggered/campaign)","title":"Filter"},"description":"Filter executions. Format: 'field:value'. Supported: status (pending/running/completed/failed/cancelled/timed_out), type (manual/api/scheduled/triggered/campaign)"}],"responses":{"200":{"description":"Successfully retrieved workflow executions","content":{"application/json":{"schema":{"title":"Response List Workflow Executions Workflows  Workflow Id  Executions Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"friendly_id":{"type":"integer"},"workflow_id":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total_items":{"type":"integer"}}}}},"example":{"ok":true,"data":[{"id":"789e0123-e89b-12d3-a456-426614174000","friendly_id":42,"workflow_id":"123e4567-e89b-12d3-a456-426614174000","type":"api","status":"completed","created_at":"2024-01-25T15:30:00Z","started_at":"2024-01-25T15:30:05Z","completed_at":"2024-01-25T15:32:00Z"}],"meta":{"limit":50,"offset":0,"total_items":1}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}},"/workflows/{workflow_id}/executions/{execution_id}":{"get":{"tags":["Workflows"],"summary":"Get workflow execution details","description":"Retrieve detailed information about a specific workflow execution including input/output data and error messages.","operationId":"get_workflow_execution_workflows__workflow_id__executions__execution_id__get","security":[{"API Key":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workflow Id"}},{"name":"execution_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Execution Id"}}],"responses":{"200":{"description":"Successfully retrieved workflow execution details","content":{"application/json":{"schema":{"title":"Response Get Workflow Execution Workflows  Workflow Id  Executions  Execution Id  Get","type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"friendly_id":{"type":"integer"},"workflow_id":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string"},"temporal_workflow_id":{"type":"string"},"temporal_run_id":{"type":"string"},"input_data":{"type":"object"},"output_data":{"type":"object"},"error_message":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"}}}}},"example":{"ok":true,"data":{"id":"789e0123-e89b-12d3-a456-426614174000","friendly_id":42,"workflow_id":"123e4567-e89b-12d3-a456-426614174000","type":"api","status":"completed","temporal_workflow_id":"workflow-789e0123-e89b-12d3-a456-426614174000","temporal_run_id":"abc123","input_data":{"phone_number":"+1234567890"},"output_data":{"call_id":"call-123","duration":120},"created_at":"2024-01-25T15:30:00Z","started_at":"2024-01-25T15:30:05Z","completed_at":"2024-01-25T15:32:00Z"}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"AUTHENTICATION_FAILED","details":"Invalid API key provided","message":"Invalid or missing API key"}}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"INSUFFICIENT_PERMISSIONS","details":"API key does not have sufficient permissions","message":"Insufficient permissions"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"details":{"type":"string"},"message":{"type":"string"}}}}},"example":{"ok":false,"error":{"code":"NOT_FOUND","details":"Resource not found","message":"Resource not found"}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API Key Authentication: Enter your organization's API key. Your key should begin with 'yk_' and can be found in your yourang.ai dashboard under Developer Settings."}}},"tags":[{"name":"Contacts","description":"Complete contact management system allowing you to create, retrieve, update, and delete contacts within your organization. Includes support for custom fields and advanced filtering options."}],"security":[{"BearerAuth":[]}]}