pinakes/docs/api/sync.md

# Sync

Multi-device library synchronization

## Endpoints

### POST /api/v1/sync/ack

Acknowledge processed changes POST /api/sync/ack

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description          |
| ------ | -------------------- |
| 200    | Changes acknowledged |
| 400    | Bad request          |
| 401    | Unauthorized         |

---

### GET /api/v1/sync/changes

Get changes since cursor GET /api/sync/changes

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name     | In    | Required | Description            |
| -------- | ----- | -------- | ---------------------- |
| `cursor` | query | No       | Sync cursor            |
| `limit`  | query | No       | Max changes (max 1000) |

#### Responses

| Status | Description          |
| ------ | -------------------- |
| 200    | Changes since cursor |
| 400    | Bad request          |
| 401    | Unauthorized         |

---

### GET /api/v1/sync/conflicts

List unresolved conflicts GET /api/sync/conflicts

**Authentication:** Required (Bearer JWT)

#### Responses

| Status | Description          |
| ------ | -------------------- |
| 200    | Unresolved conflicts |
| 401    | Unauthorized         |

---

### POST /api/v1/sync/conflicts/{id}/resolve

Resolve a sync conflict POST /api/sync/conflicts/{id}/resolve

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Conflict ID |

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description       |
| ------ | ----------------- |
| 200    | Conflict resolved |
| 400    | Bad request       |
| 401    | Unauthorized      |

---

### GET /api/v1/sync/devices

List user's sync devices GET /api/sync/devices

**Authentication:** Required (Bearer JWT)

#### Responses

| Status | Description     |
| ------ | --------------- |
| 200    | List of devices |
| 401    | Unauthorized    |

---

### POST /api/v1/sync/devices

Register a new sync device POST /api/sync/devices

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Device registered     |
| 400    | Bad request           |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### GET /api/v1/sync/devices/{id}

Get device details GET /api/sync/devices/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Device ID   |

#### Responses

| Status | Description    |
| ------ | -------------- |
| 200    | Device details |
| 401    | Unauthorized   |
| 403    | Forbidden      |
| 404    | Not found      |

---

### PUT /api/v1/sync/devices/{id}

Update a device PUT /api/sync/devices/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Device ID   |

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description    |
| ------ | -------------- |
| 200    | Device updated |
| 401    | Unauthorized   |
| 403    | Forbidden      |
| 404    | Not found      |

---

### DELETE /api/v1/sync/devices/{id}

Delete a device DELETE /api/sync/devices/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Device ID   |

#### Responses

| Status | Description    |
| ------ | -------------- |
| 204    | Device deleted |
| 401    | Unauthorized   |
| 403    | Forbidden      |
| 404    | Not found      |

---

### POST /api/v1/sync/devices/{id}/token

Regenerate device token POST /api/sync/devices/{id}/token

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Device ID   |

#### Responses

| Status | Description       |
| ------ | ----------------- |
| 200    | Token regenerated |
| 401    | Unauthorized      |
| 403    | Forbidden         |
| 404    | Not found         |

---

### GET /api/v1/sync/download/{path}

Download a file for sync (supports Range header) GET /api/sync/download/{*path}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name   | In   | Required | Description |
| ------ | ---- | -------- | ----------- |
| `path` | path | Yes      | File path   |

#### Responses

| Status | Description     |
| ------ | --------------- |
| 200    | File content    |
| 206    | Partial content |
| 401    | Unauthorized    |
| 404    | Not found       |

---

### POST /api/v1/sync/report

Report local changes from client POST /api/sync/report

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description       |
| ------ | ----------------- |
| 200    | Changes processed |
| 400    | Bad request       |
| 401    | Unauthorized      |

---

### POST /api/v1/sync/upload

Create an upload session for chunked upload POST /api/sync/upload

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description            |
| ------ | ---------------------- |
| 200    | Upload session created |
| 400    | Bad request            |
| 401    | Unauthorized           |

---

### GET /api/v1/sync/upload/{id}

Get upload session status GET /api/sync/upload/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description       |
| ---- | ---- | -------- | ----------------- |
| `id` | path | Yes      | Upload session ID |

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Upload session status |
| 401    | Unauthorized          |
| 404    | Not found             |

---

### DELETE /api/v1/sync/upload/{id}

Cancel an upload session DELETE /api/sync/upload/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description       |
| ---- | ---- | -------- | ----------------- |
| `id` | path | Yes      | Upload session ID |

#### Responses

| Status | Description      |
| ------ | ---------------- |
| 204    | Upload cancelled |
| 401    | Unauthorized     |
| 404    | Not found        |

---

### PUT /api/v1/sync/upload/{id}/chunks/{index}

Upload a chunk PUT /api/sync/upload/{id}/chunks/{index}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name    | In   | Required | Description       |
| ------- | ---- | -------- | ----------------- |
| `id`    | path | Yes      | Upload session ID |
| `index` | path | Yes      | Chunk index       |

#### Request Body

Chunk binary data `Content-Type: application/octet-stream`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description    |
| ------ | -------------- |
| 200    | Chunk received |
| 400    | Bad request    |
| 401    | Unauthorized   |
| 404    | Not found      |

---

### POST /api/v1/sync/upload/{id}/complete

Complete an upload session POST /api/sync/upload/{id}/complete

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description       |
| ---- | ---- | -------- | ----------------- |
| `id` | path | Yes      | Upload session ID |

#### Responses

| Status | Description      |
| ------ | ---------------- |
| 200    | Upload completed |
| 400    | Bad request      |
| 401    | Unauthorized     |
| 404    | Not found        |

---