{
  "openapi": "3.0.3",
  "info": {
    "title": "Ziad Chat API",
    "description": "API documentation for Ziad Chat — WhatsApp Business messaging platform.",
    "version": "0.5.0"
  },
  "servers": [
    {
      "url": "https://apichat-dev.mitracerdas.com",
      "description": "Staging"
    }
  ],
  "tags": [
    { "name": "Health" },
    { "name": "Auth" },
    { "name": "Tenant" },
    { "name": "Members" },
    { "name": "WABA" },
    { "name": "Contact" },
    { "name": "Template" },
    { "name": "Broadcast" },
    { "name": "Conversation" },
    { "name": "Webhook" },
    { "name": "Internal" }
  ],
  "paths": {
    "/api/healthz": {
      "get": {
        "tags": ["Health"],
        "summary": "Health check (JSON)",
        "responses": { "200": { "description": "Service health status" } }
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "tags": ["Auth"],
        "summary": "Register a new account",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email","password","name"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "name": { "type": "string" } } } } } },
        "responses": { "201": { "description": "Account created" }, "409": { "description": "Email already exists" } }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Login and create session",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email","password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Login successful" }, "401": { "description": "Invalid credentials" } }
      }
    },
    "/api/v1/auth/refresh": {
      "post": {
        "tags": ["Auth"],
        "summary": "Refresh access token via cookie",
        "responses": { "200": { "description": "Token refreshed" }, "401": { "description": "Refresh cookie missing or invalid" } }
      }
    },
    "/api/v1/auth/logout": {
      "post": {
        "tags": ["Auth"],
        "summary": "Logout and clear session",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Logged out" } }
      }
    },
    "/api/v1/auth/forgot-password": {
      "post": {
        "tags": ["Auth"],
        "summary": "Request password reset email",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } },
        "responses": { "200": { "description": "Reset email sent if account exists" } }
      }
    },
    "/api/v1/auth/reset-password": {
      "post": {
        "tags": ["Auth"],
        "summary": "Reset password with token",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token","password"], "properties": { "token": { "type": "string" }, "password": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Password reset" }, "400": { "description": "Invalid or expired token" } }
      }
    },
    "/api/v1/auth/verify-email": {
      "post": {
        "tags": ["Auth"],
        "summary": "Verify email address",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Email verified" } }
      }
    },
    "/api/v1/auth/accept-invite": {
      "post": {
        "tags": ["Auth"],
        "summary": "Accept a team invitation",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token","password"], "properties": { "token": { "type": "string" }, "password": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Invitation accepted" } }
      }
    },
    "/api/v1/auth/select-tenant": {
      "post": {
        "tags": ["Auth"],
        "summary": "Select active tenant/workspace",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tenant_id"], "properties": { "tenant_id": { "type": "string", "format": "uuid" } } } } } },
        "responses": { "200": { "description": "Tenant selected" } }
      }
    },
    "/api/v1/auth/switch-tenant": {
      "post": {
        "tags": ["Auth"],
        "summary": "Switch to another tenant/workspace",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tenant_id"], "properties": { "tenant_id": { "type": "string", "format": "uuid" } } } } } },
        "responses": { "200": { "description": "Tenant switched" } }
      }
    },
    "/api/v1/me": {
      "get": {
        "tags": ["Auth"],
        "summary": "Get current user profile",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Current user profile" }, "401": { "description": "Unauthorized" } }
      }
    },
    "/api/v1/tenants": {
      "get": {
        "tags": ["Tenant"],
        "summary": "List tenants for current user",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of tenants" } }
      },
      "post": {
        "tags": ["Tenant"],
        "summary": "Create a new tenant/workspace",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } } },
        "responses": { "201": { "description": "Tenant created" } }
      }
    },
    "/api/v1/tenants/current": {
      "get": {
        "tags": ["Tenant"],
        "summary": "Get current active tenant",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Current tenant" } }
      }
    },
    "/api/v1/tenants/{id}": {
      "get": {
        "tags": ["Tenant"],
        "summary": "Get tenant by ID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Tenant details" } }
      }
    },
    "/api/v1/internal/tenants": {
      "post": {
        "tags": ["Internal"],
        "summary": "Provision a school tenant (ERP auth)",
        "security": [{ "bearerAuth": [] }],
        "responses": { "201": { "description": "Tenant provisioned" } }
      }
    },
    "/api/v1/members": {
      "get": {
        "tags": ["Members"],
        "summary": "List team members",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of members" } }
      },
      "post": {
        "tags": ["Members"],
        "summary": "Invite a new member",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email","role"], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } } } } } },
        "responses": { "201": { "description": "Invitation sent" } }
      }
    },
    "/api/v1/members/roles": {
      "get": {
        "tags": ["Members"],
        "summary": "List available roles",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of roles" } }
      }
    },
    "/api/v1/waba/status": {
      "get": {
        "tags": ["WABA"],
        "summary": "Get WABA connection status",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "WABA status" } }
      }
    },
    "/api/v1/waba/connect": {
      "post": {
        "tags": ["WABA"],
        "summary": "Connect WhatsApp Business Account",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Connected" } }
      }
    },
    "/api/v1/waba/disconnect": {
      "post": {
        "tags": ["WABA"],
        "summary": "Disconnect WhatsApp Business Account",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Disconnected" } }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "tags": ["Contact"],
        "summary": "List contacts",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of contacts" } }
      },
      "post": {
        "tags": ["Contact"],
        "summary": "Create a contact",
        "security": [{ "bearerAuth": [] }],
        "responses": { "201": { "description": "Contact created" } }
      }
    },
    "/api/v1/contacts/{id}": {
      "get": {
        "tags": ["Contact"],
        "summary": "Get contact by ID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Contact details" } }
      }
    },
    "/api/v1/templates": {
      "get": {
        "tags": ["Template"],
        "summary": "List message templates",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of templates" } }
      },
      "post": {
        "tags": ["Template"],
        "summary": "Create a message template",
        "security": [{ "bearerAuth": [] }],
        "responses": { "201": { "description": "Template created" } }
      }
    },
    "/api/v1/templates/{id}": {
      "get": {
        "tags": ["Template"],
        "summary": "Get template by ID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Template details" } }
      },
      "patch": {
        "tags": ["Template"],
        "summary": "Update a message template",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Template updated" } }
      }
    },
    "/api/v1/broadcasts": {
      "get": {
        "tags": ["Broadcast"],
        "summary": "List broadcasts",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of broadcasts" } }
      },
      "post": {
        "tags": ["Broadcast"],
        "summary": "Create a broadcast",
        "security": [{ "bearerAuth": [] }],
        "responses": { "201": { "description": "Broadcast created" } }
      }
    },
    "/api/v1/broadcasts/{id}": {
      "get": {
        "tags": ["Broadcast"],
        "summary": "Get broadcast by ID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Broadcast details" } }
      }
    },
    "/api/v1/conversations": {
      "get": {
        "tags": ["Conversation"],
        "summary": "List conversations",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "List of conversations" } }
      }
    },
    "/api/v1/conversations/{id}": {
      "get": {
        "tags": ["Conversation"],
        "summary": "Get conversation by ID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Conversation details" } }
      },
      "patch": {
        "tags": ["Conversation"],
        "summary": "Update conversation (e.g. assign, close)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Conversation updated" } }
      }
    },
    "/api/v1/conversations/{id}/messages": {
      "get": {
        "tags": ["Conversation"],
        "summary": "List messages in a conversation",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "List of messages" } }
      },
      "post": {
        "tags": ["Conversation"],
        "summary": "Send a message in a conversation",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Message sent" } }
      }
    },
    "/api/v1/webhooks/whatsapp": {
      "get": {
        "tags": ["Webhook"],
        "summary": "Verify WhatsApp webhook (Meta challenge)",
        "parameters": [
          { "name": "hub.mode", "in": "query", "schema": { "type": "string" } },
          { "name": "hub.verify_token", "in": "query", "schema": { "type": "string" } },
          { "name": "hub.challenge", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Challenge echoed" } }
      },
      "post": {
        "tags": ["Webhook"],
        "summary": "Receive WhatsApp webhook event",
        "responses": { "200": { "description": "Event accepted" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}