Developer Platform

hcalls Developer Documentation & API Reference

Integrate live interview coaching, automated resume parsing, real-time audio guidance streams, and LLM agent tool-calling into your developer workflows.

Get started with the hcalls API (free, self-serve)

Agents and developers can start without a sales form. The production API is the sandbox: every new account includes 50 free credits and no credit card.

Create a free hcalls account at /login.
Approve scoped access at /oauth/authorize (public client_id hcalls-public) or copy your session Bearer token from Dashboard → Account.
Exchange the authorization code at POST /oauth/token and call /api/health or the OpenAPI operations.

Official CLI Tool (`npx hcalls`)

Automate session initialization and status queries directly from your terminal or scripts without writing API boilerplate:

# Run directly with npx

npx hcalls status

npx hcalls session create --role "Senior Engineer" --company "Stripe"

# Or install globally

npm install -g hcalls

Machine-Readable Discovery & Specifications

JSON / YAML

OpenAPI 3.1.0 Spec

Full machine-readable API catalog with request/response schemas, /api/v1 versioning, and security flows.

/openapi.json

MCP 2024-11-05

MCP Streamable Server

Model Context Protocol tools for AI agent integrations (Cursor, Claude, Devin, ChatGPT).

/.well-known/mcp

RFC 9728

Protected Resource (RFC 9728)

OAuth 2.0 protected resource metadata declaring supported scopes.

/.well-known/oauth-protected-resource

RFC 8414

Auth Server (RFC 8414)

OAuth 2.0 authorization server discovery document with WorkOS agent_auth metadata.

/.well-known/oauth-authorization-server

RFC 9727

API Catalog (RFC 9727)

Linkset catalog linking specs, documentation, health status, and service metadata.

/.well-known/api-catalog

auth.md

Agent Auth Spec (auth.md)

Detailed guide for autonomous agents, PKCE verification, and token exchange.

/auth.md

pricing.md

Pricing Markdown

Structured markdown breakdown of fuel credits, passes, and limits.

/pricing.md

llms.txt

LLMs Context Index

Compact Markdown context document optimized for LLMs and autonomous agents.

/llms.txt

agents.md

Agent Integration Guide

Step-by-step guide for AI agents: authentication, MCP tools, API quickstart, and capability discovery.

/agents.md

Authentication & Scoped Permissions (RFC 9728)

hcalls APIs support standard Bearer authentication tokens as well as granular OAuth 2.0 scopes. AI agents requesting access should declare minimum necessary scopes:

Scope Identifier	Permission Description
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

Live Guidance Stream Example (SSE)

POST /api/completion

Stream live talking points in real time as the interviewer finishes asking a question:

curl -N -X POST https://hcalls.com/api/completion \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "66687a38b1d9bf1b51e7fb5c",
    "transcript": "Tell me about a time you optimized database query performance.",
    "answer_style": "star"
  }'