Job Builder API v1

La v1 tiene tres endpoints públicos. Usa /public/generate cuando solo necesites una vista previa. Usa /public/jobs cuando quieras que CazVid cree un registro de empleo real. Usa /public/usage para consultar tu cuota diaria restante sin gastarla.

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 y pueden limitarse a uno o más workspaces. 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.

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

Las llamadas de vista previa no escriben registros de empleo. Devuelven un DTO público normalizado que tu integración puede inspeccionar antes de crear un borrador o publicar.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/job-builder/public/generate \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Looking for a remote customer support specialist in Mexico",
    "language": "en",
    "organizationId": "ORG_ID",
    "workspaceId": "WORKSPACE_ID",
    "includeDescription": true
  }'

El endpoint jobs siempre genera los detalles y la descripción. Las preguntas de filtro se omiten en la v1. Los empleos Premium y Premium+ permanecen en la app porque dependen del flujo de pago.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/job-builder/public/jobs \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Looking for a bilingual customer support specialist in Mexico",
    "language": "en",
    "organizationId": "ORG_ID",
    "workspaceId": "WORKSPACE_ID",
    "publishMode": "draft"
  }'

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/job-builder/public/jobs \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Looking for a bartender in Monterrey",
    "language": "en",
    "organizationId": "ORG_ID",
    "workspaceId": "WORKSPACE_ID",
    "publishMode": "publish"
  }'

Las respuestas de borrador y publicación incluyen el id del post creado, el modo de publicación, el estado del empleo, completePost, jobBuilderProgress y el DTO público del empleo generado. Los borradores conservan jobBuilderProgress para retomarlos en la app; al publicar se pone en null. Los empleos publicados también incluyen listId cuando se crea la lista de empleos (los borradores devuelven listId null).

{
  "postId": "POST_ID",
  "listId": "LIST_ID",
  "publishMode": "publish",
  "status": "pending",
  "completePost": true,
  "jobBuilderProgress": null,
  "job": {
    "title": "Bartender",
    "language": "en",
    "description": "<p>Generated job description...</p>",
    "workMode": {
      "type": "onsite",
      "scope": null,
      "countryCode": "MX",
      "countryName": "Mexico",
      "city": "Monterrey",
      "region": "Nuevo Leon",
      "displayName": "Monterrey, Nuevo Leon, Mexico",
      "geoNameId": "3995465",
      "coordinates": {
        "longitude": -100.3161,
        "latitude": 25.6866
      }
    },
    "salary": {
      "low": 8000,
      "recommended": 10000,
      "high": 12000,
      "period": "monthly",
      "currency": "MXN",
      "currencySymbol": "MX$",
      "negotiable": false,
      "additionalCompensation": []
    },
    "primaryEmploymentType": "fullTime",
    "employmentTypes": ["fullTime", "partTime"],
    "categories": [
      {
        "id": "CATEGORY_ID",
        "name": "Food Service",
        "primary": true
      }
    ],
    "education": ["High School Diploma or equivalent"],
    "skills": ["Customer service", "Attention to detail"]
  }
}

Envía un encabezado opcional Idempotency-Key en POST /public/jobs para que la creación de empleos sea segura de reintentar. La clave tiene de 1 a 255 caracteres ASCII visibles. La misma clave con el mismo cuerpo de solicitud repite la respuesta almacenada (con un encabezado de respuesta Idempotency-Replayed: true) sin crear un segundo empleo y sin consumir cuota - el reintento aún debe pasar el límite diario, así que una repetición intentada cuando la organización está en su tope diario devuelve 429 RATE_LIMIT_EXCEEDED. Las repeticiones están disponibles durante 24 horas después de que la solicitud original se completa; después de eso la clave se comporta como nueva. La misma clave con un cuerpo diferente devuelve 422 IDEMPOTENCY_KEY_REUSED. Un duplicado concurrente que llega mientras el primero aún se procesa devuelve 409 IDEMPOTENCY_IN_PROGRESS; una solicitud inconclusa retiene la clave como máximo 10 minutos, así que los 409 se resuelven dentro de ese límite. Un encabezado con formato inválido devuelve 400 IDEMPOTENCY_KEY_INVALID. Si el almacén de idempotencia no está disponible, la solicitud no se procesa y devuelve 503 IDEMPOTENCY_STORE_UNAVAILABLE con el cupo de cuota reembolsado - reintenta con la misma clave.

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/job-builder/public/jobs \
  -H "x-api-key: cazvid_jb_..." \
  -H "Idempotency-Key: 7c9e6a2f-unique-per-job-intent" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Looking for a bartender in Monterrey",
    "language": "en",
    "organizationId": "ORG_ID",
    "workspaceId": "WORKSPACE_ID",
    "publishMode": "publish"
  }'

GET /public/usage devuelve la cuota diaria de Job Builder de la organización que llama. Usa la misma autenticación que los demás endpoints 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-builder/public/usage \
  -H "x-api-key: cazvid_jb_..."

{
  "dailyQuota": 10,
  "used": 3,
  "remaining": 7,
  "resetsAt": "2026-07-07T00: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 el día UTC.

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

• La cuota de la v1 es de 10 llamadas exitosas a generate o jobs por organización por día UTC.
• publishMode: "publish" crea únicamente empleos estándar. Premium y Premium+ permanecen en la app en la v1.
• Los empleos publicados entran en el pipeline existente de CazVid de pendiente y aprobación. La API no marca directamente los empleos como aprobados.
• Rota las claves creando una clave nueva, actualizando tu integración y luego revocando la clave anterior.

¿También usas la Candidate Search API? Revisa sus términos de uso aceptable.

¿Prefieres controlar Job Builder desde un agente de IA en vez de HTTP directo? El servidor MCP de CazVid expone preview_job y create_job (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.