# TimeTrack Export API — LLM / Agent Reference

This document describes the read-only Export API for the TimeTrack timesheet application.
Use it to retrieve employee timesheet data or generate a PNG screenshot of a weekly timesheet.

All endpoints live at `/api/export.php` and require a valid API key.

---

## Authentication

Every request must include an API key. The employer generates keys from
Settings > API Keys in the TimeTrack dashboard.

Provide the key in **one** of these ways (pick whichever suits your tooling):

| Method | Example |
|---|---|
| **Bearer header** (preferred) | `Authorization: Bearer <API_KEY>` |
| **Query parameter** | `?api_key=<API_KEY>` |

A missing or revoked key returns `401`:
```json
{"success": false, "error": "Invalid or missing API key"}
```

Keys are **read-only** — they cannot create, update, or delete any data.

---

## Endpoints

### 1. List Employees

Returns all employees belonging to the employer who owns the API key.
Use this to discover `employee_id` values needed by the other endpoints.

```
GET /api/export.php?action=employees
```

**Response**
```json
{
  "success": true,
  "employees": [
    {
      "id": 3,
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "department": "Engineering",
      "employee_code": "EMP-003",
      "status": "active"
    }
  ]
}
```

The `id` field is the `employee_id` you pass to the other endpoints.

---

### 2. List Timesheets (JSON)

Returns timesheet entries as JSON. Supports optional filters.

```
GET /api/export.php?action=timesheets
```

**Optional query parameters**

| Parameter | Type | Description |
|---|---|---|
| `employee_id` | integer | Filter to a single employee (uses `employees.id`) |
| `start_date` | `YYYY-MM-DD` | Start of date range (inclusive). Must be paired with `end_date`. |
| `end_date` | `YYYY-MM-DD` | End of date range (inclusive). Must be paired with `start_date`. |
| `status` | string | One of `pending`, `approved`, `rejected` |

**Example — all approved timesheets for employee 3 in a specific week**
```
GET /api/export.php?action=timesheets&employee_id=3&start_date=2026-04-06&end_date=2026-04-12&status=approved
```

**Response**
```json
{
  "success": true,
  "timesheets": [
    {
      "id": 142,
      "user_id": 8,
      "employer_id": 1,
      "work_date": "2026-04-07",
      "clock_in": "08:30:00",
      "clock_out": "17:00:00",
      "break_minutes": 30,
      "total_hours": "8.00",
      "travel_km": "12.50",
      "entry_type": "manual",
      "entry_category": "work",
      "status": "approved",
      "notes": "",
      "first_name": "Jane",
      "last_name": "Smith",
      "department": "Engineering",
      "employee_record_id": 3
    }
  ]
}
```

**`entry_category`** is one of:
- `work` — regular work entry with `clock_in` / `clock_out` / `break_minutes` / `travel_km`
- `sick` — sick leave. `clock_in`, `clock_out` are `null`; `break_minutes` and `travel_km` are `0`; `total_hours` holds the hours taken.
- `holiday` — holiday / annual leave. Same shape as sick leave.

---

### 3. PNG Export of Weekly Timesheet

Returns a **PNG image** of one employee's timesheet for a single week.
The image matches the employer's "Tables" view in the dashboard: a card
with the employee name, department, date range, a table of each day's
hours, and summary totals.

```
GET /api/export.php?action=png&employee_id=<ID>
```

**Query parameters**

| Parameter | Required | Type | Description |
|---|---|---|---|
| `employee_id` | **yes** | integer | The employee's `id` from the employees list |
| `week_start` | no | `YYYY-MM-DD` | The first day of the week to render. Defaults to the **current week** on the last day of the billing week, otherwise the **most recently completed full week** (see below). |

**Default week behaviour**

When `week_start` is omitted, the billing week start day configured by the
employer (default Monday) determines which week is returned:
- On the **last day** of the billing week: the **current** week is returned.
- On any other day: the **most recently completed full week** is returned.

For example, if the billing week runs Monday to Sunday:
- On Sunday (last day): `week_start` defaults to the current Monday, covering Mon–Sun of this week.
- On Saturday or earlier: `week_start` defaults to the previous Monday, covering the last full Mon–Sun week.

**Response**

- Content-Type: `image/png`
- The image is returned inline (not as a download).
- On error (missing employee_id, employee not found) the response is JSON
  with an appropriate HTTP status code.

**Example — get last completed week for employee 3**
```
GET /api/export.php?action=png&employee_id=3
```

**Example — get a specific week**
```
GET /api/export.php?action=png&employee_id=3&week_start=2026-03-30
```

**Using with curl to save the image**
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-domain.com/api/export.php?action=png&employee_id=3" \
  --output timesheet.png
```

---

## Typical agent workflow

1. **Get employee list** — call `?action=employees` to find the `id` of the
   employee you need.
2. **Get the PNG** — call `?action=png&employee_id=<ID>` (optionally with
   `&week_start=YYYY-MM-DD`). The response body is the raw PNG bytes.
3. If you need structured data instead of an image, use
   `?action=timesheets&employee_id=<ID>&start_date=...&end_date=...`.

---

## Error responses

All errors return JSON regardless of the requested action:

```json
{"success": false, "error": "Description of what went wrong"}
```

| HTTP Code | Meaning |
|---|---|
| 400 | Bad request (missing required parameter, invalid action) |
| 401 | Missing or invalid API key |
| 404 | Employee not found or does not belong to this employer |

---

## Rate limits and permissions

- API keys are scoped to a single employer. You can only access employees
  and timesheets belonging to that employer.
- Keys are read-only. No write operations are available.
- The employer can revoke a key at any time from the dashboard. A revoked
  key immediately stops working.