peviitor API

Platformă de descoperire a joburilor — documentație API publică

https://api.peviitor.ro

Această pagină expune endpoint-uri publice ale API-ului peviitor.ro, o platformă de descoperire a joburilor. Suntem în proces de revizuire și extindere a API-ului, iar documentația se va îmbunătăți treptat.

Endpoint-uri disponibile în prezent

Endpoint-urile de mai jos sunt disponibile în acest moment și pot fi folosite pentru testare și explorare. API-ul este în curs de standardizare, iar pentru fiecare funcționalitate vom publica treptat endpoint-uri noi, împreună cu o documentație mai detaliată.

GET /v1/random/ Get a random job listing ▶

Returns a single random job from the Solr job index. Useful for discovery widgets, "job of the day" features, or testing integrations.

How it works

Queries Solr for the total number of indexed jobs
Picks a random offset between 0 and total count
Fetches exactly one document at that offset
Returns the job mapped to the peviitor Job Model Schema

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/random/" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
title	string	Exact job position title
company	string	Hiring company name (uppercase)
location	string[]	Array of cities or addresses
workmode	string	`remote`, `on-site`, or `hybrid`
url	string	Full URL to the job detail page (unique key)
salary	string	Salary interval with currency, e.g. `5000-8000 RON`
tags	string[]	Skill tags (lowercase, max 20)
cif	string	CIF/CUI of the company
date	string	ISO8601 UTC timestamp of indexing
status	string	`scraped`, `tested`, `published`, or `verified`

200 — Success

{
  "title": "Inginer IT",
  "company": "COMPANY SRL",
  "location": ["Bucure\u0219ti", "Cluj-Napoca"],
  "workmode": "remote",
  "url": "https://example.com/job/123",
  "salary": "5000-8000 RON",
  "tags": ["python", "java"],
  "cif": "12345678",
  "date": "2026-06-15T10:00:00Z",
  "status": "published"
}

404 — No Jobs Found

{
  "error": "No jobs found"
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "PROD_SERVER not set"
}

Requirements — Random

Item	Details
Method	`GET` only
Auth	None (public endpoint)
Params	None
Content-Type	`application/json`

Status codes

200A random job was found and returned successfully
404No jobs are currently indexed in the Solr core
503Solr core is unavailable or environment not configured

GET /v1/total/ Get total jobs and companies count ▶

Returns the total number of job listings and companies currently indexed in the Solr cores. Useful for dashboard counters, statistics widgets, or monitoring integrations.

How it works

Queries the job Solr core for the total number of indexed jobs
Queries the company Solr core for the total number of indexed companies
Returns both counts in a single response object

Try it

curl

curl -X GET "https://api.peviitor.ro/v1/total/" \
  -H "Accept: application/json"

Response fields

Field	Type	Description
total	object	Container object with count fields
total.jobs	number	Total number of job listings currently indexed
total.companies	number	Total number of companies currently indexed

200 — Success

{
  "total": {
    "jobs": 18452,
    "companies": 934
  }
}

405 — Method Not Allowed

{
  "error": "Only GET method allowed"
}

503 — Service Unavailable

Triggered when Solr is unreachable, returns an invalid response, or the environment is not configured. The details field contains the underlying error message for debugging.

{
  "error": "Job core unavailable",
  "details": "SOLR_SERVER not set"
}

{
  "error": "Job core unavailable",
  "details": "FETCH FAILED: http://... | Connection timed out"
}

{
  "error": "Job core unavailable",
  "details": "Invalid JSON response"
}

Requirements — Total

Item	Details
Method	`GET` only
Auth	None (public endpoint)
Params	None
Content-Type	`application/json`

Status codes

200Counts for jobs and companies returned successfully
405Request method is not GET
503Solr core is unreachable, returned invalid JSON, or environment is not configured

DELETE /v1/cleanjobs/ Delete job records for a company ▶

Permanently deletes every job document matching the given company from the job Solr core. Designed for company website owners who want to remove their listings from the peviitor platform.

How it works

Identify the company by company name, cif, or brand
Compute X-Api-Key as MD5 hash based on the provided identifiers
Send a DELETE request with confirmation body
All matching jobs are permanently removed from the index

Authentication

You must provide an X-Api-Key header computed as md5() of the identifiers you send. The key is generated from the same fields in the request body:

Body fields	X-Api-Key formula
`company` + `cif`	`md5(company + cif)` (recommended)
`company` only	`md5(company)`
`brand` only	`md5(brand)`

Request body

{
  "company": "NUME SRL",
  "cif": "12345678",
  "confirmation": "CLEAN_COMPANY_JOBS"
}

At least one of company, cif, or brand is required. The confirmation field must be exactly "CLEAN_COMPANY_JOBS".

Try it

curl

COMPANY="NUME SRL"
CIF="12345678"
KEY=$(echo -n "${COMPANY}${CIF}" | md5sum | cut -d' ' -f1)

curl -X DELETE "https://api.peviitor.ro/v1/cleanjobs/" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "'"$COMPANY"'",
    "cif": "'"$CIF"'",
    "confirmation": "CLEAN_COMPANY_JOBS"
  }'

Response fields

Field	Type	Description
message	string	Success confirmation message
jobCount	number	Number of jobs deleted
company	string	Company name (if provided)
cif	string	Company CIF (if provided)
brand	string	Company brand (if provided)

200 — Success

{
  "message": "Jobs deleted successfully",
  "jobCount": 42,
  "company": "NUME SRL",
  "cif": "12345678"
}

401 — Unauthorized

{
  "error": "Unauthorized - invalid X-Api-Key"
}

404 — No Jobs Found

{
  "error": "No jobs found",
  "message": "No jobs found matching the given criteria"
}

405 — Method Not Allowed

{
  "error": "Only DELETE method allowed"
}

503 — Service Unavailable

{
  "error": "Job core unavailable",
  "details": "PROD_SERVER not set"
}

Requirements — Cleanjobs

Item	Details
Method	`DELETE` only
Auth	`X-Api-Key: md5(company + cif)` (or `md5(company)` / `md5(brand)`)
Params	Body: `{"company"?: "...", "cif"?: "...", "brand"?: "...", "confirmation": "CLEAN_COMPANY_JOBS"}`
Content-Type	`application/json`

Status codes

200Jobs were deleted successfully
401Invalid or missing X-Api-Key header
404No jobs found matching the given criteria
405Only DELETE method is allowed
503Solr core is unavailable or environment not configured

Stare curentă a API-ului

Lucrăm la:

documentarea completă a API-ului pe baza unei specificații publice (de tip OpenAPI/Swagger)
introducerea unui mecanism de validare a domeniilor (prin înregistrări DNS TXT) pentru a lega cheile API de website-ul companiei
definirea unor endpoint-uri dedicate pentru gestionarea joburilor (creare, actualizare, închidere) într-un mod standardizat

Pe măsură ce noile endpoint-uri vor deveni disponibile, le vom publica aici împreună cu exemple de request/response și recomandări de integrare.

Cum vei putea integra website-ul tău (în curând)

Obiectivul nostru este să oferim un mod simplu și automat prin care website-urile de companii să trimită joburi către peviitor.ro prin API. Designul urmărit este:

cheile de API vor fi asociate unui domeniu de website (de exemplu, exemplu.com)
domeniul va putea fi dovedit printr-o înregistrare DNS TXT, astfel încât doar proprietarul domeniului să poată publica joburi în numele acelei companii
endpoint-uri dedicate pentru creare, actualizare și închidere joburi vor fi documentate public, cu exemple clare de integrare

Pe măsură ce aceste componente vor fi gata, le vom documenta pe această pagină.