# Where to Find the Hiring-Agent API Documentation: Complete Guide to InterviewStreet's Repository

> Locate the hiring-agent API documentation within the InterviewStreet repository. Find programmatic interfaces, data schemas, and usage examples embedded directly in the source code.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: api-reference
- Published: 2026-07-12

---

**The complete hiring-agent API documentation is embedded directly in the InterviewStreet repository's source code, with the primary programmatic interface documented in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), data schemas in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), and usage examples in [`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md).**

The interviewstreet/hiring-agent repository provides a self-contained resume processing system without external documentation portals. Instead of traditional API reference sites, this project embeds its hiring-agent API documentation within the codebase itself, making the source files the definitive specification for integration and usage.

## Primary Documentation Locations in the Repository

### README.md Overview

The [`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md) file at the repository root serves as the landing page for the hiring-agent API documentation. It contains high-level architecture descriptions, installation instructions, and the essential "CLI usage" section that demonstrates how to invoke the scoring pipeline from the command line.

### Core Source Files as API Documentation

The actual API contract is defined through Python type hints and docstrings in specific modules. The **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** file contains the Pydantic schemas that define the JSON-Resume-compatible data structures, while **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** implements the extraction pipeline. Together, these files constitute the complete programmatic interface specification.

## Essential API Components and Entry Points

### PDF Extraction Pipeline (pdf.py)

The [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) module provides the primary programmatic entry point for the hiring-agent API. The **`PDFHandler`** class implements the end-to-end extraction pipeline, exposing the **`extract_json_from_pdf`** function. This function converts PDF resume files into structured JSON data according to the schema defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

```python
from pdf import PDFHandler               # Main extraction pipeline

from evaluator import Evaluator          # Scoring / fairness evaluator

from models import JSONResume            # Pydantic schema for the result

# 1. Extract structured data from a resume PDF

handler = PDFHandler()
resume: JSONResume = handler.extract_json_from_pdf("sample_resume.pdf")

# 2. Evaluate the resume and obtain a scored report

evaluator = Evaluator()
evaluation = evaluator.evaluate_resume(resume.json())

print(evaluation)        # Human-readable summary

```

### Data Schema Definitions (models.py)

Located at the repository root, [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) defines the JSON-Resume-compatible data structures that the API returns. Key models include **`Basics`**, **`Work`**, **`Project`**, and **`Education`**, all wrapped in the **`JSONResume`** Pydantic model. These classes serve as the formal API contract, specifying exact field names, types, and validation rules.

### Evaluation and Scoring Engine (evaluator.py)

For resume scoring functionality, the [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module contains the **`Evaluator`** class. This component implements fairness-aware scoring logic and template rendering. When running the full pipeline programmatically, this module works in conjunction with **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** for GitHub profile enrichment, which occurs automatically when GitHub URLs are detected in the resume.

## Command Line Interface Reference

The **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** file serves as the CLI wrapper that orchestrates the full pipeline. According to the hiring-agent API documentation in the README, you can process resumes directly from the terminal:

```bash
python score.py path/to/resume.pdf

```

This command executes the same extraction and evaluation logic available programmatically, making it accessible for shell scripts and automation workflows.

## Summary

- The hiring-agent API documentation is embedded directly in the interviewstreet/hiring-agent repository source code
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** contains the primary extraction entry point via `PDFHandler.extract_json_from_pdf()`
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** defines the JSON-Resume schema used for all API responses, including `Basics`, `Work`, and `Project` structures
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** provides the scoring functionality with fairness-aware algorithms
- The CLI interface in **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** offers a command-line alternative to programmatic access

## Frequently Asked Questions

### Where is the hiring-agent API documentation hosted?

The documentation is not hosted on a separate documentation site. Instead, it exists as inline documentation within the Python source files—specifically [`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md) for high-level usage, [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for extraction APIs, and [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) for data schemas—in the interviewstreet/hiring-agent repository.

### What data format does the hiring-agent API return?

The API returns JSON-Resume-compatible structured data. The exact schema is defined by Pydantic models in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), including sections for `Basics` (contact info), `Work` experience, `Education`, and `Projects`, providing a standardized, machine-readable resume format that conforms to the JSON Resume standard.

### How do I extract data from a PDF using the hiring-agent API?

Import the `PDFHandler` class from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and call the `extract_json_from_pdf()` method with the file path. This function handles PDF-to-markdown conversion, LLM-powered section parsing, and returns a `JSONResume` object containing the structured data, as implemented in the [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) source file.

### Is there a REST endpoint for the hiring-agent API?

The repository does not expose a REST endpoint by default. It is designed as a Python library with a CLI interface. However, the `PDFHandler` and `Evaluator` classes in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) provide the core functionality that could be wrapped in a web framework to create REST endpoints if needed for your specific deployment.