API Reference

This is the provider-suspended jobcache/interface Core compatibility API. It is not the session-private App API and must not acquire new App state. The target public/session route table lives in jobcache/api/README.md.

Read endpoints (public)

`GET /api/postings?q=<text>&limit=<n>`

Search the shared ad set for postings matching the query string. Returns up to limit results (default 25, max 100).

curl 'https://jobcache.corbet.ch/api/postings?q=staff+engineer&limit=10'

`GET /api/search?q=<text>&limit=<n>&offset=<n>`

Legacy ad-shaped search and browse. This remains public for compatibility; product edges should use the authenticated Core contract below.

`GET /healthz`

Liveness check. Returns { ok: true, ... } on a healthy instance.

`GET /metrics`

Prometheus text format. Used by status.jobcache.corbet.ch and ops.jobcache.corbet.ch. Public.

Internal and mutation endpoints (bearer-token protected)

The general routes use Authorization: Bearer <JOBCACHE_CONTROL_TOKEN>. Participant lifecycle routes name their narrower credentials below. Do not embed any of these credentials in browser apps.

`POST /api/corpus/search`

Strict cross-product role search. CareerVector sends a validated shared request and receives a content-addressed immutable snapshot with execution provenance. This route is protected even though it reads data because it is an internal product boundary; GET /api/search remains the public compatibility surface.

`GET /api/ads/lookup?url=<ad-url>`

Look up a posting by its original ad URL. Returns the cached posting if JobCache has seen it, or 404 if not.

curl -H "Authorization: Bearer $JOBCACHE_CONTROL_TOKEN" \
  'https://jobcache.corbet.ch/api/ads/lookup?url=https://example.com/jobs/123'

`POST /api/ads/resolve`

Resolves a partially-known ad into a full posting. Used by careervector-api when a workspace imports a new job URL.

`POST /api/commands/drain`

Drains pending control commands.

`POST /api/corpus/erasures/drain?max=<n>`

Runs one bounded, manual CareerVector-to-Core erasure pass. The request uses the normal JOBCACHE_CONTROL_TOKEN; JobCache then claims the canonical erasure outbox with its separate JOBCACHE_CORPUS_WORKER_TOKEN, writes durable Core tombstones, and acknowledges only verified Core receipts. A failed item stays claimable. The outbound base URL must use HTTPS except for loopback development. There is deliberately no automatic interval.

`POST /api/corpus/participants/erase`

Applies one canonical CorpusParticipantErasure directly. This narrower lifecycle boundary uses JOBCACHE_CORPUS_LIFECYCLE_TOKEN, not the general control token, and returns a pseudonym-free CorpusParticipantErasureReceipt. All configured Core bearers require at least 24 characters and must be pairwise different; misconfiguration fails closed before route work begins.

MCP

The agent surface is the standalone jobcache/mcp/ Worker over the session-private jobcache/api/ App boundary. It mirrors public reads and explicit link-capability operations without holding a Core bearer. Both are live Cloudflare Workers. The separate jobcache/ui/ Worker consumes the same App boundary and adds no API route or credential.