{
  "openapi": "3.1.0",
  "info": {
    "title": "Voicetta Setup API",
    "version": "1.0.0",
    "description": "Agent-to-agent provisioning for Voicetta. Terminology: Connection (human UI) = Setup Tool (this API). Capability = voice action after a tool is enabled.",
    "contact": {
      "name": "Voicetta",
      "url": "https://voicetta.com",
      "email": "hello@voicetta.com"
    }
  },
  "servers": [
    {
      "url": "https://api.voicetta.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Setup",
      "description": "Setup session lifecycle. UI label for tools: Connection."
    }
  ],
  "paths": {
    "/v1/setup/openapi-note": {
      "get": {
        "tags": ["Setup"],
        "summary": "Terminology and discovery pointers",
        "operationId": "setupOpenapiNote",
        "responses": {
          "200": {
            "description": "Discovery metadata"
          }
        }
      }
    },
    "/v1/setup/tools/catalog": {
      "get": {
        "tags": ["Setup"],
        "summary": "List setup tools (UI: Connections)",
        "operationId": "listToolsCatalog",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "industry",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool catalog"
          }
        }
      }
    },
    "/v1/setup/tools/catalog/{tool_id}": {
      "get": {
        "tags": ["Setup"],
        "summary": "Get one setup tool definition",
        "operationId": "getToolCatalogItem",
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Tool definition" },
          "404": { "description": "Tool not found" }
        }
      }
    },
    "/v1/setup/sessions": {
      "post": {
        "tags": ["Setup"],
        "summary": "Create setup session",
        "operationId": "createSetupSession",
        "parameters": [
          {
            "name": "X-Partner-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": ["claude", "chatgpt", "cursor", "custom"]
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "partner_agent": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "session_id, consent_url, status"
          }
        }
      }
    },
    "/v1/setup/sessions/{session_id}": {
      "get": {
        "tags": ["Setup"],
        "summary": "Get session status envelope",
        "operationId": "getSetupSession",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "AgentEnvelope" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/consent": {
      "post": {
        "tags": ["Setup"],
        "summary": "Complete human consent (browser)",
        "operationId": "consentSetupSession",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["consent_token"],
                "properties": {
                  "consent_token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "setup_access_token" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/profile": {
      "post": {
        "tags": ["Setup"],
        "summary": "Submit business profile",
        "operationId": "submitBusinessProfile",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "profile": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/assistant": {
      "post": {
        "tags": ["Setup"],
        "summary": "Configure assistant",
        "operationId": "configureAssistant",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "config": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/knowledge": {
      "post": {
        "tags": ["Setup"],
        "summary": "Upload knowledge base content",
        "operationId": "uploadKnowledge",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "knowledge": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/phone": {
      "post": {
        "tags": ["Setup"],
        "summary": "Request phone number or skip telephony",
        "operationId": "requestPhoneNumber",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "telephony": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope, may include human_required" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/tools/select": {
      "post": {
        "tags": ["Setup"],
        "summary": "Select setup tools by tool_id",
        "operationId": "selectTools",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tool_ids"],
                "properties": {
                  "tool_ids": {
                    "type": "array",
                    "items": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope with tools" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/tools/{tool_id}/enable": {
      "post": {
        "tags": ["Setup"],
        "summary": "Enable a selected tool (UI: Connection)",
        "operationId": "enableTool",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payload": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope, may include human_required" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/tools/{tool_id}/skip": {
      "post": {
        "tags": ["Setup"],
        "summary": "Skip a selected tool",
        "operationId": "skipTool",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "tool_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "AgentEnvelope" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/tools": {
      "get": {
        "tags": ["Setup"],
        "summary": "Get tool statuses for session",
        "operationId": "getToolsStatus",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Tool status list" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/test-call": {
      "post": {
        "tags": ["Setup"],
        "summary": "Record test call result",
        "operationId": "runTestCall",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": { "type": "string", "default": "passed" },
                  "duration_sec": { "type": "integer" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "AgentEnvelope" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/handoff": {
      "get": {
        "tags": ["Setup"],
        "summary": "Final handoff card for the human Guest",
        "operationId": "getHandoffSummary",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "AgentEnvelope with handoff" }
        }
      }
    },
    "/v1/setup/sessions/{session_id}/webhooks/register": {
      "post": {
        "tags": ["Setup"],
        "summary": "Register webhook for async setup events",
        "operationId": "registerSetupWebhook",
        "security": [{ "SetupBearer": [] }],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["webhook_url"],
                "properties": {
                  "webhook_url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Webhook registered" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "SetupBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Scoped setup token issued after human consent (setup_...)"
      }
    },
    "schemas": {
      "AgentEnvelope": {
        "type": "object",
        "properties": {
          "session_id": { "type": "string" },
          "status": { "type": "string" },
          "message_for_user_agent": { "type": "string" },
          "actions_completed": {
            "type": "array",
            "items": { "type": "string" }
          },
          "human_required": {
            "type": "object",
            "properties": {
              "type": { "type": "string" },
              "url": { "type": "string" },
              "instructions": { "type": "string" },
              "fields": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          },
          "handoff": { "type": "object" }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Agent setup playbook",
    "url": "https://voicetta.com/docs/agent-setup-playbook.md"
  }
}