{"openapi":"3.1.0","info":{"title":"Suite Aerya - Integrators API v1","description":"Documentación de la API pública para Integradores y Socios Tecnológicos de Suite Aerya.\n\n**Seguridad:** Las peticiones deben autenticarse con el token Bearer del Service Account asociado a su organización en la cabecera `Authorization`.","version":"1.0.0"},"paths":{"/api/v1/integrators/reservations":{"get":{"tags":["integrators"],"summary":"List Reservations","description":"List all airline reservations for your organization with optional filters.\n\nAccess is strictly scoped to the tenant organization linked with the active Service Account.\n\nArgs:\n    current_user (CurrentUser): Authenticated context of the requesting Service Account.\n    pnr (Optional[str], optional): Search filter for PNR locator string. Defaults to None.\n    passenger_name (Optional[str], optional): Search filter for passenger name. Defaults to None.\n    status (Optional[ReservationStatus], optional): Status filter. Defaults to None.\n    skip (int, optional): Pagination offset. Defaults to 0.\n    limit (int, optional): Pagination size limit. Defaults to 50.\n\nReturns:\n    list[IntegratorReservationSummary]: List of simplified reservation summaries.","operationId":"integrator_list_reservations","parameters":[{"name":"pnr","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact or partial match of PNR","title":"Pnr"},"description":"Exact or partial match of PNR"},{"name":"passenger_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partial match of passenger first/last name","title":"Passenger Name"},"description":"Partial match of passenger first/last name"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ReservationStatus"},{"type":"null"}],"description":"Filter by flight reservation status","title":"Status"},"description":"Filter by flight reservation status"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Skip"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegratorReservationSummary"},"title":"Response Integrator List Reservations"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/reservations/{pnr}":{"get":{"tags":["integrators"],"summary":"Get Reservation","description":"Retrieve full, clean details of a single reservation by PNR locator.\n\nArgs:\n    pnr (str): PNR locator code.\n    current_user (CurrentUser): Authenticated context of the requesting Service Account.\n\nReturns:\n    IntegratorReservationDetail: Detailed reservation record.\n\nRaises:\n    HTTPException: HTTP 404 if reservation does not exist in tenant org.","operationId":"integrator_get_reservation","parameters":[{"name":"pnr","in":"path","required":true,"schema":{"type":"string","title":"Pnr"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorReservationDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/reservations/cancel":{"post":{"tags":["integrators"],"summary":"Cancel Reservations Integrator","description":"Cancel reservations by PNR for your organization.\n\nSecure endpoint for external airlines / integrators. Scoped strictly to the\ntenant organization associated with the calling Service Account or User.\n\nOnly changes the status of reservations actually registered in Suite Aerya\nto 'cancelled'. If PNRs are not found in Suite Aerya, they are recorded in\n'not_found_pnrs' without failing the batch request.\n\nArgs:\n    request (CancelReservationRequest): Cancellation request payload containing PNRs.\n    current_user (CurrentUser): Authenticated context of the requesting Service Account.\n\nReturns:\n    CancelReservationResponse: Summary of cancelled, already cancelled, and not found PNRs.\n\nRaises:\n    HTTPException: If no valid PNRs are provided in request.","operationId":"integrator_cancel_reservations","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelReservationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelReservationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/reservations/{pnr}/sync":{"post":{"tags":["integrators"],"summary":"Sync Reservation","description":"Force a manual synchronization of the PNR from the native airline PSS cache.\n\nArgs:\n    pnr (str): Target PNR locator to synchronize.\n    current_user (CurrentUser): Authenticated context of requesting Service Account.\n\nReturns:\n    dict: Synchronization status dictionary with timestamp.\n\nRaises:\n    HTTPException: HTTP 404 if reservation is not found in organization.","operationId":"integrator_sync_reservation","parameters":[{"name":"pnr","in":"path","required":true,"schema":{"type":"string","title":"Pnr"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Integrator Sync Reservation"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/stats":{"get":{"tags":["integrators"],"summary":"Get Conversation Stats","description":"Aggregate conversation metrics and breakdowns for operational dashboard KPI cards.\n\nArgs:\n    current_user (CurrentUser): Authenticated Service Account user.\n\nReturns:\n    IntegratorConversationStats: Real-time aggregated metrics across organization conversations.","operationId":"integrator_get_conversation_stats","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorConversationStats"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations":{"get":{"tags":["integrators"],"summary":"List Conversations","description":"List chat conversation summaries with rich metadata and dashboard filtering for tenant organization.\n\nArgs:\n    current_user (CurrentUser): Authenticated Service Account user.\n    status (Optional[ConversationStatus], optional): Status filter. Defaults to None.\n    resolution_status (Optional[ResolutionStatus], optional): Resolution status filter. Defaults to None.\n    priority (Optional[str], optional): Priority filter string. Defaults to None.\n    channel (Optional[ConversationChannel], optional): Channel filter. Defaults to None.\n    display_id (Optional[str], optional): Exact display_id filter. Defaults to None.\n    created_after (Optional[datetime], optional): Timestamp lower bound. Defaults to None.\n    created_before (Optional[datetime], optional): Timestamp upper bound. Defaults to None.\n    search (Optional[str], optional): Search keyword. Defaults to None.\n    escalated_queue (Optional[bool], optional): Escalated status filter. Defaults to None.\n    flag (Optional[str], optional): Specific flag filter. Defaults to None.\n    flags (Optional[list[str]], optional): List of flags filter. Defaults to None.\n    has_flags (Optional[bool], optional): Flag presence filter. Defaults to None.\n    sort_by (Optional[str], optional): Sort expression. Defaults to \"-created_at\".\n    skip (int, optional): Offset number. Defaults to 0.\n    limit (int, optional): Return limit. Defaults to 50.\n\nReturns:\n    PaginatedResponse[IntegratorConversationSummary]: Paginated conversation summaries with metadata.","operationId":"integrator_list_conversations","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ConversationStatus"},{"type":"null"}],"description":"Filter by operational status","title":"Status"},"description":"Filter by operational status"},{"name":"resolution_status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResolutionStatus"},{"type":"null"}],"description":"Filter by resolution status","title":"Resolution Status"},"description":"Filter by resolution status"},{"name":"priority","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by priority (high, medium, low)","title":"Priority"},"description":"Filter by priority (high, medium, low)"},{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ConversationChannel"},{"type":"null"}],"description":"Filter by communication channel","title":"Channel"},"description":"Filter by communication channel"},{"name":"display_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by exact display locator (e.g. DEW-000746)","title":"Display Id"},"description":"Filter by exact display locator (e.g. DEW-000746)"},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter conversations created on or after timestamp","title":"Created After"},"description":"Filter conversations created on or after timestamp"},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter conversations created on or before timestamp","title":"Created Before"},"description":"Filter conversations created on or before timestamp"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search across display_id, summary, references, participant names","title":"Search"},"description":"Search across display_id, summary, references, participant names"},{"name":"escalated_queue","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by escalated queue status","title":"Escalated Queue"},"description":"Filter by escalated queue status"},{"name":"flag","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by a specific flag (e.g. revisar, warning, urgent)","title":"Flag"},"description":"Filter by a specific flag (e.g. revisar, warning, urgent)"},{"name":"flags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by one or more specific flags","title":"Flags"},"description":"Filter by one or more specific flags"},{"name":"has_flags","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by presence or absence of flags","title":"Has Flags"},"description":"Filter by presence or absence of flags"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Field to sort by (prefix with - for descending)","default":"-created_at","title":"Sort By"},"description":"Field to sort by (prefix with - for descending)"},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Skip"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_IntegratorConversationSummary_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/{conversation_id}":{"get":{"tags":["integrators"],"summary":"Get Conversation Detail","description":"Retrieve full details for a single chat conversation including participants and history.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    current_user (CurrentUser): Authenticated Service Account context.\n    include_messages (bool, optional): If true, message buckets are flattened and returned embedded. Defaults to False.\n    message_limit (int, optional): Max messages embedded when include_messages is True. Defaults to 100.\n\nReturns:\n    IntegratorConversationDetail: Detailed conversation record with participant and status history breakdown.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found or ID is invalid.","operationId":"integrator_get_conversation_detail","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"include_messages","in":"query","required":false,"schema":{"type":"boolean","description":"Embed messages in the conversation detail response","default":false,"title":"Include Messages"},"description":"Embed messages in the conversation detail response"},{"name":"message_limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max messages when include_messages=true","default":100,"title":"Message Limit"},"description":"Max messages when include_messages=true"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorConversationDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/{conversation_id}/messages":{"get":{"tags":["integrators"],"summary":"Get Conversation Messages","description":"Retrieve full, flattened list of messages (chronological) for auditing a conversation.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    current_user (CurrentUser): Authenticated Service Account context.\n    skip (int, optional): Number of messages to skip. Defaults to 0.\n    limit (int, optional): Max messages to return. Defaults to 100.\n\nReturns:\n    list[IntegratorMessageSummary]: Chronological message thread.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found or ID is invalid.","operationId":"integrator_get_conversation_messages","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of messages to skip in chronological thread","default":0,"title":"Skip"},"description":"Number of messages to skip in chronological thread"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max messages to return","default":100,"title":"Limit"},"description":"Max messages to return"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegratorMessageSummary"},"title":"Response Integrator Get Conversation Messages"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/{conversation_id}/flags":{"get":{"tags":["integrators"],"summary":"Get Conversation Flags","description":"Retrieve the list of active flags assigned to a conversation.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    list[str]: Array of active flag strings.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found in organization.","operationId":"integrator_get_conversation_flags","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"title":"Response Integrator Get Conversation Flags"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["integrators"],"summary":"Toggle Conversation Flag","description":"Toggle a flag on a conversation (adds if absent, removes if present).\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    request (IntegratorToggleFlagRequest): Flag label to toggle.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    list[str]: Updated list of conversation flags.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found in organization.","operationId":"integrator_toggle_conversation_flag","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorToggleFlagRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"title":"Response Integrator Toggle Conversation Flag"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["integrators"],"summary":"Set Conversation Flags","description":"Set or replace the full list of flags assigned to a conversation.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    request (IntegratorSetFlagsRequest): New list of flags.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    list[str]: Updated list of conversation flags.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found in organization.","operationId":"integrator_set_conversation_flags","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorSetFlagsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"title":"Response Integrator Set Conversation Flags"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/{conversation_id}/comments":{"get":{"tags":["integrators"],"summary":"List Conversation Comments","description":"List all internal staff and integrator comments for a conversation.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    list[IntegratorInternalCommentResponse]: Chronological list of internal comments.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found in organization.","operationId":"integrator_list_conversation_comments","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegratorInternalCommentResponse"},"title":"Response Integrator List Conversation Comments"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["integrators"],"summary":"Add Conversation Comment","description":"Add an internal comment to a conversation authored by the active Service Account.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    request (IntegratorAddCommentRequest): Comment content.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    IntegratorInternalCommentResponse: Newly created internal comment.\n\nRaises:\n    HTTPException: HTTP 404 if conversation is not found in organization.","operationId":"integrator_add_conversation_comment","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorAddCommentRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorInternalCommentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/conversations/{conversation_id}/comments/{comment_id}":{"delete":{"tags":["integrators"],"summary":"Delete Conversation Comment","description":"Delete an internal comment from a conversation.\n\nArgs:\n    conversation_id (str): Conversation document identifier.\n    comment_id (str): Internal comment unique identifier.\n    current_user (CurrentUser): Authenticated Service Account context.\n\nReturns:\n    dict: Success confirmation with deleted comment ID.\n\nRaises:\n    HTTPException: HTTP 404 if conversation or comment is not found.","operationId":"integrator_delete_conversation_comment","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","title":"Conversation Id"}},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","title":"Comment Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Integrator Delete Conversation Comment"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/webhooks":{"get":{"tags":["integrators"],"summary":"List Webhooks","description":"Retrieve all outbound integrator webhook configurations.\n\nArgs:\n    current_user (CurrentUser): Authenticated Service Account user.\n\nReturns:\n    list[IntegratorWebhookResponse]: Registered webhooks with masked secrets.","operationId":"integrator_list_webhooks","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegratorWebhookResponse"},"title":"Response Integrator List Webhooks"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["integrators"],"summary":"Create Webhook","description":"Register a new developer callback URL for real-time integration events.\n\nArgs:\n    request (IntegratorWebhookCreateRequest): Payload specifying callback URL and event triggers.\n    current_user (CurrentUser): Authenticated Service Account user.\n\nReturns:\n    IntegratorWebhookResponse: Newly registered webhook endpoint metadata with raw secret.","operationId":"integrator_create_webhook","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorWebhookCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorWebhookResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/webhooks/{webhook_id}":{"delete":{"tags":["integrators"],"summary":"Delete Webhook","description":"Permanently delete an integrator webhook configuration.\n\nArgs:\n    webhook_id (str): Webhook endpoint identifier.\n    current_user (CurrentUser): Authenticated Service Account user.\n\nRaises:\n    HTTPException: HTTP 404 if webhook is not found or ID is invalid.","operationId":"integrator_delete_webhook","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","title":"Webhook Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/events/stream":{"get":{"tags":["integrators"],"summary":"Stream Integrator Events","description":"Stream real-time events for the authenticated integrator organization via Server-Sent Events (SSE).\n\nReceives new conversations, messages, status updates, flag changes, and internal comments in real time.\n\nAuthentication supports both:\n- Query parameter: `?token=<service_account_token>` (recommended for browser EventSource)\n- Header: `Authorization: Bearer <service_account_token>`\n\nReturns:\n    StreamingResponse: An SSE stream (text/event-stream) of real-time organization events.","operationId":"integrator_stream_events","parameters":[{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bearer token for authentication (query param or Authorization header)","title":"Token"},"description":"Bearer token for authentication (query param or Authorization header)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/integrators/webcomponent/token":{"post":{"tags":["integrators"],"summary":"Create Webcomponent Token Endpoint","description":"Generate a scoped, short-lived token for Web Component embedding.\n\nAllows integrators to securely embed Aerya Web Components (<aerya-dashboard>,\n<aerya-conversations>, <aerya-knowledge>, etc.) in their web applications\nwithout exposing long-lived Service Account tokens in client-side HTML or JS.\n\nThe returned token:\n- Has a short lifetime (default 60 minutes, configurable up to 24h).\n- Is restricted only to the permissions needed for the requested component.\n- Can be instantly revoked by rotating or deleting the parent Service Account.","operationId":"integrator_create_webcomponent_token","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorWebComponentTokenRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratorWebComponentTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CancelReservationRequest":{"properties":{"pnrs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Pnrs","description":"List of PNR locator codes to cancel"},"pnr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pnr","description":"Single PNR locator code to cancel"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Optional cancellation reason"},"cancelled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cancelled At","description":"Optional cancellation timestamp (UTC)"}},"type":"object","title":"CancelReservationRequest","description":"Request payload to cancel one or more PNRs for an organization.\n\nAttributes:\n    pnrs (Optional[list[str]]): List of PNR locator codes.\n    pnr (Optional[str]): Single PNR locator code.\n    reason (Optional[str]): Optional reason for cancellation from the airline.\n    cancelled_at (Optional[datetime]): Optional UTC timestamp when cancellation occurred."},"CancelReservationResponse":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"total_received":{"type":"integer","title":"Total Received"},"cancelled_count":{"type":"integer","title":"Cancelled Count"},"cancelled_pnrs":{"items":{"type":"string"},"type":"array","title":"Cancelled Pnrs"},"already_cancelled_pnrs":{"items":{"type":"string"},"type":"array","title":"Already Cancelled Pnrs","default":[]},"not_found_pnrs":{"items":{"type":"string"},"type":"array","title":"Not Found Pnrs","default":[]},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["total_received","cancelled_count","cancelled_pnrs","timestamp"],"title":"CancelReservationResponse","description":"Response payload detailing the outcome of the PNR cancellation request.\n\nAttributes:\n    success (bool): Indicates if the operation completed successfully.\n    total_received (int): Total count of unique PNRs evaluated.\n    cancelled_count (int): Number of registered reservations newly transitioned to cancelled.\n    cancelled_pnrs (list[str]): List of PNRs that were updated to cancelled.\n    already_cancelled_pnrs (list[str]): List of PNRs that were already cancelled (idempotent).\n    not_found_pnrs (list[str]): List of PNRs that were not found in Suite Aerya for this organization.\n    timestamp (datetime): UTC timestamp of the cancellation execution."},"ConversationChannel":{"type":"string","enum":["web","whatsapp","voice","email","api","instagram","mobile","ads","other"],"title":"ConversationChannel","description":"Source channel for conversation."},"ConversationStatus":{"type":"string","enum":["in_progress","in_warning","claimed","ended","unknown","escalated","open","closed","archived"],"title":"ConversationStatus","description":"Conversation lifecycle status."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IntegratorAddCommentRequest":{"properties":{"content":{"type":"string","minLength":1,"title":"Content","description":"Text content of the comment"}},"type":"object","required":["content"],"title":"IntegratorAddCommentRequest","description":"Request body to append an internal comment to a conversation.\n\nAttributes:\n    content: Text content of the comment."},"IntegratorAttachment":{"properties":{"name":{"type":"string","title":"Name"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes"}},"type":"object","required":["name"],"title":"IntegratorAttachment","description":"File attachment in a message.\n\nAttributes:\n    name: Filename.\n    url: Download URL.\n    content_type: MIME type.\n    size_bytes: File size in bytes."},"IntegratorControlState":{"properties":{"mode":{"type":"string","title":"Mode","default":"ai"},"assigned_agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assigned Agent Id"},"assigned_agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assigned Agent Name"}},"type":"object","title":"IntegratorControlState","description":"Simplified conversation control state for integrators.\n\nAttributes:\n    mode: Control mode (ai, human_control).\n    assigned_agent_id: ID of the assigned human agent if any.\n    assigned_agent_name: Name of the assigned human agent if any."},"IntegratorConversationAnalysis":{"properties":{"quality_score":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Quality Score","default":0},"sentiment":{"type":"string","title":"Sentiment","default":"neutral"},"resolution_status":{"type":"string","title":"Resolution Status","default":"unknown"},"summary":{"type":"string","title":"Summary","default":""},"topic_tags":{"items":{"type":"string"},"type":"array","title":"Topic Tags"},"customer_effort_score":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Customer Effort Score","default":5},"first_contact_resolution":{"type":"boolean","title":"First Contact Resolution","default":false},"escalation_risk":{"type":"integer","maximum":10.0,"minimum":0.0,"title":"Escalation Risk","default":0},"language":{"type":"string","title":"Language","default":""},"key_issues":{"items":{"type":"string"},"type":"array","title":"Key Issues"}},"type":"object","title":"IntegratorConversationAnalysis","description":"Post-conversation AI analysis metrics.\n\nAttributes:\n    quality_score: Agent attention quality score (0-10).\n    sentiment: Overall customer sentiment.\n    resolution_status: Resolution outcome from AI analysis.\n    summary: AI-generated conversation summary.\n    topic_tags: Detected topic categories (max 5).\n    customer_effort_score: Customer effort metric (0-10, 10=very hard).\n    first_contact_resolution: Whether resolved without escalation.\n    escalation_risk: Escalation likelihood (0-10).\n    language: Detected language ISO code.\n    key_issues: Top issues identified (max 3)."},"IntegratorConversationDetail":{"properties":{"id":{"type":"string","title":"Id"},"display_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Id"},"correlative_numeric":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Correlative Numeric"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"resolution_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Status"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"channel":{"type":"string","title":"Channel"},"total_messages":{"type":"integer","title":"Total Messages","default":0},"message_count":{"type":"integer","title":"Message Count","default":0},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"duration_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Minutes"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"},"participants":{"items":{"$ref":"#/components/schemas/IntegratorParticipantSummary"},"type":"array","title":"Participants"},"reservation_pnrs":{"items":{"type":"string"},"type":"array","title":"Reservation Pnrs"},"reservation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reservation Status"},"reservation_statuses":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Reservation Statuses"},"references":{"items":{"$ref":"#/components/schemas/IntegratorReferenceSummary"},"type":"array","title":"References"},"last_tool_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Tool Used"},"ended_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ended Reason"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_message_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Message At"},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Closed At"},"escalated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Escalated At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"is_guest":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Guest"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"tool_usage":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Tool Usage"},"tool_call_count":{"type":"integer","title":"Tool Call Count","default":0},"analysis":{"anyOf":[{"$ref":"#/components/schemas/IntegratorConversationAnalysis"},{"type":"null"}]},"escalated_queue":{"type":"boolean","title":"Escalated Queue","default":false},"designated_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Designated To"},"last_active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Active At"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"current_bucket_index":{"type":"integer","title":"Current Bucket Index","default":0},"status_history":{"items":{"$ref":"#/components/schemas/IntegratorStatusHistoryEntry"},"type":"array","title":"Status History"},"control_state":{"anyOf":[{"$ref":"#/components/schemas/IntegratorControlState"},{"type":"null"}]},"internal_comments":{"items":{"$ref":"#/components/schemas/IntegratorInternalCommentResponse"},"type":"array","title":"Internal Comments"},"messages":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntegratorMessageSummary"},"type":"array"},{"type":"null"}],"title":"Messages"}},"type":"object","required":["id","status","channel","created_at"],"title":"IntegratorConversationDetail","description":"Full detail of a chat conversation including participants, history, internal comments, and optional messages.\n\nAttributes:\n    current_bucket_index: Bucket index for message chunking.\n    status_history: Timeline of status transitions.\n    control_state: Current control state (ai vs human).\n    internal_comments: List of internal staff and integrator comments.\n    messages: Optional embedded list of chronological messages."},"IntegratorConversationStats":{"properties":{"total":{"type":"integer","title":"Total","default":0},"active":{"type":"integer","title":"Active","default":0},"resolved_today":{"type":"integer","title":"Resolved Today","default":0},"escalated":{"type":"integer","title":"Escalated","default":0},"avg_duration_minutes":{"type":"number","title":"Avg Duration Minutes","default":0.0},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status"},"by_channel":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Channel"},"by_priority":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Priority"}},"type":"object","title":"IntegratorConversationStats","description":"Aggregate conversation statistics for dashboard KPI cards.\n\nAttributes:\n    total: Total conversations in the organization.\n    active: Currently in-progress conversations.\n    resolved_today: Conversations resolved today.\n    escalated: Conversations currently in escalated queue.\n    avg_duration_minutes: Average conversation duration in minutes.\n    by_status: Count breakdown by status.\n    by_channel: Count breakdown by channel.\n    by_priority: Count breakdown by priority."},"IntegratorConversationSummary":{"properties":{"id":{"type":"string","title":"Id"},"display_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Id"},"correlative_numeric":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Correlative Numeric"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"resolution_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Status"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"channel":{"type":"string","title":"Channel"},"total_messages":{"type":"integer","title":"Total Messages","default":0},"message_count":{"type":"integer","title":"Message Count","default":0},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"duration_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Minutes"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"},"participants":{"items":{"$ref":"#/components/schemas/IntegratorParticipantSummary"},"type":"array","title":"Participants"},"reservation_pnrs":{"items":{"type":"string"},"type":"array","title":"Reservation Pnrs"},"reservation_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reservation Status"},"reservation_statuses":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Reservation Statuses"},"references":{"items":{"$ref":"#/components/schemas/IntegratorReferenceSummary"},"type":"array","title":"References"},"last_tool_used":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Tool Used"},"ended_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ended Reason"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_message_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Message At"},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Closed At"},"escalated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Escalated At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"is_guest":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Guest"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"tool_usage":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Tool Usage"},"tool_call_count":{"type":"integer","title":"Tool Call Count","default":0},"analysis":{"anyOf":[{"$ref":"#/components/schemas/IntegratorConversationAnalysis"},{"type":"null"}]},"escalated_queue":{"type":"boolean","title":"Escalated Queue","default":false},"designated_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Designated To"},"last_active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Active At"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","status","channel","created_at"],"title":"IntegratorConversationSummary","description":"Comprehensive chat conversation summary for frontend tables and developer dashboards.\n\nAttributes:\n    id: Conversation document identifier.\n    display_id: Human-readable tenant-scoped display locator (e.g. DEW-000746).\n    correlative_numeric: Sequential correlative number.\n    status: Primary operational status of the conversation.\n    resolution_status: Resolution outcome status.\n    priority: Priority tag if set.\n    channel: Originating communication channel.\n    total_messages: Total count of messages exchanged.\n    message_count: Alias for total_messages for frontend compatibility (deprecated).\n    summary: AI-generated or system conversation summary.\n    duration_minutes: Active duration in minutes once closed.\n    duration: Duration metric in minutes/seconds for table UI (deprecated alias).\n    tags: Categorization tags.\n    flags: Special attention flags.\n    participants: List of active/historical conversation participants.\n    reservation_pnrs: List of associated reservation PNRs.\n    reservation_status: Primary reservation status.\n    reservation_statuses: Map of PNR to reservation status.\n    references: Linked domain references.\n    last_tool_used: Identifier of the last AI tool invoked.\n    ended_reason: Reason conversation ended if applicable.\n    created_at: Conversation initiation timestamp.\n    last_message_at: Timestamp of latest message.\n    closed_at: Timestamp when conversation ended.\n    escalated_at: Timestamp when conversation was escalated.\n    updated_at: Timestamp of last document update.\n    platform: Platform type if available (e.g. web, mobile).\n    is_guest: Flag indicating whether user is a guest.\n    agent_id: AI Agent identifier assigned.\n    currency: Currency code if active in conversation.\n    tool_usage: Usage count breakdown per tool.\n    tool_call_count: Total tool calls executed.\n    analysis: Post-conversation AI analysis metrics.\n    escalated_queue: Whether conversation is in escalated inbox.\n    designated_to: Optional assigned human staff identifier.\n    last_active_at: Last user activity timestamp.\n    metadata: Raw operational metadata dictionary (includes phone, customer_name, wa_id, tool_usage, etc.)."},"IntegratorFlightSegment":{"properties":{"flight_number":{"type":"string","title":"Flight Number"},"carrier_code":{"type":"string","title":"Carrier Code"},"origin":{"type":"string","title":"Origin"},"destination":{"type":"string","title":"Destination"},"departure_time":{"type":"string","format":"date-time","title":"Departure Time"},"arrival_time":{"type":"string","format":"date-time","title":"Arrival Time"},"cabin_class":{"type":"string","title":"Cabin Class"}},"type":"object","required":["flight_number","carrier_code","origin","destination","departure_time","arrival_time","cabin_class"],"title":"IntegratorFlightSegment","description":"Simplified flight segment details.\n\nAttributes:\n    flight_number: Flight number.\n    carrier_code: Airline carrier code (IATA/ICAO).\n    origin: Departure airport code.\n    destination: Arrival airport code.\n    departure_time: Departure timestamp.\n    arrival_time: Arrival timestamp.\n    cabin_class: Cabin class category."},"IntegratorInternalCommentResponse":{"properties":{"id":{"type":"string","title":"Id"},"author_id":{"type":"string","title":"Author Id"},"author_email":{"type":"string","title":"Author Email"},"content":{"type":"string","title":"Content"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","author_id","author_email","content","created_at"],"title":"IntegratorInternalCommentResponse","description":"Internal staff/integrator comment attached to a conversation.\n\nAttributes:\n    id: Unique comment identifier.\n    author_id: Identifier of the author (Service Account or User ID).\n    author_email: Email / principal name of the author.\n    content: Text content of the comment.\n    created_at: Timestamp when comment was added."},"IntegratorMessageSummary":{"properties":{"sender_type":{"type":"string","title":"Sender Type"},"sender_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Name"},"sender_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Id"},"content":{"type":"string","title":"Content"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"tool_calls_count":{"type":"integer","title":"Tool Calls Count","default":0},"attachments":{"items":{"$ref":"#/components/schemas/IntegratorAttachment"},"type":"array","title":"Attachments"}},"type":"object","required":["sender_type","content","timestamp"],"title":"IntegratorMessageSummary","description":"Flat and clean message representation for integrators.\n\nAttributes:\n    sender_type: Type of sender (user, agent, admin, system).\n    sender_name: Display name or actor label of the sender.\n    sender_id: Identifier of the sender.\n    content: Message text content.\n    timestamp: Message dispatch timestamp.\n    tool_calls_count: Number of AI tool calls associated with the message.\n    attachments: List of attachments included with the message."},"IntegratorParticipantSummary":{"properties":{"actor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Id"},"actor_type":{"type":"string","title":"Actor Type"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"is_registered_user":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Registered User"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External User Id"}},"type":"object","required":["actor_type"],"title":"IntegratorParticipantSummary","description":"Participant summary representation for integrators and frontend tables.\n\nAttributes:\n    actor_id: Actor identifier if registered user or agent.\n    actor_type: Category of participant (e.g. user, agent, admin, system).\n    full_name: Full name if available.\n    email: Contact email if available.\n    is_registered_user: Flag indicating whether participant is registered in tenant system.\n    external_user_id: External system user ID."},"IntegratorPassenger":{"properties":{"first_name":{"type":"string","title":"First Name"},"last_name":{"type":"string","title":"Last Name"},"type":{"type":"string","title":"Type"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["first_name","last_name","type"],"title":"IntegratorPassenger","description":"Simplified passenger details for external consumption.\n\nAttributes:\n    first_name: First name of passenger.\n    last_name: Last name of passenger.\n    type: Passenger type code (e.g., ADT, CHD, INF).\n    gender: Gender identifier if provided.\n    email: Contact email address.\n    phone: Contact telephone number."},"IntegratorReferenceSummary":{"properties":{"kind":{"type":"string","title":"Kind"},"external_ref":{"type":"string","title":"External Ref"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["kind","external_ref"],"title":"IntegratorReferenceSummary","description":"Domain reference associated with a conversation.\n\nAttributes:\n    kind: Type of linked domain entity (e.g. airline.reservation).\n    external_ref: Locator or primary reference identifier.\n    label: Optional descriptive label.\n    entity_id: Optional database entity identifier if linked.\n    confidence: Optional confidence score for AI-detected references.\n    metadata: Optional additional metadata dict."},"IntegratorReservationDetail":{"properties":{"id":{"type":"string","title":"Id"},"pnr":{"type":"string","title":"Pnr"},"status":{"$ref":"#/components/schemas/ReservationStatus"},"passengers":{"items":{"$ref":"#/components/schemas/IntegratorPassenger"},"type":"array","title":"Passengers"},"segments":{"items":{"$ref":"#/components/schemas/IntegratorFlightSegment"},"type":"array","title":"Segments"},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email"},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Phone"},"currency":{"type":"string","title":"Currency","default":"USD"},"total_amount":{"type":"number","title":"Total Amount","default":0.0},"pss_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Pss Synced At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","pnr","status","passengers","segments","created_at","updated_at"],"title":"IntegratorReservationDetail","description":"Comprehensive reservation details structured for integrators.\n\nAttributes:\n    id: Reservation document identifier.\n    pnr: Passenger Name Record locator.\n    status: Reservation status.\n    passengers: List of detailed passenger records.\n    segments: Flight segments forming the itinerary.\n    contact_email: Primary contact email.\n    contact_phone: Primary contact phone.\n    currency: Pricing currency.\n    total_amount: Total booking price.\n    pss_synced_at: Last sync timestamp with native PSS.\n    created_at: Creation timestamp.\n    updated_at: Last modification timestamp."},"IntegratorReservationSummary":{"properties":{"id":{"type":"string","title":"Id"},"pnr":{"type":"string","title":"Pnr"},"status":{"$ref":"#/components/schemas/ReservationStatus"},"total_passengers":{"type":"integer","title":"Total Passengers"},"passenger_names":{"items":{"type":"string"},"type":"array","title":"Passenger Names"},"origin":{"type":"string","title":"Origin"},"destination":{"type":"string","title":"Destination"},"departure_time":{"type":"string","format":"date-time","title":"Departure Time"},"arrival_time":{"type":"string","format":"date-time","title":"Arrival Time"},"total_amount":{"type":"number","title":"Total Amount"},"currency":{"type":"string","title":"Currency"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","pnr","status","total_passengers","passenger_names","origin","destination","departure_time","arrival_time","total_amount","currency","created_at","updated_at"],"title":"IntegratorReservationSummary","description":"Simplified, flat summary of a reservation for developer dashboards.\n\nAttributes:\n    id: Reservation document identifier.\n    pnr: Passenger Name Record locator.\n    status: Current status of the reservation.\n    total_passengers: Count of passengers included in the booking.\n    passenger_names: List of passenger full names.\n    origin: Origin airport code (IATA).\n    destination: Destination airport code (IATA).\n    departure_time: Outbound departure timestamp.\n    arrival_time: Inbound/final arrival timestamp.\n    total_amount: Total cost of reservation.\n    currency: Currency code (e.g. USD).\n    created_at: Booking creation timestamp.\n    updated_at: Booking last update timestamp."},"IntegratorSetFlagsRequest":{"properties":{"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"List of flags to set"}},"type":"object","title":"IntegratorSetFlagsRequest","description":"Request body to replace all flags on a conversation.\n\nAttributes:\n    flags: Complete list of flags to assign."},"IntegratorStatusHistoryEntry":{"properties":{"from_status":{"type":"string","title":"From Status"},"to_status":{"type":"string","title":"To Status"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"actor_type":{"type":"string","title":"Actor Type"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"type":"object","required":["from_status","to_status","timestamp","actor_type"],"title":"IntegratorStatusHistoryEntry","description":"Entry in conversation status change history.\n\nAttributes:\n    from_status: Previous status.\n    to_status: New status.\n    timestamp: When the change occurred.\n    actor_type: Type of actor that triggered the change.\n    reason: Optional reason for the change."},"IntegratorToggleFlagRequest":{"properties":{"flag":{"type":"string","minLength":1,"title":"Flag","description":"Flag label to toggle"}},"type":"object","required":["flag"],"title":"IntegratorToggleFlagRequest","description":"Request body to toggle a flag on a conversation.\n\nAttributes:\n    flag: Flag label to toggle (e.g. 'revisar', 'warning', 'errada', 'exitosa', 'pendiente')."},"IntegratorWebComponentTokenRequest":{"properties":{"component":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component","description":"Target web component (e.g. 'dashboard', 'conversations', 'knowledge', 'reservations', 'all'). Auto-populates recommended permissions if 'permissions' is omitted.","examples":["dashboard","conversations"]},"permissions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Permissions","description":"Granular permissions to grant to the web component token. Must be a subset of the caller's permissions.","examples":[["read:dashboard","read:conversations"]]},"expires_in_minutes":{"anyOf":[{"type":"integer","maximum":1440.0,"minimum":5.0},{"type":"null"}],"title":"Expires In Minutes","description":"Token lifetime in minutes (min 5, max 1440, default 60).","default":60},"external_user_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External User Id","description":"Optional identifier of the end-user/agent in the integrator's system for auditing."}},"type":"object","title":"IntegratorWebComponentTokenRequest","description":"Request payload to generate a scoped, short-lived token for Web Component embedding."},"IntegratorWebComponentTokenResponse":{"properties":{"token":{"type":"string","title":"Token","description":"Scoped JWT token to pass to the web component <aerya-* token='...'>"},"token_type":{"type":"string","title":"Token Type","description":"Token type","default":"bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Token lifetime in seconds"},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Expiration timestamp (UTC ISO-8601)"},"org_id":{"type":"string","title":"Org Id","description":"Organization ID associated with the token"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions","description":"Permissions granted to this token"},"component":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component","description":"Target component for which the token was configured"}},"type":"object","required":["token","expires_in","expires_at","org_id","permissions"],"title":"IntegratorWebComponentTokenResponse","description":"Response containing the short-lived Web Component embedding token."},"IntegratorWebhookCreateRequest":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"Callback target URL"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Descriptive label for this webhook"},"events":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array","title":"Events","description":"Event subscriptions","default":["reservation.created","reservation.ticketed","conversation.created","conversation.escalated"]}},"type":"object","required":["url"],"title":"IntegratorWebhookCreateRequest","description":"Request payload to subscribe a callback URL to real-time integration events.\n\nAttributes:\n    url: Callback target URL.\n    description: Descriptive label for this webhook subscription.\n    events: Subscribed event triggers."},"IntegratorWebhookResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"events":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array","title":"Events"},"status":{"$ref":"#/components/schemas/WebhookEndpointStatus"},"secret":{"type":"string","title":"Secret"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","url","events","status","secret","created_at"],"title":"IntegratorWebhookResponse","description":"Registered webhook endpoint metadata returned to developer.\n\nAttributes:\n    id: Webhook subscription identifier.\n    url: Target callback URL.\n    description: Label description.\n    events: Active event subscriptions.\n    status: Operational status of the webhook endpoint.\n    secret: Signing secret (masked in list endpoints).\n    created_at: Registration timestamp."},"PaginatedResponse_IntegratorConversationSummary_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntegratorConversationSummary"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"skip":{"type":"integer","title":"Skip"},"limit":{"type":"integer","title":"Limit"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["items","total","skip","limit","has_more"],"title":"PaginatedResponse[IntegratorConversationSummary]"},"ReservationStatus":{"type":"string","enum":["pending_issue","issued","expired","cancelled"],"title":"ReservationStatus","description":"Reservation lifecycle status (aligned with Rutaca).\n\nAttributes:\n    PENDING_ISSUE (str): Booking created, awaiting ticketing.\n    ISSUED (str): Ticket issued / approved.\n    EXPIRED (str): Time limit passed.\n    CANCELLED (str): Reservation cancelled by airline or system."},"ResolutionStatus":{"type":"string","enum":["timeout","agent_closed","bot_resolved","unresolved"],"title":"ResolutionStatus","description":"Resolution status for the conversation."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookEndpointStatus":{"type":"string","enum":["active","inactive","disabled"],"title":"WebhookEndpointStatus","description":"Status of a webhook endpoint.\n\nAttributes:\n    ACTIVE (str): The endpoint is active and receiving events.\n    INACTIVE (str): The endpoint is inactive and not receiving events.\n    DISABLED (str): The endpoint has been disabled by the system, usually due to repeated failures."},"WebhookEvent":{"type":"string","enum":["payment.checkout.requested","payment.checkout.created","payment.checkout.failed","payment.transaction.pending","payment.transaction.processing","payment.transaction.completed","payment.transaction.failed","payment.transaction.cancelled","payment.transaction.refunded","conversation.created","conversation.message_added","conversation.control_state_updated","conversation.escalated","conversation.ended","reservation.created","reservation.confirmed","reservation.ticketed","webhook.test"],"title":"WebhookEvent","description":"Canonical webhook event types across domains.\n\nAttributes:\n    PAYMENT_CHECKOUT_REQUESTED (str): Event triggered when a checkout is requested.\n    PAYMENT_CHECKOUT_CREATED (str): Event triggered when a checkout is created.\n    PAYMENT_CHECKOUT_FAILED (str): Event triggered when a checkout fails.\n    PAYMENT_TRANSACTION_PENDING (str): Event triggered when a transaction is pending.\n    PAYMENT_TRANSACTION_PROCESSING (str): Event triggered when a transaction is processing.\n    PAYMENT_TRANSACTION_COMPLETED (str): Event triggered when a transaction is completed.\n    PAYMENT_TRANSACTION_FAILED (str): Event triggered when a transaction fails.\n    PAYMENT_TRANSACTION_CANCELLED (str): Event triggered when a transaction is cancelled.\n    PAYMENT_TRANSACTION_REFUNDED (str): Event triggered when a transaction is refunded.\n    CONVERSATION_CREATED (str): Event triggered when a conversation is created.\n    CONVERSATION_MESSAGE_ADDED (str): Event triggered when a message is added to a conversation.\n    CONVERSATION_CONTROL_STATE_UPDATED (str): Event triggered when a conversation's control state is updated.\n    CONVERSATION_ESCALATED (str): Event triggered when a conversation is escalated.\n    CONVERSATION_ENDED (str): Event triggered when a conversation is ended.\n    RESERVATION_CREATED (str): Event triggered when a reservation is created.\n    RESERVATION_CONFIRMED (str): Event triggered when a reservation is confirmed.\n    RESERVATION_TICKETED (str): Event triggered when a reservation is ticketed.\n    WEBHOOK_TEST (str): Event triggered to test the webhook configuration."}}}}