# Data contracts

## API payloads

### POST `/api/children`

```json
{
  "fullName": "Alice Durand",
  "colorHex": "#FF7F50",
  "birthDate": "2016-09-12",
  "notes": "Allergie aux arachides"
}
```

**Response**

```json
{
  "id": "ch_001",
  "fullName": "Alice Durand",
  "colorHex": "#FF7F50",
  "birthDate": "2016-09-12",
  "notes": "Allergie aux arachides",
  "createdAt": "2025-10-11T08:00:00Z"
}
```

### POST `/api/children/{id}/schedules`

Multipart upload (`file`, `metadata`).

`metadata` example:

```json
{
  "periodStart": "2025-10-13",
  "periodEnd": "2025-10-19",
  "tags": ["ecole", "sport"]
}
```

**Response**

```json
{
  "scheduleId": "sc_101",
  "status": "processing",
  "childId": "ch_001"
}
```

### GET `/api/children/{id}/schedules/{scheduleId}`

```json
{
  "id": "sc_101",
  "childId": "ch_001",
  "periodStart": "2025-10-13",
  "periodEnd": "2025-10-19",
  "activities": [
    {
      "id": "ac_500",
      "title": "Piscine",
      "category": "sport",
      "startDateTime": "2025-10-14T17:00:00Z",
      "endDateTime": "2025-10-14T18:00:00Z",
      "location": "Centre aquatique",
      "reminders": [
        {
          "id": "re_910",
          "offsetMinutes": 120,
          "channel": "push"
        }
      ],
      "metadata": {
        "bring": "maillot, bonnet"
      }
    }
  ],
  "sourceFileUrl": "https://storage/planning.pdf",
  "status": "ready"
}
```

## Ingestion contract

### Request

```json
{
  "scheduleId": "sc_101",
  "childId": "ch_001",
  "filePath": "s3://bucket/planning.pdf",
  "options": {
    "language": "fr",
    "timezone": "Europe/Paris"
  }
}
```

### Response

```json
{
  "scheduleId": "sc_101",
  "status": "completed",
  "activities": [
    {
      "title": "Gym",
      "startDate": "2025-10-15",
      "startTime": "17:30",
      "endTime": "18:30",
      "category": "sport",
      "confidence": 0.88,
      "reminders": [
        {"offsetMinutes": 60, "channel": "push"}
      ],
      "notes": "Tenue sportive + bouteille d eau"
    }
  ],
  "warnings": [
    "Could not detect teacher name"
  ],
  "rawText": "Mardi: Gym 17h30-18h30..."
}
```

## WebSocket feed (future)

```json
{
  "type": "schedule.updated",
  "payload": {
    "scheduleId": "sc_101",
    "childId": "ch_001",
    "updates": [
      {"activityId": "ac_500", "field": "startDateTime", "value": "2025-10-14T16:50:00Z"}
    ]
  }
}
```