Job Search API v1

La v1 tiene dos endpoints públicos. Usa /public/search para encontrar empleos públicos con una consulta y filtros opcionales. Usa /public/usage para consultar tu cuota diaria restante sin gastarla. El contrato OpenAPI se sirve en /public/openapi.json.

Envía tu clave de API con el encabezado x-api-key o como un token Authorization: Bearer. Las claves pertenecen a una organización; los propietarios y administradores las gestionan en la app en Perfil > Developer API, y quienes buscan empleo también pueden crear una. Las claves en texto plano se muestran una sola vez al crearlas y CazVid las almacena solo como hash. Trata las claves como secretos: no las pongas en código de frontend, apps móviles, capturas de pantalla, registros ni mensajes de soporte. El mismo formato de clave (cazvid_jb_...) sirve para todas las familias de la CazVid Developer API; cada clave lleva solo los alcances que permite tu plan.

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

POST /public/search recibe un query opcional y filtros estructurados opcionales. Envía query en lenguaje natural (por ejemplo 'empleos de almacén en Bogotá'), u omítelo para explorar solo con filtros. Envía page y pageSize para paginar; pageSize está limitado a 25 y page a 100. Las solicitudes por encima de esos límites devuelven 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
  }'

Cada resultado es un empleo público. Los campos anulables se omiten o son null cuando CazVid no tiene ese dato. Cuando están presentes, slug identifica el empleo en cazvid.com y applyUrl es la página canónica del empleo por la que se postula la persona (https://cazvid.com/job/<slug>, o /empleo/<slug> en español); ambos son null para un empleo sin página pública. Nunca se incluyen ids de plataforma sin procesar ni campos de contacto.

{
  "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
}

La respuesta envuelve los resultados con metadatos de paginación. Esta API pagina solo con hasMore - no hay un conteo total.

• jobs - los empleos de esta página.
• hasMore - true cuando existe otra página. Solicita la siguiente incrementando page.
• page - el número de página (base 1) devuelto.
• pageSize - el tamaño de página devuelto.
• No hay campo de conteo total. No esperes un total ni un count: sigue solicitando páginas mientras hasMore sea true.

GET /public/usage devuelve la cuota diaria de Job Search de la organización que llama. Usa la misma autenticación que la búsqueda y no cuenta para la cuota, así que puedes consultarlo antes de un lote para evitar respuestas 429. Las consultas están limitadas a 60 solicitudes por minuto por clave de API; al excederlo se devuelve la forma estándar de 429 con details.period en 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"
}

Las respuestas de error usan valores errorCode estables para que las integraciones no tengan que analizar mensajes de texto. Cada error devuelve el path de la solicitud; las respuestas 429 añaden retryAfter, el número de segundos hasta que se reinicia la ventana del límite. Un 429 de la cuota diaria lleva details.period utc_day; un 429 del límite por minuto o del límite de consultas de uso lleva minute; un 429 del backstop por IP lleva minute con details.scope en 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"
}

Los empleos se proporcionan para atender la búsqueda de empleo del usuario final que tienes enfrente, no para copiarse ni revenderse. Al usar esta API aceptas lo siguiente. Estos términos pueden ser reemplazados por términos formales de la API cuando la API pase a disponibilidad general.

• Sin duplicación masiva ni redistribución. No copies el índice de empleos a tu propio almacén ni construyas una bolsa de empleo o conjunto de datos competidor a partir de él.
• Sin retención más allá de atender la solicitud. Conserva los resultados solo el tiempo necesario para responder la búsqueda que tienes enfrente; no construyas una copia persistente del índice de empleos.
• Sin reventa. Los empleos y cualquier campo derivado de ellos no pueden venderse, sublicenciarse ni redistribuirse.
• Postúlate a través de CazVid. Envía a quienes buscan empleo al applyUrl en cazvid.com; no hagas scraping para evitarlo ni redirijas las postulaciones fuera de la plataforma.
• Sin evasión de la cuota. No uses varias claves, organizaciones ni cuentas para evadir la cuota diaria por organización, el límite por minuto ni el backstop por IP.

• La cuota de la v1 es de 500 llamadas exitosas a search por organización por día UTC. El alcance de job-search es gratuito y está separado de las cuotas de Job Builder y Candidate Search.
• Un límite por organización de 30 búsquedas por minuto, más un backstop por IP de 60 por minuto, protege el backend de búsqueda compartido. Al exceder cualquiera se devuelve 429 con details.period en minute (el bloqueo por IP añade details.scope en ip).
• pageSize está limitado a 25 y page a 100. Las solicitudes por encima de esos límites devuelven 400 VALIDATION_ERROR.
• Los resultados son empleos públicos. Incluyen un applyUrl y un slug cuando el empleo tiene página pública, pero ningún dato de contacto del reclutador ni ids de plataforma sin procesar.
• Rota las claves creando una clave nueva, actualizando tu integración y luego revocando la anterior. Cada organización puede tener hasta 10 claves activas en todas las familias.

¿Prefieres controlar la búsqueda de empleo desde un agente de IA en vez de HTTP directo? El servidor MCP de CazVid expone search_jobs (además de list_api_usage) a Claude Code, Claude.ai, ChatGPT, Cursor y VS Code, con esta misma clave de API y cuota diaria.