# hcalls Developer Documentation & API Reference

> Machine-readable APIs, WebSocket real-time streams, OAuth 2.0 scoped authentication, Model Context Protocol (MCP) server integration, and official CLI for hcalls.

## Overview
hcalls provides a comprehensive REST and WebSocket/SSE API surface enabling programmatic session management, automated resume parsing, real-time AI interview coaching, and LLM agent tool calling.

## API Versioning & Deprecation Policy
- **Current Version**: `v1` (Path: `/api/v1/*`, Base URL: `https://hcalls.com/api/v1`).
- **Semantic Versioning**: hcalls strictly adheres to SemVer 2.0.
- **Deprecation Timeline**: Deprecated endpoints are announced with a minimum 6-month deprecation period and flagged via standard RFC 8594 `Sunset` and `Deprecation` HTTP headers.
- **Version Headers**: Responses advertise `X-API-Version: 1.0.0`.

## Rate Limiting Conventions
hcalls enforces standard RFC 6585 and IETF RateLimit headers across all REST endpoints:
- `RateLimit-Limit`: Request quota allowed within current time window (e.g. 120 requests/minute).
- `RateLimit-Remaining`: Remaining requests available in the current window.
- `RateLimit-Reset`: Time in seconds until the rate limit quota resets.
- `RateLimit-Policy`: Quota definition (e.g. `120;w=60`).
- `Retry-After`: Sent on HTTP 429 responses indicating seconds to wait before retrying.

## Official CLI Tool
Install or run the official hcalls CLI via npm or npx:
```bash
# Run without installation
npx hcalls status
npx hcalls session create --role "Senior Engineer" --company "Stripe"

# Global installation
npm install -g hcalls
```

## Model Context Protocol (MCP) Integration
Connect Claude Desktop, Cursor, Devin, or custom AI agents directly to hcalls via Streamable HTTP:
- **Server Endpoint**: `https://hcalls.com/.well-known/mcp` (or `https://hcalls.com/api/mcp`)
- **Server Card**: `https://hcalls.com/.well-known/mcp/server-card.json`
- **Manifest**: `https://hcalls.com/mcp.json`

### Available MCP Tools
1. `hcalls_create_session`: Initialize live interview session with role & company.
2. `hcalls_get_session`: Fetch session transcript and AI performance score.
3. `hcalls_list_sessions`: List active and completed sessions.
4. `hcalls_upload_resume`: Parse resume text into structured STAR grounding data.
5. `hcalls_get_user_profile`: Retrieve active credit balance and tier.

## Machine-Readable Specifications
- **OpenAPI 3.1.0 Specification**: `https://hcalls.com/openapi.json` (`https://hcalls.com/openapi.yaml`)
- **RFC 9728 Protected Resource Metadata**: `https://hcalls.com/.well-known/oauth-protected-resource`
- **RFC 8414 OAuth 2.0 Authorization Server**: `https://hcalls.com/.well-known/oauth-authorization-server`
- **RFC 9727 API Catalog**: `https://hcalls.com/.well-known/api-catalog`
- **Authentication Spec (auth.md)**: `https://hcalls.com/auth.md`
- **API Health Check**: `https://hcalls.com/api/health`

## Authentication & OAuth 2.0
All API endpoints require Bearer Token authorization or OAuth 2.0 access tokens.

```http
Authorization: Bearer <access_token>
Content-Type: application/json
```

### Supported Permission 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.

## Core API Endpoints (v1)

### 1. Resume Management
- `POST /api/v1/resumes/upload`: Upload and auto-parse PDF/DOCX/TXT resumes using AI.
- `GET /api/v1/resumes`: List user resumes with cursor-based pagination (`cursor`, `limit`).
- `POST /api/v1/resumes`: Create a structured resume profile directly from JSON.
- `GET /api/v1/resumes/{id}`: Retrieve structured resume details.
- `PUT /api/v1/resumes/{id}`: Update structured resume details.
- `DELETE /api/v1/resumes/{id}`: Delete a resume profile.

### 2. Live Call Sessions
- `POST /api/v1/sessions`: Initialize a paid/standard live assistance session.
- `POST /api/v1/sessions/free`: Initialize a 10-minute free trial session.
- `GET /api/v1/sessions`: List user call sessions with cursor pagination.
- `GET /api/v1/sessions/{id}`: Retrieve full session details, transcripts, and post-call feedback.
- `PUT /api/v1/sessions/{id}`: Update live session config or save interim transcript chunks.
- `DELETE /api/v1/sessions/{id}`: Delete a session.

### 3. Real-Time AI Copilot Guidance
- `POST /api/v1/completion`: Live streaming SSE copilot guidance based on speech-to-text transcript chunks, matched resume, and job description.
- `POST /api/v1/sessions/{id}/summary`: Generate post-interview performance analysis and feedback report.

### 4. RFC 9457 Error Response Model
All API error responses return structured RFC 9457 `application/problem+json`:
```json
{
  "type": "https://hcalls.com/docs/errors#UNAUTHORIZED",
  "title": "Unauthorized",
  "status": 401,
  "code": "UNAUTHORIZED",
  "detail": "Missing or invalid Bearer access token.",
  "instance": "/api/v1/sessions",
  "resolution": "Authenticate via /oauth/authorize or /oauth/token.",
  "documentation_url": "https://hcalls.com/docs"
}
```