{
  "openapi": "3.1.0",
  "info": {
    "title": "OptiComm.AI Agents API",
    "description": "Programmatically initiate AI agent calls, check call statuses, and orchestrate multi-channel communication. Deploy dedicated AI agents for every employee and customer across Voice, WhatsApp, Email, and API channels.",
    "version": "1.0.0",
    "contact": {
      "name": "OptiComm.AI Support",
      "email": "contact@opticomm.ai",
      "url": "https://agents.opticomm.ai"
    }
  },
  "servers": [
    {
      "url": "https://wwryungezqbhcsywzwei.supabase.co/functions/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/external-api": {
      "post": {
        "operationId": "externalApiAction",
        "summary": "Execute an API action (initiate_call or check_status)",
        "description": "Single endpoint for all API actions. Use 'action' field to specify the operation. Requires X-API-Key authentication. Supports rate limiting, idempotency, DNC compliance, and webhooks.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/InitiateCallRequest" },
                  { "$ref": "#/components/schemas/CheckStatusRequest" }
                ],
                "discriminator": {
                  "propertyName": "action"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/InitiateCallResponse" },
                    { "$ref": "#/components/schemas/CheckStatusResponse" }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request — invalid action, missing fields, or invalid phone format",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Authentication failed — missing, invalid, or expired API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Forbidden — IP not allowed, permission denied, agent not allowed, or phone on DNC",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Not found — agent or call record not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimitResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error or call initiation failure",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key in format sk_live_xxx (production) or sk_test_xxx (testing). Create keys in Company Settings → API."
      }
    },
    "schemas": {
      "InitiateCallRequest": {
        "type": "object",
        "required": ["action", "agent_id", "phone_number"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["initiate_call"],
            "description": "The API action to perform"
          },
          "agent_id": {
            "type": "string",
            "description": "Agent UUID or ElevenLabs agent ID (agent_*). Must belong to the authenticated company."
          },
          "phone_number": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{6,14}$",
            "description": "Phone number in E.164 format (e.g., +40712345678)"
          },
          "variables": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Dynamic variables injected into the agent's prompt context (e.g., customer_name, order_id)"
          },
          "first_message_override": {
            "type": "string",
            "description": "Override the agent's default greeting message for this call"
          },
          "request_id": {
            "type": "string",
            "description": "Idempotency key. Duplicate requests with the same request_id return the original response instead of initiating a new call."
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to receive POST callbacks when call status changes (initiated, completed, failed)"
          }
        }
      },
      "CheckStatusRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["check_status"],
            "description": "The API action to perform"
          },
          "call_id": {
            "type": "string",
            "description": "The call_id returned from initiate_call. Either call_id or request_id is required."
          },
          "request_id": {
            "type": "string",
            "description": "The idempotency key used during initiate_call. Either call_id or request_id is required."
          }
        }
      },
      "InitiateCallResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "enum": [true] },
          "call_id": { "type": "string", "description": "Unique call record ID" },
          "conversation_id": { "type": "string", "description": "ElevenLabs conversation ID for tracking" },
          "status": { "type": "string", "enum": ["initiated"] },
          "message": { "type": "string" },
          "duplicate": { "type": "boolean", "description": "True if this was a duplicate request_id" }
        }
      },
      "CheckStatusResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "enum": [true] },
          "call_id": { "type": "string" },
          "conversation_id": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "calling", "completed", "failed"] },
          "duration_seconds": { "type": "number", "nullable": true },
          "outcome": { "type": "string", "nullable": true },
          "error_message": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": {
            "type": "string",
            "enum": [
              "MISSING_API_KEY",
              "INVALID_API_KEY_FORMAT",
              "INVALID_API_KEY",
              "API_KEY_EXPIRED",
              "IP_NOT_ALLOWED",
              "PERMISSION_DENIED",
              "AGENT_NOT_ALLOWED",
              "PHONE_ON_DNC",
              "INVALID_ACTION",
              "MISSING_FIELDS",
              "INVALID_PHONE_FORMAT",
              "MISSING_CALL_ID",
              "AGENT_NOT_FOUND",
              "CALL_NOT_FOUND",
              "CALL_FAILED",
              "INTERNAL_ERROR"
            ]
          },
          "message": { "type": "string", "description": "Human-readable error description" }
        }
      },
      "RateLimitResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": { "type": "string", "enum": ["RATE_LIMIT_EXCEEDED", "DAILY_LIMIT_EXCEEDED"] },
          "message": { "type": "string" },
          "retry_after": { "type": "number", "description": "Seconds to wait before retrying" }
        }
      }
    }
  }
}