Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Esteban-Mendez-j/Proyecto-Docker/llms.txt

Use this file to discover all available pages before exploring further.

The vacancies API lets companies publish and manage job postings while giving candidates and guests the ability to browse, search, and filter active openings. All write operations require a valid company session cookie. Read operations that benefit from personalisation accept an optional token to tailor results through the ML prediction model.

​
VacanteDTO fields

Every vacancy is represented by a VacanteDTO object with the following fields.
​
nvacantes
integer
Unique vacancy ID.
​
titulo
string
required
Job posting title. Max 100 characters.
​
cargo
string
required
Job position or role name. Max 50 characters.
​
tipo
string
required
Contract type (e.g. "Tiempo completo", "Prácticas"). Max 15 characters.
​
modalidad
string
required
Work modality (e.g. "Presencial", "Remoto", "Híbrido"). Max 50 characters.
​
ciudad
string
required
City where the vacancy is located. Max 50 characters.
​
departamento
string
required
Department or state. Max 50 characters.
​
sueldo
number
Monthly salary offered.
​
experiencia
string
Required years of experience (e.g. "2"). Max 4 characters.
​
descripcion
string
Full vacancy description. Max 400 characters.
​
requerimientos
string
Candidate requirements. Max 400 characters.
​
aptitudes
string[]
List of desired skills.
​
videoLink
string
Path to an optional presentation video file.
​
fechaPublicacion
string (ISO date)
Date the vacancy was published (YYYY-MM-DD).
​
isActive
boolean
Whether the vacancy is currently active system-wide.
​
activaPorEmpresa
boolean
Whether the company has toggled the vacancy on.
​
idUsuario
integer
ID of the company user that owns this vacancy.
​
nameEmpresa
string
Display name of the owning company.
​
imagenEmpresa
string
Profile image URL of the owning company.
​
totalpostulaciones
integer
Total number of applications ever submitted.
​
nPostulados
integer
Current active applicant count.
​
candidatoPostulado
boolean
Whether the authenticated candidate has an active application for this vacancy.
​
estadoPostulacion
string
The authenticated candidate’s application status for this vacancy.
​
vacanteGuardada
boolean
Whether the authenticated candidate has saved this vacancy. Defaults to false.
​
numeroGuardadosFavoritos
integer
Total number of times this vacancy has been saved by candidates.
​
numCompartidos
integer
Number of times the vacancy has been shared.
​
visitas
integer
Total visit/view count. Defaults to 0.
​
prediccion
number
ML match score between the authenticated candidate and this vacancy. Defaults to 0.0.
​
comentarioAdmin
string
Administrative note attached to the vacancy.

​
FiltroVacanteDTO fields

Filter bodies sent to the /listar endpoints use the following fields (all optional unless otherwise noted).
​
titulo
string
Filter by posting title (partial match).
​
cargo
string
Filter by position name.
​
tipo
string
Filter by contract type.
​
modalidad
string
Filter by work modality.
​
ciudad
string
Filter by city.
​
experiencia
string
Filter by required years of experience.
​
sueldo
number
Minimum salary filter.
​
nameEmpresa
string
Filter by company name.
​
fechaPublicacion
string (ISO date)
Filter vacancies published on or after this date.
​
isActive
boolean
Filter by active state. Set automatically to true for the public filtered listing.
​
activaPorEmpresa
boolean
Filter by the company’s own active toggle.
​
estadoPostulacion
string
Filter by the candidate’s application status on each vacancy.
​
isFavorita
boolean
When true, returns only vacancies the candidate has saved.
​
video
boolean
When true, returns only vacancies that have a video. Defaults to false.

​
Endpoints

​
List own vacancies

