{
	"openapi": "3.0.3",
	"info": {
		"title": "Samora AI API",
		"description": "The Samora AI API lets you trigger immediate outbound calls and manage outbound campaigns through the Samora AI system. Use it to start calls with your AI agents, pass context via metadata, create campaigns, add recipients, and manage campaign lifecycle from your server.\n\n**Authentication:** Every request must include your organization API key in the `X-API-Key` header. These APIs are intended for server-to-server integrations; do not expose your organization API key in browser or mobile clients.\n\n**Phone number format:** Destination numbers must be in E.164 format (e.g. `+919876543210`) and include the country code. The pattern is: `+` followed by 10-15 digits.\n\n**Call statuses:** When you fetch call details, `status` can be: `PENDING`, `TRIGGERED`, `ONGOING`, `CALL_FINISHED`, `UNANSWERED`, `REJECTED`.\n\n**Campaign statuses:** Campaign `status` can be: `DRAFT`, `SCHEDULED`, `IN_PROGRESS`, `PAUSED`, `FINISHED`, `FAILED`, `CANCELLED`.\n\n**Campaign lifecycle:** Recipients can be added only while a campaign is `DRAFT` or `PAUSED`. Campaigns can be started only from `DRAFT` or `PAUSED`, stopped only from `IN_PROGRESS`, and cancelled unless they are already `FINISHED`, `FAILED`, or `CANCELLED`.\n\n**Transcripts and recordings:** For finished calls, presigned URLs for transcript and recording are valid for 60 minutes.\n",
		"version": "1.0.0",
		"license": {
			"name": "Proprietary"
		}
	},
	"servers": [
		{
			"url": "https://api.samora.ai",
			"description": "Production server"
		}
	],
	"security": [
		{
			"ApiKeyAuth": []
		}
	],
	"paths": {
		"/v1/call/trigger": {
			"post": {
				"description": "Triggers an immediate outbound call using the specified AI agent. The call is queued and processed asynchronously.",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/TriggerCallRequest"
							}
						}
					}
				},
				"responses": {
					"202": {
						"description": "Call request accepted and queued",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/TriggerCallResponse"
								},
								"examples": {
									"success": {
										"value": {
											"message": "Call request accepted",
											"status": "accepted",
											"call_id": "550e8400-e29b-41d4-a716-446655440000"
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad request - invalid request body or phone number format",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"invalidPhoneNumber": {
										"value": {
											"message": "Invalid phone number format. Please use E.164 format (e.g., +919876543210)"
										}
									}
								}
							}
						}
					},
					"404": {
						"description": "Agent not found or does not belong to your company",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"agentNotFound": {
										"value": {
											"message": "Agent not found or does not belong to your company"
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal server error",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					}
				}
			}
		},
		"/v1/call/{call_id}": {
			"get": {
				"description": "Retrieves detailed information about a specific call by its ID. The call must belong to an agent that belongs to your company. Transcript and recording URLs are presigned and valid for 60 minutes.",
				"parameters": [
					{
						"name": "call_id",
						"in": "path",
						"required": true,
						"description": "The UUID of the call to retrieve. Returned as `call_id` from the Trigger call endpoint.",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Call details",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/GetCallDetailsResponse"
								},
								"examples": {
									"finishedCall": {
										"value": {
											"message": "Call details fetched successfully",
											"data": {
												"agent_id": "123e4567-e89b-12d3-a456-426614174000",
												"created_at": "2024-01-15T10:30:00Z",
												"updated_at": "2024-01-15T10:35:00Z",
												"started_at": "2024-01-15T10:30:05Z",
												"ended_at": "2024-01-15T10:35:30Z",
												"transcript_url": "https://s3.amazonaws.com/bucket/transcript.pdf?X-Amz-Algorithm=...",
												"recording_url": "https://s3.amazonaws.com/bucket/recording.mp3?X-Amz-Algorithm=...",
												"status": "CALL_FINISHED",
												"call_variables": {
													"name": "John Doe",
													"email": "john.doe@example.com",
													"customer_id": "CUST-001"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad request - invalid call ID format",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					},
					"404": {
						"description": "Call not found or does not belong to your company",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"callNotFound": {
										"value": {
											"message": "Call not found or does not belong to your company"
										}
									}
								}
							}
						}
					},
					"500": {
						"description": "Internal server error",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}": {
			"post": {
				"description": "Creates a draft outbound campaign for the specified agent. The agent must belong to your organization.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/CreateCampaignRequest"
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Campaign created successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CreateCampaignResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			},
			"get": {
				"description": "Lists outbound campaigns for the specified agent.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"name": "page",
						"in": "query",
						"schema": {
							"type": "integer",
							"default": 1,
							"minimum": 1
						}
					},
					{
						"name": "page_size",
						"in": "query",
						"schema": {
							"type": "integer",
							"default": 10,
							"minimum": 1
						}
					},
					{
						"name": "search",
						"in": "query",
						"description": "Search by campaign name.",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "status",
						"in": "query",
						"description": "Filter by campaign status. Repeat the query parameter for multiple statuses.",
						"schema": {
							"type": "array",
							"items": {
								"$ref": "#/components/schemas/CampaignStatus"
							}
						},
						"style": "form",
						"explode": true
					},
					{
						"name": "sort_by",
						"in": "query",
						"schema": {
							"type": "string",
							"default": "created_at"
						}
					},
					{
						"name": "sort_dir",
						"in": "query",
						"schema": {
							"type": "string",
							"enum": ["asc", "desc"],
							"default": "desc"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Campaigns fetched successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ListCampaignsResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}/{campaign_id}": {
			"get": {
				"description": "Retrieves campaign details and aggregate call statistics.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"responses": {
					"200": {
						"description": "Campaign fetched successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/GetCampaignResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			},
			"put": {
				"description": "Updates retry settings for a draft campaign.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/UpdateCampaignSettingsRequest"
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Campaign settings updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CampaignEnvelopeResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}/{campaign_id}/scheduled-calls": {
			"post": {
				"description": "Adds recipients to a campaign by creating scheduled outbound call records. Recipients can be added only when campaign status is DRAFT or PAUSED.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/AddCampaignRecipientsRequest"
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Campaign calls scheduled successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/AddCampaignRecipientsResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}/{campaign_id}/start": {
			"post": {
				"description": "Starts a campaign. Campaign status must be DRAFT or PAUSED.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"responses": {
					"200": {
						"description": "Campaign started successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CampaignEnvelopeResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}/{campaign_id}/stop": {
			"post": {
				"description": "Stops an active campaign and marks it as PAUSED. Campaign status must be IN_PROGRESS.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"responses": {
					"200": {
						"description": "Campaign stopped successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CampaignEnvelopeResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v1/external/campaigns/{agent_id}/{campaign_id}/cancel": {
			"post": {
				"description": "Cancels a campaign and cancels pending outbound calls for it. Campaign status must not be FINISHED, FAILED, or CANCELLED.",
				"parameters": [
					{
						"$ref": "#/components/parameters/AgentId"
					},
					{
						"$ref": "#/components/parameters/CampaignId"
					}
				],
				"responses": {
					"200": {
						"description": "Campaign cancelled successfully",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CampaignEnvelopeResponse"
								}
							}
						}
					},
					"400": {
						"$ref": "#/components/responses/BadRequest"
					},
					"404": {
						"$ref": "#/components/responses/NotFound"
					},
					"500": {
						"$ref": "#/components/responses/InternalServerError"
					}
				}
			}
		},
		"/v2/webhooks": {
			"post": {
				"description": "Creates a new webhook to receive call event notifications.\n\nThe webhook secret is returned only once during creation and should be saved securely.\n",
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/CreateWebhookRequest"
							},
							"examples": {
								"basic": {
									"value": {
										"agent_id": "123e4567-e89b-12d3-a456-426614174000",
										"name": "CRM Integration",
										"url": "https://your-server.com/webhooks/samora",
										"events": ["CALL_FINISHED", "CALL_FAILED"]
									}
								},
								"withOptions": {
									"value": {
										"agent_id": "123e4567-e89b-12d3-a456-426614174000",
										"name": "Full Data Webhook",
										"url": "https://your-server.com/webhooks/samora",
										"events": ["CALL_FINISHED"],
										"data_options": {
											"include_transcript": true,
											"include_recording_url": true
										},
										"custom_headers": {
											"X-Custom-Header": "my-value"
										}
									}
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Webhook created successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["message", "data"],
									"properties": {
										"message": {
											"type": "string"
										},
										"data": {
											"$ref": "#/components/schemas/WebhookResponse"
										}
									},
									"additionalProperties": false
								},
								"examples": {
									"created": {
										"value": {
											"message": "Webhook created successfully. Save the secret - it will not be shown again.",
											"data": {
												"id": "550e8400-e29b-41d4-a716-446655440000",
												"agent_id": "123e4567-e89b-12d3-a456-426614174000",
												"name": "CRM Integration",
												"url": "https://your-server.com/webhooks/samora",
												"secret": "whsec_abc123def456ghi789...",
												"events": ["CALL_FINISHED", "CALL_FAILED"],
												"data_options": {
													"include_transcript": false,
													"include_recording_url": false
												},
												"custom_headers": {},
												"is_active": true,
												"created_at": "2024-01-15T10:30:00Z",
												"updated_at": "2024-01-15T10:30:00Z"
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Invalid request body",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"invalidRequest": {
										"value": {
											"message": "Invalid request body"
										}
									}
								}
							}
						}
					},
					"403": {
						"description": "Agent does not belong to your company",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"forbidden": {
										"value": {
											"message": "Agent does not belong to your company"
										}
									}
								}
							}
						}
					}
				}
			},
			"get": {
				"description": "Lists all webhooks for your company. Optionally filter by agent_id.",
				"parameters": [
					{
						"name": "agent_id",
						"in": "query",
						"required": false,
						"description": "Filter webhooks by agent ID",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Webhooks retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["data"],
									"properties": {
										"data": {
											"$ref": "#/components/schemas/WebhookListResponse"
										}
									},
									"additionalProperties": false
								},
								"examples": {
									"success": {
										"value": {
											"data": {
												"webhooks": [
													{
														"id": "550e8400-e29b-41d4-a716-446655440000",
														"agent_id": "123e4567-e89b-12d3-a456-426614174000",
														"name": "CRM Integration",
														"url": "https://your-server.com/webhooks/samora",
														"events": ["CALL_FINISHED", "CALL_FAILED"],
														"data_options": {
															"include_transcript": true,
															"include_recording_url": false
														},
														"custom_headers": {},
														"is_active": true,
														"created_at": "2024-01-15T10:30:00Z",
														"updated_at": "2024-01-15T10:30:00Z"
													}
												],
												"total_count": 1
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/v2/webhooks/events": {
			"get": {
				"description": "Returns the catalog of available webhook event types and their descriptions.",
				"responses": {
					"200": {
						"description": "Events catalog retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["data"],
									"properties": {
										"data": {
											"$ref": "#/components/schemas/EventsCatalogResponse"
										}
									},
									"additionalProperties": false
								},
								"examples": {
									"success": {
										"value": {
											"data": {
												"events": [
													{
														"event_type": "CALL_STARTED",
														"display_name": "Call Started",
														"description": "Triggered when a call begins (inbound or outbound). Basic call info available.",
														"available_data_options": []
													},
													{
														"event_type": "CALL_FINISHED",
														"display_name": "Call Finished",
														"description": "Triggered when a call ends with transcript and recording available.",
														"available_data_options": [
															"include_transcript",
															"include_recording_url"
														]
													},
													{
														"event_type": "CALL_FAILED",
														"display_name": "Call Failed",
														"description": "Triggered when a call fails, is rejected, or goes unanswered.",
														"available_data_options": []
													}
												]
											}
										}
									}
								}
							}
						}
					}
				}
			}
		},
		"/v2/webhooks/{webhook_id}": {
			"get": {
				"description": "Retrieves details of a specific webhook by ID.",
				"parameters": [
					{
						"name": "webhook_id",
						"in": "path",
						"required": true,
						"description": "The UUID of the webhook",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Webhook retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["data"],
									"properties": {
										"data": {
											"$ref": "#/components/schemas/WebhookResponse"
										}
									},
									"additionalProperties": false
								}
							}
						}
					},
					"403": {
						"description": "Webhook does not belong to your company",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"forbidden": {
										"value": {
											"message": "Webhook does not belong to your company"
										}
									}
								}
							}
						}
					},
					"404": {
						"description": "Webhook not found",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								},
								"examples": {
									"notFound": {
										"value": {
											"message": "Webhook not found"
										}
									}
								}
							}
						}
					}
				}
			},
			"put": {
				"description": "Updates an existing webhook configuration. All fields are optional.",
				"parameters": [
					{
						"name": "webhook_id",
						"in": "path",
						"required": true,
						"description": "The UUID of the webhook to update",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/UpdateWebhookRequest"
							},
							"examples": {
								"updateUrl": {
									"value": {
										"url": "https://new-server.com/webhooks/samora"
									}
								},
								"disableWebhook": {
									"value": {
										"is_active": false
									}
								},
								"updateEvents": {
									"value": {
										"events": ["CALL_FINISHED"],
										"data_options": {
											"include_transcript": true,
											"include_recording_url": true
										}
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Webhook updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["message", "data"],
									"properties": {
										"message": {
											"type": "string"
										},
										"data": {
											"$ref": "#/components/schemas/WebhookResponse"
										}
									},
									"additionalProperties": false
								}
							}
						}
					},
					"400": {
						"description": "Invalid request body",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					},
					"404": {
						"description": "Webhook not found",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					}
				}
			},
			"delete": {
				"description": "Deletes a webhook. This action cannot be undone.",
				"parameters": [
					{
						"name": "webhook_id",
						"in": "path",
						"required": true,
						"description": "The UUID of the webhook to delete",
						"schema": {
							"type": "string",
							"format": "uuid"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Webhook deleted successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": ["message"],
									"properties": {
										"message": {
											"type": "string"
										}
									},
									"additionalProperties": false
								},
								"examples": {
									"deleted": {
										"value": {
											"message": "Webhook deleted successfully"
										}
									}
								}
							}
						}
					},
					"404": {
						"description": "Webhook not found",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Error"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"securitySchemes": {
			"ApiKeyAuth": {
				"type": "apiKey",
				"in": "header",
				"name": "X-API-Key",
				"description": "Your unique organization API key. Required on all requests."
			}
		},
		"parameters": {
			"AgentId": {
				"name": "agent_id",
				"in": "path",
				"required": true,
				"description": "The UUID of the AI agent that owns the campaign.",
				"schema": {
					"type": "string",
					"format": "uuid"
				}
			},
			"CampaignId": {
				"name": "campaign_id",
				"in": "path",
				"required": true,
				"description": "The UUID of the campaign.",
				"schema": {
					"type": "string",
					"format": "uuid"
				}
			}
		},
		"responses": {
			"BadRequest": {
				"description": "Bad request",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/Error"
						}
					}
				}
			},
			"NotFound": {
				"description": "Resource not found or does not belong to your organization",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/Error"
						}
					}
				}
			},
			"InternalServerError": {
				"description": "Internal server error",
				"content": {
					"application/json": {
						"schema": {
							"$ref": "#/components/schemas/Error"
						}
					}
				}
			}
		},
		"schemas": {
			"TriggerCallRequest": {
				"type": "object",
				"required": ["agent_id", "to_number"],
				"properties": {
					"agent_id": {
						"type": "string",
						"format": "uuid",
						"description": "The UUID of the AI agent to conduct the call."
					},
					"to_number": {
						"type": "string",
						"description": "The destination phone number in E.164 format (e.g. +919876543210). Must include country code. Pattern: + followed by 10-15 digits.",
						"pattern": "^\\+[0-9]{10,15}$"
					},
					"metadata": {
						"type": "object",
						"additionalProperties": true,
						"description": "Optional. Additional metadata to pass context to the agent (e.g. customer information, call objectives). Arbitrary key-value pairs."
					}
				},
				"additionalProperties": false
			},
			"TriggerCallResponse": {
				"type": "object",
				"required": ["message", "status", "call_id"],
				"properties": {
					"message": {
						"type": "string",
						"description": "Human-readable status message."
					},
					"status": {
						"type": "string",
						"description": "Status value, e.g. accepted.",
						"example": "accepted"
					},
					"call_id": {
						"type": "string",
						"format": "uuid",
						"description": "The unique identifier for the call (UUID). Use this to fetch call details later."
					}
				},
				"additionalProperties": false
			},
			"GetCallDetailsResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string",
						"description": "Human-readable status message."
					},
					"data": {
						"$ref": "#/components/schemas/CallDetails"
					}
				},
				"additionalProperties": false
			},
			"CallDetails": {
				"type": "object",
				"required": ["agent_id", "created_at", "updated_at", "status"],
				"properties": {
					"agent_id": {
						"type": "string",
						"format": "uuid",
						"description": "The UUID of the AI agent that conducted the call."
					},
					"created_at": {
						"type": "string",
						"format": "date-time",
						"description": "Timestamp when the call record was created (ISO 8601)."
					},
					"updated_at": {
						"type": "string",
						"format": "date-time",
						"description": "Timestamp when the call record was last updated (ISO 8601)."
					},
					"started_at": {
						"type": "string",
						"nullable": true,
						"format": "date-time",
						"description": "Timestamp when the call started (ISO 8601). Null if not yet started."
					},
					"ended_at": {
						"type": "string",
						"nullable": true,
						"format": "date-time",
						"description": "Timestamp when the call ended (ISO 8601). Null if not yet ended."
					},
					"transcript_url": {
						"type": "string",
						"nullable": true,
						"format": "uri",
						"description": "Presigned URL to access the call transcript (valid for 60 minutes). Null if not available."
					},
					"recording_url": {
						"type": "string",
						"nullable": true,
						"format": "uri",
						"description": "Presigned URL to access the call recording (valid for 60 minutes). Null if not available."
					},
					"status": {
						"type": "string",
						"enum": [
							"PENDING",
							"TRIGGERED",
							"ONGOING",
							"CALL_FINISHED",
							"UNANSWERED",
							"REJECTED"
						],
						"description": "Current status of the call."
					},
					"call_variables": {
						"type": "object",
						"nullable": true,
						"additionalProperties": true,
						"description": "Additional variables associated with the call (e.g. metadata passed at trigger time). Null if none."
					}
				},
				"additionalProperties": false
			},
			"CampaignStatus": {
				"type": "string",
				"enum": [
					"DRAFT",
					"SCHEDULED",
					"IN_PROGRESS",
					"PAUSED",
					"FINISHED",
					"FAILED",
					"CANCELLED"
				]
			},
			"RetryConfig": {
				"type": "object",
				"description": "Optional retry behavior for campaign calls. Retries are attempted when a call ends with one of the statuses listed in `retry_on`.",
				"properties": {
					"max_retries": {
						"type": "integer",
						"minimum": 0,
						"description": "Maximum retry attempts per recipient call."
					},
					"retry_delay_minutes": {
						"type": "integer",
						"minimum": 1,
						"description": "Delay in minutes before each retry attempt."
					},
					"retry_on": {
						"type": "array",
						"description": "Call statuses that should trigger a retry.",
						"items": {
							"type": "string",
							"enum": ["UNANSWERED", "REJECTED", "VOICEMAIL", "FAILED"]
						}
					}
				},
				"additionalProperties": false,
				"example": {
					"max_retries": 2,
					"retry_delay_minutes": 30,
					"retry_on": ["UNANSWERED", "REJECTED", "VOICEMAIL"]
				}
			},
			"CreateCampaignRequest": {
				"type": "object",
				"required": ["name"],
				"properties": {
					"name": {
						"type": "string",
						"description": "Campaign name."
					},
					"retry_config": {
						"$ref": "#/components/schemas/RetryConfig"
					}
				},
				"additionalProperties": false
			},
			"CreateCampaignResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string"
					},
					"data": {
						"type": "object",
						"required": ["campaign_id"],
						"properties": {
							"campaign_id": {
								"type": "string",
								"format": "uuid"
							}
						},
						"additionalProperties": false
					}
				},
				"additionalProperties": false
			},
			"UpdateCampaignSettingsRequest": {
				"type": "object",
				"properties": {
					"retry_config": {
						"$ref": "#/components/schemas/RetryConfig"
					}
				},
				"additionalProperties": false
			},
			"Campaign": {
				"type": "object",
				"properties": {
					"id": {
						"type": "string",
						"format": "uuid"
					},
					"name": {
						"type": "string"
					},
					"agent_id": {
						"type": "string",
						"format": "uuid"
					},
					"agent_name": {
						"type": "string",
						"description": "Agent name, included on responses that join campaign and agent details."
					},
					"status": {
						"$ref": "#/components/schemas/CampaignStatus"
					},
					"cps": {
						"type": "integer"
					},
					"metadata": {
						"type": "object",
						"additionalProperties": true
					},
					"retry_config": {
						"type": "object",
						"additionalProperties": true
					},
					"schedule_config": {
						"type": "object",
						"additionalProperties": true
					},
					"call_stats": {
						"$ref": "#/components/schemas/CampaignCallStats"
					},
					"created_at": {
						"type": "string",
						"format": "date-time"
					},
					"updated_at": {
						"type": "string",
						"format": "date-time"
					}
				},
				"additionalProperties": true
			},
			"CampaignCallStats": {
				"type": "object",
				"properties": {
					"total": {
						"type": "integer"
					},
					"finished": {
						"type": "integer"
					},
					"pending": {
						"type": "integer"
					},
					"unanswered": {
						"type": "integer"
					},
					"failed": {
						"type": "integer"
					},
					"total_duration": {
						"type": "string",
						"description": "Human-readable total call duration."
					}
				},
				"additionalProperties": false
			},
			"ListCampaignsResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string"
					},
					"data": {
						"type": "object",
						"required": ["campaigns", "page", "page_size", "total"],
						"properties": {
							"campaigns": {
								"type": "array",
								"items": {
									"$ref": "#/components/schemas/Campaign"
								}
							},
							"page": {
								"type": "integer"
							},
							"page_size": {
								"type": "integer"
							},
							"total": {
								"type": "integer"
							}
						},
						"additionalProperties": false
					}
				},
				"additionalProperties": false
			},
			"GetCampaignResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string"
					},
					"data": {
						"type": "object",
						"required": ["campaign", "stats"],
						"properties": {
							"campaign": {
								"$ref": "#/components/schemas/Campaign"
							},
							"stats": {
								"$ref": "#/components/schemas/CampaignCallStats"
							}
						},
						"additionalProperties": false
					}
				},
				"additionalProperties": false
			},
			"CampaignEnvelopeResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string"
					},
					"data": {
						"$ref": "#/components/schemas/Campaign"
					}
				},
				"additionalProperties": false
			},
			"CampaignRecipient": {
				"type": "object",
				"required": ["to_number"],
				"properties": {
					"to_number": {
						"type": "string",
						"description": "Destination phone number in E.164 format.",
						"pattern": "^\\+[0-9]{10,15}$"
					},
					"call_variables": {
						"type": "object",
						"description": "Variables passed to the agent for this recipient.",
						"additionalProperties": true
					}
				},
				"additionalProperties": false
			},
			"AddCampaignRecipientsRequest": {
				"type": "object",
				"required": ["phone_numbers"],
				"properties": {
					"phone_numbers": {
						"type": "array",
						"minItems": 1,
						"items": {
							"$ref": "#/components/schemas/CampaignRecipient"
						}
					}
				},
				"additionalProperties": false
			},
			"AddCampaignRecipientsResponse": {
				"type": "object",
				"required": ["message", "data"],
				"properties": {
					"message": {
						"type": "string"
					},
					"data": {
						"type": "object",
						"required": ["scheduled_call_ids"],
						"properties": {
							"scheduled_call_ids": {
								"type": "array",
								"items": {
									"type": "string",
									"format": "uuid"
								}
							}
						},
						"additionalProperties": false
					}
				},
				"additionalProperties": false
			},
			"DataOptions": {
				"type": "object",
				"properties": {
					"include_transcript": {
						"type": "boolean",
						"default": false,
						"description": "Include the full call transcript in webhook payload."
					},
					"include_recording_url": {
						"type": "boolean",
						"default": false,
						"description": "Include the call recording URL in webhook payload."
					}
				},
				"additionalProperties": false
			},
			"CustomHeaders": {
				"type": "object",
				"description": "Custom HTTP headers to send with webhook requests.",
				"additionalProperties": {
					"type": "string"
				}
			},
			"CreateWebhookRequest": {
				"type": "object",
				"required": ["agent_id", "name", "url", "events"],
				"properties": {
					"agent_id": {
						"type": "string",
						"format": "uuid",
						"description": "The UUID of the agent this webhook is associated with."
					},
					"name": {
						"type": "string",
						"minLength": 1,
						"maxLength": 255,
						"description": "A friendly name for this webhook."
					},
					"url": {
						"type": "string",
						"format": "uri",
						"description": "The HTTPS URL where webhook payloads will be sent."
					},
					"events": {
						"type": "array",
						"minItems": 1,
						"description": "List of event types to subscribe to.",
						"items": {
							"type": "string",
							"enum": ["CALL_STARTED", "CALL_FINISHED", "CALL_FAILED"]
						}
					},
					"data_options": {
						"$ref": "#/components/schemas/DataOptions"
					},
					"custom_headers": {
						"$ref": "#/components/schemas/CustomHeaders"
					}
				},
				"additionalProperties": false
			},
			"UpdateWebhookRequest": {
				"type": "object",
				"properties": {
					"name": {
						"type": "string",
						"minLength": 1,
						"maxLength": 255,
						"description": "A friendly name for this webhook."
					},
					"url": {
						"type": "string",
						"format": "uri",
						"description": "The HTTPS URL where webhook payloads will be sent."
					},
					"events": {
						"type": "array",
						"minItems": 1,
						"description": "List of event types to subscribe to.",
						"items": {
							"type": "string",
							"enum": ["CALL_STARTED", "CALL_FINISHED", "CALL_FAILED"]
						}
					},
					"data_options": {
						"$ref": "#/components/schemas/DataOptions"
					},
					"custom_headers": {
						"$ref": "#/components/schemas/CustomHeaders"
					},
					"is_active": {
						"type": "boolean",
						"description": "Enable or disable the webhook."
					}
				},
				"additionalProperties": false
			},
			"WebhookResponse": {
				"type": "object",
				"properties": {
					"id": {
						"type": "string",
						"format": "uuid",
						"description": "Unique identifier for the webhook."
					},
					"agent_id": {
						"type": "string",
						"format": "uuid",
						"description": "The agent this webhook is associated with."
					},
					"name": {
						"type": "string",
						"description": "The webhook name."
					},
					"url": {
						"type": "string",
						"format": "uri",
						"description": "The webhook URL."
					},
					"secret": {
						"type": "string",
						"description": "The webhook signing secret. Returned only on creation."
					},
					"events": {
						"type": "array",
						"items": {
							"type": "string"
						},
						"description": "Subscribed event types."
					},
					"data_options": {
						"$ref": "#/components/schemas/DataOptions"
					},
					"custom_headers": {
						"$ref": "#/components/schemas/CustomHeaders"
					},
					"is_active": {
						"type": "boolean",
						"description": "Whether the webhook is active."
					},
					"created_at": {
						"type": "string",
						"format": "date-time"
					},
					"updated_at": {
						"type": "string",
						"format": "date-time"
					}
				},
				"additionalProperties": false
			},
			"WebhookListResponse": {
				"type": "object",
				"required": ["webhooks", "total_count"],
				"properties": {
					"webhooks": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/WebhookResponse"
						}
					},
					"total_count": {
						"type": "integer"
					}
				},
				"additionalProperties": false
			},
			"EventCatalog": {
				"type": "object",
				"required": [
					"event_type",
					"display_name",
					"description",
					"available_data_options"
				],
				"properties": {
					"event_type": {
						"type": "string",
						"description": "The event type identifier."
					},
					"display_name": {
						"type": "string",
						"description": "Human-readable name."
					},
					"description": {
						"type": "string",
						"description": "Description of when this event fires."
					},
					"available_data_options": {
						"type": "array",
						"items": {
							"type": "string"
						},
						"description": "Data options available for this event type."
					}
				},
				"additionalProperties": false
			},
			"EventsCatalogResponse": {
				"type": "object",
				"required": ["events"],
				"properties": {
					"events": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/EventCatalog"
						}
					}
				},
				"additionalProperties": false
			},
			"Error": {
				"type": "object",
				"required": ["message"],
				"properties": {
					"message": {
						"type": "string",
						"description": "Error message."
					}
				},
				"additionalProperties": false
			}
		}
	}
}