{
  "openapi": "3.1.0",
  "info": {
    "title": "Maandrik Voz",
    "version": "0.3.12",
    "description": "Outbound voice notifications with optional DTMF menus and advisory Asterisk AMD. Alarm orchestration remains external."
  },
  "servers": [
    {
      "url": "https://voz.maandrik.com",
      "description": "Produção Maandrik"
    },
    {
      "url": "http://127.0.0.1:8088",
      "description": "Local development. Calls are simulated by default."
    }
  ],
  "security": [
    {
      "CampaignKey": []
    }
  ],
  "paths": {
    "/calls": {
      "post": {
        "operationId": "createCall",
        "summary": "Create a call",
        "description": "Accepts one outbound call. Omitted menu inherits the campaign menu; null disables it. AMD is enabled by default and never prevents message playback. Poll the call for its response and detection result. No redial or escalation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCall"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Call accepted; does not prove the recipient answered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Call"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key already used with different content.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "All call lines are in use. No call was accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Calling service is unavailable. No call was accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            },
            "description": "Use the same key and content to safely resend a request. Scoped to the campaign, retained with call history. Reusing the key with different content returns 409."
          }
        ]
      }
    },
    "/calls/{id}": {
      "get": {
        "operationId": "getCall",
        "summary": "Get call status",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Call belonging to the authenticated campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Call"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Call not found in this campaign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "health",
        "summary": "Check process health",
        "description": "Checks PostgreSQL and controller readiness. Does not verify Speech, SIP registration, telephone delivery or audible playback.",
        "security": [],
        "responses": {
          "200": {
            "description": "Process is available.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["ok"],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Controller or database unavailable."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "CampaignKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Opaque API key scoped to a campaign. Store only its hash."
      }
    },
    "schemas": {
      "CreateCall": {
        "type": "object",
        "additionalProperties": false,
        "required": ["to", "text"],
        "properties": {
          "to": {
            "type": "string",
            "description": "International phone number with + or 00 country code. Portuguese 9-digit landline/mobile numbers default to +351. Spaces, parentheses and hyphens are accepted; stored numbers use E.164.",
            "example": "+351900000000"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000,
            "pattern": "\\S",
            "description": "Plain text to read in European Portuguese.",
            "example": "Alarme Maandrik. O servidor de aplicações está indisponível."
          },
          "menu": {
            "$ref": "#/components/schemas/Menu"
          },
          "amd": {
            "type": "boolean",
            "default": true,
            "description": "Advisory analysis in parallel with playback; never delays audio. MACHINE still receives message and menu."
          },
          "callerId": {
            "type": "string",
            "pattern": "^\\+?[1-9]\\d{5,14}$",
            "description": "Optional approved outgoing number. Omit to use the configured default (production: +351308801160; alternative: +351923389652). Other active Zadarma numbers are validated before accepting the call.",
            "example": "+351308801160"
          }
        }
      },
      "Call": {
        "type": "object",
        "required": [
          "id",
          "to",
          "status",
          "project",
          "menu",
          "response",
          "direction",
          "answeredAt",
          "durationSeconds",
          "estimatedCost",
          "createdAt",
          "updatedAt",
          "mode"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "to": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "preparing",
              "calling",
              "answered",
              "reading",
              "completed",
              "not_answered",
              "hung_up_early",
              "failed",
              "unknown",
              "detecting",
              "waiting_for_input",
              "responded",
              "no_response",
              "busy",
              "rejected"
            ],
            "description": "completed means playback finished; responded means a menu choice was saved. no_response means no valid choice. rejected is network-signalled refusal, not proof of a manual rejection; busy is separate. unknown means execution is uncertain. Calls are never automatically repeated."
          },
          "reason": {
            "type": ["string", "null"]
          },
          "project": {
            "type": ["string", "null"]
          },
          "menu": {
            "$ref": "#/components/schemas/Menu"
          },
          "response": {
            "type": ["object", "null"],
            "properties": {
              "key": {
                "type": ["string", "null"]
              },
              "label": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": ["record", "none"]
              },
              "at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "description": "record confirms a key selection, not necessarily acceptance: inspect key/label. none means no choice. null may mean pending, not requested or an uncertain interrupted execution."
          },
          "direction": {
            "type": "string",
            "const": "outbound"
          },
          "answeredAt": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "durationSeconds": {
            "type": ["integer", "null"],
            "minimum": 0
          },
          "estimatedCost": {
            "type": ["number", "null"],
            "minimum": 0,
            "description": "Estimated EUR cost; null when no reliable tariff or usage is available. Never substitute Azure prices for another provider."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string",
            "enum": ["live", "simulated"]
          },
          "detection": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "result": {
                "type": ["string", "null"],
                "enum": ["HUMAN", "MACHINE", "NOTSURE", "HANGUP", "UNAVAILABLE", null]
              },
              "cause": {
                "type": ["string", "null"]
              }
            },
            "description": "Heuristic, not confirmation of receipt. Disabled for historical calls; not fabricated in simulation."
          },
          "callerId": {
            "type": ["string", "null"],
            "description": "Outgoing number selected for this call. Null for older records."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "English message explaining what happened."
          }
        }
      },
      "Menu": {
        "type": ["object", "null"],
        "additionalProperties": false,
        "required": ["options"],
        "properties": {
          "question": {
            "type": "string",
            "maxLength": 300
          },
          "timeoutSeconds": {
            "type": "integer",
            "minimum": 3,
            "maximum": 20,
            "default": 8
          },
          "retries": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2,
            "default": 1
          },
          "options": {
            "type": "array",
            "minItems": 1,
            "maxItems": 9,
            "description": "Unique digit keys. At least one record action. Repeat is limited to three per call.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["key", "label"],
              "properties": {
                "key": {
                  "type": "string",
                  "pattern": "^[0-9]$"
                },
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 60
                },
                "action": {
                  "type": "string",
                  "enum": ["record", "repeat"],
                  "default": "record"
                },
                "reply": {
                  "type": "string",
                  "maxLength": 300
                }
              }
            }
          }
        }
      }
    }
  }
}
