Introduction

CareerK API integration guide for frontend applications

CareerK API

This documentation is the integration contract for frontend clients.

API Base Path

Use this base path for all endpoints:

{API_ORIGIN}/api/v1

Local example:

http://localhost:3000/api/v1

Treat /api/v1 as the canonical API namespace for frontend development.

Global Response Contract

Most successful responses are wrapped in a consistent envelope:

{
  "success": true,
  "data": {},
  "message": "Success",
  "meta": {
    "timestamp": "2026-02-27T00:00:00.000Z",
    "path": "/jobs",
    "method": "GET"
  }
}

Frontend Notes

• data contains endpoint-specific payload.
• message is human-readable and can be shown in toasts/snackbars.
• meta is useful for logging, debugging, and tracing.

Global Error Contract

Errors are returned in this envelope:

{
  "success": false,
  "error": {
    "message": "Unauthorized",
    "statusCode": 401,
    "timestamp": "2026-02-27T00:00:00.000Z",
    "path": "/jobs/bookmarks",
    "method": "GET",
    "details": "Bad Request"
  }
}

Frontend Notes

• Always read error.statusCode for control flow.
• error.message may be a string or an array (especially for validation errors).
• error.details is optional.

Authentication Model

CareerK uses access token + refresh token authentication.

• Access token: sent in Authorization header.
• Refresh token: stored in an HTTP-only cookie named refreshToken.
• Protected endpoints: require valid access token.
• Role-protected endpoints: return 403 when user role is not allowed.

Authorization header format:

Authorization: Bearer <accessToken>

Use credentials: 'include' for browser requests so refresh-token cookie flow works correctly.

Query and Pagination Conventions

Most list endpoints support:

• page (default commonly 1)
• limit (default commonly 20)
• endpoint-specific filters (for example search, location, jobType)

Use query params as strings in URLs, for example:

/jobs?page=1&limit=20&search=frontend

File Upload Flow (CV)

CV upload is a multi-step flow:

1. Request a pre-signed upload URL from API.
2. Upload file directly to storage using returned uploadUrl.
3. Confirm upload with API.
4. Optionally preview and confirm parsed data.

The direct upload request (PUT {uploadUrl}) is against storage, not the CareerK API host.

Status Code Guide

Code	Meaning
200	Success
201	Created
400	Validation or bad request
401	Missing/invalid authentication
403	Authenticated but not authorized for role/resource
404	Resource not found
409	Conflict (duplicate/resource state conflict)
500	Internal server error

Where To Start

• Authentication Endpoints
• Jobs API
• Job Seeker API
• CV API
• Company API