> ## Documentation Index
> Fetch the complete documentation index at: https://careerk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
{API_ORIGIN}/api/v1
```

Local example:

```text theme={null}
http://localhost:3000/api/v1
```

<Note>
  Treat `/api/v1` as the canonical API namespace for frontend development.
</Note>

## Global Response Contract

Most successful responses are wrapped in a consistent envelope:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```http theme={null}
Authorization: Bearer <accessToken>
```

<Warning>
  Use `credentials: 'include'` for browser requests so refresh-token cookie flow works correctly.
</Warning>

## 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:

```text theme={null}
/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.

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

## 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](/api-reference/auth/introduction)
* [Jobs API](/api-reference/jobs/introduction)
* [Job Seeker API](/job-seeker/introduction)
* [CV API](/api-reference/cv/introduction)
* [Company API](/api-reference/company/introduction)