Job Search API v1

V1 has two public endpoints. Use /public/search to find public job posts with a query plus optional filters. Use /public/usage to check your remaining daily quota without spending it. The OpenAPI contract is served at /public/openapi.json.

Send your API key with the x-api-key header or as an Authorization: Bearer token. Keys belong to an organization; org owners and admins manage them in the app under Profile > Developer API, and job seekers can create one too. Plaintext keys are shown once when created and stored hash-only by CazVid. Treat keys as secrets: do not put them in frontend code, mobile apps, screenshots, logs, or support messages. The same key format (cazvid_jb_...) serves every CazVid Developer API family; each key carries only the scopes your plan allows.

x-api-key: cazvid_jb_...
Authorization: Bearer cazvid_jb_...
Content-Type: application/json

POST /public/search takes an optional query plus optional structured filters. Send query in plain language (for example 'warehouse jobs in Bogota'), or leave it out to browse by filters alone. Send page and pageSize to page through results; pageSize is capped at 25 and page at 100. Requests above those bounds return 400 VALIDATION_ERROR.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/job-search/public/search \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "warehouse jobs in Bogota",
    "location": "Bogota, Colombia",
    "remote": false,
    "language": "es",
    "page": 1,
    "pageSize": 10
  }'

Each result is a public job post. Nullable fields are omitted or null when CazVid does not have that data. When present, slug identifies the job on cazvid.com and applyUrl is the canonical job page a seeker applies through (https://cazvid.com/job/<slug>, or /empleo/<slug> in Spanish); both are null for a job with no public page. No raw platform ids and no contact fields are ever included.

{
  "jobs": [
    {
      "title": "Warehouse Operator",
      "description": "Join our Bogota distribution center as a warehouse operator...",
      "companyName": "Andes Logistics",
      "authorName": "Andes Logistics HR",
      "jobType": "full-time",
      "typeOfWork": "on-site",
      "isRemote": false,
      "remoteWorkScope": null,
      "locationName": "Bogota, Colombia",
      "locationCountryCode": "CO",
      "payAmount": 1800000,
      "payCurrency": "COP",
      "payType": "monthly",
      "isNegotiable": false,
      "language": "es",
      "occupationTitles": ["Warehouse Operator", "Logistics Assistant"],
      "occupationFamilies": ["Transportation and Logistics"],
      "createdAt": "2026-07-01T12:30:00.000Z",
      "refreshedAt": "2026-07-08T09:00:00.000Z",
      "slug": "warehouse-operator-bogota-andes-logistics",
      "applyUrl": "https://cazvid.com/empleo/warehouse-operator-bogota-andes-logistics",
      "videoUrl": "https://ik.imagekit.io/cazvid/videos/example.mp4",
      "thumbnailUrl": "https://ik.imagekit.io/cazvid/thumbs/example.jpg"
    }
  ],
  "hasMore": true,
  "page": 1,
  "pageSize": 10
}

The response wraps the results with pagination metadata. This API paginates on hasMore only - there is no total count.

• jobs - the job posts for this page.
• hasMore - true when another page exists. Request the next page by incrementing page.
• page - the echoed 1-based page number.
• pageSize - the echoed page size.
• There is no total-count field. Do not expect a total or count: keep requesting pages while hasMore is true.

GET /public/usage returns the calling organization's daily Job Search quota. It uses the same authentication as search and does not count against the quota, so you can poll it before a batch to avoid 429 responses. Polling is throttled to 60 requests per minute per API key; exceeding it returns the standard 429 shape with details.period set to minute.

curl https://aio-backend-prod.cazvid.app/api/v3.0/job-search/public/usage \
  -H "x-api-key: cazvid_jb_..."

{
  "dailyQuota": 500,
  "used": 12,
  "remaining": 488,
  "resetsAt": "2026-07-11T00:00:00.000Z",
  "period": "utc_day"
}

Error responses use stable errorCode values so integrations do not need to parse prose messages. Every error echoes the request path; 429 responses add retryAfter, the number of seconds until the limit window resets. A 429 from the daily quota carries details.period of utc_day; a 429 from the per-minute burst or usage throttle carries minute; a 429 from the per-IP backstop carries minute with details.scope of ip.

{
  "statusCode": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message": "Daily Job Search API quota exceeded.",
  "details": {
    "limit": 500,
    "period": "utc_day"
  },
  "retryAfter": 21600,
  "path": "/api/v3.0/job-search/public/search"
}

Job posts are provided to serve the end user's job search in front of you, not to be copied or resold. By using this API you agree to the following. These terms may be replaced by formal API terms at general availability.

• No bulk mirroring or redistribution. Do not copy the job index into your own store or build a competing job board or dataset from it.
• No retention beyond serving the request. Hold results only as long as needed to answer the search in front of you; do not build a persistent shadow copy of the job index.
• No resale. Job posts and any fields derived from them may not be sold, sublicensed, or redistributed.
• Apply through CazVid. Send seekers to the applyUrl on cazvid.com; do not scrape around it or redirect applications off-platform.
• No quota circumvention. Do not use multiple keys, organizations, or accounts to evade the per-organization daily quota, the per-minute burst limit, or the per-IP backstop.

• V1 quota is 500 successful search calls per organization per UTC day. The job-search scope is free and separate from the Job Builder and Candidate Search quotas.
• A per-organization burst limit of 30 searches per minute, plus a 60-per-minute per-IP backstop, protects the shared search backend. Exceeding either returns 429 with details.period set to minute (the per-IP block adds details.scope of ip).
• pageSize is capped at 25 and page at 100. Requests above those bounds return 400 VALIDATION_ERROR.
• Results are public job posts. They carry an applyUrl and slug when the job has a public page, but no hiring-manager contact details and no raw platform ids.
• Rotate keys by creating a new key, updating your integration, then revoking the old key. Each organization can hold up to 10 active keys across all families.

Prefer to drive job search from an AI agent instead of raw HTTP? The CazVid MCP server exposes search_jobs (plus list_api_usage) to Claude Code, Claude.ai, ChatGPT, Cursor, and VS Code, using this same API key and daily quota.