# PEZAJOB REST API

Base URL: `/api/`

Browse the interactive docs at [http://127.0.0.1:8000/api/](http://127.0.0.1:8000/api/) when the dev server is running (Browsable API).

## Authentication

Obtain a token with your account email and password:

```http
POST /api/auth/token/
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}
```

Response:

```json
{
  "token": "abc123...",
  "user": { "id": 1, "email": "...", "role": "seeker" }
}
```

Use the token on protected requests:

```http
Authorization: Token abc123...
```

Session authentication also works when logged in via the website (Browsable API).

## Public endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/home/` | Homepage feed (stats, featured jobs, companies, talent, blog, podcast, testimonials) |
| GET | `/api/jobs/` | List active jobs |
| GET | `/api/jobs/{slug}/` | Job detail |
| GET | `/api/companies/` | List companies |
| GET | `/api/companies/{slug}/` | Company detail |
| GET | `/api/companies/{slug}/jobs/` | Jobs at a company |
| GET | `/api/seekers/` | Public talent profiles |
| GET | `/api/seekers/{slug}/` | Seeker profile |
| GET | `/api/blog/` | Blog posts |
| GET | `/api/blog/{slug}/` | Blog post |
| GET | `/api/podcast/` | Podcast episodes |
| GET | `/api/podcast/{slug}/` | Episode detail |
| GET | `/api/plans/` | Subscription plans (filter: `audience`, `category`) |
| GET | `/api/testimonials/` | Approved testimonials |
| POST | `/api/testimonials/` | Submit a testimonial |

### Query parameters (jobs example)

```
GET /api/jobs/?q=engineer&location=Lusaka&job_type=full_time&category=technology&ordering=-created_at
```

Common params: `search`, `ordering`, `page`, plus resource-specific filters (`industry`, `tier`, `audience`, etc.).

## Authenticated endpoints

| Method | Endpoint | Role | Description |
|--------|----------|------|-------------|
| GET | `/api/me/` | Any | Current user + profile summary |
| GET | `/api/me/applications/` | Seeker | My job applications |
| GET | `/api/me/saved-jobs/` | Any | My saved jobs |
| GET | `/api/me/received-applications/` | Company | Applications to my jobs (list) |
| GET | `/api/applications/` | Company | ATS pipeline (filter: `status`, `job`, `q`) |
| GET | `/api/applications/{id}/` | Company | Application detail with notes, events, interviews |
| PATCH | `/api/applications/{id}/` | Company | Update `status` and/or `rating` |
| POST | `/api/applications/{id}/notes/` | Company | Add a private note (`body`) |
| POST | `/api/applications/bulk_status/` | Company | Bulk update (`ids`, `status`) |
| GET | `/api/conversations/` | Seeker / Company | Message threads |
| GET | `/api/conversations/{id}/` | Seeker / Company | Thread with messages (marks read) |
| POST | `/api/conversations/{id}/send/` | Seeker / Company | Send message (`body`) |
| POST | `/api/conversations/start/` | Seeker / Company | Open thread (`application_id`) |
| POST | `/api/jobs/{slug}/apply/` | Seeker | Apply to a job |
| POST | `/api/jobs/{slug}/save/` | Any | Toggle save/bookmark |

### Apply to a job

```http
POST /api/jobs/senior-software-engineer-airtel/apply/
Authorization: Token ...
Content-Type: multipart/form-data

cover_letter=Hello...
cv_file=@resume.pdf
linkedin_url=https://linkedin.com/in/you
```

## Pagination

List endpoints return paginated JSON:

```json
{
  "count": 8,
  "next": null,
  "previous": null,
  "results": []
}
```

Default page size: 20.