API — Zadania

Endpointy do pobierania treści zadań, rozpoczynania, kończenia i przesyłania prac kreatywnych.

Wszystkie endpointy wymagają Authorization: Bearer <token>.

GET /app/tasks/:id

Pełne dane zadania z blokami treści (content blocks).

Response 200:

{
  "data": {
    "id": "task_vowel_o",
    "location_id": "loc_a_vowels",
    "title": "Litera O",
    "description": "Narysuj coś, co zaczyna się na literę O!",
    "type": "creative",
    "difficulty": "medium",
    "xp_reward": 15,
    "estimated_minutes": 5,
    "status": "available",
    "content_blocks": [
      {
        "type": "text",
        "body": "Litera **O** jest okrągła jak obręcz!"
      },
      {
        "type": "image",
        "url": "https://cdn.lumos-islands.pl/tasks/letter_o.png",
        "alt": "Litera O"
      },
      {
        "type": "audio",
        "url": "https://cdn.lumos-islands.pl/tasks/letter_o.mp3",
        "duration_seconds": 8
      },
      {
        "type": "prompt",
        "body": "Narysuj coś, co zaczyna się na literę O.",
        "input_type": "drawing"
      }
    ]
  }
}

Typy content blocks

Typ	Pola	Opis
text	body	Tekst (Markdown)
image	url, alt	Obrazek
audio	url, duration_seconds	Nagranie audio
video	url, duration_seconds, thumbnail_url	Wideo
quiz	question, options[], correct_index	Pytanie quiz
matching	pairs[]	Pary do połączenia
ordering	items[]	Elementy do uporządkowania
fill_blank	template, blanks[]	Uzupełnianie luk
prompt	body, input_type	Polecenie pracy twórczej

Pole input_type w bloku prompt: drawing, photo, audio_recording, text_input.

POST /app/tasks/:id/start

Rozpoczyna zadanie — rejestruje czas startu.

Request: pusty body

Response 200:

{
  "data": {
    "task_id": "task_vowel_o",
    "started_at": "2026-03-08T10:00:00Z",
    "status": "in_progress"
  }
}

Błędy:

HTTP	code	Kiedy
409	ALREADY_STARTED	Zadanie jest już w trakcie
403	TASK_LOCKED	Zadanie jest zablokowane

POST /app/tasks/:id/complete

Ukończ zadanie — przesyła odpowiedzi i zwraca nagrodę.

Request:

{
  "answers": [
    {
      "block_index": 3,
      "type": "quiz",
      "selected_index": 2
    }
  ],
  "time_spent_seconds": 142
}

Dla zadań kreatywnych pole answers może być puste (praca jest przesyłana osobno przez submit-creative).

Response 200:

{
  "data": {
    "task_id": "task_vowel_o",
    "completed_at": "2026-03-08T10:05:22Z",
    "correct_answers": 1,
    "total_questions": 1,
    "xp_earned": 15,
    "xp_bonus": 5,
    "total_xp": 20,
    "new_xp_total": 340,
    "level_up": {
      "new_level": 4,
      "level_name": "Odkrywca",
      "unlocked_items": ["hat_explorer"]
    },
    "badges_earned": [
      {
        "id": "badge_first_creative",
        "name": "Pierwszy Artysta",
        "icon_url": "https://cdn.lumos-islands.pl/badges/first_creative.png"
      }
    ],
    "unlocked_items": [
      {
        "id": "hat-pirate",
        "name": "Piracka czapka",
        "category": "hats",
        "thumbnail_url": "https://cdn.lumos-islands.pl/avatar/accessories/pirate_hat.png"
      }
    ],
    "location_completed": false
  }
}

Pole level_up jest obecne tylko gdy dziecko awansuje na nowy poziom. Pole badges_earned to tablica (może być pusta). Pole unlocked_items to tablica przedmiotów odblokowanych na statku kosmicznym (ubrania awatara, akcesoria, dekoracje pokoju) — może być pusta. Przedmioty odblokowywane są przez zdobycie odznak, osiągnięcie poziomu lub kamienie milowe (np. ukończenie N zadań).

POST /app/tasks/:id/submit-creative

Przesyła pracę twórczą (rysunek, zdjęcie, nagranie audio). Używa multipart/form-data.

Headers:

Authorization: Bearer <token>
Content-Type: multipart/form-data

Form fields:

Pole	Typ	Wymagane	Opis
file	binary	tak	Plik pracy (PNG, JPEG, MP3, MP4)
block_index	int	tak	Indeks bloku prompt w zadaniu
comment	string	nie	Komentarz dziecka

Response 201:

{
  "data": {
    "submission_id": "sub_x9y8z7",
    "task_id": "task_vowel_o",
    "file_url": "https://cdn.lumos-islands.pl/submissions/sub_x9y8z7.png",
    "submitted_at": "2026-03-08T10:04:00Z",
    "status": "submitted"
  }
}

Błędy:

HTTP	code	Kiedy
400	INVALID_FILE_TYPE	Nieprawidłowy format pliku
413	FILE_TOO_LARGE	Plik przekracza 10 MB
409	ALREADY_SUBMITTED	Praca już została przesłana dla tego bloku