{
  "openapi": "3.1.0",
  "info": {
    "title": "hcalls API",
    "summary": "Real-Time AI Interview Assistant & Copilot API Surface",
    "description": "Programmatic API for managing resumes, creating live assistance sessions, streaming real-time AI interview talking points, and executing post-interview evaluations. Features instant self-serve onboarding with 50 free credits, no credit card required.",
    "version": "1.0.0",
    "x-api-version": "1.0.0",
    "x-deprecation-policy": "hcalls follows Semantic Versioning (SemVer 2.0). Breaking changes are signaled with minimum 6-month advance notice via standard RFC 8594 Sunset and Deprecation HTTP response headers.",
    "x-cli": {
      "npm": "hcalls",
      "command": "npx hcalls",
      "documentation": "https://hcalls.com/docs#cli"
    },
    "termsOfService": "https://hcalls.com/terms",
    "contact": {
      "name": "hcalls Developer Support",
      "email": "contact@hcalls.com",
      "url": "https://hcalls.com/docs"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://hcalls.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://hcalls.com/api/v1",
      "description": "Production v1 API Gateway"
    },
    {
      "url": "https://hcalls.com",
      "description": "Production Root Gateway"
    },
    {
      "url": "https://api.hcalls.com",
      "description": "Direct Backend API Server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "API Service Health Check",
        "description": "Returns operational, version, and uptime status for the hcalls API service.",
        "operationId": "getHealthV1",
        "parameters": [
          {
            "name": "X-API-Version",
            "in": "header",
            "required": false,
            "schema": { "type": "string", "default": "1.0.0" },
            "description": "API version requested by client"
          }
        ],
        "responses": {
          "200": {
            "description": "Service is healthy and operating normally.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "pass" },
                    "service": { "type": "string", "example": "hcalls-api" },
                    "version": { "type": "string", "example": "1.0.0" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  },
                  "required": ["status", "service", "version"]
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health Check (Root)",
        "description": "Returns operational and uptime status for the hcalls API service.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy and operating normally.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "pass" },
                    "service": { "type": "string", "example": "hcalls-api" },
                    "version": { "type": "string", "example": "1.0.0" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  },
                  "required": ["status", "service", "version"]
                }
              }
            }
          },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/resumes/upload": {
      "post": {
        "summary": "Upload and Auto-Parse Resume Document",
        "description": "Extracts text from PDF, DOCX, or TXT documents, parses work history and skills into structured JSON, and saves the resume profile.",
        "operationId": "uploadResumeV1",
        "security": [
          { "OAuth2": ["resumes:upload"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "Binary resume file (PDF, DOCX, TXT)" },
                  "title": { "type": "string", "description": "Optional title or label for this resume profile" }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resume parsed and stored successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResumeResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/resumes/upload": {
      "post": {
        "summary": "Upload and Auto-Parse Resume",
        "description": "Extracts text from PDF, DOCX, or TXT documents, parses work history and skills into structured JSON, and saves the resume profile.",
        "operationId": "uploadResume",
        "security": [
          { "OAuth2": ["resumes:upload"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": { "type": "string", "format": "binary", "description": "Binary resume file (PDF, DOCX, TXT)" },
                  "title": { "type": "string", "description": "Optional title for this resume profile" }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resume parsed and stored successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResumeResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/resumes": {
      "get": {
        "summary": "List User Resumes (Cursor-based Pagination)",
        "description": "Retrieves parsed resume profiles associated with the authenticated account using cursor-based pagination.",
        "operationId": "listResumesV1",
        "security": [
          { "OAuth2": ["resumes:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for next page of items" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Number of items to return" },
          { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by resume title or keywords" }
        ],
        "responses": {
          "200": {
            "description": "List of resumes retrieved successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedResumesResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "post": {
        "summary": "Create Resume Profile from Structured JSON",
        "description": "Creates a structured resume profile directly from JSON fields including experience, skills, and education.",
        "operationId": "createResumeV1",
        "security": [
          { "OAuth2": ["resumes:write"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ResumeInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Resume profile created successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResumeResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/resumes": {
      "get": {
        "summary": "List User Resumes",
        "description": "Retrieves parsed resumes associated with the authenticated account.",
        "operationId": "listResumes",
        "security": [
          { "OAuth2": ["resumes:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "search", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "List of resumes retrieved.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedResumesResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "post": {
        "summary": "Create Resume JSON",
        "description": "Creates a structured resume profile directly from JSON.",
        "operationId": "createResume",
        "security": [
          { "OAuth2": ["resumes:write"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ResumeInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Resume created successfully.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ResumeResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/resumes/{id}": {
      "get": {
        "summary": "Get Resume Details by ID",
        "description": "Retrieves the parsed content, education, skills, and work history for a specific resume ID.",
        "operationId": "getResumeByIdV1",
        "security": [
          { "OAuth2": ["resumes:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the resume profile" }
        ],
        "responses": {
          "200": {
            "description": "Resume profile details retrieved.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeResponse" } } }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "put": {
        "summary": "Update Resume Details by ID",
        "description": "Updates resume profile fields, skills, work history items, or summary content.",
        "operationId": "updateResumeV1",
        "security": [
          { "OAuth2": ["resumes:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the resume profile" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeInput" } } }
        },
        "responses": {
          "200": {
            "description": "Resume profile updated successfully.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeResponse" } } }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "delete": {
        "summary": "Delete Resume Profile by ID",
        "description": "Permanently deletes a resume profile and removes associated grounding vector contexts.",
        "operationId": "deleteResumeV1",
        "security": [
          { "OAuth2": ["resumes:delete"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the resume profile" }
        ],
        "responses": {
          "200": {
            "description": "Resume deleted successfully.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/resumes/{id}": {
      "get": {
        "summary": "Get Resume by ID",
        "description": "Retrieves the parsed content, education, skills, and work history for a specific resume ID.",
        "operationId": "getResumeById",
        "security": [
          { "OAuth2": ["resumes:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeResponse" } } }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "put": {
        "summary": "Update Resume",
        "description": "Updates resume profile fields, skills, or work history.",
        "operationId": "updateResume",
        "security": [
          { "OAuth2": ["resumes:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeInput" } } }
        },
        "responses": {
          "200": {
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeResponse" } } }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "delete": {
        "summary": "Delete Resume",
        "description": "Permanently deletes a resume profile.",
        "operationId": "deleteResume",
        "security": [
          { "OAuth2": ["resumes:delete"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/sessions": {
      "get": {
        "summary": "List Call Sessions (Cursor-based Pagination)",
        "description": "Lists active and completed interview assistance sessions with pagination for the authenticated user.",
        "operationId": "listSessionsV1",
        "security": [
          { "OAuth2": ["sessions:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor identifier for pagination" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "completed", "all"], "default": "all" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "List of interview sessions retrieved.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedSessionsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "403": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "post": {
        "summary": "Create Live Assistance Call Session",
        "description": "Initializes a standard live interview assistance session configuration matching role and company.",
        "operationId": "createSessionV1",
        "security": [
          { "OAuth2": ["sessions:create"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSessionInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Live session initialized successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  },
                  "required": ["success", "session"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "402": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/sessions": {
      "get": {
        "summary": "List Call Sessions",
        "description": "Lists call sessions for the authenticated user.",
        "operationId": "listSessions",
        "security": [
          { "OAuth2": ["sessions:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "completed", "all"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PaginatedSessionsResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "post": {
        "summary": "Create Paid/Standard Call Session",
        "description": "Initializes a standard live interview assistance session configuration.",
        "operationId": "createSession",
        "security": [
          { "OAuth2": ["sessions:create"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSessionInput" }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/sessions/free": {
      "post": {
        "summary": "Create Free Trial Session (Self-Serve Onboarding)",
        "description": "Initializes a 10-minute trial session with no credit card required.",
        "operationId": "createFreeSessionV1",
        "security": [
          { "OAuth2": ["sessions:create"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSessionInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Free trial session created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  },
                  "required": ["success", "session"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/sessions/free": {
      "post": {
        "summary": "Create Free Trial Session",
        "description": "Initializes a 10-minute trial session with rate-limiting cooldown.",
        "operationId": "createFreeSession",
        "security": [
          { "OAuth2": ["sessions:create"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSessionInput" }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/sessions/{id}": {
      "get": {
        "summary": "Get Session Details by ID",
        "description": "Retrieves the full configuration, real-time transcripts, and evaluation score for an interview session.",
        "operationId": "getSessionByIdV1",
        "security": [
          { "OAuth2": ["sessions:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the call session" }
        ],
        "responses": {
          "200": {
            "description": "Session details retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  },
                  "required": ["success", "session"]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "put": {
        "summary": "Update Live Session State or Transcripts",
        "description": "Updates session configuration, active status, or saves incremental audio transcript chunks.",
        "operationId": "updateSessionV1",
        "security": [
          { "OAuth2": ["sessions:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the call session" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateSessionInput" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  },
                  "required": ["success", "session"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "delete": {
        "summary": "Delete Live Session by ID",
        "description": "Permanently deletes an interview session and purges associated transcripts.",
        "operationId": "deleteSessionV1",
        "security": [
          { "OAuth2": ["sessions:delete"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the call session" }
        ],
        "responses": {
          "200": {
            "description": "Session deleted successfully.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"] }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/sessions/{id}": {
      "get": {
        "summary": "Get Session Details",
        "description": "Retrieves the full configuration, real-time transcripts, and evaluation score for an interview session.",
        "operationId": "getSessionById",
        "security": [
          { "OAuth2": ["sessions:read"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "put": {
        "summary": "Update Session Configuration or Save Transcripts",
        "description": "Updates live session configuration or saves interim transcript chunks.",
        "operationId": "updateSession",
        "security": [
          { "OAuth2": ["sessions:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateSessionInput" }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "session": { "$ref": "#/components/schemas/CallSession" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      },
      "delete": {
        "summary": "Delete Session",
        "description": "Permanently deletes an interview session.",
        "operationId": "deleteSession",
        "security": [
          { "OAuth2": ["sessions:delete"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/completion": {
      "post": {
        "summary": "Stream Real-Time AI Copilot Guidance (SSE)",
        "description": "Streams structured STAR talking points over Server-Sent Events (SSE) based on live audio transcript, resume context, and job description.",
        "operationId": "streamCompletionV1",
        "security": [
          { "OAuth2": ["sessions:stream"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "session_id": { "type": "string", "description": "Active session ID" },
                  "transcript": { "type": "string", "description": "Interviewer question or discussion segment" },
                  "answer_style": { "type": "string", "enum": ["quick", "star", "bullet"], "default": "star" }
                },
                "required": ["session_id", "transcript"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Events streaming structured response chunks.",
            "content": {
              "text/event-stream": {
                "schema": { "type": "string", "description": "data: JSON chunk\\n\\n" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "402": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/completion": {
      "post": {
        "summary": "Stream Real-Time AI Copilot Guidance",
        "description": "Streams structured talking points over Server-Sent Events (SSE) based on live audio transcript, resume, and job description.",
        "operationId": "streamCompletion",
        "security": [
          { "OAuth2": ["sessions:stream"] },
          { "BearerAuth": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "session_id": { "type": "string" },
                  "transcript": { "type": "string", "description": "Interviewer question or discussion segment" },
                  "answer_style": { "type": "string", "enum": ["quick", "star", "bullet"], "default": "star" }
                },
                "required": ["session_id", "transcript"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-Sent Events streaming structured response chunks.",
            "content": {
              "text/event-stream": {
                "schema": { "type": "string", "description": "data: JSON chunk\\n\\n" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/v1/sessions/{id}/summary": {
      "post": {
        "summary": "Generate Post-Interview Performance Analysis",
        "description": "Compiles comprehensive evaluation report, competency scores, strengths, and targeted improvement points from the session transcript.",
        "operationId": "generateSessionSummaryV1",
        "security": [
          { "OAuth2": ["sessions:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the call session" }
        ],
        "responses": {
          "200": {
            "description": "Summary generated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "summary": { "type": "string" },
                    "strengths": { "type": "array", "items": { "type": "string" } },
                    "improvements": { "type": "array", "items": { "type": "string" } }
                  },
                  "required": ["success", "summary"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/sessions/{id}/summary": {
      "post": {
        "summary": "Generate Post-Interview Summary",
        "description": "Compiles evaluation report and actionable score breakdown.",
        "operationId": "generateSessionSummary",
        "security": [
          { "OAuth2": ["sessions:write"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "summary": { "type": "string" },
                    "strengths": { "type": "array", "items": { "type": "string" } },
                    "improvements": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "404": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    },
    "/api/auth/oauth/token": {
      "post": {
        "summary": "OAuth 2.0 Token Grant Exchange",
        "description": "Exchange client credentials, authorization codes with PKCE, or refresh tokens for OAuth 2.0 access tokens.",
        "operationId": "oauthToken",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": { "type": "string", "enum": ["authorization_code", "client_credentials", "refresh_token"] },
                  "client_id": { "type": "string", "example": "hcalls-public" },
                  "client_secret": { "type": "string" },
                  "code": { "type": "string" },
                  "code_verifier": { "type": "string", "description": "PKCE S256 code verifier string" },
                  "redirect_uri": { "type": "string" },
                  "refresh_token": { "type": "string" }
                },
                "required": ["grant_type"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Access token issued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer", "example": 3600 },
                    "scope": { "type": "string" },
                    "refresh_token": { "type": "string" }
                  },
                  "required": ["access_token", "token_type", "expires_in"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ProblemDetails" },
          "401": { "$ref": "#/components/responses/ProblemDetails" },
          "429": { "$ref": "#/components/responses/ProblemDetails" },
          "500": { "$ref": "#/components/responses/ProblemDetails" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 scoped authentication granting granular access to hcalls services.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://hcalls.com/oauth/authorize",
            "tokenUrl": "https://hcalls.com/api/auth/oauth/token",
            "scopes": {
              "sessions:create": "Create a new live interview assistance session",
              "sessions:read": "Read interview session details, transcripts, and evaluation reports",
              "sessions:write": "Update session notes, preferences, and transcripts",
              "sessions:delete": "Permanently delete interview sessions",
              "sessions:stream": "Stream real-time AI copilot guidance talking points over SSE",
              "resumes:upload": "Upload PDF, DOCX, or TXT resumes for automated AI parsing",
              "resumes:read": "List and retrieve structured resume profiles",
              "resumes:write": "Create and modify structured resume details",
              "resumes:delete": "Delete resume profiles",
              "user:read": "Read user profile, referral data, and credit balance",
              "user:write": "Update user settings and preferences",
              "billing:read": "Read subscription tier, pass status, and transaction history"
            }
          },
          "clientCredentials": {
            "tokenUrl": "https://hcalls.com/api/auth/oauth/token",
            "scopes": {
              "sessions:create": "Create a new live interview assistance session",
              "sessions:read": "Read interview session details, transcripts, and evaluation reports",
              "sessions:write": "Update session notes, preferences, and transcripts",
              "sessions:delete": "Permanently delete interview sessions",
              "sessions:stream": "Stream real-time AI copilot guidance talking points over SSE",
              "resumes:upload": "Upload PDF, DOCX, or TXT resumes for automated AI parsing",
              "resumes:read": "List and retrieve structured resume profiles",
              "resumes:write": "Create and modify structured resume details",
              "resumes:delete": "Delete resume profiles",
              "user:read": "Read user profile, referral data, and credit balance",
              "user:write": "Update user settings and preferences",
              "billing:read": "Read subscription tier, pass status, and transaction history"
            }
          }
        }
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "User session token or API key provided via Authorization: Bearer header."
      }
    },
    "schemas": {
      "Resume": {
        "type": "object",
        "properties": {
          "_id": { "type": "string" },
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "experience": { "type": "array", "items": { "type": "object" } },
          "education": { "type": "array", "items": { "type": "object" } },
          "skills": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["_id", "title"]
      },
      "ResumeInput": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "summary": { "type": "string" },
          "experience": { "type": "array", "items": { "type": "object" } },
          "education": { "type": "array", "items": { "type": "object" } },
          "skills": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["title"]
      },
      "ResumeResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "resume": { "$ref": "#/components/schemas/Resume" }
        },
        "required": ["success", "resume"]
      },
      "PaginatedResumesResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Resume" } },
          "resumes": { "type": "array", "items": { "$ref": "#/components/schemas/Resume" } },
          "next_cursor": { "type": "string", "nullable": true },
          "has_more": { "type": "boolean" },
          "total_count": { "type": "integer" }
        },
        "required": ["success"]
      },
      "CallSession": {
        "type": "object",
        "properties": {
          "_id": { "type": "string" },
          "title": { "type": "string" },
          "role": { "type": "string" },
          "company": { "type": "string" },
          "status": { "type": "string", "enum": ["created", "active", "completed"] },
          "created_at": { "type": "string", "format": "date-time" }
        },
        "required": ["_id", "role", "company", "status"]
      },
      "CreateSessionInput": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "role": { "type": "string" },
          "company": { "type": "string" },
          "resume_id": { "type": "string" },
          "job_description": { "type": "string" }
        },
        "required": ["role", "company"]
      },
      "UpdateSessionInput": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "status": { "type": "string" },
          "transcript_chunk": { "type": "string" }
        }
      },
      "PaginatedSessionsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallSession" } },
          "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CallSession" } },
          "next_cursor": { "type": "string", "nullable": true },
          "has_more": { "type": "boolean" },
          "total_count": { "type": "integer" }
        },
        "required": ["success"]
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" },
          "instance": { "type": "string" },
          "code": { "type": "string" },
          "resolution": { "type": "string" },
          "documentation_url": { "type": "string" }
        },
        "required": ["title", "status"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "status": { "type": "integer" }
        },
        "required": ["code", "message"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "$ref": "#/components/schemas/Error" }
        },
        "required": ["error"]
      }
    },
    "responses": {
      "ProblemDetails": {
        "description": "RFC 9457 structured error problem details response.",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "Error": {
        "description": "Standard error response.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    }
  }
}