--- title: "Migrator — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference modułu Migrator: endpointy REST API v1 (lista, szczegóły, logi, start, wykonanie, ponów nieudane, usuń), zakresy account:*, narzędzia MCP oraz przykłady curl i JSON-RPC. Poświadczenia źródła są tylko do zapisu." url: "https://nodea.pl/pl/dokumentacja-api/migrations" lang: "pl" updated: "2026-07-16" --- # Migrator — API v1 i MCP | Dokumentacja Nodea > Reference modułu Migrator — endpointy API v1 (lista z filtrem, szczegóły z zasobami, logi, start biegu, wykonanie, ponów nieudane zasoby, usuń), zakresy account:read/write/delete, narzędzia MCP i przykłady. Poświadczenia dostawcy źródłowego nigdy nie wracają. Moduł **Migrator** przenosi monitoring, kontakty, strony statusu i encje WHMCS z zewnętrznych dostawców do Nodea. Bieg migracji (MigratorRun) przechodzi cykl: start → discovery (odczyt zasobów przez API dostawcy) → przegląd → wykonanie (plan + import). Dokument opisuje warstwę REST API v1 (/api/v1) oraz narzędzia MCP z tego modułu. ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się osobistym tokenem Passport przez nagłówek Authorization: Bearer \. Trasy tego modułu są chronione zakresem konta odpowiadającym poziomowi operacji: - account:read — listowanie, podgląd, logi. - account:write — start biegu, wykonanie, ponowienie nieudanych zasobów. - account:delete — trwałe usunięcie biegu (kaskada zasobów i logów). Cały moduł jest dodatkowo bramkowany flagą Pennant features:migrator — wyłączenie ukrywa go w web UI i w API. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. Dodatkowo **start biegu jest limitowany do 5 prób na minutę** na użytkownika (wspólny budżet z web i MCP, kod discovery\_rate\_limited / 429). W MCP każde narzędzie wymaga też zakresu transportowego mcp:use oraz flagi migrator. ## Własność i widoczność (ownership) Biegi migracji nie mają klasy polityki ani modelu współdzielenia — każdy dostęp jest twardo ograniczony do właściciela przez user\_id. Cudzy lub nieznany identyfikator zwraca konsekwentnie 404 (a nie 403), więc API nigdy nie potwierdza istnienia cudzego biegu. W MCP odpowiada temu jeden komunikat „nie znaleziono lub brak dostępu”. Identyfikator biegu to **UUID** (string). ## Bezpieczeństwo danych wrażliwych **Poświadczenia dostawcy źródłowego są wyłącznie do zapisu (write-only): przyjmowane przy starcie biegu, przechowywane zaszyfrowane (encrypted:json + $hidden na modelu) i nigdy niezwracane przez żaden zasób.** Wewnętrzne kolumny — wznawialny kursor checkpoint, surowy blob plan, wewnętrzne discovery\_summary, credentials\_purge\_at — także nie są eksponowane. Zasoby biegu nie ujawniają surowych blobów dostawcy (external\_data/normalized\_data) ani wewnętrznego powiązania importu (target\_model/target\_id). ## Efekty uboczne — asynchroniczne i stan biegu Start, wykonanie i ponowienie działają out-of-band przez kolejkę (dedykowane kolejki discovery/planning/resources) — akcje zwracają 202 Accepted, a właściwy start biegu 201 Created z zasobem. Wykonać można tylko bieg w stanie awaiting\_review (inaczej 422, kod run\_not\_awaiting\_review). Ponowienie odrzuca się, gdy nie ma nieudanych zasobów (422, kod no\_failed\_resources). ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/migrationsaccount:readLista biegów właściciela (najnowsze pierwsze), paginowana. Filtry status, provider. Każdy wiersz: total\_resources, failed\_resources. GET/api/v1/migrations/{run}account:readSzczegóły biegu z zasobami (cap 500) oraz meta.resource\_counts (rozkład per status). GET/api/v1/migrations/{run}/logsaccount:readDziennik biegu (najnowsze pierwsze), paginowany. Filtr errors\_only. POST/api/v1/migrationsaccount:writeStart biegu (provider + credentials write-only). Kolejkuje discovery. Zwraca 201; limit 5/min → 429. POST/api/v1/migrations/{run}/executeaccount:writeWykonanie biegu (plan + import). Tylko stan awaiting\_review. Zwraca 202/422. POST/api/v1/migrations/{run}/retry-failedaccount:writePonowienie nieudanych zasobów (reset do pending + redispatch). Zwraca 202 z retried; brak nieudanych → 422. DELETE/api/v1/migrations/{run}account:deleteTrwałe usunięcie biegu (kaskada). Zwraca 204. ### GET /migrations — parametry zapytania - status (enum, opcjonalny) — pending, discovering, awaiting\_review, executing, paused\_conflicts, completed, completed\_with\_errors, failed, cancelled. - provider (enum, opcjonalny) — uptime\_robot, statuscake, pingdom, better\_stack, oh\_dear, hetrix\_tools, site24x7, whmcs, phpipam. - per\_page (int 1–100, domyślnie 20), page (int ≥1). Wiersz biegu (MigrationRunResource): id (UUID), provider, status, stats, total\_resources, failed\_resources, error\_message, started\_at, finished\_at, created\_at, updated\_at. Szczegóły dokładają resources\[\] (zasób: id, resource\_type, external\_id, action, status, attempts, error\_message). Log (MigrationLogResource): id, level, message, context, logged\_at. ### POST /migrations — parametry ciała - provider (string, wymagany) — jeden z dostawców powyżej. - credentials (obiekt klucz→string, opcjonalny) — **write-only**. Pola wymagane zależą od dostawcy: schemat credentials\_schema z config/migrator.php wymusza obecność pól oznaczonych jako required (brak → 422 na credentials.\). ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak wymaganego scope. - 404 — nieznany lub cudzy bieg. - 422 — walidacja, wykonanie biegu spoza awaiting\_review (run\_not\_awaiting\_review), brak nieudanych zasobów do ponowienia (no\_failed\_resources). - 429 — przekroczony limit startów (discovery\_rate\_limited). ## Przykłady — API ### Lista biegów z filtrem statusu i dostawcy curl -s "https://app.nodea.io/api/v1/migrations?status=awaiting\_review&provider=uptime\_robot" \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Start biegu migracji (poświadczenia write-only) curl -s -X POST https://app.nodea.io/api/v1/migrations \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Content-Type: application/json" \\ -d '{ "provider": "uptime\_robot", "credentials": { "api\_key": "u123456-abcdef..." } }' ### Wykonanie zrewidowanego biegu curl -s -X POST https://app.nodea.io/api/v1/migrations/{run}/execute \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Ponowienie nieudanych zasobów curl -s -X POST https://app.nodea.io/api/v1/migrations/{run}/retry-failed \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ## MCP — narzędzia Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope w ensureScope) oraz flagę migrator (narzędzie na nieaktywnej fladze znika z tools/list). Identyfikator biegu to UUID (string). Brakujący i cudzy identyfikator zwracają ten sam błąd. Start, wykonanie i ponowienie są asynchroniczne (potwierdzenie zlecenia). Narzędzie niszczące migration-delete jest oznaczone jako destructive i wymaga jawnego confirm: true. Poświadczenia dostawcy pozostają write-only. NazwaScopeTrybOpismigrations-listaccount:readread-onlyLista biegów (najnowsze pierwsze) z total\_resources/failed\_resources. Filtry status, provider; page, per\_page (max 50). migration-getaccount:readread-onlySzczegóły biegu: nagłówek, zasoby (cap 500), 50 ostatnich logów i resource\_counts. Param: id. Poświadczenia nigdy nie wracają. migration-createaccount:writezapisStart biegu; provider, credentials (obiekt, write-only). Kolejkuje discovery. Limit 5/min. migration-executeaccount:writezapisWykonanie biegu (plan + import); id. Tylko stan awaiting\_review. migration-retry-failedaccount:writezapisPonowienie nieudanych zasobów; id. Odrzucone, gdy brak nieudanych. migration-deleteaccount:deletedestrukcyjne (confirm)Trwałe usunięcie biegu wraz z zasobami i logami. Wymaga confirm: true; id. ### Przykłady — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "migration-create", "arguments": { "provider": "uptime\_robot", "credentials": { "api\_key": "u123456-abcdef..." } } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "migration-delete", "arguments": { "id": "9b1f...uuid", "confirm": true } } } ## Powiązane - [Domeny — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/domains) - [Hosting](https://nodea.pl/pl/slownik-pojec/hosting) --- Wersje językowe: [en](https://nodea.io/en/api-docs/migrations.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)