Jobhuntr Agent API — Documentation

This folder contains the documentation for the Jobhuntr Agent API: how external agents (automations, scripts, third-party systems) and users interact with the service gateway for agent tokens and agent-only endpoints.

Full API list

Detailed docs (request/response fields, examples, errors): api/

Guidelines for agents: search, read, and submit jobs

Authentication

• Use an agent token (sk_agt_...) for all job-description endpoints. Send it as: Authorization: Bearer sk_agt_<your_token>.
• Do not use a user JWT on /api/agent/ paths — the server returns 403.

How to search / read jobs

1. Call GET /api/agent/job-descriptions/ with your agent token.
2. Optionally add query parameters: page, page_size (max 100), company_name, job_title, location, job_type, remote_type (onsite | remote | hybrid), senior_level (junior | mid | senior).
3. Response is paginated: data, total_count, page, page_size. Each item in data is metadata only; pos_context (full job text) is never returned.

How to submit new jobs

1. Call POST /api/agent/job-descriptions/ with your agent token and JSON body.
2. Required body fields: url, job_title, company_name, location, pos_context.
3. Optional: linkedin_job_id, post_time, hiring_team, num_applicants, salary_range, job_type, remote_type, senior_level, eoy, provide_visa_sponsorship.
4. Same URL upserts; response is metadata only (pos_context never returned).

How to report bad or mismatched data

• Call POST /api/agent/job-descriptions/{job_description_id}/misalignment-report with optional body {"reason": "..."} when stored content does not match the URL.

Typical agent workflow

1. Obtain token (once, via app or user-authenticated client):
   POST /api/agent-tokens/me/get-or-create with user JWT → store token when is_new is true.

2. Submit jobs:
   POST /api/agent/job-descriptions/ with agent token and required fields. Store returned id if needed.

3. List recent jobs:
   GET /api/agent/job-descriptions/ with agent token and optional filters to poll or sync.

4. Report bad data:
   POST /api/agent/job-descriptions/{id}/misalignment-report with optional reason when content does not match the URL.

Documentation index