Returns the paginated list of vacancies created by the authenticated company. 
GET /api/vacantes
Requires a valid jwtToken cookie belonging to a company account.
Query parameters
​
page
integer
default:"0"
Zero-based page number.
​
size
integer
default:"10"
Number of results per page.
Response 
{
  "content": [ /* VacanteDTO[] */ ],
  "totalElements": 42,
  "totalPages": 5,
  "number": 0,
  "size": 10
}
Example 
curl -X GET "https://api.searchjobs.dev/api/vacantes?page=0&size=10" \
  -H "Cookie: jwtToken=<token>"

​
Filter own vacancies

Returns the authenticated company’s vacancies that match the supplied filter criteria. 
POST /api/vacantes/listar
Requires a valid jwtToken cookie belonging to a company account.
Query parameters
​
page
integer
default:"0"
Zero-based page number.
​
size
integer
default:"10"
Number of results per page.
Request body — application/json — FiltroVacanteDTO 
{
  "titulo": "Desarrollador",
  "modalidad": "Remoto",
  "ciudad": "Bogotá",
  "tipo": "Tiempo completo",
  "experiencia": "2",
  "sueldo": 3000000,
  "activaPorEmpresa": true,
  "video": false
}
Response — paginated map identical to GET /api/vacantes. Example 
curl -X POST "https://api.searchjobs.dev/api/vacantes/listar?page=0&size=10" \
  -H "Cookie: jwtToken=<token>" \
  -H "Content-Type: application/json" \
  -d '{"modalidad":"Remoto","ciudad":"Bogotá"}'

​
Filter all active vacancies

Returns active vacancies for candidates and guests. When the requester is an authenticated candidate with a complete profile (nivelEducativo, aptitudes, and experiencia all set), results are re-ranked by the ML prediction score. Otherwise results are returned in standard order. 
POST /api/vacantes/listar/filtradas
The jwtToken cookie is optional. When omitted, the caller is treated as a guest and personalised ranking is disabled.
Query parameters
​
page
integer
default:"0"
Zero-based page number.
​
size
integer
default:"10"
Number of results per page.
Request body — application/json — FiltroVacanteDTO 
{
  "titulo": "Diseñador",
  "ciudad": "Medellín",
  "modalidad": "Híbrido",
  "isFavorita": false
}
Response — paginated map. Each VacanteDTO item includes a prediccion score when ML ranking is active. Example 
curl -X POST "https://api.searchjobs.dev/api/vacantes/listar/filtradas" \
  -H "Cookie: jwtToken=<candidate-token>" \
  -H "Content-Type: application/json" \
  -d '{"ciudad":"Medellín"}'
Returns a curated list of vacancies sorted by publication date, salary, and required experience. Suitable for a homepage featured section. 
GET /api/vacantes/Top/listar
The jwtToken cookie is optional. When provided, the authenticated user’s ID is forwarded to the service for potential personalisation.
Response 
{
  "vacantes": [ /* VacanteDTO[] */ ]
}
Example 
curl -X GET "https://api.searchjobs.dev/api/vacantes/Top/listar"
Returns the company’s own vacancies ranked by total application count. 
GET /api/vacantes/popular/listar
Requires a valid jwtToken cookie belonging to a company account.
Response 
{
  "vacantes": [ /* VacanteDTO[] */ ]
}
Example 
curl -X GET "https://api.searchjobs.dev/api/vacantes/popular/listar" \
  -H "Cookie: jwtToken=<company-token>"

​
Get vacancy details

Returns the full details of a single vacancy. When the requester is an authenticated candidate, the response includes candidate-specific fields (candidatoPostulado, estadoPostulacion, vacanteGuardada, prediccion). 
GET /api/vacantes/seleccion/{nvacantes}
The jwtToken cookie is optional.
Path parameters
​
nvacantes
integer
required
Vacancy ID.
Response 
{
  "vacanteSeleccionada": { /* VacanteDTO */ }
}
Returns 404 with { "mensaje": "Vacante no encontrada" } if the ID does not exist. Example 
curl -X GET "https://api.searchjobs.dev/api/vacantes/seleccion/7" \
  -H "Cookie: jwtToken=<candidate-token>"

​
Create vacancy

