JobScanner · API v1
Remote jobs, with evidence

Client reference · Authentication · Queries · Publication rules

JobScanner API user manual

The JobScanner API provides collected remote jobs that are eligible for applicants in the United States. It serves published PostgreSQL snapshots, keeps mandatory exclusions in place, and separates approved jobs from work that still needs review.

API base URL: https://api.jobscanner.top
Public guide: https://api.jobscanner.top/guide
Fallback base URL: https://jobs-api-production-2a3e969b.up.railway.app

Use the custom domain for client integrations. HTTPS and API-key access were verified on 2026-11-16. The Railway address remains available as a fallback and serves the same API with the same authentication requirements. This guide contains no live job-count claims.

1. What an approved job means

A job in the default checked bucket has a saved full description, passes the deterministic US-eligibility and mandatory exclusion rules, and has a matching AI suitability approval for the exact published content, policy, model, and prompt version. Collection, duplicate detection, source verification, and mandatory filtering run without AI. The subsequent AI review can reject or defer a candidate; it cannot override a mandatory exclusion or turn an incomplete description into a full one.

The review bucket is separate. Depending on the job, it can contain an incomplete description, uncertain US eligibility, a full description awaiting AI review, an uncertain AI result, a processing error, or a decision that no longer matches the current content or policy. A review record is not an approved job. Inspect processing.deterministic_bucket, processing.ai_status, processing.completion_status, description_kind, and us_eligibility together.

When collection refreshes the snapshot, the publisher can reuse an immutable prior AI decision only if the job's public content hash, policy fingerprint, model, and prompt version still match. This preserves an approved subset while new candidates await review. A changed or missing decision does not inherit approval merely because the canonical job ID is familiar.

The API does not promise every opening on every source. A source can be blocked, unavailable, empty, or partially collected. A saved opening can close after collection. Expiry dates are enforced when supplied, but an absent expiry date is not evidence that applications are still open.

For applications, prefer employer or applicant-tracking-system (ATS) links observed in the source. job_url retains the original listing for provenance, while apply_url carries the available application destination. A source page or application destination may still require an additional navigation step; the service does not check every URL or guarantee that every link opens a résumé/contact form directly. It does not submit applications.

2. Obtain and protect an API key

Ask the service owner for a client-specific key and the scopes your integration requires. There is no public sign-up, key-creation, or collection-control endpoint.

Scope Access
jobs:read Approved jobs, permitted job details, source status/counts, and the OpenAPI document. Required for every configured key.
jobs:review Also permits the separate review bucket and review details. Optional; granted in addition to jobs:read.

Supply one authentication header:

X-API-Key: YOUR_CLIENT_KEY

Alternatively:

Authorization: Bearer YOUR_CLIENT_KEY

Do not send both headers, duplicate authentication headers, or credentials in query parameters. Query parameters named api_key, apikey, key, token, or authorization are rejected. Use HTTPS. Store the plaintext key in your backend's secret store or a protected environment variable; do not put it in a public web page, source repository, analytics event, screenshot, or application log. Browser integrations should call your own backend, which holds the key. This service does not provide a browser CORS integration or a public anonymous data feed.

The server configuration stores SHA-256 key digests, not plaintext client keys. Revocation is performed by the service owner removing the corresponding key configuration. A key identifies a client, not an end-user account. All clients currently share the owner's published job policy; keys do not select different exclusion rules.

3. Quick start

Set JOBS_API_KEY through your secret manager. The commands below read it from the environment and use https://api.jobscanner.top unless you override JOBS_API_URL. To use the fallback, set JOBS_API_URL to https://jobs-api-production-2a3e969b.up.railway.app; paths and authentication stay the same.

curl

JOBS_API_URL="${JOBS_API_URL:-https://api.jobscanner.top}"
curl --fail-with-body --get "$JOBS_API_URL/v1/jobs" \
  --data-urlencode 'q=engineer' \
  --data-urlencode 'limit=25' \
  -H "X-API-Key: $JOBS_API_KEY"

