Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DincaAlex/unilink/llms.txt

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

The Jobs API exposes three endpoints for working with internship listings in UniLink. You can retrieve the full catalogue of postings, fetch a single offer by its ID, or — if you are authenticated as an empresa account — publish a brand-new listing. Internally, requirements, benefits, and skills are stored as JSON strings in SQLite and are automatically parsed into arrays before being returned.

​
GET /api/jobs

Returns every job listing in the database, ordered by id ascending. This endpoint accepts no query parameters or request body.

​
Response

A JSON array of job objects. Each object contains the following fields:
​
id
number
Auto-assigned primary key for the listing.
​
title
string
Job title, e.g. "Asistente de Investigación — IA".
​
company
string
Employer name and optional department, e.g. "UNMSM · Ing. Sistemas".
​
location
string
Human-readable city and modality string, e.g. "Lima, Presencial".
​
type
string
Whether the internship is internal to the university or external. One of interna or externa.
​
modality
string
Work modality. One of Presencial, Híbrido, or Remoto.
​
area
string
Professional area of the role, e.g. "Tecnología" or "Administración".
​
salary
string
Display string for the monthly stipend, e.g. "S/ 1,200 / mes".
​
salaryNum
number
Numeric value of the monthly salary in Peruvian soles, used for filtering and sorting.
​
posted
string
Human-readable relative posting date, e.g. "Hace 3 días".
​
daysAgo
number
Number of days since the listing was published.
​
deadline
string
Application deadline in YYYY-MM-DD format.
​
duration
string
Length of the internship, e.g. "3 meses".
​
hoursPerWeek
number
Required hours per week.
​
status
string
Current listing status. One of abierto, por_cerrar, or cerrado.
​
initials
string
Two-letter initials used for the company avatar, e.g. "TC".
​
color
string
Hex color code for the company avatar background, e.g. "#4f46e5".
​
description
string
Full plain-text description of the role and responsibilities.
​
requirements
string[]
List of candidate requirements, e.g. ["Cursando 6to semestre o más"].
​
benefits
string[]
List of benefits offered, e.g. ["Constancia de prácticas"].
​
skills
string[]
Technical or soft skills expected, e.g. ["Python", "Machine Learning"].
​
applicants
number
Number of students who have applied to this listing.
​
postedBy
string
Email address of the empresa account that created the listing.

​
Example request

curl http://localhost:3001/api/jobs

​
Example response

[
  {
    "id": 1,
    "title": "Asistente de Investigación — IA",
    "company": "UNMSM · Ing. Sistemas",
    "location": "Lima, Presencial",
    "type": "interna",
    "modality": "Presencial",
    "area": "Tecnología",
    "salary": "S/ 1,200 / mes",
    "salaryNum": 1200,
    "status": "abierto",
    "requirements": ["Cursando 6to semestre o más"],
    "benefits": ["Constancia de prácticas"],
    "skills": ["Python", "Machine Learning"]
  }
]

​
GET /api/jobs/:id

Returns the full details of a single job listing identified by its numeric id.

​
Path parameter

​
id
number
required
The integer ID of the job listing to retrieve.

​
Response

Returns the matching job object (same shape as a single element from GET /api/jobs) on success, or a 404 error if no listing exists with the given ID.
​
error
string
Present only on a 404 response. Value: "Oferta no encontrada."

​
Example request

curl http://localhost:3001/api/jobs/1

​
Error response (404)

{
  "error": "Oferta no encontrada."
}

​
POST /api/jobs

Creates a new internship listing. The request must include the header x-role: empresa; any other value — or omitting the header entirely — returns a 403 Forbidden error.
This endpoint is restricted to empresa accounts. Requests without the x-role: empresa header will be rejected with HTTP 403.

​
Request body

​
title
string
required
Job title for the listing.
​
company
string
required
Employer name and optional department, formatted as "Name · Department".
​
location
string
required
City and modality string shown in the feed card, e.g. "Lima, Remoto".
​
type
string
required
Internship type: interna for university-published roles, externa for company-published roles.
​
modality
string
required
Work modality: Presencial, Híbrido, or Remoto.
​
area
string
required
Professional area of the role, e.g. "Tecnología".
​
salary
string
required
Human-readable salary string, e.g. "S/ 1,500 / mes".
​
salaryNum
number
required
Numeric monthly salary in soles, used for filtering.
​
deadline
string
required
Application deadline in YYYY-MM-DD format.
​
duration
string
required
Duration of the internship, e.g. "3 meses".
​
hoursPerWeek
number
required
Weekly hour commitment.
​
description
string
required
Full description of the role and its responsibilities.
​
requirements
string[]
required
Array of candidate requirement strings.
​
benefits
string[]
required
Array of benefit strings offered to the intern.
​
skills
string[]
required
Array of required or desired skills.

​
Response

Returns 201 Created with the newly created job object, including the server-generated id.

​
Example request

curl -X POST http://localhost:3001/api/jobs \
  -H "Content-Type: application/json" \
  -H "x-role: empresa" \
  -d '{
    "title": "Practicante Frontend",
    "company": "TechCorp SAC",
    "location": "Lima, Remoto",
    "type": "externa",
    "modality": "Remoto",
    "area": "Tecnología",
    "salary": "S/ 1,500 / mes",
    "salaryNum": 1500,
    "posted": "Hace 0 días",
    "daysAgo": 0,
    "deadline": "2025-08-31",
    "duration": "3 meses",
    "hoursPerWeek": 20,
    "status": "abierto",
    "initials": "TC",
    "color": "#4f46e5",
    "description": "Desarrollo de interfaces React.",
    "requirements": ["React básico"],
    "benefits": ["Laptop corporativa"],
    "skills": ["React", "CSS"],
    "applicants": 0,
    "postedBy": "maria.fernandez@talenthub.pe"
  }'

​
Example response (201 Created)

{
  "id": 15,
  "title": "Practicante Frontend",
  "company": "TechCorp SAC",
  "location": "Lima, Remoto",
  "type": "externa",
  "modality": "Remoto",
  "area": "Tecnología",
  "salary": "S/ 1,500 / mes",
  "salaryNum": 1500,
  "posted": "Hace 0 días",
  "daysAgo": 0,
  "deadline": "2025-08-31",
  "duration": "3 meses",
  "hoursPerWeek": 20,
  "status": "abierto",
  "initials": "TC",
  "color": "#4f46e5",
  "description": "Desarrollo de interfaces React.",
  "requirements": ["React básico"],
  "benefits": ["Laptop corporativa"],
  "skills": ["React", "CSS"],
  "applicants": 0,
  "postedBy": "maria.fernandez@talenthub.pe"
}

​
Error response (403 Forbidden)

{
  "error": "Esta acción requiere una cuenta de empresa."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us