API Reference
The Jobven API provides programmatic access to job listings and company data. All endpoints follow REST conventions and return JSON responses.
Base URL
All API requests should be made to:
https://api.jobven.com
Authentication
All endpoints require an API key passed in the X-API-Key header:
curl -H "X-API-Key: your_api_key" \
"https://api.jobven.com/v1/public/jobs"
OpenAPI Specification
The API is described by an OpenAPI 3.0 document, generated from the live API:
https://api.jobven.com/api/docs/public-json
Use it to generate a typed client, import every endpoint into Postman or Insomnia, or give an AI coding assistant the exact parameters and response fields. No API key is needed to fetch it.
For example, TypeScript types for every request and response:
npx openapi-typescript https://api.jobven.com/api/docs/public-json -o jobven.d.ts
Request Format
The API uses GET requests with query parameters for filtering and pagination:
GET /v1/public/jobs?skills=react&remoteType=remote&limit=20
Array parameters use repeated keys:
GET /v1/public/jobs?skills=react&skills=typescript&remoteType=remote&remoteType=hybrid
Response Format
Jobs Endpoint
Jobs returns a paginated response with metadata:
{
"data": [...],
"meta": {
"count": 20,
"nextCursor": "eyJpZCI6IjEyMyJ9",
"hasMore": true
}
}
| Field | Description |
|---|---|
data | Array of job objects |
meta.total | Exact number of matching results. Only present when you pass includeTotal=true |
meta.count | Results in this response |
meta.nextCursor | Cursor for next page (null if no more) |
meta.hasMore | Whether more results exist |
Companies Endpoint
Companies pages by number, with page, limit, total and totalPages in meta:
{
"data": [
{ "id": 1042, "name": "TechCorp", "website": "https://techcorp.com" }
],
"meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
/company-profiles adds each company's profile; see Companies.
Error Codes
When an error occurs, the API returns an appropriate HTTP status code with details:
| Code | Name | Description |
|---|---|---|
400 | Bad Request | Invalid parameters or malformed request |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Valid key but insufficient permissions |
404 | Not Found | Resource does not exist |
422 | Unprocessable Entity | The request is valid but could not be completed, such as a job search that runs too long. The message says what to change |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Something went wrong on our end |
Error Response
{
"statusCode": 401,
"message": "Invalid API key",
"error": "Unauthorized"
}
Rate Limit Errors
When you exceed your rate limit, you'll receive a 429 response with retry information:
{
"statusCode": 429,
"message": "Rate limit exceeded. Please retry after 1 second.",
"error": "Too Many Requests"
}
Check the X-RateLimit-Remaining header to monitor your usage. See Authentication for rate limit details by tier.
Next Steps
Explore the available endpoints and data types: