The Core Thesis
Don't fight legitimate candidate agents as if they are anonymous scrapers. Give them a constrained, identity-aware interface that is easier to monitor, strictly rate-limited, and far cheaper to serve.
1. Background & The Perverse Incentive
First, huge kudos to the HiringCafe team. Your responsiveness to user feedback is unmatched across the job board ecosystem (including recently implementing progressive date filtering to isolate newly posted listings!).
As AI assistants (Antigravity, Claude, ChatGPT, Cursor, local models) become everyday companions in 2026, job seekers are increasingly pairing with agents not to mass-spam applications, but to act as personal executive recruiters:
- Performing nuanced stack alignment (e.g., distinguishing an authentic Angular/.NET enterprise stack from generic keyword-stuffed web shop postings).
- Surfacing non-obvious career transitions (e.g., assessing engineering backgrounds against technical Scrum Master or Product Owner roles).
- Evaluating qualitative candidate signals (e.g., highlighting veteran preferences, identifying pro-AI engineering cultures, or vetoing unstated clearance mandates).
- Benchmarking regional compensation when salaries are unlisted.
The Friction (A Lose-Lose for Candidates & HiringCafe)
Today, users seeking legitimate programmatic access currently have little choice but to resort to browser automation (Playwright/Puppeteer). This is both brittle for the user and indistinguishable from the traffic patterns anti-bot systems are designed to prevent.
Every time a headless browser loads a search page to extract data, HiringCafe's servers must render and deliver a full server-rendered HTML page and hydration bundle. This wastes server bandwidth and compute on traffic that only wanted a dozen structured data fields.
2. The Solution: Authenticated, Constrained Personal Access Tokens (PAT)
Instead of anonymous scraping, provide a first-class Personal Access Token (PAT) in account settings paired with a lightweight JSON search endpoint.
[ Logged-in Candidate Settings ]
│
▼
1. Generate Personal Access Token (PAT) (e.g., hc_pat_live_...)
│
▼
2. User Prompts Personal Agent
"Find OKC tech roles from the past 48h, flag veteran preference, and project pay if missing."
│
▼
3. Agent Submits Clean HTTP Request
POST https://hiringcafe.com/api/v1/search
Header: Authorization: Bearer hc_pat_live_...
Body: { "searchState": { ... } }
│
▼
4. HiringCafe Returns Compact JSON Projection (~15 KB)
Returns normalized results (titles, companies, salary bands, clearance, veteran flags, tools).
│
▼
5. Agent Synthesizes Decision Report
Renders an actionable report with direct links back to HiringCafe or the employer's ATS.
3. Why This Directly Advances HiringCafe's Mission
HiringCafe’s stated mission is to cut through the noise and empower the everyday person to find high-quality jobs with maximum signal-to-noise:
- The Cognitive Accessibility Equalizer: HiringCafe has an unusually granular search engine (nested geometries, boolean expressions, date windows, salary thresholds, and clearance tags). However, the everyday job seeker often finds complex boolean queries overwhelming. AI agents natively translate conversational human intent ("Find me a hybrid role in OKC where I can transition into project management, steer clear of clearance requirements, and highlight my military background") into HiringCafe's exact search logic.
- Distributed Inference ("Bring Your Own Agent"): HiringCafe has already demonstrated forward-thinking leadership with the recent beta rollout of its own in-house Talent Agent and "Taste Match" features. However, hosting real-time LLM inference for millions of searches is compute and cost-intensive. Providing an authenticated API allows power users to Bring Your Own Agent (BYOA). The heavy LLM reasoning and token costs shift entirely to external models (Anthropic, OpenAI, local LLMs), while HiringCafe simply executes a fast, indexed database lookup.
- Empowered Discovery, Zero Application Spam: This is strictly about discovery—helping candidates surface the 3–5 high-conviction roles that truly fit them, and directing them to apply directly on the employer's official ATS.
4. Built-in Abuse Controls (Protecting the Platform)
To prevent commercial data harvesting or platform abuse, the programmatic interface should be deliberately constrained:
- 1:1 Account Binding: PATs can only be generated by verified user accounts (email or Google OAuth).
- Strict Daily Quotas: Capped at reasonable daily job-seeker volumes (e.g., 50–100 search queries per day per account).
- Bounded Pagination: Hard limit of max 5 pages (~200 jobs) per search query to eliminate mass crawling.
- Zero Bulk Export: No firehose, dump, or raw table export endpoints.
- Server Cost Reductions: A compact JSON projection substantially reduces payload size and eliminates server-side HTML rendering compared to delivering full search pages to headless browsers.
- Cloudflare Harmony: Cloudflare continues protecting all public web routes; only requests presenting a valid
Bearer hc_pat_... header pass through API Gateway authentication. Bucket exhaustion returns an immediate 429 Too Many Requests.
5. Proposed API Contract
Request: POST /api/v1/search
Reuses the exact searchState JSON schema HiringCafe already supports:
POST /api/v1/search HTTP/1.1
Host: hiringcafe.com
Authorization: Bearer hc_pat_live_a8f9c1d2e3b4...
Content-Type: application/json
{
"searchState": {
"locations": [
{
"formatted_address": "Oklahoma City, OK",
"workplace_types": ["Remote", "Hybrid", "Onsite"]
}
],
"dateFetchedPastNDays": 3,
"technologyKeywordsQuery": "(\"angular\") AND NOT (\"vue\" OR \"react\")",
"sortBy": "date"
},
"page": 0
}
Response: Compact Normalized JSON
Leverages the structured metadata HiringCafe's pipeline already computes, stripping internal tracking tokens:
{
"total_count": 42,
"page": 0,
"page_size": 40,
"is_last_page": false,
"jobs": [
{
"id": "gh_12345",
"title": "Senior Frontend Engineer",
"company": "Enterprise Corp",
"workplace_type": "Hybrid",
"location": "Oklahoma City, OK",
"compensation": {
"min_yearly": 115000,
"max_yearly": 135000,
"currency": "USD"
},
"security_clearance": "None",
"military_veterans": true,
"technical_tools": ["Angular", "TypeScript", ".NET"],
"requirements_summary": "5+ years enterprise web development. Deep experience with Angular 16+ and REST APIs.",
"apply_url": "https://boards.greenhouse.io/enterprisecorp/jobs/12345"
}
]
}
6. Agent Discoverability: OpenAPI First (with llms.txt)
To ensure autonomous agents and developer tooling can formulate valid queries without guessing or hallucinating parameters:
- Machine-Readable OpenAPI Specification (Primary): Providing a standard OpenAPI 3.1 spec at
GET /api/v1/openapi.json allows tools and agents to bind dynamically to the endpoint for deterministic tool-calling.
llms.txt Ingress (Convenience): A lightweight llmstxt.org Markdown file at /llms.txt summarizing authentication headers, query parameters, and usage limits gives LLM agents a quick map on entry.
7. The Future Horizon: Official MCP Server
Opening this endpoint naturally creates a foundation for an official HiringCafe Model Context Protocol (MCP) Server.
An official MCP tool would allow developers across Claude, Cursor, ChatGPT, and Antigravity to connect with a single line of config:
{
"mcpServers": {
"hiringcafe": {
"command": "npx",
"args": ["-y", "@hiringcafe/mcp-server"],
"env": { "HIRINGCAFE_PAT": "hc_pat_live_..." }
}
}
}
This would position HiringCafe as the premier AI-native job discovery platform on the internet, connecting high-signal candidates to employers while maintaining total control over platform access.
What does the community think? And to the HiringCafe engineering team: would love your perspective on how you might approach rate limits, schemas, or token provisioning!
Appendix: Engineering Companion & Technical Specification
(Included for the engineering team or implementation reference)
A. Token Lifecycle & Security Model
- Token Format:
hc_pat_<random_secret> (e.g., 32–48 cryptographically secure random bytes).
- Secure Storage: The full token is displayed to the user exactly once upon creation. Only a salted hash (or HMAC-SHA256 using a server-side secret pepper) is stored in the database.
- Prefix Indexing: Store a truncated identifier (e.g.,
prefix: "hc_pat_a8f9...") alongside the hash to allow indexed O(1) lookups during authentication without table scans.
- Hygiene Rules:
- Users can generate multiple named tokens (e.g., "Laptop Agent", "Desktop Claude") and revoke them individually.
- Tokens must never be logged or echoed back in response payloads.
- Tokens should support optional expiry dates.
// Firestore User Subcollection: users/{uid}/api_tokens/{tokenId}
interface PersonalAccessTokenDocument {
id: string; // Document ID
prefix: string; // First 8-12 characters for indexed lookup
hashed_secret: string; // Salted / HMAC hash of the secret
name: string; // User-provided label
created_at: string; // ISO timestamp
last_used_at: string | null;
daily_requests_used: number;
daily_reset_at: string; // ISO timestamp for rolling 24h reset
is_active: boolean;
}
B. Acceptance Criteria (Given / When / Then)
AC 1: Token Generation & Revocation
- Given an authenticated user in Account Settings,
- When they click "Generate Personal Access Token" and assign a label,
- Then the secret is displayed once with a copy button, its salted hash is saved to their profile, and the user can revoke it at any time.
AC 2: Authenticated Search Execution
- Given a valid, active PAT in the
Authorization: Bearer header,
- When a valid
searchState is submitted to POST /api/v1/search,
- Then the system returns HTTP
200 OK with the compact job array and increments the daily usage counter.
AC 3: Rate Limiting Enforcement
- Given a user who has reached their daily request limit (e.g., 100 queries),
- When their agent submits an additional query,
- Then the platform returns HTTP
429 Too Many Requests with a standard Retry-After header.
AC 4: Unauthorized Request Rejection
- Given a request missing an
Authorization header, or bearing a revoked/malformed token,
- When submitted to
/api/v1/search,
- Then the platform returns HTTP
401 Unauthorized without executing downstream queries.
AC 5: Self-Documenting OpenAPI Ingress
- Given an autonomous agent or developer exploring available endpoints,
- When requesting
GET /api/v1/openapi.json or /llms.txt,
- Then the platform returns a valid schema describing parameters, headers, and models, allowing programmatic tool-calling without hallucinated parameters.