Creates a new vacancy associated with the authenticated company. Accepts multipart/form-data so that an optional promotional video can be uploaded at the same time. 
POST /api/vacantes/add
Requires a valid jwtToken cookie belonging to a company account.
Request parts — multipart/form-data
​
vacante
JSON (VacanteDTO)
required
Vacancy data serialised as JSON. Required fields: titulo, cargo, tipo, modalidad, ciudad, departamento.
​
video
file
Optional promotional video file. When provided, the server stores it and sets videoLink on the vacancy.
Response 
{
  "status": 201,
  "mensaje": "Tiempo completo creada con exito!"
}
On error: 
{
  "status": 400,
  "mensaje": "Error al Crear la vacante."
}
Example 
curl -X POST "https://api.searchjobs.dev/api/vacantes/add" \
  -H "Cookie: jwtToken=<company-token>" \
  -F 'vacante={"titulo":"Backend Developer","cargo":"Desarrollador","tipo":"Tiempo completo","modalidad":"Remoto","ciudad":"Bogotá","departamento":"Cundinamarca"};type=application/json' \
  -F "video=@promo.mp4"

​
Get vacancy for editing

Returns the raw vacancy data by ID for pre-populating an edit form. 
GET /api/vacantes/edit/{nvacantes}
Path parameters
​
nvacantes
integer
required
Vacancy ID.
Response — VacanteDTO object directly.

​
Update vacancy

Updates an existing vacancy. Accepts multipart/form-data to allow replacing or removing the promotional video. 
PUT /api/vacantes/edit/{nvacantes}
Path parameters
​
nvacantes
integer
required
Vacancy ID to update.
Request parts — multipart/form-data
​
vacante
JSON (VacanteDTO)
required
Updated vacancy data.
​
video
file
Optional new video file. If provided and a video already exists, the previous file is deleted before saving the new one.
​
eliminarVideo
boolean
When true, removes the current video without uploading a replacement.
Response 
{
  "status": 201,
  "mensaje": "Vacante actualizada con éxito!"
}
Example 
curl -X PUT "https://api.searchjobs.dev/api/vacantes/edit/7" \
  -H "Cookie: jwtToken=<company-token>" \
  -F 'vacante={"titulo":"Senior Backend Developer","cargo":"Desarrollador Senior","tipo":"Tiempo completo","modalidad":"Remoto","ciudad":"Bogotá","departamento":"Cundinamarca"};type=application/json' \
  -F "eliminarVideo=true"

​
Toggle vacancy active state

Activates or deactivates a vacancy. 
PUT /api/vacantes/estado/{idVacante}
Path parameters
​
idVacante
integer
required
Vacancy ID.
Query parameters
​
estado
boolean
required
Pass true to activate, false to deactivate.
Response — 200 OK with empty body. Example 
curl -X PUT "https://api.searchjobs.dev/api/vacantes/estado/7?estado=false" \
  -H "Cookie: jwtToken=<company-token>"

​
Increment share counter

Increments the numCompartidos counter by one each time a vacancy is shared. 
PUT /api/vacantes/edit/numCompartidos/{idVacante}
Path parameters
​
idVacante
integer
required
Vacancy ID.
Response — 200 OK with empty body.

​
Register a visit

Increments the visit counter for a vacancy each time it is viewed. 
POST /api/vacantes/visita/{nvacantes}
Path parameters
​
nvacantes
integer
required
Vacancy ID.
Response — 200 OK with empty body.

​
Autocomplete suggestions

Returns a list of title/cargo strings that match the supplied prefix. Useful for powering a search autocomplete widget. 
GET /api/vacantes/sugerencias
Query parameters
​
query
string
required
The search prefix. An empty string returns an empty array.
Response — string[] 
["Desarrollador Backend", "Desarrollador Frontend", "Desarrollador Fullstack"]
Example 
curl "https://api.searchjobs.dev/api/vacantes/sugerencias?query=desa"

Build docs developers (and LLMs) love

Get started for freeTalk to us