Retrieve review records only with a review-enabled key:

curl --fail-with-body --get "$JOBS_API_URL/v1/jobs" \
  --data-urlencode 'bucket=review' \
  --data-urlencode 'limit=25' \
  -H "Authorization: Bearer $JOBS_API_KEY"

Find jobs at recently founded companies with no more than three explicitly supported interviews:

curl --fail-with-body --get "$JOBS_API_URL/v1/jobs" \
  --data-urlencode 'new_company=true' \
  --data-urlencode 'max_interviews=3' \
  -H "X-API-Key: $JOBS_API_KEY"

These filters omit records whose company founding status or exact interview count is unknown. An empty result does not prove no such jobs exist.

PowerShell

if (-not $env:JOBS_API_KEY) { throw 'Set JOBS_API_KEY in your secret environment.' }
$apiBase = if ($env:JOBS_API_URL) {
    $env:JOBS_API_URL.TrimEnd('/')
} else {
    'https://api.jobscanner.top'
}
$headers = @{ 'X-API-Key' = $env:JOBS_API_KEY }
$search = [Uri]::EscapeDataString('software engineer')
$page = Invoke-RestMethod -Method Get `
    -Uri "$apiBase/v1/jobs?q=$search&limit=25" -Headers $headers -TimeoutSec 30
$page.data | Select-Object id, title, company, location, interview_count, job_url

if ($page.pagination.next_cursor) {
    $cursor = [Uri]::EscapeDataString($page.pagination.next_cursor)
    $nextPage = Invoke-RestMethod -Method Get `
        -Uri "$apiBase/v1/jobs?q=$search&limit=25&cursor=$cursor" `
        -Headers $headers -TimeoutSec 30
}

Keep the same filters when requesting the next page. The complete pagination and retry rules below also apply to PowerShell clients.

Python: page through approved results

This standard-library example retries bounded transient failures, restarts pagination when the published snapshot changes, and deduplicates by the stable API id. For production imports, replace the in-memory dictionary with a database upsert keyed by id.

import json
import os
import time
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = os.environ.get("JOBS_API_URL", "https://api.jobscanner.top").rstrip("/")
KEY = os.environ["JOBS_API_KEY"]


class SnapshotChanged(Exception):
    pass


def get_page(params):
    request = Request(
        BASE + "/v1/jobs?" + urlencode(params),
        headers={"X-API-Key": KEY, "Accept": "application/json"},
    )
    for attempt in range(5):
        try:
            with urlopen(request, timeout=30) as response:
                return json.load(response)
        except HTTPError as error:
            if error.code == 409:
                raise SnapshotChanged() from None
            if error.code not in (429, 503) or attempt == 4:
                raise
            delay = int(error.headers.get("Retry-After", "5"))
            time.sleep(max(1, min(delay, 60)))


def collect_approved():
    for restart in range(3):
        # Each successful result set belongs to one pagination attempt.
        jobs, params = {}, {"bucket": "checked", "limit": 100}
        try:
            while True:
                page = get_page(params)
                for job in page["data"]:
                    jobs[job["id"]] = job
                cursor = page["pagination"]["next_cursor"]
                if cursor is None:
                    return jobs, page["snapshot"]
                params["cursor"] = cursor
        except SnapshotChanged:
            if restart == 2:
                raise RuntimeError("Snapshot kept changing; retry the import later.") from None


jobs, snapshot = collect_approved()
print({"imported": len(jobs), "snapshot_id": snapshot["id"]})

Persisting a cursor allows a short interruption to resume only while its signature, client identity, filters, expiry, and snapshot remain valid. A cursor is not a durable synchronization checkpoint. Store imported IDs independently.

JavaScript: backend request

This example is for a Node.js backend with built-in fetch. Do not ship the key to browser code.

const base = (process.env.JOBS_API_URL ?? "https://api.jobscanner.top").replace(/\/$/, "");
const key = process.env.JOBS_API_KEY;
if (!key) throw new Error("Set JOBS_API_KEY in the backend secret environment.");

const params = new URLSearchParams({ q: "engineer", limit: "25" });
const response = await fetch(`${base}/v1/jobs?${params}`, {
  headers: { "X-API-Key": key, Accept: "application/json" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  // Handle 409 by restarting pagination; honor Retry-After for 429/503.
  throw new Error(`Jobs API returned HTTP ${response.status}`);
}
const page = await response.json();
for (const job of page.data) {
  console.log({ id: job.id, title: job.title, company: job.company });
}

4. Endpoints

All endpoints are read-only. Only /, /guide, and /healthz are public.

Method and path Authentication Result
GET / None Redirects to /guide.
GET /guide None This static guide; no private job data.
GET /healthz None Process liveness: {"status":"ok","service":"jobs-api"}. Does not prove data publication is ready or sources are healthy.
GET /v1/jobs jobs:read; also jobs:review when requested Paginated list in one bucket.
GET /v1/jobs/{job_id} jobs:read; review details also require jobs:review One accessible, unexpired job and snapshot metadata.
GET /v1/sources jobs:read Source statuses and current accessible counts by bucket. Review counts require review scope.
GET /openapi.json Valid API key Machine-readable endpoint and query-parameter schema with header authentication definitions.

Interactive /docs and /redoc pages are disabled. Public collection-start, job-write, key-management, and model-execution endpoints are not provided.

GET /v1/jobs parameters

Parameter Type/default Meaning
bucket checked or review; default checked Approved results or the separate review queue.
limit Integer 1–100; default 25 Maximum records in this page.
q String, at most 200 characters; default empty Case-insensitive literal substring in job title or company. Does not search descriptions or perform semantic/AI search.
source Source identifier, at most 40 characters; default empty Exact source filter. Use identifiers returned by /v1/sources; lowercase letters, digits, _, and -, beginning with a letter.
company String, at most 150 characters; default empty Case-insensitive literal substring in employer name.
new_company Optional true or false Filters evidence-backed recently founded classification; unknown values match neither.
startup Optional true or false Filters evidence-backed startup classification; unknown values match neither.
min_interviews Optional integer 0–50 Minimum exact supported interview count; unknown totals are omitted.
max_interviews Optional integer 0–50 Maximum exact supported interview count; must be at least min_interviews when both are set.
cursor Opaque string, at most 2,048 characters Continuation token returned by the previous page.

Filters are combined with AND. % and _ in text searches are literal characters, not SQL wildcards. The order is ascending stable id; there is no relevance ranking, date sorting, page-number parameter, or total-count field in the list response. company_id is a response identifier, not a query parameter. The current target country is always US; this API has no country-switch parameter.

GET /v1/jobs/{job_id}

Use the job's API id, a lowercase 64-character hexadecimal canonical identifier. Do not substitute source_job_id, a company ID, or an application URL. A valid-looking ID can return 404 when the job does not exist, is excluded/rejected/expired, or is in a bucket the key cannot access. This avoids disclosing inaccessible records.

GET /v1/sources

Each entry can include source, counts, status, and reason. Counts refer to current accessible published rows, not all raw captures or all jobs on that website. A provider with no accessible results may still appear with an empty counts object and a collection status. Reasons are sanitized codes; private errors, headers, credentials, and raw source responses are not exposed.

Use returned source identifiers rather than hardcoding a guarantee that every configured website is currently supplying jobs. Collection status belongs to the published collection snapshot; it is not a real-time probe.

5. Response format

A list response has data, snapshot, and pagination objects. The following example is entirely synthetic; Example Labs, its job, identifiers, URLs, dates, and counts are illustrative, not collected openings. Optional fields are omitted here to keep the example readable.

{
  "data": [
    {
      "id": "0000000000000000000000000000000000000000000000000000000000000000",
      "source": "greenhouse",
      "source_job_id": "example-job-42",
      "title": "Software Engineer",
      "company": "Example Labs",
      "location": "Remote — United States",
      "remote_type": "remote",
      "job_url": "https://example.org/jobs/example-job-42",
      "apply_url": "https://example.org/apply/example-job-42",
      "description": "Example Labs was founded in 2024 and is a startup. This role is fully remote within the United States. Build and maintain our software. The process includes an application, three interviews (recruiter, technical, and hiring manager), and an assessment.",
      "description_kind": "full",
      "bucket": "checked",
      "us_eligibility": "eligible",
      "processing": {
        "deterministic_bucket": "checked",
        "ai_status": "approved",
        "completion_status": "complete"
      },
      "company_founded_year": 2024,
      "company_is_startup": true,
      "company_is_new": true,
      "company_evidence": [
        {
          "quote": "Example Labs was founded in 2024 and is a startup.",
          "source_url": "https://example.org/jobs/example-job-42"
        }
      ],
      "interview_count": 3,
      "expires_at": null,
      "classification_reasons": []
    }
  ],
  "snapshot": {
    "id": "synthetic-snapshot-id",
    "at": "2026-11-16T12:00:00+00:00",
    "target_country": "US",
    "publication_stage": "ai_completed",
    "freshness": "saved_observations_not_live_revalidated"
  },
  "pagination": {
    "limit": 25,
    "next_cursor": null,
    "has_more": false
  }
}

Job fields

Field Meaning
id Stable canonical job ID for deduplication and detail lookup.
source, source_job_id Original retained provider and provider-specific identifier. A source ID alone is not globally unique.
title, company, location, remote_type, employment_type Saved source attributes; some source strings may be empty or missing.
job_url Original public job/source URL retained for provenance; it may be a job-board listing.
apply_url Available source-observed application destination, preferably the employer or ATS URL, or null. The service does not verify every destination as a directly usable form. Unsupported or credential-bearing URLs are suppressed.
description Saved text. It can be incomplete in review results. Render it as text, not executable HTML.
description_kind full, summary, unknown, or missing; only full can be approved.
bucket Public bucket, checked or review.
filter_status Saved deterministic filtering label. It is not a substitute for bucket and processing; an AI-pending job can retain a deterministic passing label.
processing.deterministic_bucket Mandatory rule result before the AI approval gate.
processing.ai_status pending, approved, review, or error for visible results. Rejected jobs are not served.
processing.completion_status complete for checked jobs, otherwise needs_review.
us_eligibility Saved geography assessment. Unknown/uncertain eligibility is not approval.
classification_reasons Allowed public deterministic reason codes; this is not an exhaustive model rationale.
fetched_at Saved observation time, when available.
date_posted Source posting date/time, when supplied; not necessarily a precise timestamp.
valid_until Original saved deadline string or null.
expires_at Normalized exclusive UTC expiry or null if absent/unrecognized.
provenance Available SHA-256 description/response hashes and public response URL. May be empty for historical records. No raw captures, cookies, or internal storage paths are exposed.
company_id Stable normalized employer-name identifier, or null for unknown employers. It is not a verified legal-entity or ownership identifier.
company_founded_year, company_is_startup, company_is_new, company_evidence Evidence-backed company attributes described below. Unknown facts are null, with no invented date.
interview_count, interview_process Evidence-backed interview information described below.

Snapshot and pagination fields

snapshot.id identifies the published view. snapshot.at is the candidate snapshot's reference timestamp, not every job's collection date or the time of the latest AI review. target_country is US. publication_stage=ai_completed means a reviewed publication is available; it does not mean every deterministic candidate finished AI processing. processing_counts, when present, reports pending, approved, rejected, review, and error work remaining/completed. These processing counts concern the publication workflow and can differ from accessible live list counts because of expiry and bucket visibility.

Policy metadata identifies the version and fingerprint used by the publication. Company metadata reports new_company_max_age_years; the configured initial value is 5. A new policy, content revision, reviewer version, or published approval set can require a new snapshot.

pagination.next_cursor is either an opaque continuation token or null. has_more indicates whether the query had another row beyond this page. Cursors expire after 24 hours and are bound to the API key identity, exact normalized filters, and snapshot. Do not decode, modify, share between clients, or treat them as stable record IDs.

6. Pagination, refreshes, and deduplication

  1. Start without cursor and choose the desired bucket and filters.
  2. Import each returned record using id as the upsert key.
  3. When next_cursor is non-null, request the next page with the same filters and that cursor. limit may remain unchanged; keeping it constant is simplest.
  4. Stop when next_cursor is null.
  5. On 409 snapshot_changed, discard the cursor and restart from page one. Keep your deduplication table; a restarted traversal can return IDs you already imported.
  6. On an invalid/expired cursor (400), start a new traversal with the intended filters.

The collector already skips known canonical jobs; client-side upserts still matter for pagination restarts and future snapshots. Stable IDs do not mean a row will stay visible forever: a job may expire or cease to meet the publication rules. If maintaining a complete mirror, compare IDs only after a successful full traversal of one snapshot; do not delete records merely because a traversal failed halfway through. There is no tombstone or incremental updated_since endpoint in this version.

7. Mandatory exclusions

The original exclusions remain active, using case-insensitive, normalized whole-word/phrase matching. Negated mentions are still excluded: a description saying that a listed condition is not required does not waive the keyword rule. Earlier saved exclusion evidence is retained when a later observation looks cleaner.

The description rules include: hybrid; onsite/on-site; security clearance; active clearance; clearance required; clearance eligible (including the supplied misspelling); ability to obtain clearance; maintain clearance; public trust; public trust clearance; top secret; in-person interview; onsite interview; in-office interview; final-round onsite; office visit required; in-person meeting required; in-person panel interview; onsite onboarding; first day onsite; and secret clearance. Relevant plural, punctuation, spacing, and supplied typo variants are normalized by the configured rules.

Excluded employer names include Leidos, GDIT/General Dynamics Information Technology, CACI, SAIC/Science Applications International Corporation, Lockheed Martin, Shopify (including shopihy), Maximus, Oracle, NVIDIA, and G2i. Employer-prefix matching uses word boundaries. Explicit source classifications as Government, Government Agency, or Government Organization are also excluded. A publicly traded company is not automatically a government organization. AI may additionally reject government affiliation when the saved description explicitly supports it; it does not use an unsupported name-based guess.

The product policy additionally excludes internship roles and every mention of the word “equity” in the configured job text/compensation fields, including benefits, diversity/equity wording, and negated mentions. The active mode is any_equity, not merely equity-only compensation. Internship titles/employment types are deterministic exclusions; description-only internship context is assessed during suitability review so a past internship requirement is not confused with the advertised role itself.

Expired jobs and jobs rejected by US geography rules are excluded. Incomplete descriptions stay separate; AI cannot promote them. Rejected/excluded records are not available through a public bucket or detail endpoint.

8. Companies: recently founded and startup are separate facts

“New company” means recently founded, not recently encountered by the scraper. The initial cutoff is five calendar years, inclusive, measured from the snapshot's year. For a 2026 snapshot, an explicitly supported founding year from 2021 through 2026 qualifies. This year-based calculation does not claim an exact founding anniversary.

company_founded_year requires an exact supporting quote from the saved description, linking a year to language such as founded, established, incorporated, or launched. A copyright year, a software release year, an employee's joining date, or the collector's first-seen timestamp is not used as a founding date. Without adequate evidence, the field and company_is_new remain null.

company_is_startup is a separate nullable assessment supported by explicit text. A recently founded company is not automatically a startup, and a startup is not automatically recently founded. new_company=false and startup=false select supported false classifications; neither filter includes unknown values.

company_evidence pairs supporting quotes with the public job URL. Name normalization joins case, punctuation, and common legal-suffix variants for stable identifiers. It does not prove two similarly named employers are the same legal entity, infer corporate ownership, or treat a shared Greenhouse/Lever URL host as the employer's own domain. Company facts are only as strong as the saved supporting text; the API does not claim a live independent company-registry check.

9. Interview process and counts

interview_process contains:

Field Meaning
steps Ordered evidence-backed steps. Each has order, type, label, and an exact supporting evidence quote.
steps[].type interview, assessment, application, or other.
interview_count Exact supported interview total, or null. The top-level interview_count mirrors it.
count_min, count_max Supported bounds when available; can be null.
status explicit, inferred, ambiguous, or not_stated. inferred denotes interpretation of supported process text, not a new external fact.
evidence Exact quoted description fragments supporting the interpretation.

Count interviews, not every hiring step. An application form, take-home assessment, background check, or offer stage does not automatically add an interview. A panel with several people is not automatically several interviews. Unknown totals stay null, never zero. Zero requires explicit evidence of no interviews. Ambiguous totals are not converted into an exact number.

The min_interviews and max_interviews filters use supported exact totals only. They omit jobs with unknown totals or only a range. Read the quotes and status when interpreting an inferred count. Source descriptions can omit, simplify, or change a hiring process after collection.

10. Freshness, provenance, and safe consumption

Collection starts a cycle every 12 hours to find jobs not previously collected, covering the 14 configured multi-source providers and then HiringCafe. Individual source refresh intervals and retry deadlines can defer a source within a cycle. Newly collected means a newly discovered canonical job, not necessarily a job posted within the last 12 hours: older unseen jobs can appear, especially when posting dates are missing or collection reaches previously unseen listings. AI review continues processing new candidates between cycles, so approved results can change before the next collection begins. API requests do not start either process.

Historical records with incomplete descriptions remain in review; the cycle does not automatically refetch every incomplete historical job.

A successful source replay/audit establishes the saved description's provenance. Available response and description hashes let you identify the exact saved text; they are not proof of current availability or an independent endorsement of the employer. Historical seed records are admitted only with registered immutable import proof. Full text is not fabricated from a short summary.

A date-only deadline includes that whole UTC calendar day and expires at the next UTC midnight. An explicitly timezone-aware deadline expires at that exact UTC instant. Missing, malformed, or timezone-less deadlines are not guessed and produce no normalized expiry. An opening can still close before a supplied deadline.

The API filters known expiries at request time. Snapshot publication does not refetch every employer website. Snapshot atomicity prevents clients from reading a half-written candidate set; it does not mean the underlying websites were observed simultaneously.

Treat titles, descriptions, evidence quotes, and external URLs as untrusted source content. Render strings safely and review external links before navigating. They are job data, not instructions for your application, an AI agent, or the maintenance worker. The API returns allowlisted fields and suppresses private capture data and credential-bearing URLs.

11. Rate limits and errors

Authenticated responses include X-RateLimit-Limit and X-RateLimit-Remaining. The default allowance is 60 requests per minute per key; the owner can configure a different value. A token bucket allows an initial burst and replenishes continuously. The limit is shared by all callers using the same key. Polling more frequently does not make collection or AI review run faster.

On 429, wait at least the integer seconds in Retry-After, add jitter when many clients retry, and use a bounded retry policy. On temporary 503, follow Retry-After as well. Do not repeatedly retry authentication, scope, or validation errors without correcting the request.

HTTP status Typical response/reason Client action
200 Successful response; an empty data list is valid. Process results.
307 / redirects to /guide. Follow the public guide redirect.
400 credentials_must_use_headers, or detail explaining an invalid/expired/mismatched cursor. Move credentials into one header; restart pagination if necessary.
401 {"error":"unauthorized"} Check the key and exactly one authentication header.
403 detail explaining unavailable review scope. Use an appropriately scoped key or request checked results.
404 Job absent from accessible unexpired listings, or unknown route. Do not assume the ID is a public job.
409 {"error":"snapshot_changed","action":"restart_pagination"} Discard the cursor and restart; deduplicate imported IDs.
422 {"error":"invalid_request"} Correct types, bounds, ID shape, filter lengths, or interview range.
429 {"error":"rate_limited"} Honor Retry-After.
503 {"error":"not_ready","stage":"suitability_review_pending"} Wait for a reviewed publication; initial Retry-After is 60 seconds.
503 {"error":"temporarily_unavailable"} Retry after the supplied delay; report persistent failures to the owner.

Error bodies use either error or detail, depending on the failure. Do not require one uniform envelope for all errors. Unexpected proxy/platform failures may not use the application's JSON format. Log status and a sanitized error code, not authentication headers, full request URLs containing accidental secrets, or database connection details.

12. Service-owner operations

Clients do not need PostgreSQL, Railway credentials, or a model-provider key. The public API service uses its own SELECT-only database role and hashed API-key configuration. Collection, audited candidate publication, and AI suitability review are separate background operations. The API itself cannot start them or write source jobs.

Production suitability analysis uses the existing ChatGPT-authenticated Codex CLI worker through a private authenticated bridge. The separate analysis worker is configured with provider codex; it does not need an OpenAI API key or OpenAI API credits for this deployment. The public API key is an independent client credential and is still required for job-data requests. Codex login credentials and bridge authentication are never exposed to API clients.

With Railway continuous mode enabled, a whole collection cycle starts every 12 hours: one multi-source run across the 14 configured providers, a ten-minute cooldown, then one HiringCafe Byparr run. Each regular phase has a collection window of up to two hours. The next whole cycle is due 12 hours after the current cycle's start, rather than 12 hours after its completion. Cycles never overlap; missed start slots are skipped without catch-up bursts. The initial deployment can use a shorter smoke phase; audits, exports, and shutdown cleanup can add time outside the collection window.

The separate suitability worker continuously processes newly published pending candidates in repeated batches through the existing private Codex bridge. The initial batch size is five with five-second polling between iterations; a batch limit is not a lifetime limit on analyzed jobs. AI review does not wait for the next 12-hour collection cycle. API traffic does not initiate collection or AI analysis.

Only one collection child runs at a time. Persistent state records its run ID, frozen settings, and cycle schedule before launch, so a restart resumes the same active run with its original deadline instead of creating a duplicate run or a fresh two-hour window. Database checks run once per deployment before collection. Failed child processes back off rather than restarting in a tight loop; finalized failed phases allow the other phase to continue. Source refresh intervals and future retry deadlines remain effective across cycles: Himalayas retains its 24-hour provider refresh, and Retry-After or HiringCafe rate-limit cooldowns can defer individual sources. A blocked source is recorded as blocked; automatic operation is not a promise that every provider will become accessible or refresh every 12 hours.

Continuous collection retains each run's new-job checked, review, and excluded CSV/JSONL exports and its audit evidence. It avoids repeatedly copying the entire historical dataset into combined and US export files after every phase. PostgreSQL and the canonical API projection still cover the complete audited history; suppressing redundant whole-history downloads does not narrow the API dataset or merge incomplete descriptions into approved results. Existing export files are retained.

For per-client key setup and rotation, see the deployment README maintained with the service. Generate a high-entropy random client key outside the source repository, securely deliver its plaintext once, and configure only its SHA-256 digest with an identifier, jobs:read, optional jobs:review, and a request limit. To rotate without downtime, add the replacement hash, deploy it, migrate the client, then remove the old entry. Revoke a compromised key promptly. Rotating the cursor-signing secret invalidates existing cursors.

Keep one API process and one service replica while using the current in-memory per-key limiter. Scaling to multiple replicas requires a shared limit implementation. The API container has no browser, collector executable, Codex credentials, or model SDK. The analysis worker communicates with the signed-in Codex worker over the private bridge; keep those credentials separate from client API keys and the API's read-only database role.

After changing policy or model/prompt versions, publish a new audited candidate view and attach only matching immutable AI decisions. Never mark pending candidates approved merely to make the API return data. Monitor provider status, review/error/pending counts, source audits, database health, and data freshness separately from /healthz. Use https://api.jobscanner.top as the canonical client base URL and retain the Railway address as a fallback. Monitor the custom domain's DNS and HTTPS availability, and communicate any base-URL changes to clients.