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

> Explore the ai-job-search service. Discover its thin-client wrapper architecture and how individual skill modules offer typed helper functions instead of a unified public API.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: api-reference
- Published: 2026-09-02

---

**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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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:

```typescript
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobnet-search/cli/src/helpers.ts), this wrapper queries the Danish Jobnet database:

```typescript
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/jobdanmark-search/cli/src/helpers.ts):

```typescript
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.agents/skills/freehire-search/cli/src/helpers.ts):

```typescript
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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.