Is There a Defined API for the ai-job-search Service?

The ai-job-search repository does not expose a unified public API; instead, it implements a thin-client wrapper architecture where individual skill modules provide typed helper functions to query external job portals.

The MadsLorentzen/ai-job-search project is architected as a collection of agent-based CLI tools rather than a monolithic service with a defined REST interface. If you are looking for a centralized endpoint to consume, the codebase intentionally does not provide one. Instead, the "API" consists of client-side utilities distributed across portal-specific skill directories that wrap third-party job search services like Jobnet, JobDanmark, and JobIndex.

Why ai-job-search Uses a Thin-Client Architecture

The repository follows a thin-pointer design that keeps canonical specifications under the .claude/ directory while delegating implementation details to .agents/skills/<portal>/. Each skill is a deliberately thin wrapper that translates command-line options into HTTP requests against external APIs.

This design choice means there is no single api/ folder or OpenAPI specification defining a native ai-job-search service. The architecture prioritizes direct consumption of public job portal endpoints over abstraction layers, ensuring that the underlying data remains fresh and unmodified.

The Client API: Skill-Based Helper Modules

The actual programmatic interface resides in portal-specific helpers.ts files located under each skill's CLI source directory. These modules export three core asynchronous functions:

• apiFetch<T>: General-purpose wrapper for GET requests with query parameters.
• apiPost<T>: For endpoints requiring request bodies.
• apiGet<T>: Specialized wrapper for simple GET operations.

All helpers share the same TypeScript signature pattern:

export async function apiFetch<T>(path: string, params?: Record<string, string>): Promise<T>;
export async function apiPost<T>(path: string, body: unknown): Promise<T>;
export async function apiGet<T>(path: string, params?: Record<string, string>): Promise<T>;

These functions automatically prepend the portal-specific base URL defined within each helpers.ts file. They attach a constant USER_AGENT header (typically formatted as 'jobnet-cli/1.0' or similar per portal), enforce a default 10-second timeout via AbortSignal, and implement exponential back-off retry logic for transient 5xx errors.

Querying Job Portals: Code Examples

To interact programmatically with the ai-job-search suite, you import directly from the relevant skill's helper module. Below are practical implementations for the most common wrappers.

Searching the Jobnet Portal

Located in .agents/skills/jobnet-search/cli/src/helpers.ts, this wrapper queries the Danish Jobnet database:

import { apiFetch } from '.agents/skills/jobnet-search/cli/src/helpers.ts';

async function searchJobnet() {
  const params = { q: 'data scientist', region: 'DK' };
  const result = await apiFetch<SearchApiResponse>('/FindJob/Search', params);
  console.log(result.hits);
}
searchJobnet();

JobDanmark Autocomplete Suggestions

The JobDanmark skill provides type-ahead functionality via its wrapper in .agents/skills/jobdanmark-search/cli/src/helpers.ts:

import { apiFetch } from '.agents/skills/jobdanmark-search/cli/src/helpers.ts';

async function getSuggestions() {
  const params = { q: 'frontend' };
  const suggestions = await apiFetch<string[]>('/api/search/autocomplete', params);
  console.log(suggestions);
}
getSuggestions();

Retrieving FreeHire Job Listings

For the FreeHire portal, use apiGet from .agents/skills/freehire-search/cli/src/helpers.ts:

import { apiGet } from '.agents/skills/freehire-search/cli/src/helpers.ts';

async function freeHireSearch() {
  const params = { q: 'python', remote: 'true' };
  const jobs = await apiGet<Job[]>('/api/v1/agent/jobs/search', params);
  console.log(jobs);
}
freeHireSearch();

Critical Implementation Files

The following files constitute the public client API surface area for the ai-job-search system:

• .agents/skills/jobnet-search/cli/src/helpers.ts — Core apiFetch and apiPost wrappers for the Jobnet portal, including base URL configuration and retry logic.
• .agents/skills/jobdanmark-search/cli/src/helpers.ts — Implements the same wrapper pattern for JobDanmark’s autocomplete and search endpoints.
• .agents/skills/jobindex-search/cli/src/helpers.ts — Client-side wrapper for JobIndex’s public search API.
• .agents/skills/freehire-search/cli/src/helpers.ts — Provides apiGet for the FreeHire agent-specific endpoints.
• .agents/skills/<portal>/cli/README.md — Human-readable documentation of available CLI commands and parameters for each wrapper.
• .agents/skills/<portal>/SKILL.md — Canonical specification defining required URLs, parameters, and behavior contracts for the skill.
• tests/ — Test suites verifying helper function behavior, including User-Agent string validation, timeout handling, and retry mechanisms.

Summary

• The ai-job-search repository does not ship with a centralized REST API or server component.
• Programmatic access is provided via typed helper functions (apiFetch, apiPost, apiGet) exported from individual skill modules under .agents/skills/.
• Each skill acts as a thin client wrapper around external portals like Jobnet, JobDanmark, FreeHire, and JobIndex.
• Helper modules enforce consistent networking policies: explicit User-Agent headers, 10-second request timeouts, and exponential back-off on server errors.
• To consume the service programmatically, import and invoke functions directly from the relevant portal's helpers.ts file.

Frequently Asked Questions

Does ai-job-search expose a REST API endpoint?

No. The MadsLorentzen/ai-job-search codebase is designed exclusively as a client-side tool suite. There is no server component listening on HTTP ports; instead, CLI commands and imported helper functions make direct requests to external job portal APIs.

How do I programmatically interact with ai-job-search?

Import the helper functions from the specific skill directory you require. For example, import { apiFetch } from .agents/skills/jobnet-search/cli/src/helpers.ts and call it with the target endpoint path and query parameters. These functions return typed promises resolving to the JSON payloads from the underlying external service.

What authentication does the ai-job-search API require?

The repository itself implements no proprietary authentication mechanism for a native API. Any authentication requirements are delegated to the underlying external job portals (e.g., Jobnet or JobIndex session cookies). The helpers.ts modules handle HTTP transport but do not inject first-party ai-job-search auth tokens.

Can I deploy ai-job-search as a backend microservice?

Not without significant custom development. The codebase is intentionally client-facing and CLI-oriented. To expose it as a microservice, you would need to build your own HTTP server layer that imports and wraps the helper functions from .agents/skills/*/cli/src/helpers.ts into REST or gRPC endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}