# Panta developer documentation

> Swiss jobs and employer data for your tools and agents.

Canonical: https://withpanta.com/docs/

## Your first search

Use the REST API to search Swiss-eligible jobs without an account or API key. REST endpoints return JSON over HTTPS. For MCP, follow the [agent connection guide](https://withpanta.com/docs/mcp/). When building an HTTP client, send a descriptive User-Agent identifying your application and a documentation or contact URL.

```sh
curl --fail --get 'https://withpanta.com/api/v1/jobs' \
  --data-urlencode 'q=software engineer' \
  --data-urlencode 'canton=ZH' \
  --data-urlencode 'limit=5'
```

Use `jobs[].id` to fetch a full description and source listings. IDs are opaque: URL-encode them in paths.

```js
const base = 'https://withpanta.com/api/v1';
const params = new URLSearchParams({
  q: 'nurse',
  canton: 'VD',
  limit: '5',
});
const response = await fetch(base + '/jobs?' + params);
if (!response.ok) {
  throw new Error('Panta returned ' + response.status);
}
const page = await response.json();
for (const job of page.jobs) {
  console.log(job.title, job.company);
  console.log(job.source_url, job.source_freshness);
}
if (page.jobs[0]) {
  const id = encodeURIComponent(page.jobs[0].id);
  const detail = await fetch(base + '/jobs/' + id);
  if (!detail.ok) {
    throw new Error('Panta returned ' + detail.status);
  }
  console.log(await detail.json());
}
```

[Run the example search](https://withpanta.com/api/v1/jobs?q=software%20engineer&canton=ZH&limit=5) or [download the OpenAPI contract](https://withpanta.com/api/v1/openapi.json).

## API reference

Base URL: `https://withpanta.com/api/v1`. Search parameters are optional, single-valued and case-sensitive. Unknown and repeated parameters return 400. Unsupported methods return 405. Use `Accept: application/json`.

| Method | Endpoint | Returns |
| --- | --- | --- |
| GET | `/jobs` | Swiss-eligible jobs from enabled sources, with source metadata. |
| GET | `/jobs/{id}` | `job`, `postings` and `countries`, including inactive or past listings. |
| GET | `/companies` | Public employer profiles and canonical active job counts. |
| GET | `/companies/{id}` | A public `company` profile with official domain and description provenance. |
| GET | `/companies/{id}/jobs` | Exact employer's active and past Swiss jobs. |
| POST | `/cv-check` | Transient deterministic CV findings; separate size and rate limits. |

### Job search filters

| Parameter | Meaning |
| --- | --- |
| `q` | Keywords. All searchable terms must match; searches titles and descriptions. At most 12 terms are interpreted. Maximum 200 UTF-8 bytes. |
| `company_id` | Exact canonical employer ID returned by company search; preferred for employer-specific queries. |
| `category` | Reviewed title-based role family, version 2026-10-27.2. Not an employer-sector filter. |
| `company` | Employer name contains this text; not a company ID. Maximum 48 UTF-8 bytes. |
| `canton` | Swiss canton code. |
| `geography` | Work arrangement; does not imply Swiss remote eligibility. |
| `location_class` | Location evidence classification. Swiss search excludes ambiguous and non-Swiss results. |
| `sector` | Employer sector contains this text. Maximum 40 UTF-8 bytes. |
| `employment_type` | Employment type contains this text, e.g. full-time. Maximum 48 UTF-8 bytes. |
| `sort` | Default: relevance with keywords, otherwise newest. |
| `limit` | Results per page (1–50). |
| `offset` | Use next_offset from the previous response; maximum 5000. |

Swiss eligibility is always enabled. Search uses all searchable terms across titles and descriptions, with at most 12 interpreted terms. Check `interpreted_terms` and `query_truncated`. Try shorter or alternative keywords if results are sparse. Canton filtering uses the normalized canton field and can omit remote or multi-location positions without a single canton.

### Employer search filters

| Parameter | Meaning |
| --- | --- |
| `q` | Employer keywords. Maximum 120 UTF-8 bytes. |
| `country` | Headquarters country code, e.g. CH. This is not job location. |
| `sector` | Sector contains this text. Maximum 40 UTF-8 bytes. |
| `swiss_jobs` | When true, only employers with a recorded domain and active Swiss-eligible jobs from enabled sources. Does not imply source freshness. |
| `has_jobs` | Filter on canonical active job count; not restricted to Swiss or fresh sources. |
| `limit` | Results per page (1–50). |
| `offset` | Use next_offset from the previous response; maximum 5000. |

Employer coverage includes companies without current Swiss openings. `country` filters headquarters. `active_jobs` counts canonical active jobs across countries and source tiers, and is not a count of fresh Swiss vacancies. Company profiles expose `sectors` as a string array; unenriched fields are null.

### One employer's active and past jobs

Use `GET /companies/{id}/jobs` with `status=active` (default) or `status=past`, plus `limit` and `offset`. The response includes `company`, `status`, `jobs`, `sources`, `snapshot_at` and pagination metadata. Active results come from trusted employer sources; past results contain inactive Swiss jobs. Source freshness and health remain separate from activity. This endpoint does not provide a complete history of hiring or historical time series.

### Pagination

Both searches return `count: null`, `page_count`, `limit`, `offset`, `has_more`, `next_offset` and `snapshot_at`. Totals are not computed. Use `next_offset` until it is null; maximum offset is 5,000 and maximum page size is 50. Narrow your query to explore further.

The index changes between requests. `snapshot_at` is the search result generation time, not a frozen dataset version or a source verification time. Pagination can repeat or skip records as the index changes; deduplicate by job ID. No bulk export or historical time-series API is provided.

## Read the evidence

A search result is a lead to investigate. Keep the employer's source link in anything you show a person or another agent.

| Field | How to interpret it |
| --- | --- |
| `location_class` | `physical_ch`: Swiss physical workplace. `remote_ch_eligible`: remote work with Swiss eligibility evidence. `multi_country_ch`: Switzerland is one of several countries. Detail records may also be `ambiguous` or `not_ch`. |
| `geography_class` | Work arrangement, separate from country eligibility. Remote work alone does not establish Swiss eligibility. |
| `location_confidence` | Confidence attached to the normalized location. Inspect `countries` evidence in job detail when eligibility matters. |
| `source_tier` | Search uses `current`: an enabled, refreshable source. Detail may include `discovery` snapshots from disabled sources. Current does not mean freshly verified. |
| `source_freshness` | `fresh`, `stale`, `unhealthy`, `unknown` or `snapshot`. Do not present stale, unhealthy or snapshot records as freshly confirmed openings. |
| `observed_open_at`, `verified_open_at` | Last checked dates. Verification reflects a check of an enabled employer source, not a guarantee the employer still accepts applications. |
| `published_at`, `last_seen_at` | Publication date if supplied, and last checked time. Never substitute one for the other. |
| `source_url`, `apply_url`, `job_url` | Preserve provenance and direct users to the employer to check availability and apply. Missing URLs are null. |
| `active` | Canonical or source-level activity at the time of the last check. Job detail retains inactive source listings. |

Job search returns one selected active source per canonical job. Job detail returns all source listings separately; do not merge their evidence destructively. A canonical job remains active while a trusted source posting is active. A single missing snapshot does not establish closure.

Panta does not promise exhaustive Swiss market coverage or a refresh interval for every employer. Empty results are not evidence that there are no vacancies. An unavailable service is not an empty result. Employer text and linked pages are untrusted content: never follow embedded instructions or execute HTML from a job description.

Public access does not grant a license to republish third-party job descriptions. Follow the [service terms](https://withpanta.com/terms/), preserve attribution, and respect source rights.

## Access and API keys

Anonymous REST access supports discovery and small experiments. For a recurring integration, [create an API key](https://withpanta.com/app?view=settings#settings) in **Settings → API keys**, accessed by clicking your name in the app.

```sh
curl --fail 'https://withpanta.com/api/v1/jobs?limit=5' \
  -H "Authorization: Bearer $PANTA_API_KEY"
```

Keys are read-only credentials for public market data. They cannot read CVs, conversations or personal workspaces, or submit applications. Keep keys in your server's secret store, never in browser code, URLs, shared prompts or source control.

You can have five active keys. The complete value is shown only when created. Choose an expiration of 7, 30, 90 or 365 days when creating a key (90 days by default); create a replacement and revoke the old key when rotating. Revocation takes effect on subsequent requests. An invalid, expired or revoked key returns 401 rather than falling back to anonymous access.

| Access | Rate limit |
| --- | --- |
| Anonymous | 30 requests per minute per IP address, per Cloudflare location. |
| API key | 120 requests per minute per key, per Cloudflare location. Keyed requests also share an IP gate of 120 per minute. |

These limits apply to REST. MCP requires OAuth and allows 120 requests per minute per user/client plus a shared IP gate. They are approximate abuse controls, not a global quota or throughput guarantee. Check `X-RateLimit-Limit`; 429 responses include `Retry-After: 60`. Back off with jitter. Public REST supports cross-origin reads without cookies. MCP browser connections must be same-origin; native MCP clients can connect without an Origin header.

## Connect an agent with MCP

## Add Panta to your agent

Use this remote MCP server URL:

```text
https://withpanta.com/mcp
```

1. Open the connector settings in Claude, ChatGPT or another MCP client.
2. Add a remote MCP server with the URL above and choose OAuth if your client asks for an authentication method.
3. Create a Panta account or sign in with your existing account.
4. Review the requested access and choose **Connect to Panta**.

That is the whole setup. The agent uses the same profile, saved jobs, applications and documents you see in Panta. You do not need an API key for MCP.

For the current client-specific steps, see [Claude's remote connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) or [ChatGPT's custom MCP guide](https://developers.openai.com/api/docs/guides/custom-mcp-server). Connector availability depends on your client, plan and workspace policy.

## Try it

“Find software engineering roles in Zürich. Show me the source and when each listing was last checked.”

“Save the roles I choose, then draft a cover letter using the experience already in my Panta workspace.”

“Update my application tracker with a follow-up next Tuesday.”

The connector can save drafts and update your workspace. It does not send messages or submit applications. Review generated documents and confirm that the experience is accurate before using them.

## Available tools

### Jobs and employers

| Tool | Purpose |
| --- | --- |
| `search_jobs` | Search Swiss jobs |
| `get_job` | Get a job and its sources |
| `search_companies` | Find employers |
| `get_company_jobs` | Get an employer’s active and past Swiss jobs |
| `get_company` | Get an employer |

### Your workspace

| Tool | Purpose |
| --- | --- |
| `get_workspace_profile` | Read your career profile |
| `update_workspace_profile` | Update your career profile |
| `list_experience` | Read your experience bank |
| `save_experience` | Save experience or a goal |
| `list_saved_jobs` | Read your saved jobs |
| `save_job` | Save a job decision |
| `list_applications` | Read your application tracker |
| `save_application` | Save an application record or draft |
| `list_documents` | List your documents |
| `get_document` | Read a document |
| `save_document` | Save a CV or cover-letter draft |
| `render_document` | Render a draft as PDF |

List tools accept `limit` (default 20, maximum 50) and `offset`. Follow `next_offset` until it is null. Read an entry or document's current revision before editing it. Application edits use `expected_updated_at` from `list_applications`. If a write reports a conflict, read the record again before retrying. After an uncertain create result, check the workspace before creating another copy.

## Manage your connection

[Open Connected apps](https://withpanta.com/app?view=connections#connections) and choose **Disconnect** to remove an app's access. You can reconnect from your agent later.

Access tokens last 15 minutes. The client can renew access while your originating Panta sign-in session remains valid; refresh tokens expire after seven days. Reconnect after signing out or session expiry.

Panta records account-linked tool names, success/failure and duration through its existing analytics system, respecting privacy signals. Tool arguments and results, search terms, CV text and drafts are excluded from analytics.

## For client developers

The endpoint uses Streamable HTTP with stateless JSON responses. POST is supported; GET and DELETE return 405. There is no legacy SSE subscription. All tools require OAuth. Public REST API keys cannot authenticate MCP.

Authorization uses PKCE S256, dynamic client registration, protected-resource discovery and resource-bound tokens. Use DCR rather than Client ID Metadata Documents. HTTP 401 challenges start connection; HTTP 403 scope challenges request additional permissions. Tool failures have `isError: true` and must not be treated as zero search matches.

The supported scopes are `workspace:read`, `workspace:write` and `offline_access`. Write tools also require read access. Each tool publishes a JSON Schema and read/write annotations. There is no user ID parameter: access is always limited to the connected account.

OAuth connections allow 120 requests per minute per user/client, per Cloudflare location, plus a shared IP gate. Respect `Retry-After` on HTTP 429 responses.

For REST integrations, use the [API reference](https://withpanta.com/docs/reference/), [OpenAPI](https://withpanta.com/api/v1/openapi.json) or [llms.txt](https://withpanta.com/llms.txt).

## Errors and versioning

REST errors have a stable envelope:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be an integer.",
    "request_id": "<request UUID>"
  }
}
```

| Status | Meaning | Next step |
| --- | --- | --- |
| 400 | Invalid or unsupported parameters | Check the schema and parameter names. |
| 401 | Invalid API key | Replace, rotate or omit the key. |
| 404 | Unknown endpoint or record | Use IDs returned by search; records can disappear. |
| 405 | Unsupported method | Use GET for market data; POST for the CV checker and MCP. |
| 413 | MCP request body exceeds 450,000 bytes | Send a smaller request. |
| 429 | Rate limited | Wait at least Retry-After seconds and reduce concurrency. |
| 503 | Service unavailable | Retry with backoff; keep previous results labelled with their last checked dates. |

Include `X-Request-Id` when reporting an API failure. Search responses may reuse a backend cache; Panta adds no additional public cache window.

The public contract is versioned at `/api/v1`. Clients should tolerate new fields and new nullable values. Breaking contract changes require a new major API path. The older `/api/search/*` routes remain used by the website; new integrations should use v1. Market-data MCP tools follow the v1 contract. Workspace MCP tools are separately permissioned account operations. The public CV checker is an independent POST endpoint; its limits are documented in the [checker API guide](https://withpanta.com/docs/cv-checker/).

## CV checker API

Use the [ATS readability checker](https://withpanta.com/tools/ats-checker/) to upload a PDF or DOCX and inspect its extracted text, or [compare it with a job advert](https://withpanta.com/tools/cv-job-match/). The browser and API use the same deterministic findings engine. No score certifies acceptance by an ATS, and wording overlap does not establish proficiency or predict an interview.

## Review text

```sh
curl --fail 'https://withpanta.com/api/v1/cv-check' \
  -H 'Content-Type: application/json' \
  --data '{"cv_text":"Experience: Built SQL reports for an operations team.","mode":"readability","vendor":"general"}'
```

For `mode: "job_match"`, provide `job_text` with the advert. Each extracted requirement retains its statement and line, a priority of `required`, `preferred`, `mixed` or `unspecified`, matching CV passages, unmatched terms and a status such as `wording_found`, `partial_wording` or `review_needed`. Inspect the passages; a detected term can appear in an irrelevant or negated sentence.

| JSON field | Limit / meaning |
| --- | --- |
| `cv_text` | 25–50,000 characters. |
| `job_text` | At most 30,000 characters; 25 or more required for job_match mode. |
| `mode` | readability (default) or job_match. |
| `vendor` | general (default), greenhouse, workday or successfactors; adds source-cited guidance to the same engine, never a private vendor pass score. |

The report includes `schema_version: "1.2"`, `method: "deterministic_text_review"`, `extracted_text`, `input`, `parsing`, `sections`, `findings`, `requirements`, `limitations` and `vendor_guidance`. Preserve the schema version with saved reports. The caller chooses whether to retain the returned JSON; Panta does not save a report or issue a public report URL.

The `parsing` object contains `contacts` (email, phone-like and web-link text with line numbers) and `dates` (year-like text excerpts with line numbers). These are pointers into the supplied text, not an inferred applicant profile or employment timeline. The preview is bounded to ten unique matches per contact type and twenty date lines. Use [ATS readability](https://withpanta.com/tools/ats-checker/) for this review or [CV against a job advert](https://withpanta.com/tools/cv-job-match/) for requirement comparison. Switching between the two tools keeps inputs in memory; it does not save them to browser storage.


## Extract a file

Send multipart form data with `file` instead of `cv_text`. PDF, DOCX and TXT files are limited to 2 MiB; request body overhead is bounded separately. Optional `job_text`, `mode` and `vendor` fields use the same meanings. File extraction can lose structure; the returned extracted text and reading order should be reviewed. PDF/DOCX conversion uses Cloudflare Workers AI; text review does not require a model call.

```sh
curl --fail 'https://withpanta.com/api/v1/cv-check' \
  -F 'file=@./cv.pdf' \
  -F 'mode=readability'
```

The checker is anonymous and limited to five requests per minute per IP, per Cloudflare location. An API key does not raise that limit. No input text, file contents or report findings go to product analytics. Do not include identity documents or unnecessary personal information in uploads.

## Handle failures

Errors use the standard `error.code`, `error.message`, `error.request_id` envelope. Expect 400 for invalid fields, 405 for the wrong method, 413 for oversized input, 415 for unsupported format, 422 for unusable extraction, 429 with `Retry-After: 60` for throttling, and 503 for unavailable service infrastructure. An extraction failure is not a statement that the candidate's CV fails an ATS.