# landfeed API and MCP > Sourced, dated answers about Polish działki ewidencyjne (cadastral parcels). Public REST origin: https://mcp.agentdzialek.pl Remote MCP (Streamable HTTP): https://mcp.agentdzialek.pl/mcp Human console: https://app.agentdzialek.pl Documentation: https://docs.agentdzialek.pl Use an account API key in X-Api-Key for REST; connectors use OAuth for the /mcp resource. Six MCP tools share REST evidence and billing. POST /v1/ask is a separate, account-key endpoint supporting JSON and typed SSE. Never turn unknown into no. Four coverage states are covered, covered_no_data, not_covered, not_computed. Retain source, as_of (source date), note and actual scope. On ambiguous input, ask for obręb (cadastral precinct) or explicit candidate selection; never silently choose. Gmina means municipality; MPZP means miejscowy plan zagospodarowania przestrzennego (local spatial development plan); POG means plan ogólny (general municipal plan); WZ means warunki zabudowy (development conditions). Read cost before calling and settlement from billing after the response. A timeout or disconnect leaves settlement uncertain. Never automatically replay a consequential operation. Budget-stopped ask-v2 turns are free, with new facts/artifacts withheld. Retain complete signed artifacts and continuation on the client for follow-up turns. Never request, store or serve owner/holder data or KW (księga wieczysta, land and mortgage register) numbers. No legal advice, no address-level transaction prices and no investor names. Plan data does not settle buildability; mapped roads do not settle legal access. RCN aggregates describe the whole obręb, not a parcel valuation. The reference renders the immutable OpenAPI contract, including explicitly dormant operations. Runtime discovery omits dormant methods. Fixture examples are recorded test observations, not current coverage guarantees. Source-authored schema identifiers, dev-server metadata and error links are preserved verbatim; use the public origin above for actual calls. Refer to the changelog and operation availability before adopting a feature. ## Guides and reference - [Envelope](https://docs.agentdzialek.pl/envelope.md) - [Errors catalogue](https://docs.agentdzialek.pl/errors.md) - [Ask endpoint and SSE streaming](https://docs.agentdzialek.pl/guides/en/ask-sse.md) - [API keys and MCP OAuth](https://docs.agentdzialek.pl/guides/en/authentication.md) - [Changelog](https://docs.agentdzialek.pl/guides/en/changelog.md) - [Four coverage states: unknown is never no](https://docs.agentdzialek.pl/guides/en/coverage.md) - [Credits, prices and refunds](https://docs.agentdzialek.pl/guides/en/credits.md) - [MCP setup: Claude, ChatGPT, Claude Code and Cursor](https://docs.agentdzialek.pl/guides/en/mcp-setup.md) - [What landfeed never answers](https://docs.agentdzialek.pl/guides/en/never-answers.md) - [Quickstart in 3 minutes](https://docs.agentdzialek.pl/guides/en/quickstart.md) - [Rate and size limits](https://docs.agentdzialek.pl/guides/en/rate-limits.md) - [Sources, dates, licences and attribution](https://docs.agentdzialek.pl/guides/en/sources.md) - [Events, watches and signed webhooks](https://docs.agentdzialek.pl/guides/en/webhooks.md) - [AddressValue](https://docs.agentdzialek.pl/layers/AddressValue.md) - [BuildingsValue](https://docs.agentdzialek.pl/layers/BuildingsValue.md) - [FloodValue](https://docs.agentdzialek.pl/layers/FloodValue.md) - [LandslideValue](https://docs.agentdzialek.pl/layers/LandslideValue.md) - [MpzpValue](https://docs.agentdzialek.pl/layers/MpzpValue.md) - [PermitsValue](https://docs.agentdzialek.pl/layers/PermitsValue.md) - [PlanningValue](https://docs.agentdzialek.pl/layers/PlanningValue.md) - [PogValue](https://docs.agentdzialek.pl/layers/PogValue.md) - [PricesValue](https://docs.agentdzialek.pl/layers/PricesValue.md) - [ProtectedValue](https://docs.agentdzialek.pl/layers/ProtectedValue.md) - [RoadAccessValue](https://docs.agentdzialek.pl/layers/RoadAccessValue.md) - [SoilValue](https://docs.agentdzialek.pl/layers/SoilValue.md) - [WzValue](https://docs.agentdzialek.pl/layers/WzValue.md) - [Six MCP tools](https://docs.agentdzialek.pl/mcp.md) - [POST /v1/account/keys](https://docs.agentdzialek.pl/operations/account_keys_create.md) - [GET /v1/account/keys](https://docs.agentdzialek.pl/operations/account_keys_list.md) - [DELETE /v1/account/keys/{key_id}](https://docs.agentdzialek.pl/operations/account_keys_revoke.md) - [POST /v1/account/keys/{key_id}/rotate](https://docs.agentdzialek.pl/operations/account_keys_rotate.md) - [GET /v1/account/ledger](https://docs.agentdzialek.pl/operations/account_ledger.md) - [GET /v1/account/usage](https://docs.agentdzialek.pl/operations/account_usage.md) - [POST /v1/ask](https://docs.agentdzialek.pl/operations/ask.md) - [GET /v1/billing/account](https://docs.agentdzialek.pl/operations/billing_account.md) - [DELETE /v1/billing/account](https://docs.agentdzialek.pl/operations/billing_account_delete.md) - [POST /v1/billing/checkout](https://docs.agentdzialek.pl/operations/billing_checkout.md) - [GET /v1/billing/plans](https://docs.agentdzialek.pl/operations/billing_plans.md) - [POST /v1/billing/stripe/webhook](https://docs.agentdzialek.pl/operations/billing_stripe_webhook.md) - [GET /v1/billing/team](https://docs.agentdzialek.pl/operations/billing_team.md) - [POST /v1/billing/team/accept](https://docs.agentdzialek.pl/operations/billing_team_accept.md) - [POST /v1/billing/team/invitations](https://docs.agentdzialek.pl/operations/billing_team_invite.md) - [DELETE /v1/billing/team/members/{account_id}](https://docs.agentdzialek.pl/operations/billing_team_remove.md) - [DELETE /v1/billing/team/invitations/{invitation_id}](https://docs.agentdzialek.pl/operations/billing_team_revoke_invite.md) - [PATCH /v1/billing/team/members/{account_id}](https://docs.agentdzialek.pl/operations/billing_team_role.md) - [GET /v1/check](https://docs.agentdzialek.pl/operations/check.md) - [POST /v1/check](https://docs.agentdzialek.pl/operations/check_batch.md) - [GET /v1/check/jobs/{job_id}](https://docs.agentdzialek.pl/operations/check_job.md) - [GET /v1/check/jobs/{job_id}/results](https://docs.agentdzialek.pl/operations/check_job_results.md) - [GET /v1/events](https://docs.agentdzialek.pl/operations/events.md) - [POST /v1/events/query](https://docs.agentdzialek.pl/operations/events_query.md) - [GET /v1/gminy/{teryt}/planning](https://docs.agentdzialek.pl/operations/gmina_planning.md) - [GET /v1/gminy/planning](https://docs.agentdzialek.pl/operations/gmina_planning_lookup.md) - [GET /v1/layer/{layer}](https://docs.agentdzialek.pl/operations/layer.md) - [GET /v1/openapi.json](https://docs.agentdzialek.pl/operations/openapi.md) - [GET /v1/parcel](https://docs.agentdzialek.pl/operations/parcel.md) - [POST /v1/parcel/batch](https://docs.agentdzialek.pl/operations/parcel_batch.md) - [GET /v1/places](https://docs.agentdzialek.pl/operations/places.md) - [GET /v1/resolve](https://docs.agentdzialek.pl/operations/resolve.md) - [GET /v1/search](https://docs.agentdzialek.pl/operations/search.md) - [POST /v1/search](https://docs.agentdzialek.pl/operations/search_polygon.md) - [GET /v1/sources](https://docs.agentdzialek.pl/operations/sources.md) - [GET /v1/watches/{watch_id}/attempts](https://docs.agentdzialek.pl/operations/watch_attempts.md) - [POST /v1/watches](https://docs.agentdzialek.pl/operations/watch_create.md) - [DELETE /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_delete.md) - [GET /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_get.md) - [GET /v1/watches](https://docs.agentdzialek.pl/operations/watch_list.md) - [POST /v1/watches/{watch_id}/webhook/rotate](https://docs.agentdzialek.pl/operations/watch_secret_rotate.md) - [PUT /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_update.md) - [PUT /v1/watches/{watch_id}/webhook](https://docs.agentdzialek.pl/operations/watch_webhook_configure.md) - [DELETE /v1/watches/{watch_id}/webhook](https://docs.agentdzialek.pl/operations/watch_webhook_remove.md) - [OpenAPI schemas](https://docs.agentdzialek.pl/schemas.md) - [SSE event reference](https://docs.agentdzialek.pl/sse-events.md) - [MCP tool: check](https://docs.agentdzialek.pl/tools/check.md) - [MCP tool: events](https://docs.agentdzialek.pl/tools/events.md) - [MCP tool: layer](https://docs.agentdzialek.pl/tools/layer.md) - [MCP tool: parcel](https://docs.agentdzialek.pl/tools/parcel.md) - [MCP tool: resolve](https://docs.agentdzialek.pl/tools/resolve.md) - [MCP tool: search](https://docs.agentdzialek.pl/tools/search.md) ## Every endpoint - [GET /v1/account/keys](https://docs.agentdzialek.pl/operations/account_keys_list.md): Lista ważnych kluczy tego konta; tylko dla właściciela lub administratora zespołu. - [POST /v1/account/keys](https://docs.agentdzialek.pl/operations/account_keys_create.md): Utwórz klucz konta i pokaż jego sekret jeden raz. - [DELETE /v1/account/keys/{key_id}](https://docs.agentdzialek.pl/operations/account_keys_revoke.md): Natychmiast unieważnij klucz tego konta; tylko dla właściciela lub administratora zespołu. - [POST /v1/account/keys/{key_id}/rotate](https://docs.agentdzialek.pl/operations/account_keys_rotate.md): Wymień klucz z 24-godzinnym okresem wspólnej ważności; pokaż nowy sekret jeden raz. - [GET /v1/account/ledger](https://docs.agentdzialek.pl/operations/account_ledger.md): Odczytaj zaksięgowane zmiany kredytów we wspólnej puli. - [GET /v1/account/usage](https://docs.agentdzialek.pl/operations/account_usage.md): Rozliczone zużycie netto kredytów według operacji i dnia UTC w okresie rozliczeniowym. - [POST /v1/ask](https://docs.agentdzialek.pl/operations/ask.md): Odpowiedz na pytanie o działkę po polsku na podstawie płatnych odczytów landfeed. - [DELETE /v1/billing/account](https://docs.agentdzialek.pl/operations/billing_account_delete.md): Unieważnij dane uwierzytelniające i usuń pola osobowe; trwale anuluj testową subskrypcję i usuń klienta Stripe. Zachowaj pseudonimowe rekordy księgowe. - [GET /v1/billing/account](https://docs.agentdzialek.pl/operations/billing_account.md): Wspólna pula kont, rola i obliczone saldo kredytów. - [POST /v1/billing/checkout](https://docs.agentdzialek.pl/operations/billing_checkout.md): Utwórz testową subskrypcję Stripe Checkout z ochroną przed powtórnym utworzeniem. - [GET /v1/billing/plans](https://docs.agentdzialek.pl/operations/billing_plans.md): Katalog planów abonamentowych w trybie testowym. - [POST /v1/billing/stripe/webhook](https://docs.agentdzialek.pl/operations/billing_stripe_webhook.md): Testowe zdarzenia Stripe z weryfikacją podpisu i ochroną przed ponownym przetworzeniem. Dane trybu produkcyjnego nie są przyjmowane. - [GET /v1/billing/team](https://docs.agentdzialek.pl/operations/billing_team.md): Lista członków uwierzytelnionej wspólnej puli kont. - [POST /v1/billing/team/accept](https://docs.agentdzialek.pl/operations/billing_team_accept.md): Przyjmij zaproszenie przypisane do uwierzytelnionego, istniejącego konta. - [POST /v1/billing/team/invitations](https://docs.agentdzialek.pl/operations/billing_team_invite.md): Właściciel tworzy zaproszenie ważne siedem dni, rezerwując jedno z pięciu miejsc. - [DELETE /v1/billing/team/invitations/{invitation_id}](https://docs.agentdzialek.pl/operations/billing_team_revoke_invite.md): Właściciel lub administrator unieważnia nieprzyjęte zaproszenie. - [DELETE /v1/billing/team/members/{account_id}](https://docs.agentdzialek.pl/operations/billing_team_remove.md): Właściciel lub administrator usuwa miejsce; członek może zrezygnować z własnego miejsca. Właściciela nie można usunąć. - [PATCH /v1/billing/team/members/{account_id}](https://docs.agentdzialek.pl/operations/billing_team_role.md): Właściciel ustawia rolę admin lub member. Nie można zmienić właściciela. - [GET /v1/check](https://docs.agentdzialek.pl/operations/check.md): Czy można tu budować? Wynik według stałych reguł, ze wskazaniem sprawdzeń, źródeł i pełnej karty działki. - [POST /v1/check](https://docs.agentdzialek.pl/operations/check_batch.md): Zbiorcze sprawdzenie check. (dormant, not served) - [GET /v1/check/jobs/{job_id}](https://docs.agentdzialek.pl/operations/check_job.md): Zadanie sprawdzenia check. (dormant, not served) - [GET /v1/check/jobs/{job_id}/results](https://docs.agentdzialek.pl/operations/check_job_results.md): Wyniki zadania check. (dormant, not served) - [GET /v1/events](https://docs.agentdzialek.pl/operations/events.md): Zmiany dotyczące działki, otoczenia punktu albo gminy wskazanej w q, od najnowszych. - [POST /v1/events/query](https://docs.agentdzialek.pl/operations/events_query.md): Pobierz zdarzenia określonych typów, przekazując w treści żądania do 10 000 identyfikatorów działek albo obszar. - [GET /v1/gminy/planning](https://docs.agentdzialek.pl/operations/gmina_planning_lookup.md): Jak /v1/gminy/{teryt}/planning, z gminą rozpoznaną na podstawie q (nazwa gminy lub tekst opisujący działkę), id albo point. - [GET /v1/gminy/{teryt}/planning](https://docs.agentdzialek.pl/operations/gmina_planning.md): Stan planowania w gminie: plan ogólny, zakres MPZP i zasady wydawania WZ w dniu zapytania. - [GET /v1/layer/{layer}](https://docs.agentdzialek.pl/operations/layer.md): Jedna odpowiedź tematyczna dla jednej działki. - [GET /v1/openapi.json](https://docs.agentdzialek.pl/operations/openapi.md): Ta specyfikacja w postaci udostępnianej przez usługę. - [GET /v1/parcel](https://docs.agentdzialek.pl/operations/parcel.md): Pełna karta jednej działki z danymi źródłowymi. - [POST /v1/parcel/batch](https://docs.agentdzialek.pl/operations/parcel_batch.md): Do 1 000 działek w jednym żądaniu; każdy element to q, id albo point. - [GET /v1/places](https://docs.agentdzialek.pl/operations/places.md): Bezpłatne podpowiedzi nazw polskich gmin, powiatów, obrębów i miejscowości na podstawie początku nazwy. - [GET /v1/resolve](https://docs.agentdzialek.pl/operations/resolve.md): Rozpoznaj kandydatów na działkę na podstawie tekstu użytkownika, identyfikatora albo punktu. - [GET /v1/search](https://docs.agentdzialek.pl/operations/search.md): Działki według adresu lub tekstu (q), w pobliżu działki (id) albo punktu lub w obszarze bbox. - [POST /v1/search](https://docs.agentdzialek.pl/operations/search_polygon.md): Wyszukaj w powiecie, gminie lub obszarze Polygon z filtrami o określonych typach i stronicowaniem kursorem; dotychczasowe zapytania wielokątowe pozostają poprawne. - [GET /v1/sources](https://docs.agentdzialek.pl/operations/sources.md): Wszystkie źródła udostępniane przez API, z licencją, wskazaniem pochodzenia, as_of, aktualnością i zakresem danych. - [GET /v1/watches](https://docs.agentdzialek.pl/operations/watch_list.md): Lista obserwowanych wyników tego konta. - [POST /v1/watches](https://docs.agentdzialek.pl/operations/watch_create.md): Utwórz obserwację przyszłych zdarzeń przypisaną do konta. - [DELETE /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_delete.md): Usuń obserwację tego konta i anuluj oczekujące wysyłki. - [GET /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_get.md): Odczytaj obserwację tego konta. - [PUT /v1/watches/{watch_id}](https://docs.agentdzialek.pl/operations/watch_update.md): Zastąp elementy obserwacji tego konta; powiadomienia w kolejce zachowują pierwotny zestaw dopasowań. - [GET /v1/watches/{watch_id}/attempts](https://docs.agentdzialek.pl/operations/watch_attempts.md): Dziennik wysyłek tego konta, bez adresów URL i treści odpowiedzi. - [DELETE /v1/watches/{watch_id}/webhook](https://docs.agentdzialek.pl/operations/watch_webhook_remove.md): Usuń webhook i anuluj jego oczekujące wysyłki. - [PUT /v1/watches/{watch_id}/webhook](https://docs.agentdzialek.pl/operations/watch_webhook_configure.md): Zarejestruj lub zastąp webhook HTTPS; operacja jednorazowo zwraca nowy sekret do podpisywania i anuluje poprzednią kolejkę. - [POST /v1/watches/{watch_id}/webhook/rotate](https://docs.agentdzialek.pl/operations/watch_secret_rotate.md): Zmień sekret konta do podpisywania i ujawnij go jednokrotnie. Oczekujące wysyłki korzystają z nowego klucza. ## Every error code - `-32600`: [-32600](https://docs.agentdzialek.pl/errors.md#-32600) - `-32601`: [-32601](https://docs.agentdzialek.pl/errors.md#-32601) - `-32602`: [-32602](https://docs.agentdzialek.pl/errors.md#-32602) - `-32603`: [-32603](https://docs.agentdzialek.pl/errors.md#-32603) - `-32700`: [-32700](https://docs.agentdzialek.pl/errors.md#-32700) - `access_denied`: [access_denied](https://docs.agentdzialek.pl/errors.md#access_denied) - `account_inactive`: [account_inactive](https://docs.agentdzialek.pl/errors.md#account_inactive) - `account_required`: [account_required](https://docs.agentdzialek.pl/errors.md#account_required) - `ambiguous`: [ambiguous](https://docs.agentdzialek.pl/errors.md#ambiguous) - `billing_unavailable`: [billing_unavailable](https://docs.agentdzialek.pl/errors.md#billing_unavailable) - `blocked_destination`: [blocked_destination](https://docs.agentdzialek.pl/errors.md#blocked_destination) - `body_too_large`: [body_too_large](https://docs.agentdzialek.pl/errors.md#body_too_large) - `cancelled`: [cancelled](https://docs.agentdzialek.pl/errors.md#cancelled) - `client_result_required`: [client_result_required](https://docs.agentdzialek.pl/errors.md#client_result_required) - `confirmation_required`: [confirmation_required](https://docs.agentdzialek.pl/errors.md#confirmation_required) - `conflicting_historical_evidence`: [conflicting_historical_evidence](https://docs.agentdzialek.pl/errors.md#conflicting_historical_evidence) - `conflicting_version_provenance`: [conflicting_version_provenance](https://docs.agentdzialek.pl/errors.md#conflicting_version_provenance) - `context_too_large`: [context_too_large](https://docs.agentdzialek.pl/errors.md#context_too_large) - `duplicate_artifact`: [duplicate_artifact](https://docs.agentdzialek.pl/errors.md#duplicate_artifact) - `event_type_has_no_producer`: [event_type_has_no_producer](https://docs.agentdzialek.pl/errors.md#event_type_has_no_producer) - `expired_continuation`: [expired_continuation](https://docs.agentdzialek.pl/errors.md#expired_continuation) - `idempotency_conflict`: [idempotency_conflict](https://docs.agentdzialek.pl/errors.md#idempotency_conflict) - `incomplete_version_provenance`: [incomplete_version_provenance](https://docs.agentdzialek.pl/errors.md#incomplete_version_provenance) - `insufficient_credits`: [insufficient_credits](https://docs.agentdzialek.pl/errors.md#insufficient_credits) - `internal`: [internal](https://docs.agentdzialek.pl/errors.md#internal) - `invalid_arguments`: [invalid_arguments](https://docs.agentdzialek.pl/errors.md#invalid_arguments) - `invalid_client`: [invalid_client](https://docs.agentdzialek.pl/errors.md#invalid_client) - `invalid_client_metadata`: [invalid_client_metadata](https://docs.agentdzialek.pl/errors.md#invalid_client_metadata) - `invalid_client_tool`: [invalid_client_tool](https://docs.agentdzialek.pl/errors.md#invalid_client_tool) - `invalid_digest`: [invalid_digest](https://docs.agentdzialek.pl/errors.md#invalid_digest) - `invalid_grant`: [invalid_grant](https://docs.agentdzialek.pl/errors.md#invalid_grant) - `invalid_id`: [invalid_id](https://docs.agentdzialek.pl/errors.md#invalid_id) - `invalid_input`: [invalid_input](https://docs.agentdzialek.pl/errors.md#invalid_input) - `invalid_polygon`: [invalid_polygon](https://docs.agentdzialek.pl/errors.md#invalid_polygon) - `invalid_redirect_uri`: [invalid_redirect_uri](https://docs.agentdzialek.pl/errors.md#invalid_redirect_uri) - `invalid_request`: [invalid_request](https://docs.agentdzialek.pl/errors.md#invalid_request) - `invalid_response`: [invalid_response](https://docs.agentdzialek.pl/errors.md#invalid_response) - `invalid_scope`: [invalid_scope](https://docs.agentdzialek.pl/errors.md#invalid_scope) - `invalid_software_statement`: [invalid_software_statement](https://docs.agentdzialek.pl/errors.md#invalid_software_statement) - `invalid_target`: [invalid_target](https://docs.agentdzialek.pl/errors.md#invalid_target) - `invalid_webhook_url`: [invalid_webhook_url](https://docs.agentdzialek.pl/errors.md#invalid_webhook_url) - `missing_artifact`: [missing_artifact](https://docs.agentdzialek.pl/errors.md#missing_artifact) - `missing_historical_evidence`: [missing_historical_evidence](https://docs.agentdzialek.pl/errors.md#missing_historical_evidence) - `not_covered`: [not_covered](https://docs.agentdzialek.pl/errors.md#not_covered) - `not_found`: [not_found](https://docs.agentdzialek.pl/errors.md#not_found) - `note_required`: [note_required](https://docs.agentdzialek.pl/errors.md#note_required) - `private_content`: [private_content](https://docs.agentdzialek.pl/errors.md#private_content) - `provider_unavailable`: [provider_unavailable](https://docs.agentdzialek.pl/errors.md#provider_unavailable) - `rate_limited`: [rate_limited](https://docs.agentdzialek.pl/errors.md#rate_limited) - `resolution_unavailable`: [resolution_unavailable](https://docs.agentdzialek.pl/errors.md#resolution_unavailable) - `response_too_large`: [response_too_large](https://docs.agentdzialek.pl/errors.md#response_too_large) - `server_error`: [server_error](https://docs.agentdzialek.pl/errors.md#server_error) - `signing_unavailable`: [signing_unavailable](https://docs.agentdzialek.pl/errors.md#signing_unavailable) - `source_unavailable`: [source_unavailable](https://docs.agentdzialek.pl/errors.md#source_unavailable) - `temporarily_unavailable`: [temporarily_unavailable](https://docs.agentdzialek.pl/errors.md#temporarily_unavailable) - `timeout`: [timeout](https://docs.agentdzialek.pl/errors.md#timeout) - `transport_error`: [transport_error](https://docs.agentdzialek.pl/errors.md#transport_error) - `unapproved_software_statement`: [unapproved_software_statement](https://docs.agentdzialek.pl/errors.md#unapproved_software_statement) - `unapproved_source`: [unapproved_source](https://docs.agentdzialek.pl/errors.md#unapproved_source) - `unauthorized`: [unauthorized](https://docs.agentdzialek.pl/errors.md#unauthorized) - `unauthorized_client`: [unauthorized_client](https://docs.agentdzialek.pl/errors.md#unauthorized_client) - `unavailable`: [unavailable](https://docs.agentdzialek.pl/errors.md#unavailable) - `unexpected_continuation`: [unexpected_continuation](https://docs.agentdzialek.pl/errors.md#unexpected_continuation) - `unknown_tool`: [unknown_tool](https://docs.agentdzialek.pl/errors.md#unknown_tool) - `unsafe_event`: [unsafe_event](https://docs.agentdzialek.pl/errors.md#unsafe_event) - `unsupported_grant_type`: [unsupported_grant_type](https://docs.agentdzialek.pl/errors.md#unsupported_grant_type) - `unsupported_legacy_event`: [unsupported_legacy_event](https://docs.agentdzialek.pl/errors.md#unsupported_legacy_event) - `unsupported_response_type`: [unsupported_response_type](https://docs.agentdzialek.pl/errors.md#unsupported_response_type) - `validation_work_limit`: [validation_work_limit](https://docs.agentdzialek.pl/errors.md#validation_work_limit) - `watch_limit`: [watch_limit](https://docs.agentdzialek.pl/errors.md#watch_limit) - `watch_unavailable`: [watch_unavailable](https://docs.agentdzialek.pl/errors.md#watch_unavailable) - `webhook_unconfigured`: [webhook_unconfigured](https://docs.agentdzialek.pl/errors.md#webhook_unconfigured) # Envelope Każda odpowiedź /v1, udana lub błędna, przez REST lub MCP, ma format Envelope. Niejednoznaczność nie jest błędem: zwracane są HTTP 200, status ambiguous i kandydaci. Wartości nie są zgadywane: gdy państwo nie publikuje danych, coverage wynosi not_covered, a value jest null. Pole billing wskazuje naliczone i zwrócone opłaty oraz zastosowaną regułę. Dokumentacja: docs/landfeed/README.md, krok 1; uzasadnienie: context/research/cenogram-teardown-2026-10-12.md, części 8 i 9. Wersja kontraktu 2.0.0 dodaje wymagania: meta.contract_version włącza obowiązkowe informacje o pochodzeniu danych v2, a przestrzeń adresów HTTP i meta.api_version pozostają v1. Zgodność ze starszą wersją nie uprawnia do udostępniania danych z niezatwierdzonych źródeł. ## Cost and inputs Envelope cost depends on the operation. Example `GET /v1/parcel`: `x-request-cost`: 1 request per call. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\p{L}\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Errors and ambiguity Każdy błąd wskazuje dalszy krok: zawsze zawiera hint i odnośnik do dokumentacji, przykładowe id przy zapytaniu o działkę oraz signup_url przy HTTP 401. ```json { "additionalProperties": false, "description": "Każdy błąd wskazuje dalszy krok: zawsze zawiera hint i odnośnik do dokumentacji, przykładowe id przy zapytaniu o działkę oraz signup_url przy HTTP 401.", "properties": { "code": { "description": "invalid_input 400 (brak lub kilka parametrów q|id|point, błędne id lub point; bezpłatne). not_found 404 (zwrot opłaty). ambiguous 200 (odpowiada statusowi; lista kandydatów). not_covered 200 (rozpoznano miejsce poza załadowanym zakresem danych; zwrot opłaty). unauthorized 401 (brak lub błędny X-Api-Key; bezpłatne). rate_limited 429. source_unavailable 503 (błąd źródła odpytywanego podczas żądania; zwrot opłaty). internal 500 (zwrot opłaty).", "enum": [ "invalid_input", "not_found", "ambiguous", "not_covered", "unauthorized", "rate_limited", "source_unavailable", "internal" ], "type": "string" }, "docs": { "type": "string" }, "example_id": { "description": "Poprawny identyfikator w ujednoliconej postaci, np. „146501_1.0101.12/3”.", "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "hint": { "description": "Wskazówka dotycząca dalszego wywołania, np. „Przekaż dokładnie jeden parametr: q, id albo point” lub „Dodaj nazwę lub numer obrębu”.", "minLength": 1, "type": "string" }, "message": { "description": "Jedno zdanie, które agent może przekazać użytkownikowi.", "type": "string" }, "signup_url": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "hint", "docs" ], "type": "object" } ``` ## Status ok: wynik obecny (HTTP 200). ambiguous: result=null, niepusta lista kandydatów (200, naliczana opłata). not_found: brak dopasowania do danych wejściowych (404, zwrot opłaty). not_covered: rozpoznano miejsce, ale nie obejmuje go żaden załadowany zbiór ani źródło (200, result=null, zwrot opłaty). error: zobacz error.code. ```json { "description": "ok: wynik obecny (HTTP 200). ambiguous: result=null, niepusta lista kandydatów (200, naliczana opłata). not_found: brak dopasowania do danych wejściowych (404, zwrot opłaty). not_covered: rozpoznano miejsce, ale nie obejmuje go żaden załadowany zbiór ani źródło (200, result=null, zwrot opłaty). error: zobacz error.code.", "enum": [ "ok", "ambiguous", "not_found", "not_covered", "error" ], "type": "string" } ``` ## Candidates not specified in the source contract ```json { "additionalProperties": false, "properties": { "area_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "#/$defs/LonLat" }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Gmina administracyjna (admin_gmina_teryt, ostatnia cyfra 1, 2 lub 3), której kod przyjmuje /v1/gminy/{teryt}/planning. Jednostka TERYT w identyfikatorze działki jest inna dla typów jednostek 4, 5, 8 i 9.", "pattern": "^[0-9]{7}$", "type": "string" }, "held": { "default": true, "description": "Wartość false, gdy kandydat występuje w rejestrze krajowym, lecz jego zbioru danych jeszcze nie załadowano.", "type": "boolean" }, "id": { "description": "Ujednolicony ParcelId dla kind=parcel, siedmioznakowy TERYT dla kind=gmina lub identyfikator obrębu dla kind=obreb.", "type": "string" }, "kind": { "enum": [ "parcel", "obreb", "gmina", "address" ], "type": "string" }, "label": { "description": "Czytelna etykieta, np. „dz. 284/5, obręb Pogorzelec, gm. Pogorzela (pow. gostyński)”.", "type": "string" }, "match_reason": { "description": "Informacja o dopasowanych częściach zapytania, np. „miejscowość dopasowana w przybliżeniu: Lesnowola na Lesznowola (odległość 1), numer dopasowany dokładnie”.", "type": "string" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": "string" }, "powiat_name": { "type": "string" }, "voivodeship": { "pattern": "^[0-9]{2}$", "type": "string" } }, "required": [ "id", "kind", "label", "confidence" ], "type": "object" } ``` ## Pagination Stronicowanie list wyników za pomocą kursora (search, events, sources). ```json { "additionalProperties": false, "description": "Stronicowanie list wyników za pomocą kursora (search, events, sources).", "properties": { "has_more": { "type": "boolean" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "has_more", "next_cursor" ], "type": "object" } ``` ## Layer frame Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` ## Source attribution Pozycja /v1/sources cytowana w odpowiedzi tematycznej. as_of to data danych źródłowych z ostatniej udanej aktualizacji, a nie czas żądania. ```json { "additionalProperties": false, "description": "Pozycja /v1/sources cytowana w odpowiedzi tematycznej. as_of to data danych źródłowych z ostatniej udanej aktualizacji, a nie czas żądania.", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "attribution": { "type": "string" }, "fallback": { "default": false, "description": "Wartość true, gdy to źródło udzieliło odpowiedzi z powodu braku rekordu w źródle podstawowym, np. własny przegląd planów ogólnych przy braku wpisu w Rejestrze Urbanistycznym.", "type": "boolean" }, "id": { "description": "Identyfikator źródła: source_status.source_id.", "type": "string" }, "licence": { "type": "string" }, "publisher": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "attribution", "as_of" ], "type": "object" } ``` ## ETag and caching ### ETag Dla GET według id (parcel, check, layer). Przekaż tę wartość jako If-None-Match. Obejmuje dokładnie treść odpowiedzi, bez pominiętych danych. Każda wcześniej obliczona kategoria w odpowiedzi (pog, wz, mpzp, flood, landslide, protected, buildings) wnosi L_hash i L_version z parcel_record; not_computed wnosi znacznik null. Każda kategoria ustalana podczas żądania (permits, prices, road_access, soil) wnosi as_of źródła i datę odpowiedzi (UTC, YYYY-MM-DD); cały ETag jest wtedy słaby, W/"...", i zmienia się co najmniej raz na dobę nawet bez zmian w źródle. ETag obejmuje też żądany zestaw kategorii i tryb geometrii, więc layers=flood i pełna karta nigdy nie mają wspólnego ETag. Odpowiedź wyłącznie z wcześniej obliczonych danych ma silny ETag, zmieniający się tylko po zmianie objętego nim skrótu lub wersji. /v1/check zawsze zawiera road_access, więc jego ETag jest zawsze słaby. If-None-Match stosuje słabe porównanie (RFC 9110 13.1.2): słaby ETag nadal pozwala uzyskać HTTP 304 w tym samym dniu. ```json { "description": "Dla GET według id (parcel, check, layer). Przekaż tę wartość jako If-None-Match. Obejmuje dokładnie treść odpowiedzi, bez pominiętych danych. Każda wcześniej obliczona kategoria w odpowiedzi (pog, wz, mpzp, flood, landslide, protected, buildings) wnosi L_hash i L_version z parcel_record; not_computed wnosi znacznik null. Każda kategoria ustalana podczas żądania (permits, prices, road_access, soil) wnosi as_of źródła i datę odpowiedzi (UTC, YYYY-MM-DD); cały ETag jest wtedy słaby, W/\"...\", i zmienia się co najmniej raz na dobę nawet bez zmian w źródle. ETag obejmuje też żądany zestaw kategorii i tryb geometrii, więc layers=flood i pełna karta nigdy nie mają wspólnego ETag. Odpowiedź wyłącznie z wcześniej obliczonych danych ma silny ETag, zmieniający się tylko po zmianie objętego nim skrótu lub wersji. /v1/check zawsze zawiera road_access, więc jego ETag jest zawsze słaby. If-None-Match stosuje słabe porównanie (RFC 9110 13.1.2): słaby ETag nadal pozwala uzyskać HTTP 304 w tym samym dniu.", "schema": { "type": "string" } } ``` ### CacheControl W uwierzytelnionych odpowiedziach zawsze private, max-age=0, must-revalidate, nigdy public. ```json { "description": "W uwierzytelnionych odpowiedziach zawsze private, max-age=0, must-revalidate, nigdy public.", "schema": { "type": "string" } } ``` ### XRequestCost Wartość x-request-cost operacji. ```json { "description": "Wartość x-request-cost operacji.", "schema": { "type": "integer" } } ``` ### XCreditsCharged Ta sama wartość co billing.charged. ```json { "description": "Ta sama wartość co billing.charged.", "schema": { "type": "integer" } } ``` ### XCreditsRefunded Ta sama wartość co billing.refunded. ```json { "description": "Ta sama wartość co billing.refunded.", "schema": { "type": "integer" } } ``` ### 304 ```json { "description": "If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } } } ``` ## Complete envelope schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `auth` | no | `{"additionalProperties": false, "properties": {"kind": {"enum": ["api_key", "oauth_connector"], "type": "string"}}, "required": ["kind"], "type": "object"}` | Obie metody korzystają z tego samego salda kredytów konta; połączenie nie ma osobnego salda. | | `billing` | yes | `{"additionalProperties": false, "properties": {"charged": {"minimum": 0, "type": "integer"}, "cost": {"description": "Wartość x-request-cost danej operacji; w operacji zbiorczej liczona na element.", "minimum": 0, "type": "integer"}, "credits": {"description": "Liczba zużytych kredytów konta po zwrotach, równa charged. Jedno wywołanie lub arkusz = 1; eksport = ceil(rows/100); operacja zbiorcza = jeden kredyt na identyfikator, pomniejszony o zwroty dla elementów. Odmowy i niedostępne odpowiedzi nie zużywają kredytów. Klucz API i połączenie korzystają z tego samego konta.", "minimum": 0, "type": "integer"}, "refunded": {"minimum": 0, "type": "integer"}, "rule": {"enum": ["charged", "free_operation", "free_invalid_input", "free_unauthorized", "free_not_modified", "refunded_client_error", "refunded_server_error", "refunded_not_covered", "refunded_not_computed", "batch_mixed"], "type": "string"}}, "required": ["cost", "charged", "refunded", "rule"], "type": "object"}` | Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. | | `candidates` | yes | `{"items": {"oneOf": [{"$ref": "#/$defs/Candidate"}, {"$ref": "#/$defs/ListingCandidate"}]}, "type": "array"}` | Lista niepusta przy statusie ambiguous i zawsze zwracana przez /v1/resolve. Kandydaci są uporządkowani malejąco według pewności dopasowania. Agent ponawia wywołanie z id= albo pokazuje listę użytkownikowi; nigdy nie wybiera bez jego wiedzy. | | `corpus_coverage` | no | `{"additionalProperties": false, "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "held_parcels": {"type": "integer"}, "held_pct": {"maximum": 100, "minimum": 0, "type": ["number", "null"]}, "note": {"type": "string"}, "scope": {"description": "national, kod województwa albo siedmioznakowy TERYT gminy.", "type": "string"}, "source_parcels": {"type": ["integer", "null"]}}, "required": ["scope", "source_parcels", "held_parcels", "held_pct", "as_of", "note"], "type": "object"}` | Zakres posiadanych danych z danego rejestru, pozwalający odróżnić brak wyniku od braku załadowanych danych. Zwracany przy rozpoznawaniu oraz przy każdym statusie not_found lub not_covered. | | `coverage_summary` | no | `{"additionalProperties": false, "properties": {"generated_at": {"format": "date-time", "type": "string"}, "gminas": {"minimum": 0, "type": "integer"}, "layers": {"additionalProperties": false, "properties": {"buildings": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "flood": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "landslide": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "mpzp": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "parcel": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "pog": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "protected": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}, "wz": {"additionalProperties": false, "properties": {"gminas": {"minimum": 0, "type": "integer"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of"], "type": "object"}}, "required": ["parcel", "pog", "wz", "mpzp", "flood", "landslide", "protected", "buildings"], "type": "object"}, "line": {"minLength": 1, "type": "string"}, "newest_as_of": {"format": "date", "type": ["string", "null"]}, "note": {"minLength": 1, "type": "string"}, "oldest_as_of": {"format": "date", "type": ["string", "null"]}, "unmeasured_layers": {"items": {"$ref": "#/$defs/LayerKey"}, "type": "array", "uniqueItems": true}, "voivodeships": {"maximum": 16, "minimum": 0, "type": "integer"}}, "required": ["gminas", "voivodeships", "oldest_as_of", "newest_as_of", "layers", "unmeasured_layers", "generated_at", "line", "note"], "type": "object"}` | not specified in the source contract | | `error` | yes | `{"oneOf": [{"type": "null"}, {"$ref": "#/$defs/Error"}]}` | not specified in the source contract | | `links` | no | `{"additionalProperties": {"$ref": "#/$defs/Link"}, "properties": {"map": {"$ref": "#/$defs/Link"}, "sheet": {"anyOf": [{"$ref": "#/$defs/Link"}, {"$ref": "#/$defs/SignedLink"}]}, "tiles": {"$ref": "#/$defs/Link"}}, "type": "object"}` | Dalsze wywołania, które agent może zaplanować, wraz z kosztem każdego z nich, np. {"check": {"href": "/v1/check?id=...", "cost": 1}}. | | `meta` | yes | `{"additionalProperties": false, "properties": {"api_version": {"const": "v1", "type": "string"}, "calls": {"description": "Liczba żądań potrzebnych do uzyskania odpowiedzi. Zawsze 1 dla pojedynczego odczytu; sprawdzane w teście pomiarowym.", "minimum": 1, "type": "integer"}, "contract_version": {"const": "2.0.0"}, "disclaimer": {"type": ["string", "null"]}, "etag": {"description": "Ta sama wartość co nagłówek ETag przy GET według id. Zakres i warunki słabego znacznika (W/): openapi.yaml components.headers.ETag.", "type": ["string", "null"]}, "excluded": {"description": "Pola wyłączone z udostępniania: numery KW, dane właścicieli i władających, nazwy inwestorów oraz ceny transakcyjne powiązane z konkretnym adresem.", "items": {"type": "string"}, "type": "array"}, "generated_at": {"format": "date-time", "type": "string"}, "operation": {"enum": ["parcel", "layer", "check", "resolve", "resolve_listing", "search", "events", "check_batch", "check_job", "check_results", "sources", "planning"], "type": "string"}, "request_id": {"type": "string"}}, "required": ["request_id", "api_version", "generated_at", "calls"], "type": "object"}` | not specified in the source contract | | `needs_obreb` | no | `{"default": false, "type": "boolean"}` | Wartość true, gdy numer działki występuje w kilku obrębach rozpoznanej gminy, a dane wejściowe nie wskazują jednego z nich. | | `page` | no | `{"additionalProperties": false, "properties": {"has_more": {"type": "boolean"}, "limit": {"maximum": 1000, "minimum": 1, "type": "integer"}, "next_cursor": {"type": ["string", "null"]}}, "required": ["limit", "has_more", "next_cursor"], "type": "object"}` | Stronicowanie list wyników za pomocą kursora (search, events, sources). | | `plan` | no | `{"enum": ["free", "start", "pro", "team", "developer", "platform"], "type": "string"}` | not specified in the source contract | | `query` | yes | `{"additionalProperties": false, "allOf": [{"if": {"not": {"required": ["kind"]}}, "then": {"properties": {"input": {"$ref": "#/$defs/QueryInput"}}}}, {"if": {"properties": {"kind": {"const": "q"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/QueryInput", "required": ["q"]}}}}, {"if": {"properties": {"kind": {"const": "id"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/QueryInput", "required": ["id"]}}}}, {"if": {"properties": {"kind": {"const": "point"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/QueryInput", "anyOf": [{"required": ["point"]}, {"required": ["lat", "lng"]}]}}}}, {"if": {"properties": {"kind": {"enum": ["none", "bbox", "polygon", "path"]}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/NoQueryInput"}}}}, {"if": {"properties": {"kind": {"const": "bbox"}}, "required": ["kind"]}, "then": {"properties": {"input": {"required": ["bbox"]}}}}, {"if": {"properties": {"kind": {"const": "polygon"}}, "required": ["kind"]}, "then": {"properties": {"input": {"required": ["polygon"]}}}}, {"if": {"properties": {"kind": {"const": "path"}}, "required": ["kind"]}, "then": {"properties": {"input": {"required": ["teryt"]}}}}, {"if": {"properties": {"kind": {"const": "batch"}}, "required": ["kind"]}, "then": {"properties": {"input": {"properties": {"items": {"maxItems": 1000, "minItems": 1, "type": "array"}}, "required": ["items"]}}}}, {"if": {"properties": {"kind": {"const": "search"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/SearchRequestV2"}}}}, {"if": {"properties": {"kind": {"const": "events"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/EventsRequestV2"}}}}, {"if": {"properties": {"kind": {"const": "listing"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/ListingResolveRequest"}}}}, {"if": {"properties": {"kind": {"const": "check_batch"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/BatchCheckRequest"}}}}, {"if": {"properties": {"kind": {"const": "job"}}, "required": ["kind"]}, "then": {"properties": {"input": {"$ref": "#/$defs/JobQuery"}}}}], "properties": {"input": {"additionalProperties": true, "description": "Parametry wejściowe w otrzymanej postaci. Obiekt dopuszcza też pozostałe parametry żądania, np. layers, limit, cursor i radius_m.", "type": "object"}, "kind": {"description": "q, id, point: jeden poprawny wariant q\|id\|point (point obejmuje też parę lat+lng). none: brak q\|id\|point, np. GET /v1/sources bez danych wejściowych. bbox: GET /v1/search?bbox. polygon: POST /v1/search. path: odczyt według parametru ścieżki, input {teryt} dla /v1/gminy/{teryt}/planning. batch: POST /v1/parcel/batch, input {items, ...}; odpowiedź każdego elementu określa własny kind. invalid: HTTP 400 z danymi, które nie przeszły walidacji (np. q i id jednocześnie lub błędne id); wyłącznie przy statusie error.", "enum": ["q", "id", "point", "none", "bbox", "polygon", "path", "batch", "invalid", "search", "events", "listing", "check_batch", "job"], "type": "string"}, "resolved": {"description": "Sposób rozpoznania działki lub gminy na podstawie danych wejściowych. Wartość null przy statusie ambiguous lub not_found.", "oneOf": [{"type": "null"}, {"additionalProperties": false, "properties": {"confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "from": {"enum": ["q", "id", "point"], "type": "string"}, "id": {"type": "string"}, "method": {"enum": ["exact_id", "normalised_id", "text_parcel", "text_parcel_fuzzy", "text_address", "text_gmina", "point_in_polygon"], "type": "string"}, "note": {"description": "Założenie przyjęte podczas rozpoznawania, np. „Lesnowola odczytano jako Lesznowola (dopasowanie przybliżone, obniżona pewność)”.", "type": ["string", "null"]}}, "required": ["from", "method", "id", "confidence"], "type": "object"}]}}, "required": ["input", "resolved"], "type": "object"}` | Przekazane zapytanie i sposób jego rozpoznania. kind określa postać danych wejściowych; input zawiera otrzymane parametry zapytania, ścieżki lub treści żądania, więc błędne dane są powtarzane dokładnie w otrzymanej postaci. Bez kind pole input musi być poprawnym QueryInput, używanym już w każdym odczycie q\|id\|point. | | `result` | yes | `{"type": ["object", "array", "null"]}` | Dane właściwe dla danego punktu API (openapi.yaml). Wartość null, gdy status jest inny niż ok. | | `search_facets` | no | `{"additionalProperties": false, "properties": {"filters": {"additionalProperties": {"$ref": "#/$defs/FeatureFilterFacet"}, "propertyNames": {"enum": ["area_min_m2", "area_max_m2", "land_use_class", "shape_regularity_min", "frontage_min_m", "road_access", "buildings_present", "public_road_max_m", "rcn_price_min_pln_m2", "rcn_price_max_pln_m2", "gunb_activity_min", "pog_zone_class"]}, "type": "object"}, "matched_count": {"minimum": 0, "type": "integer"}, "scope_count": {"minimum": 0, "type": "integer"}}, "required": ["scope_count", "matched_count", "filters"], "type": "object"}` | not specified in the source contract | | `sources` | yes | `{"items": {"$ref": "#/$defs/SourceRef"}, "type": "array"}` | Wszystkie źródła wykorzystane do ustalenia wyniku, bez powtórzeń. Każda odpowiedź tematyczna wskazuje także własne źródło. | | `status` | yes | `{"enum": ["ok", "ambiguous", "not_found", "not_covered", "error"], "type": "string"}` | ok: wynik obecny (HTTP 200). ambiguous: result=null, niepusta lista kandydatów (200, naliczana opłata). not_found: brak dopasowania do danych wejściowych (404, zwrot opłaty). not_covered: rozpoznano miejsce, ale nie obejmuje go żaden załadowany zbiór ani źródło (200, result=null, zwrot opłaty). error: zobacz error.code. | ```json { "$defs": { "AreaV2": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "official_m2": { "exclusiveMinimum": 0, "type": "number" } } }, "if": { "properties": { "source": { "const": "computed" } } }, "then": { "properties": { "note": { "const": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna." }, "official_m2": { "type": "null" } } } } ], "properties": { "geometry_m2": { "exclusiveMinimum": 0, "type": "number" }, "note": { "minLength": 1, "type": "string" }, "official_m2": { "anyOf": [ { "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ] }, "provenance": { "$ref": "#/$defs/SourceRef" }, "source": { "enum": [ "egib", "computed" ], "type": "string" } }, "required": [ "official_m2", "geometry_m2", "source", "provenance", "note" ], "type": "object" }, "AskCall": { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "layer": { "$ref": "#/$defs/LayerKey" }, "layers": { "items": { "$ref": "#/$defs/LayerKey" }, "maxItems": 16, "minItems": 1, "type": "array", "uniqueItems": true }, "limit": { "maximum": 20, "minimum": 1, "type": "integer" }, "point": { "maxLength": 70, "minLength": 3, "type": "string" }, "polygon": { "$ref": "#/$defs/SearchPolygon" }, "q": { "maxLength": 500, "minLength": 1, "type": "string" }, "radius_m": { "maximum": 2000, "minimum": 0, "type": "integer" }, "since": { "maxLength": 10, "type": "string" } }, "type": "object" }, "charged": { "maximum": 20, "minimum": 0, "type": "integer" }, "cost": { "maximum": 20, "minimum": 0, "type": "integer" }, "id": { "pattern": "^t[1-9][0-9]*$", "type": "string" }, "operation": { "type": "string" }, "refunded": { "maximum": 20, "minimum": 0, "type": "integer" }, "status": { "type": "string" }, "tool": { "enum": [ "resolve", "check", "parcel", "search", "events", "sources" ] } }, "required": [ "id", "tool", "operation", "status", "cost", "charged", "refunded", "arguments" ], "type": "object" }, "AskCitation": { "additionalProperties": false, "properties": { "answer_sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "as_of": { "format": "date", "type": [ "string", "null" ] }, "call_id": { "pattern": "^t[1-9][0-9]*$", "type": "string" }, "coverage": { "enum": [ "covered", "covered_no_data", "not_covered", "not_computed" ] }, "id": { "pattern": "^c[1-9][0-9]*$", "type": "string" }, "layer_key": { "maxLength": 80, "minLength": 1, "type": "string" }, "method": { "type": [ "string", "null" ] }, "pointer": { "pattern": "^/", "type": "string" }, "scope": { "type": [ "string", "null" ] }, "source": { "$ref": "#/$defs/SourceRef" } }, "required": [ "id", "call_id", "pointer", "answer_sha256", "layer_key", "source", "as_of", "coverage", "scope", "method" ], "type": "object" }, "AskClientTool": { "additionalProperties": false, "properties": { "description": { "maxLength": 500, "minLength": 1, "type": "string" }, "input_schema": { "maxProperties": 32, "type": "object" }, "name": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" } }, "required": [ "name", "description", "input_schema" ], "type": "object" }, "AskContinuation": { "additionalProperties": false, "properties": { "digest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "state": { "type": "object" } }, "required": [ "state", "digest" ], "type": "object" }, "AskEvent": { "description": "Format SSE: event: \\ndata: \\n\\n. Każdy przyjęty strumień kończy dokładnie jedno done; może je poprzedzać error. Kroki są zapowiadane przed wykonaniem publicznej operacji. Wyniki zawierają dokładne treści publicznych odpowiedzi.", "oneOf": [ { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "estimated_credits": { "maximum": 20, "minimum": 0, "type": "integer" }, "label": { "maxLength": 300, "minLength": 1, "type": "string" }, "request": { "additionalProperties": false, "properties": { "body": { "type": [ "object", "null" ] }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "pattern": "^/v1/", "type": "string" }, "query": { "type": "object" } }, "required": [ "method", "path", "query", "body" ], "type": "object" }, "step_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "tool": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "step_id", "tool", "label", "request", "estimated_credits" ], "type": "object" }, "event": { "const": "step.started" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "artifact_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "credits_charged": { "maximum": 20, "minimum": 0, "type": "integer" }, "duration_ms": { "minimum": 0, "type": "integer" }, "status": { "maxLength": 80, "minLength": 1, "type": "string" }, "step_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "step_id", "status", "credits_charged", "duration_ms" ], "type": "object" }, "event": { "const": "step.finished" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "$ref": "#/$defs/AskSignedResult" }, "event": { "const": "artifact" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "text": { "maxLength": 24000, "minLength": 1, "type": "string" } }, "required": [ "text" ], "type": "object" }, "event": { "const": "answer.delta" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "artifact_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "as_of": { "format": "date", "type": [ "string", "null" ] }, "citation_id": { "minimum": 1, "type": "integer" }, "layer": { "maxLength": 80, "minLength": 1, "type": "string" }, "source": { "$ref": "#/$defs/SourceRef" } }, "required": [ "citation_id", "artifact_id", "source", "as_of" ], "type": "object" }, "maxItems": 40, "type": "array" }, "event": { "const": "answer.citations" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "arguments": { "type": "object" }, "call_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "name": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "call_id", "name", "arguments" ], "type": "object" }, "event": { "const": "client_tool.call" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "action": { "maxLength": 64, "minLength": 1, "type": "string" }, "credits": { "maximum": 20, "minimum": 0, "type": "integer" }, "label": { "maxLength": 300, "minLength": 1, "type": "string" }, "step_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "step_id", "action", "label", "credits" ], "type": "object" }, "event": { "const": "confirm.required" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "max_credits": { "maximum": 20, "minimum": 0, "type": "integer" }, "needed": { "maximum": 1000, "minimum": 1, "type": "integer" }, "plan": { "items": { "additionalProperties": false, "properties": { "estimated_credits": { "maximum": 20, "minimum": 0, "type": "integer" }, "label": { "maxLength": 300, "minLength": 1, "type": "string" }, "request": { "additionalProperties": false, "properties": { "body": { "type": [ "object", "null" ] }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "pattern": "^/v1/", "type": "string" }, "query": { "type": "object" } }, "required": [ "method", "path", "query", "body" ], "type": "object" }, "step_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "tool": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "step_id", "tool", "label", "request", "estimated_credits" ], "type": "object" }, "maxItems": 12, "type": "array" } }, "required": [ "needed", "max_credits", "plan" ], "type": "object" }, "event": { "const": "budget.exceeded" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "continuation": { "anyOf": [ { "$ref": "#/$defs/AskContinuation" }, { "type": "null" } ] }, "credits_total": { "maximum": 20, "minimum": 0, "type": "integer" } }, "required": [ "credits_total", "continuation" ], "type": "object" }, "event": { "const": "done" } }, "required": [ "event", "data" ], "type": "object" }, { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "code": { "maxLength": 80, "minLength": 1, "type": "string" }, "message": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "message", "code" ], "type": "object" }, "event": { "const": "error" } }, "required": [ "event", "data" ], "type": "object" } ] }, "AskRequest": { "additionalProperties": false, "properties": { "client_results": { "items": { "additionalProperties": false, "properties": { "call_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "result": { "type": "object" } }, "required": [ "call_id", "result" ], "type": "object" }, "maxItems": 1, "type": "array" }, "client_tools": { "items": { "$ref": "#/$defs/AskClientTool" }, "maxItems": 12, "type": "array" }, "confirmation": { "additionalProperties": false, "properties": { "approved": { "type": "boolean" }, "step_id": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "step_id", "approved" ], "type": "object" }, "context": { "additionalProperties": false, "maxProperties": 1, "minProperties": 1, "properties": { "area": { "$ref": "#/$defs/SearchPolygon" }, "parcel_id": { "$ref": "#/$defs/ParcelIdInput" }, "search_query": { "maxLength": 500, "minLength": 1, "type": "string" }, "watch_id": { "format": "uuid", "type": "string" } }, "required": [], "type": "object" }, "continuation": { "$ref": "#/$defs/AskContinuation" }, "max_credits": { "default": 5, "maximum": 20, "minimum": 1, "type": "integer" }, "messages": { "items": { "$ref": "#/$defs/AskTurn" }, "maxItems": 100, "type": "array" }, "question": { "maxLength": 2000, "minLength": 1, "type": "string" }, "results": { "items": { "$ref": "#/$defs/AskSignedResult" }, "maxItems": 40, "type": "array" }, "version": { "const": "ask-v2" } }, "required": [ "question" ], "type": "object" }, "AskResponse": { "additionalProperties": false, "properties": { "answer": { "maxLength": 24000, "type": "string" }, "billing": { "$ref": "#/$defs/BillingV2" }, "calls": { "items": { "$ref": "#/$defs/AskCall" }, "maxItems": 12, "type": "array" }, "citations": { "items": { "$ref": "#/$defs/AskCitation" }, "maxItems": 40, "type": "array" }, "continuation": { "anyOf": [ { "$ref": "#/$defs/AskContinuation" }, { "type": "null" } ] }, "events": { "items": { "$ref": "#/$defs/AskEvent" }, "maxItems": 150, "type": "array" }, "max_credits": { "maximum": 20, "minimum": 1, "type": "integer" }, "meta": { "additionalProperties": false, "properties": { "contract_version": { "const": "2.0.0" }, "prompt_version": { "enum": [ "ask-v1", "ask-v2" ] }, "request_id": { "format": "uuid", "type": "string" }, "tools_version": { "enum": [ "ask-tools-v1", "ask-tools-v2" ] } }, "required": [ "request_id", "contract_version", "prompt_version", "tools_version" ], "type": "object" }, "missing": { "items": { "maxLength": 200, "type": "string" }, "maxItems": 20, "type": "array" }, "status": { "enum": [ "answered", "incomplete", "budget_exhausted", "unavailable", "insufficient_credits", "refused", "error" ] } }, "required": [ "status", "answer", "citations", "calls", "missing", "max_credits", "billing", "meta" ], "type": "object" }, "AskSignedResult": { "additionalProperties": false, "properties": { "artifact_id": { "maxLength": 80, "minLength": 1, "type": "string" }, "data": { "type": "object" }, "digest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" }, "type": { "enum": [ "parcel_card", "search_results", "watch_list", "events", "api_snippet", "coverage" ] } }, "required": [ "artifact_id", "type", "title", "data", "digest" ], "type": "object" }, "AskTurn": { "additionalProperties": false, "properties": { "artifact_ids": { "items": { "maxLength": 80, "minLength": 1, "type": "string" }, "maxItems": 40, "type": "array" }, "content": { "maxLength": 24000, "minLength": 1, "type": "string" }, "role": { "enum": [ "user", "assistant" ] } }, "required": [ "role", "content" ], "type": "object" }, "Auth": { "additionalProperties": false, "description": "Obie metody korzystają z tego samego salda kredytów konta; połączenie nie ma osobnego salda.", "properties": { "kind": { "enum": [ "api_key", "oauth_connector" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "BatchCheckItem": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "result": { "type": "null" } } }, "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "error": { "type": "null" }, "result": { "$ref": "#/$defs/CheckResultV2" } } } }, { "if": { "properties": { "status": { "const": "error" } } }, "then": { "properties": { "error": { "$ref": "#/$defs/Error" } } } } ], "properties": { "billing": { "allOf": [ { "$ref": "#/$defs/BillingV2" }, { "properties": { "cost": { "const": 1 } } } ] }, "error": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ] }, "parcel_id": { "$ref": "#/$defs/ParcelId" }, "result": { "anyOf": [ { "$ref": "#/$defs/CheckResultV2" }, { "type": "null" } ] }, "status": { "enum": [ "ok", "not_found", "not_covered", "error" ], "type": "string" } }, "required": [ "parcel_id", "status", "result", "billing", "error" ], "type": "object" }, "BatchCheckJob": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "state": { "const": "completed" } } }, "then": { "properties": { "error": { "type": "null" }, "results_url": { "pattern": "^/v1/check/jobs/[^/]+/results$", "type": "string" } } } }, { "if": { "properties": { "state": { "const": "failed" } } }, "then": { "properties": { "error": { "$ref": "#/$defs/Error" } } } } ], "properties": { "completed": { "maximum": 10000, "minimum": 0, "type": "integer" }, "error": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ] }, "id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "results_url": { "anyOf": [ { "pattern": "^/v1/check/jobs/[^/]+/results$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "completed", "failed" ], "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" }, "total": { "maximum": 10000, "minimum": 1, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "state", "submitted_at", "updated_at", "total", "completed", "results_url", "error" ], "type": "object" }, "BatchCheckRequest": { "additionalProperties": false, "description": "Zarezerwowany kontrakt, niedostępny w bieżącej usłudze. POST /v1/check z Idempotency-Key; 1 kredyt za identyfikator po ukończeniu według dotychczasowych zwrotów za element. Zlecenie i odpytywanie są bezpłatne. To samo konto, klucz i treść zwracają to samo zadanie bez ponownej opłaty; inna treść z tym samym kluczem oznacza 409 i zwrot. Klucze są zachowywane co najmniej 24 godziny po zakończeniu zadania.", "properties": { "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "parcel_ids" ], "type": "object", "x-runtime-supported": false }, "BatchCheckResults": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/$defs/BatchCheckItem" }, "maxItems": 1000, "type": "array" }, "job_id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "page": { "$ref": "#/$defs/Page" } }, "required": [ "job_id", "items", "page" ], "type": "object" }, "BatchCheckSubmission": { "additionalProperties": false, "description": "Sprawdzenie na poziomie protokołu, czy sama treść żądania nie jest traktowana jako poprawne zgłoszenie zbiorcze.", "properties": { "body": { "$ref": "#/$defs/BatchCheckRequest" }, "headers": { "additionalProperties": false, "properties": { "Idempotency-Key": { "$ref": "#/$defs/IdempotencyKey" } }, "required": [ "Idempotency-Key" ], "type": "object" } }, "required": [ "headers", "body" ], "type": "object" }, "Billing": { "additionalProperties": false, "description": "Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów.", "properties": { "charged": { "minimum": 0, "type": "integer" }, "cost": { "description": "Wartość x-request-cost danej operacji; w operacji zbiorczej liczona na element.", "minimum": 0, "type": "integer" }, "credits": { "description": "Liczba zużytych kredytów konta po zwrotach, równa charged. Jedno wywołanie lub arkusz = 1; eksport = ceil(rows/100); operacja zbiorcza = jeden kredyt na identyfikator, pomniejszony o zwroty dla elementów. Odmowy i niedostępne odpowiedzi nie zużywają kredytów. Klucz API i połączenie korzystają z tego samego konta.", "minimum": 0, "type": "integer" }, "refunded": { "minimum": 0, "type": "integer" }, "rule": { "enum": [ "charged", "free_operation", "free_invalid_input", "free_unauthorized", "free_not_modified", "refunded_client_error", "refunded_server_error", "refunded_not_covered", "refunded_not_computed", "batch_mixed" ], "type": "string" } }, "required": [ "cost", "charged", "refunded", "rule" ], "type": "object" }, "BillingV2": { "allOf": [ { "$ref": "#/$defs/Billing" }, { "required": [ "credits" ] } ] }, "Candidate": { "additionalProperties": false, "properties": { "area_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "#/$defs/LonLat" }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Gmina administracyjna (admin_gmina_teryt, ostatnia cyfra 1, 2 lub 3), której kod przyjmuje /v1/gminy/{teryt}/planning. Jednostka TERYT w identyfikatorze działki jest inna dla typów jednostek 4, 5, 8 i 9.", "pattern": "^[0-9]{7}$", "type": "string" }, "held": { "default": true, "description": "Wartość false, gdy kandydat występuje w rejestrze krajowym, lecz jego zbioru danych jeszcze nie załadowano.", "type": "boolean" }, "id": { "description": "Ujednolicony ParcelId dla kind=parcel, siedmioznakowy TERYT dla kind=gmina lub identyfikator obrębu dla kind=obreb.", "type": "string" }, "kind": { "enum": [ "parcel", "obreb", "gmina", "address" ], "type": "string" }, "label": { "description": "Czytelna etykieta, np. „dz. 284/5, obręb Pogorzelec, gm. Pogorzela (pow. gostyński)”.", "type": "string" }, "match_reason": { "description": "Informacja o dopasowanych częściach zapytania, np. „miejscowość dopasowana w przybliżeniu: Lesnowola na Lesznowola (odległość 1), numer dopasowany dokładnie”.", "type": "string" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": "string" }, "powiat_name": { "type": "string" }, "voivodeship": { "pattern": "^[0-9]{2}$", "type": "string" } }, "required": [ "id", "kind", "label", "confidence" ], "type": "object" }, "CheckResultV2": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "verdict": { "const": "pass" } }, "required": [ "verdict" ] }, "then": { "properties": { "checks": { "items": { "properties": { "result": { "const": "pass" } } }, "maxItems": 8, "minItems": 8 }, "record": { "properties": { "layers": { "properties": { "flood": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "landslide": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "mpzp": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "pog": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "protected": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "road_access": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "wz": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } } }, "required": [ "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access" ] } } } } } } ], "properties": { "checks": { "items": { "additionalProperties": false, "properties": { "basis": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "id": { "enum": [ "pog_zone", "wz_possible", "mpzp_status", "mpzp_params", "flood_q100", "landslide", "protected", "road_access" ], "type": "string" }, "layer": { "$ref": "#/$defs/LayerKey" }, "result": { "enum": [ "pass", "fail", "warn", "unknown" ], "type": "string" }, "source": { "$ref": "#/$defs/SourceRef" }, "value": {} }, "required": [ "id", "layer", "result", "source" ], "type": "object" }, "type": "array" }, "disclaimer": { "type": "string" }, "id": { "$ref": "#/$defs/ParcelId" }, "record": { "$ref": "#/$defs/ParcelRecordV2" }, "verdict": { "description": "Reguła przeniesiona z bezpłatnego sprawdzania (geofeed/resolve). pass: wszystkie sprawdzenia zakończone pomyślnie. fail: negatywny wynik sprawdzenia rozstrzygającego (brak ścieżki WZ i MPZP dopuszczającego zabudowę). conditional: możliwość zabudowy zależy od wskazanego warunku (dojazd, powódź, forma ochrony). unknown: wynik sprawdzenia rozstrzygającego jest nieznany.", "enum": [ "pass", "conditional", "fail", "unknown" ], "type": "string" } }, "required": [ "verdict", "checks", "record", "disclaimer" ], "type": "object" }, "CorpusCoverage": { "additionalProperties": false, "description": "Zakres posiadanych danych z danego rejestru, pozwalający odróżnić brak wyniku od braku załadowanych danych. Zwracany przy rozpoznawaniu oraz przy każdym statusie not_found lub not_covered.", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "held_parcels": { "type": "integer" }, "held_pct": { "maximum": 100, "minimum": 0, "type": [ "number", "null" ] }, "note": { "type": "string" }, "scope": { "description": "national, kod województwa albo siedmioznakowy TERYT gminy.", "type": "string" }, "source_parcels": { "type": [ "integer", "null" ] } }, "required": [ "scope", "source_parcels", "held_parcels", "held_pct", "as_of", "note" ], "type": "object" }, "Coverage": { "description": "Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem.", "enum": [ "covered", "covered_no_data", "not_covered", "not_computed" ], "type": "string" }, "Error": { "additionalProperties": false, "description": "Każdy błąd wskazuje dalszy krok: zawsze zawiera hint i odnośnik do dokumentacji, przykładowe id przy zapytaniu o działkę oraz signup_url przy HTTP 401.", "properties": { "code": { "description": "invalid_input 400 (brak lub kilka parametrów q|id|point, błędne id lub point; bezpłatne). not_found 404 (zwrot opłaty). ambiguous 200 (odpowiada statusowi; lista kandydatów). not_covered 200 (rozpoznano miejsce poza załadowanym zakresem danych; zwrot opłaty). unauthorized 401 (brak lub błędny X-Api-Key; bezpłatne). rate_limited 429. source_unavailable 503 (błąd źródła odpytywanego podczas żądania; zwrot opłaty). internal 500 (zwrot opłaty).", "enum": [ "invalid_input", "not_found", "ambiguous", "not_covered", "unauthorized", "rate_limited", "source_unavailable", "internal" ], "type": "string" }, "docs": { "type": "string" }, "example_id": { "description": "Poprawny identyfikator w ujednoliconej postaci, np. „146501_1.0101.12/3”.", "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "hint": { "description": "Wskazówka dotycząca dalszego wywołania, np. „Przekaż dokładnie jeden parametr: q, id albo point” lub „Dodaj nazwę lub numer obrębu”.", "minLength": 1, "type": "string" }, "message": { "description": "Jedno zdanie, które agent może przekazać użytkownikowi.", "type": "string" }, "signup_url": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "hint", "docs" ], "type": "object" }, "EventTypeV2": { "enum": [ "gunb_permit", "plan_general_adopted", "mpzp_status_changed", "rcn_transaction_aggregate", "listing_seen", "source_refreshed", "coverage_changed" ], "type": "string" }, "EventV2": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "gunb_permit" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "permit_id": { "minLength": 1, "type": "string" }, "status": { "enum": [ "applied", "issued", "refused", "withdrawn" ], "type": "string" } }, "required": [ "permit_id", "status" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "plan_general_adopted" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "gmina_teryt": { "pattern": "^[0-9]{6}[123]$", "type": "string" }, "resolution_id": { "minLength": 1, "type": "string" } }, "required": [ "gmina_teryt", "resolution_id" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "mpzp_status_changed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "properties": { "effective_from": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "plan_id": { "minLength": 1, "type": "string" }, "status": { "$ref": "#/$defs/MpzpStatus" } }, "required": [ "plan_id", "status", "effective_from" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "rcn_transaction_aggregate" } } }, "then": { "not": { "required": [ "parcel_ids" ] }, "properties": { "data": { "$ref": "#/$defs/RcnAggregate" } }, "required": [ "data", "area" ] } }, { "if": { "properties": { "type": { "const": "source_refreshed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "layer_version": { "minLength": 1, "type": "string" }, "source_id": { "minLength": 1, "type": "string" } }, "required": [ "source_id", "layer_version" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "coverage_changed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "after": { "$ref": "#/$defs/Coverage" }, "before": { "$ref": "#/$defs/Coverage" }, "layer": { "$ref": "#/$defs/LayerKey" } }, "required": [ "layer", "before", "after" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "listing_seen" } } }, "then": { "not": { "anyOf": [ { "required": [ "area" ] }, { "required": [ "data" ] } ] }, "required": [ "parcel_ids" ] } } ], "oneOf": [ { "not": { "required": [ "area" ] }, "required": [ "parcel_ids" ] }, { "not": { "required": [ "parcel_ids" ] }, "required": [ "area" ] } ], "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "as_of": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "data": {}, "id": { "minLength": 1, "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "occurred_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true }, "source": { "$ref": "#/$defs/SourceRef" }, "type": { "$ref": "#/$defs/EventTypeV2" } }, "required": [ "id", "type", "occurred_at", "observed_at", "source", "as_of" ], "type": "object" }, "EventsGetParcelIds": { "description": "Mała lista działek w GET zdarzeń; większe listy korzystają z POST /v1/events/query (do 10 000 identyfikatorów).", "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "EventsRequestV2": { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "parcel_ids" ] }, "required": [ "area" ] }, { "not": { "required": [ "area" ] }, "required": [ "parcel_ids" ] } ], "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "cursor": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true }, "since": { "format": "date-time", "type": "string" }, "types": { "items": { "$ref": "#/$defs/EventTypeV2" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [], "type": "object" }, "ExportV2": { "additionalProperties": false, "properties": { "format": { "enum": [ "csv", "geojson" ], "type": "string" }, "link": { "$ref": "#/$defs/SignedLink" }, "rows": { "maximum": 2000, "minimum": 0, "type": "integer" } }, "required": [ "format", "rows", "link" ], "type": "object" }, "FeatureAnswer": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "then": { "properties": { "as_of": { "format": "date", "type": "string" } } } }, { "if": { "properties": { "coverage": { "const": "covered" } } }, "then": { "properties": { "value": { "not": { "type": "null" } } } } } ], "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "coverage": { "$ref": "#/$defs/Coverage" }, "method": { "minLength": 1, "type": "string" }, "note": { "minLength": 1, "type": "string" }, "source": { "$ref": "#/$defs/SourceRef" }, "sources": { "items": { "$ref": "#/$defs/SourceRef" }, "minItems": 1, "type": "array" }, "unit": { "type": [ "string", "null" ] }, "value": {} }, "required": [ "value", "unit", "source", "as_of", "method", "coverage", "note" ], "type": "object" }, "FeatureFilterFacet": { "additionalProperties": false, "properties": { "coverage_semantics": { "const": "unknown_excluded_and_counted; independent_scope_before_other_filters_and_pagination" }, "excluded_known": { "minimum": 0, "type": "integer" }, "excluded_unknown": { "minimum": 0, "type": "integer" }, "matched": { "minimum": 0, "type": "integer" } }, "required": [ "matched", "excluded_unknown", "excluded_known", "coverage_semantics" ], "type": "object" }, "FeatureSearchFacets": { "additionalProperties": false, "properties": { "filters": { "additionalProperties": { "$ref": "#/$defs/FeatureFilterFacet" }, "propertyNames": { "enum": [ "area_min_m2", "area_max_m2", "land_use_class", "shape_regularity_min", "frontage_min_m", "road_access", "buildings_present", "public_road_max_m", "rcn_price_min_pln_m2", "rcn_price_max_pln_m2", "gunb_activity_min", "pog_zone_class" ] }, "type": "object" }, "matched_count": { "minimum": 0, "type": "integer" }, "scope_count": { "minimum": 0, "type": "integer" } }, "required": [ "scope_count", "matched_count", "filters" ], "type": "object" }, "FeatureSearchFilters": { "additionalProperties": false, "description": "Filtry cech obejmują wartości graniczne. Nieznane wartości i null nigdy nie spełniają filtra, również dla false. Powierzchnia geometryczna jest podana w m². Agregat RCN dotyczy stałej grupy co najmniej 6 transakcji w gminie, po zaokrągleniu do 50 zł/m². GUNB podaje potwierdzoną liczbę wpisów w promieniu 500 m. Dolna granica przedziału nie może przekraczać górnej.", "properties": { "area_max_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "area_min_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "buildings_present": { "type": "boolean" }, "frontage_min_m": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "gunb_activity_min": { "description": "Minimalna liczba wpisów RWDZ jednoznacznie powiązanych z działkami w promieniu 500 m. Jest to potwierdzona liczba co najmniej tylu wpisów. Jeśli nie osiąga minimum, dane nie wystarczają do rozstrzygnięcia; działka jest liczona w excluded_unknown.", "maximum": 1000000000000.0, "minimum": 0, "type": "integer" }, "land_use_class": { "enum": [ "R", "Ł", "Ps", "Br", "B", "Ba", "Bi", "Bp", "Bz", "K", "Ls", "Lz", "Lzr", "N", "Wp", "Ws", "Wsr", "W", "dr", "Tk", "Ti", "Tr", "E" ], "type": "string" }, "pog_zone_class": { "enum": [ "SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP" ], "type": "string" }, "public_road_max_m": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "rcn_price_max_pln_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "rcn_price_min_pln_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "road_access": { "type": "boolean" }, "shape_regularity_min": { "maximum": 1, "minimum": 0, "type": "number" } }, "type": "object" }, "IdempotencyKey": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string" }, "JobQuery": { "additionalProperties": false, "properties": { "cursor": { "minLength": 1, "type": [ "string", "null" ] }, "job_id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" } }, "required": [ "job_id" ], "type": "object" }, "LayerAnswer": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" }, "LayerAnswerV2": { "allOf": [ { "$ref": "#/$defs/LayerAnswer" }, { "required": [ "licence", "scope", "method" ] }, { "if": { "properties": { "method": { "const": "extracted" } }, "required": [ "method" ] }, "then": { "required": [ "confidence", "threshold" ] } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "prices" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/RcnAggregate" } } } } ], "description": "Format odpowiedzi tematycznej v2. Walidator wymaga zgodności ze sprawdzoną licencją i confidence >= threshold dla każdego stanu poza not_covered. Poniżej progu zwracane są not_covered i null; nie jest to piąty stan zakresu danych." }, "LayerKey": { "description": "planning zwraca w jednym żądaniu informacje planistyczne: plan ogólny, MPZP, WZ i stan planowania w gminie.", "enum": [ "parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil" ], "type": "string" }, "Licence": { "additionalProperties": false, "description": "Dokładna, sprawdzona decyzja z licence_decisions.json, powiązana z source.id. Źródło bez sprawdzonej decyzji nie może być udostępniane. terms_url=null oznacza brak adresu URL w decyzji, a nie nieograniczone prawo ponownego wykorzystania.", "properties": { "approved_at": { "const": "2026-10-16" }, "approved_by": { "const": "operator" }, "attribution": { "minLength": 1, "type": "string" }, "position": { "enum": [ "cc0", "cc_by_4_0", "local_law_no_copyright", "open_data", "own_computation", "statutory_open_data" ], "type": "string" }, "review_ref": { "minLength": 1, "type": "string" }, "terms_url": { "anyOf": [ { "format": "uri", "pattern": "^https://", "type": "string" }, { "type": "null" } ] } }, "required": [ "position", "attribution", "terms_url", "review_ref" ], "type": "object" }, "Link": { "additionalProperties": false, "properties": { "cost": { "minimum": 0, "type": "integer" }, "href": { "type": "string" } }, "required": [ "href", "cost" ], "type": "object" }, "ListingCandidate": { "additionalProperties": false, "description": "Wyłącznie uporządkowane przesłanki lokalizacyjne. reason opisuje metodę dopasowania i nigdy nie cytuje treści ogłoszenia. Pojedynczy kandydat nadal jest kandydatem, a nie pewnie rozpoznaną działką.", "properties": { "distance_m": { "minimum": 0, "type": "number" }, "parcel_id": { "$ref": "#/$defs/ParcelId" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "score": { "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "parcel_id", "score", "reason", "distance_m" ], "type": "object" }, "ListingResolution": { "additionalProperties": false, "description": "Wynik zawiera wyłącznie kandydatów, nigdy treść, zdjęcia ani ceny z ogłoszenia; bez wynikowej działki i automatycznego wyboru. Pusta lista kandydatów oznacza not_found i zwrot opłaty. Przełącznik: LANDFEED_LISTING_LOOKUP_ENABLED.", "properties": { "candidates": { "items": { "$ref": "#/$defs/ListingCandidate" }, "maxItems": 100, "type": "array" }, "listing_url": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" } }, "required": [ "listing_url", "candidates" ], "type": "object" }, "ListingResolveRequest": { "additionalProperties": false, "description": "Przełącznik LANDFEED_LISTING_LOOKUP_ENABLED, domyślnie false. Wyłączone wyszukiwanie zwraca bezpłatną odmowę. Udostępnienie wymaga akceptacji ryzyka danego portalu i sposobu wskazywania każdego źródła.", "properties": { "listing_url": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" } }, "required": [ "listing_url" ], "type": "object" }, "LonLat": { "description": "Kolejność GeoJSON: [lng, lat], układ WGS84.", "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "Meta": { "additionalProperties": false, "properties": { "api_version": { "const": "v1", "type": "string" }, "calls": { "description": "Liczba żądań potrzebnych do uzyskania odpowiedzi. Zawsze 1 dla pojedynczego odczytu; sprawdzane w teście pomiarowym.", "minimum": 1, "type": "integer" }, "contract_version": { "const": "2.0.0" }, "disclaimer": { "type": [ "string", "null" ] }, "etag": { "description": "Ta sama wartość co nagłówek ETag przy GET według id. Zakres i warunki słabego znacznika (W/): openapi.yaml components.headers.ETag.", "type": [ "string", "null" ] }, "excluded": { "description": "Pola wyłączone z udostępniania: numery KW, dane właścicieli i władających, nazwy inwestorów oraz ceny transakcyjne powiązane z konkretnym adresem.", "items": { "type": "string" }, "type": "array" }, "generated_at": { "format": "date-time", "type": "string" }, "operation": { "enum": [ "parcel", "layer", "check", "resolve", "resolve_listing", "search", "events", "check_batch", "check_job", "check_results", "sources", "planning" ], "type": "string" }, "request_id": { "type": "string" } }, "required": [ "request_id", "api_version", "generated_at", "calls" ], "type": "object" }, "Method": { "enum": [ "official", "derived", "computed", "extracted" ], "type": "string" }, "MpzpStatus": { "anyOf": [ { "$ref": "#/$defs/PlanStatus" }, { "type": "null" } ], "description": "Status prawny MPZP; null, gdy integracja wymienia plan lub strefę, ale nie publikuje statusu prawnego. Taki rekord ma coverage=covered i effective_from=null, a note wyjaśnia brak statusu. Statusy draft, adopted i in_force wymagają potwierdzenia w źródle; brak danych nigdy nie oznacza none." }, "MpzpValue": { "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "properties": { "effective_from": { "format": "date", "type": [ "string", "null" ] }, "plans": { "items": { "type": "object" }, "type": "array" }, "status": { "$ref": "#/$defs/MpzpStatus" }, "symbol": { "type": [ "string", "null" ] } }, "required": [ "status", "symbol", "plans", "effective_from" ], "type": "object" }, "NoQueryInput": { "description": "Dane wejściowe bez q, id, point, lat ani lng (rodzaje QueryEcho: none, bbox, polygon, path).", "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "type": "object" }, "Page": { "additionalProperties": false, "description": "Stronicowanie list wyników za pomocą kursora (search, events, sources).", "properties": { "has_more": { "type": "boolean" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "has_more", "next_cursor" ], "type": "object" }, "ParcelFeatures": { "additionalProperties": false, "properties": { "access_and_roads": { "additionalProperties": false, "properties": { "frontage_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_dr_parcels", "egib_parcels" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "public_road_distance_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "bdot_roads" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "road_access": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "bdot_roads", "egib_dr_parcels", "egib_parcels" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } ] } }, "required": [ "public_road_distance_m", "road_access", "frontage_m" ], "type": "object" }, "amenities": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "buildings_and_surroundings": { "additionalProperties": false, "properties": { "building_count": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "building_coverage_pct": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "percent" }, "value": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "building_footprint_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "buildings_500m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "buildings_present": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } ] } }, "required": [ "buildings_present", "building_count", "building_footprint_m2", "building_coverage_pct", "buildings_500m" ], "type": "object" }, "development_activity": { "additionalProperties": false, "properties": { "gunb_activity_500m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "gunb_permits" ] } } }, "unit": { "const": "count_min" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "gunb_activity_gmina": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "gunb_permits" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] } }, "required": [ "gunb_activity_gmina", "gunb_activity_500m" ], "type": "object" }, "land_use": { "additionalProperties": false, "properties": { "land_use_classes": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "items": { "pattern": "^[A-Za-zŁłŻż]{1,5}(?:[IVX]{1,4}[ab]?)?$", "type": "string" }, "maxItems": 100, "type": "array", "uniqueItems": true }, { "type": "null" } ] } } } ] }, "pog_zone_class": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "pog_sweep", "pog_zones" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "enum": [ "SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP" ], "type": "string" }, { "type": "null" } ] } } } ] } }, "required": [ "land_use_classes", "pog_zone_class" ], "type": "object" }, "prices_nearby": { "additionalProperties": false, "properties": { "rcn_gmina_median_pln_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "rcn_clean_agg" ] } } }, "unit": { "const": "PLN/m2" }, "value": { "anyOf": [ { "minimum": 0, "multipleOf": 50, "type": "number" }, { "type": "null" } ] } } } ] }, "rcn_gmina_sales_count": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "rcn_clean_agg" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 6, "type": "integer" }, { "type": "null" } ] } } } ] } }, "required": [ "rcn_gmina_median_pln_m2", "rcn_gmina_sales_count" ], "type": "object" }, "shape_and_size": { "additionalProperties": false, "properties": { "area_geometry_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "area_official_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "elongation": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "minimum": 1, "type": "number" }, { "type": "null" } ] } } } ] }, "perimeter_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "shape_regularity": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "maximum": 1, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "squareness": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "maximum": 1, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] } }, "required": [ "area_official_m2", "area_geometry_m2", "perimeter_m", "shape_regularity", "squareness", "elongation" ], "type": "object" } }, "required": [ "shape_and_size", "access_and_roads", "land_use", "buildings_and_surroundings", "prices_nearby", "development_activity", "amenities" ], "type": "object" }, "ParcelId": { "description": "Ujednolicony identyfikator EGiB id_dzialki, będący kluczem głównym: „_” po sześciocyfrowym prefiksie, bez skrajnych spacji, numer do 64 znaków z ostatnim członem (po ostatniej kropce) zawierającym tylko litery, cyfry, „_” i „/”; postać z łącznikiem wymaga normalizacji. Wcześniejsze człony mogą zawierać oznaczenie arkusza AR_ z literami, spacjami i łącznikami („240702_2.0001.AR_10BORONÓW LAS.310/121”). gmina_teryt (7 znaków, WWPPGGR) to jednostka TERYT w identyfikatorze; gminę administracyjną określa admin_gmina_teryt (nagłówek parcel_record.sql).", "maxLength": 100, "pattern": "^[0-9]{6}_[0-9]\\.[0-9]{1,4}\\.(?=[^\\n]{1,64}$)(?:[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]*\\.)?[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_/]+$", "type": "string" }, "ParcelIdInput": { "description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string" }, "ParcelRecordV2": { "additionalProperties": false, "properties": { "adjacent_parcel_ids": { "description": "Identyfikatory do 50 aktywnych działek wczytanych do API, które mają wspólny odcinek granicy. Kolejność według identyfikatora; sam kontakt punktowy nie wystarcza.", "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 50, "type": "array", "uniqueItems": true }, "adjacent_parcel_ids_truncated": { "type": "boolean" }, "admin": { "additionalProperties": false, "properties": { "admin_gmina_teryt": { "description": "Gmina administracyjna (parcel_record.admin_gmina_teryt), której kod przyjmuje /v1/gminy/{teryt}/planning.", "type": [ "string", "null" ] }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Jednostka TERYT w identyfikatorze działki (parcel_record.gmina_teryt).", "type": "string" }, "gmina_type": { "type": [ "string", "null" ] }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" }, "voivodeship_name": { "type": "string" } }, "required": [ "voivodeship", "gmina_teryt", "gmina_name", "obreb_id", "number" ], "type": "object" }, "area": { "$ref": "#/$defs/AreaV2" }, "centroid": { "$ref": "#/$defs/LonLat" }, "display_geometry": { "additionalProperties": false, "description": "Granica do wyświetlania: uproszczenie do 0,5 m w EPSG:2180, GeoJSON w EPSG:4326. Dokładny eksport wymaga osobnego płatnego żądania geometry=full.", "properties": { "coordinates": { "items": { "items": { "items": { "$ref": "#/$defs/LonLat" }, "type": "array" }, "type": "array" }, "type": "array" }, "type": { "const": "MultiPolygon" } }, "required": [ "type", "coordinates" ], "type": "object" }, "display_simplified": { "const": true }, "features": { "$ref": "#/$defs/ParcelFeatures" }, "geometry": { "additionalProperties": false, "properties": { "coordinates": { "items": { "items": { "items": { "$ref": "#/$defs/LonLat" }, "type": "array" }, "type": "array" }, "type": "array" }, "type": { "const": "MultiPolygon" } }, "required": [ "type", "coordinates" ], "type": [ "object", "null" ] }, "id": { "$ref": "#/$defs/ParcelId" }, "layers": { "additionalProperties": { "$ref": "#/$defs/LayerAnswerV2" }, "propertyNames": { "enum": [ "parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil" ] }, "type": "object" }, "record_as_of": { "format": "date", "type": [ "string", "null" ] }, "record_hash": { "type": [ "string", "null" ] } }, "required": [ "id", "admin", "area", "layers", "record_hash" ], "type": "object" }, "PlaceParent": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "teryt": { "minLength": 1, "type": "string" }, "type": { "enum": [ "voivodeship", "powiat", "gmina", "obreb" ] } }, "required": [ "id", "name", "type", "teryt" ], "type": "object" }, "PlaceSuggestion": { "additionalProperties": false, "description": "Kod TERC gminy lub powiatu; pełny identyfikator EGiB dla obrębu. Nazwy PRG bez zapisanego SIMC zachowują teryt=null; gmina nadrzędna jest podana osobno.", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "code_system": { "enum": [ "TERC", "EGiB", "SIMC" ] }, "coverage": { "$ref": "#/$defs/Coverage" }, "id": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "note": { "minLength": 1, "type": "string" }, "parent": { "anyOf": [ { "$ref": "#/$defs/PlaceParent" }, { "type": "null" } ] }, "source": { "$ref": "#/$defs/SourceRef" }, "teryt": { "minLength": 1, "type": [ "string", "null" ] }, "type": { "enum": [ "gmina", "powiat", "obreb", "miejscowosc" ] } }, "required": [ "id", "name", "type", "teryt", "code_system", "parent", "coverage", "source", "as_of", "note" ], "type": "object" }, "PlacesResult": { "additionalProperties": false, "properties": { "coverage": { "$ref": "#/$defs/Coverage" }, "note": { "minLength": 1, "type": "string" }, "places": { "items": { "$ref": "#/$defs/PlaceSuggestion" }, "maxItems": 20, "type": "array" } }, "required": [ "places", "coverage", "note" ], "type": "object" }, "Plan": { "enum": [ "free", "start", "pro", "team", "developer", "platform" ], "type": "string" }, "PlanStatus": { "description": "Status planu ogólnego lub MPZP: draft (projekt, nieuchwalony), adopted (uchwalony, jeszcze nie obowiązuje), in_force (obowiązuje), none (źródło nie zawiera rekordu takiego planu dla tego miejsca). Statusom adopted i in_force towarzyszy effective_from.", "enum": [ "draft", "adopted", "in_force", "none" ], "type": "string" }, "QueryEcho": { "additionalProperties": false, "allOf": [ { "if": { "not": { "required": [ "kind" ] } }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput" } } } }, { "if": { "properties": { "kind": { "const": "q" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "q" ] } } } }, { "if": { "properties": { "kind": { "const": "id" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "id" ] } } } }, { "if": { "properties": { "kind": { "const": "point" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "anyOf": [ { "required": [ "point" ] }, { "required": [ "lat", "lng" ] } ] } } } }, { "if": { "properties": { "kind": { "enum": [ "none", "bbox", "polygon", "path" ] } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/NoQueryInput" } } } }, { "if": { "properties": { "kind": { "const": "bbox" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "bbox" ] } } } }, { "if": { "properties": { "kind": { "const": "polygon" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "polygon" ] } } } }, { "if": { "properties": { "kind": { "const": "path" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "teryt" ] } } } }, { "if": { "properties": { "kind": { "const": "batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "properties": { "items": { "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "items" ] } } } }, { "if": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "events" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/EventsRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" } } } }, { "if": { "properties": { "kind": { "const": "check_batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/BatchCheckRequest" } } } }, { "if": { "properties": { "kind": { "const": "job" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/JobQuery" } } } } ], "description": "Przekazane zapytanie i sposób jego rozpoznania. kind określa postać danych wejściowych; input zawiera otrzymane parametry zapytania, ścieżki lub treści żądania, więc błędne dane są powtarzane dokładnie w otrzymanej postaci. Bez kind pole input musi być poprawnym QueryInput, używanym już w każdym odczycie q|id|point.", "properties": { "input": { "additionalProperties": true, "description": "Parametry wejściowe w otrzymanej postaci. Obiekt dopuszcza też pozostałe parametry żądania, np. layers, limit, cursor i radius_m.", "type": "object" }, "kind": { "description": "q, id, point: jeden poprawny wariant q|id|point (point obejmuje też parę lat+lng). none: brak q|id|point, np. GET /v1/sources bez danych wejściowych. bbox: GET /v1/search?bbox. polygon: POST /v1/search. path: odczyt według parametru ścieżki, input {teryt} dla /v1/gminy/{teryt}/planning. batch: POST /v1/parcel/batch, input {items, ...}; odpowiedź każdego elementu określa własny kind. invalid: HTTP 400 z danymi, które nie przeszły walidacji (np. q i id jednocześnie lub błędne id); wyłącznie przy statusie error.", "enum": [ "q", "id", "point", "none", "bbox", "polygon", "path", "batch", "invalid", "search", "events", "listing", "check_batch", "job" ], "type": "string" }, "resolved": { "description": "Sposób rozpoznania działki lub gminy na podstawie danych wejściowych. Wartość null przy statusie ambiguous lub not_found.", "oneOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "from": { "enum": [ "q", "id", "point" ], "type": "string" }, "id": { "type": "string" }, "method": { "enum": [ "exact_id", "normalised_id", "text_parcel", "text_parcel_fuzzy", "text_address", "text_gmina", "point_in_polygon" ], "type": "string" }, "note": { "description": "Założenie przyjęte podczas rozpoznawania, np. „Lesnowola odczytano jako Lesznowola (dopasowanie przybliżone, obniżona pewność)”.", "type": [ "string", "null" ] } }, "required": [ "from", "method", "id", "confidence" ], "type": "object" } ] } }, "required": [ "input", "resolved" ], "type": "object" }, "QueryInput": { "description": "Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty.", "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "description": "Współrzędne WGS84 w stopniach dziesiętnych, w formacie lat,lng, np. „52.2297,21.0122”. Wskazują działkę zawierającą ten punkt.", "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "description": "Dowolny tekst wpisany przez użytkownika, np. „pogorzelec dziłaka 284/5”, „Marcinowice 221”, „Lesnowola 25/18”, „obręb 9 / O18”, adres albo pełny identyfikator w jednej z obsługiwanych postaci.", "maxLength": 300, "minLength": 1, "type": "string" } }, "type": "object" }, "RcnAggregate": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "unit_id": { "pattern": "^[0-9]{6}_[0-9]\\.[0-9]{1,4}$", "type": "string" } } }, "if": { "properties": { "scope": { "const": "gmina" } } }, "then": { "properties": { "unit_id": { "pattern": "^[0-9]{6}[123]$", "type": "string" } } } } ], "description": "Co najmniej 6 różnych sprzedaży. Publikowana jest wyłącznie mediana grupy transakcji, zaokrąglona do najbliższych 50 zł/m², przy remisie do parzystej wielokrotności. Nie publikuje się dokładnej wartości pozycyjnej ani ceny pojedynczej sprzedaży. Minimalna liczebność jest sprawdzana przed publikacją, a wyniki muszą uniemożliwiać odtworzenie danych przez różnicowanie. Wyłącznie zamknięty zestaw danych zbiorczych.", "properties": { "count": { "minimum": 6, "type": "integer" }, "k_floor": { "const": 6 }, "median_price_m2": { "minimum": 0, "multipleOf": 50, "type": "number" }, "scope": { "enum": [ "obreb", "gmina" ], "type": "string" }, "unit_id": { "minLength": 1, "type": "string" }, "vintage": { "format": "date", "type": "string" } }, "required": [ "count", "k_floor", "median_price_m2", "scope", "unit_id", "vintage" ], "type": "object" }, "Scope": { "enum": [ "parcel_polygon", "point", "obreb", "gmina", "grid" ], "type": "string" }, "SearchArea": { "oneOf": [ { "$ref": "#/$defs/TerytArea" }, { "$ref": "#/$defs/SearchPolygon" } ] }, "SearchFilterEvidence": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "coverage": { "$ref": "#/$defs/Coverage" }, "note": { "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "value": { "type": [ "boolean", "number", "string", "null" ] } }, "required": [ "coverage", "value", "source", "as_of", "scope", "note" ], "type": "object" }, "SearchFilters": { "additionalProperties": false, "description": "Każdy warunek wymaga danych o stanie covered lub covered_no_data w zadeklarowanym zakresie. Wynik nieznany ani not_computed nigdy nie spełnia filtra, także warunku o wartości false. Powierzchnia min<=max; obie granice są włączne, w m².", "properties": { "area_m2": { "additionalProperties": false, "properties": { "max": { "exclusiveMinimum": 0, "type": "number" }, "min": { "minimum": 0, "type": "number" } }, "required": [], "type": "object" }, "building_present": { "type": "boolean" }, "no_nature_protection": { "type": "boolean" }, "outside_flood_q100": { "type": "boolean" }, "plan_general_zones": { "items": { "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "public_road_access": { "type": "boolean" } }, "required": [], "type": "object" }, "SearchPolygon": { "additionalProperties": false, "description": "WGS84 [longitude,latitude]; jeden zamknięty, prosty pierścień zewnętrzny bez otworów, do 512 wierzchołków wraz z domknięciem, dodatnia powierzchnia do 4 000 000 m². Walidator odrzuca pierścienie zdegenerowane; ostateczne przyjęcie wymaga sprawdzenia topologii i typu geography w PostGIS podczas obsługi żądania.", "properties": { "coordinates": { "items": { "items": { "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "maxItems": 512, "minItems": 4, "type": "array" }, "maxItems": 1, "minItems": 1, "type": "array" }, "type": { "const": "Polygon" } }, "required": [ "type", "coordinates" ], "type": "object" }, "SearchRequestV2": { "additionalProperties": false, "description": "Zarezerwowany kontrakt, niedostępny w bieżącej usłudze. Do 2 000 wyników w stałym zbiorze kursora. Wielokąt do 512 wierzchołków i 4 km²; jednostki TERYT obejmują cały powiat lub gminę. Zwykła strona kosztuje 1 kredyt; eksport kosztuje ceil(rows/100) zamiast ceny strony, bez podwójnej opłaty.", "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "cursor": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ] }, "filters": { "$ref": "#/$defs/SearchFilters" }, "format": { "enum": [ "csv", "geojson" ], "type": "string" }, "limit": { "default": 100, "maximum": 1000, "minimum": 1, "type": "integer" } }, "required": [ "area" ], "type": "object", "x-runtime-supported": false }, "SearchResultV2": { "additionalProperties": false, "properties": { "export": { "$ref": "#/$defs/ExportV2" }, "items": { "items": { "additionalProperties": false, "properties": { "address": { "description": "Adres PRG przy wyszukiwaniu według adresu.", "type": [ "string", "null" ] }, "admin_gmina_teryt": { "description": "Gmina administracyjna (parcel_record.admin_gmina_teryt), której kod przyjmuje /v1/gminy/{teryt}/planning.", "type": [ "string", "null" ] }, "area_official_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "#/$defs/LonLat" }, "distance_m": { "type": [ "number", "null" ] }, "filter_evidence": { "additionalProperties": false, "properties": { "area_m2": { "$ref": "#/$defs/SearchFilterEvidence" }, "building_present": { "$ref": "#/$defs/SearchFilterEvidence" }, "no_nature_protection": { "$ref": "#/$defs/SearchFilterEvidence" }, "outside_flood_q100": { "$ref": "#/$defs/SearchFilterEvidence" }, "plan_general_zones": { "$ref": "#/$defs/SearchFilterEvidence" }, "public_road_access": { "$ref": "#/$defs/SearchFilterEvidence" } }, "type": "object" }, "flags": { "additionalProperties": false, "properties": { "building_present": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "no_nature_protection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "outside_flood_q100": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "plan_general_zone_match": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "public_road_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "outside_flood_q100", "no_nature_protection", "plan_general_zone_match", "public_road_access", "building_present" ], "type": "object" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Jednostka TERYT w identyfikatorze działki (parcel_record.gmina_teryt).", "type": "string" }, "id": { "$ref": "#/$defs/ParcelId" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" } }, "required": [ "id", "gmina_teryt", "gmina_name", "obreb_name", "number", "centroid", "flags" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "page": { "$ref": "#/$defs/Page" } }, "required": [ "items", "page" ], "type": "object" }, "SignedLink": { "additionalProperties": false, "description": "Podpisany przez serwer adres HTTPS uprawniający do pobrania zasobu; expires_at jest obowiązkowe. Walidator wymaga niepustego parametru signature w zapytaniu.", "properties": { "cost": { "minimum": 0, "type": "integer" }, "expires_at": { "format": "date-time", "type": "string" }, "href": { "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "href", "cost", "expires_at" ], "type": "object" }, "SourceRef": { "additionalProperties": false, "description": "Pozycja /v1/sources cytowana w odpowiedzi tematycznej. as_of to data danych źródłowych z ostatniej udanej aktualizacji, a nie czas żądania.", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "attribution": { "type": "string" }, "fallback": { "default": false, "description": "Wartość true, gdy to źródło udzieliło odpowiedzi z powodu braku rekordu w źródle podstawowym, np. własny przegląd planów ogólnych przy braku wpisu w Rejestrze Urbanistycznym.", "type": "boolean" }, "id": { "description": "Identyfikator źródła: source_status.source_id.", "type": "string" }, "licence": { "type": "string" }, "publisher": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "attribution", "as_of" ], "type": "object" }, "Status": { "description": "ok: wynik obecny (HTTP 200). ambiguous: result=null, niepusta lista kandydatów (200, naliczana opłata). not_found: brak dopasowania do danych wejściowych (404, zwrot opłaty). not_covered: rozpoznano miejsce, ale nie obejmuje go żaden załadowany zbiór ani źródło (200, result=null, zwrot opłaty). error: zobacz error.code.", "enum": [ "ok", "ambiguous", "not_found", "not_covered", "error" ], "type": "string" }, "TerytArea": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "powiat" }, "teryt": { "pattern": "^[0-9]{4}$", "type": "string" } }, "required": [ "kind", "teryt" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "gmina" }, "teryt": { "pattern": "^[0-9]{6}[123]$", "type": "string" } }, "required": [ "kind", "teryt" ], "type": "object" } ] } }, "$id": "https://landfeed.pl/contracts/envelope.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "allOf": [ { "$comment": "status error requires an error object.", "if": { "properties": { "status": { "const": "error" } }, "required": [ "status" ] }, "then": { "properties": { "error": { "type": "object" } } } }, { "$comment": "status ambiguous requires at least one candidate.", "if": { "properties": { "status": { "const": "ambiguous" } }, "required": [ "status" ] }, "then": { "properties": { "candidates": { "minItems": 1 } } } }, { "$comment": "result is present only when status is ok.", "if": { "properties": { "status": { "not": { "const": "ok" } } }, "required": [ "status" ] }, "then": { "properties": { "result": { "type": "null" } } } }, { "$comment": "the echo of an invalid input belongs to a status error response (400).", "if": { "properties": { "query": { "properties": { "kind": { "const": "invalid" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, "then": { "properties": { "status": { "const": "error" } } } }, { "if": { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, "then": { "properties": { "billing": { "required": [ "credits" ] }, "links": { "properties": { "sheet": { "$ref": "#/$defs/SignedLink" } } }, "meta": { "required": [ "operation" ] }, "query": { "additionalProperties": false, "allOf": [ { "if": { "not": { "required": [ "kind" ] } }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput" } } } }, { "if": { "properties": { "kind": { "const": "q" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "q" ] } } } }, { "if": { "properties": { "kind": { "const": "id" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "id" ] } } } }, { "if": { "properties": { "kind": { "const": "point" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "anyOf": [ { "required": [ "point" ] }, { "required": [ "lat", "lng" ] } ] } } } }, { "if": { "properties": { "kind": { "enum": [ "none", "bbox", "polygon", "path" ] } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/NoQueryInput" } } } }, { "if": { "properties": { "kind": { "const": "bbox" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "bbox" ] } } } }, { "if": { "properties": { "kind": { "const": "polygon" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "polygon" ] } } } }, { "if": { "properties": { "kind": { "const": "path" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "teryt" ] } } } }, { "if": { "properties": { "kind": { "const": "batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "properties": { "items": { "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "items" ] } } } }, { "if": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "events" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/EventsRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" } } } }, { "if": { "properties": { "kind": { "const": "check_batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/BatchCheckRequest" } } } }, { "if": { "properties": { "kind": { "const": "job" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/JobQuery" } } } } ], "description": "Przekazane zapytanie i sposób jego rozpoznania. kind określa postać danych wejściowych; input zawiera otrzymane parametry zapytania, ścieżki lub treści żądania, więc błędne dane są powtarzane dokładnie w otrzymanej postaci. Bez kind pole input musi być poprawnym QueryInput, używanym już w każdym odczycie q|id|point.", "properties": { "input": { "additionalProperties": false, "description": "Powtórzone parametry żądania z dozwolonej listy. Kontrola prywatności obowiązuje także przed zwróceniem błędnych danych wejściowych.", "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "bbox": { "items": { "type": "number" }, "type": "array" }, "cursor": { "type": [ "string", "null" ] }, "filters": { "$ref": "#/$defs/SearchFilters" }, "format": { "type": [ "string", "null" ] }, "geometry": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/$defs/QueryInput", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "description": "Współrzędne WGS84 w stopniach dziesiętnych, w formacie lat,lng, np. „52.2297,21.0122”. Wskazują działkę zawierającą ten punkt.", "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "description": "Dowolny tekst wpisany przez użytkownika, np. „pogorzelec dziłaka 284/5”, „Marcinowice 221”, „Lesnowola 25/18”, „obręb 9 / O18”, adres albo pełny identyfikator w jednej z obsługiwanych postaci.", "maxLength": 300, "minLength": 1, "type": "string" } } }, "type": "array" }, "job_id": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "layer": { "type": [ "string", "null" ] }, "layers": { "items": { "type": "string" }, "type": "array" }, "limit": { "type": "number" }, "listing_url": { "type": [ "string", "null" ] }, "lng": { "type": "number" }, "parcel_ids": { "items": { "type": "string" }, "type": "array" }, "point": { "items": { "type": "number" }, "type": "array" }, "polygon": { "$ref": "#/$defs/SearchPolygon" }, "q": { "type": [ "string", "null" ] }, "radius_m": { "type": "number" }, "results": { "type": "boolean" }, "since": { "type": [ "string", "null" ] }, "teryt": { "type": [ "string", "null" ] }, "types": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "kind": { "description": "q, id, point: jeden poprawny wariant q|id|point (point obejmuje też parę lat+lng). none: brak q|id|point, np. GET /v1/sources bez danych wejściowych. bbox: GET /v1/search?bbox. polygon: POST /v1/search. path: odczyt według parametru ścieżki, input {teryt} dla /v1/gminy/{teryt}/planning. batch: POST /v1/parcel/batch, input {items, ...}; odpowiedź każdego elementu określa własny kind. invalid: HTTP 400 z danymi, które nie przeszły walidacji (np. q i id jednocześnie lub błędne id); wyłącznie przy statusie error.", "enum": [ "q", "id", "point", "none", "bbox", "polygon", "path", "batch", "invalid", "search", "events", "listing", "check_batch", "job" ], "type": "string" }, "resolved": { "description": "Sposób rozpoznania działki lub gminy na podstawie danych wejściowych. Wartość null przy statusie ambiguous lub not_found.", "oneOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "from": { "enum": [ "q", "id", "point" ], "type": "string" }, "id": { "type": "string" }, "method": { "enum": [ "exact_id", "normalised_id", "text_parcel", "text_parcel_fuzzy", "text_address", "text_gmina", "point_in_polygon" ], "type": "string" }, "note": { "description": "Założenie przyjęte podczas rozpoznawania, np. „Lesnowola odczytano jako Lesznowola (dopasowanie przybliżone, obniżona pewność)”.", "type": [ "string", "null" ] } }, "required": [ "from", "method", "id", "confidence" ], "type": "object" } ] } }, "required": [ "input", "resolved" ], "type": "object" } }, "required": [ "auth", "plan" ] } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "parcel" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/ParcelRecordV2", "required": [ "display_geometry", "display_simplified", "adjacent_parcel_ids", "adjacent_parcel_ids_truncated" ] } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "layer" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "additionalProperties": false, "properties": { "answer": { "$ref": "#/$defs/LayerAnswerV2" }, "id": { "$ref": "#/$defs/ParcelId" } }, "required": [ "id", "answer" ], "type": "object" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "check" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/CheckResultV2" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "search" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/SearchResultV2" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "events" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "items": { "$ref": "#/$defs/EventV2" }, "type": "array" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "check_batch" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckJob" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "check_job" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckJob" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "check_results" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckResults" } } } }, { "if": { "allOf": [ { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, { "properties": { "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] } } } ] }, "then": { "allOf": [ { "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "status": { "const": "ambiguous" } } } } ], "properties": { "candidates": { "items": { "$ref": "#/$defs/ListingCandidate" }, "type": "array" }, "query": { "properties": { "resolved": { "type": "null" } } }, "result": { "type": "null" } } } }, { "$comment": "Listing input/kind and operation bind bidirectionally, including error echoes; no confident selection.", "if": { "anyOf": [ { "properties": { "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] } }, "required": [ "meta" ] }, { "properties": { "query": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, { "properties": { "query": { "properties": { "input": { "required": [ "listing_url" ] } }, "required": [ "input" ] } }, "required": [ "query" ] } ] }, "then": { "properties": { "candidates": { "items": { "$ref": "#/$defs/ListingCandidate" }, "type": "array" }, "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] }, "query": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" }, "kind": { "const": "listing" }, "resolved": { "type": "null" } }, "required": [ "kind" ] }, "result": { "type": "null" }, "status": { "enum": [ "ambiguous", "not_found", "error", "not_covered" ] } } } }, { "if": { "anyOf": [ { "properties": { "query": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, { "properties": { "query": { "properties": { "input": { "required": [ "filters" ] } } } } } ] }, "then": { "properties": { "meta": { "properties": { "operation": { "const": "search" } }, "required": [ "operation" ] }, "query": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" }, "kind": { "const": "search" } }, "required": [ "kind" ] } } } } ], "description": "Każda odpowiedź /v1, udana lub błędna, przez REST lub MCP, ma format Envelope. Niejednoznaczność nie jest błędem: zwracane są HTTP 200, status ambiguous i kandydaci. Wartości nie są zgadywane: gdy państwo nie publikuje danych, coverage wynosi not_covered, a value jest null. Pole billing wskazuje naliczone i zwrócone opłaty oraz zastosowaną regułę. Dokumentacja: docs/landfeed/README.md, krok 1; uzasadnienie: context/research/cenogram-teardown-2026-10-12.md, części 8 i 9. Wersja kontraktu 2.0.0 dodaje wymagania: meta.contract_version włącza obowiązkowe informacje o pochodzeniu danych v2, a przestrzeń adresów HTTP i meta.api_version pozostają v1. Zgodność ze starszą wersją nie uprawnia do udostępniania danych z niezatwierdzonych źródeł.", "properties": { "auth": { "$ref": "#/$defs/Auth" }, "billing": { "$ref": "#/$defs/Billing" }, "candidates": { "description": "Lista niepusta przy statusie ambiguous i zawsze zwracana przez /v1/resolve. Kandydaci są uporządkowani malejąco według pewności dopasowania. Agent ponawia wywołanie z id= albo pokazuje listę użytkownikowi; nigdy nie wybiera bez jego wiedzy.", "items": { "oneOf": [ { "$ref": "#/$defs/Candidate" }, { "$ref": "#/$defs/ListingCandidate" } ] }, "type": "array" }, "corpus_coverage": { "$ref": "#/$defs/CorpusCoverage" }, "coverage_summary": { "additionalProperties": false, "properties": { "generated_at": { "format": "date-time", "type": "string" }, "gminas": { "minimum": 0, "type": "integer" }, "layers": { "additionalProperties": false, "properties": { "buildings": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "flood": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "landslide": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "mpzp": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "parcel": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "pog": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "protected": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "wz": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" } }, "required": [ "parcel", "pog", "wz", "mpzp", "flood", "landslide", "protected", "buildings" ], "type": "object" }, "line": { "minLength": 1, "type": "string" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "note": { "minLength": 1, "type": "string" }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "unmeasured_layers": { "items": { "$ref": "#/$defs/LayerKey" }, "type": "array", "uniqueItems": true }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of", "layers", "unmeasured_layers", "generated_at", "line", "note" ], "type": "object" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Error" } ] }, "links": { "additionalProperties": { "$ref": "#/$defs/Link" }, "description": "Dalsze wywołania, które agent może zaplanować, wraz z kosztem każdego z nich, np. {\"check\": {\"href\": \"/v1/check?id=...\", \"cost\": 1}}.", "properties": { "map": { "$ref": "#/$defs/Link" }, "sheet": { "anyOf": [ { "$ref": "#/$defs/Link" }, { "$ref": "#/$defs/SignedLink" } ] }, "tiles": { "$ref": "#/$defs/Link" } }, "type": "object" }, "meta": { "$ref": "#/$defs/Meta" }, "needs_obreb": { "default": false, "description": "Wartość true, gdy numer działki występuje w kilku obrębach rozpoznanej gminy, a dane wejściowe nie wskazują jednego z nich.", "type": "boolean" }, "page": { "$ref": "#/$defs/Page" }, "plan": { "$ref": "#/$defs/Plan" }, "query": { "$ref": "#/$defs/QueryEcho" }, "result": { "description": "Dane właściwe dla danego punktu API (openapi.yaml). Wartość null, gdy status jest inny niż ok.", "type": [ "object", "array", "null" ] }, "search_facets": { "$ref": "#/$defs/FeatureSearchFacets" }, "sources": { "description": "Wszystkie źródła wykorzystane do ustalenia wyniku, bez powtórzeń. Każda odpowiedź tematyczna wskazuje także własne źródło.", "items": { "$ref": "#/$defs/SourceRef" }, "type": "array" }, "status": { "$ref": "#/$defs/Status" } }, "required": [ "status", "query", "result", "candidates", "sources", "billing", "error", "meta" ], "title": "Format odpowiedzi landfeed 2.0.0 (zgodny z v1)", "type": "object", "x-contract-version": "2.0.0", "x-layer-sources": { "address": [ "prg_addresses" ], "admin": [ "teryt_units" ], "buildings": [ "bdot_buildings", "bdot_buildings_attrs", "egib_buildings" ], "flood": [ "mzp_flood" ], "landslide": [ "sopo_landslides" ], "mpzp": [ "kimpzp_symbols", "mpzp_boundaries" ], "parcel": [ "egib_parcels" ], "permits": [ "gunb_permits", "permits_near_parcel" ], "planning": [ "gmina_planning_status", "kimpzp_symbols", "mpzp_boundaries", "pog_sweep", "pog_zones", "wz_possible" ], "pog": [ "pog_sweep", "pog_zones" ], "prices": [ "rcn_clean_agg" ], "protected": [ "gdos_protected" ], "road_access": [ "bdot_roads", "egib_dr_parcels", "road_access_verdict" ], "soil": [ "kieg_soil" ], "wz": [ "pog_sweep", "pog_zones", "wz_possible" ] } } ``` ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/parcel" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # Errors catalogue Codes are extracted from API, OAuth, watch, ask and stdio MCP emission sites. Parcel errors use `error.code`; watch uses an `error` string; OAuth uses its own JSON error; ask may send `error` SSE data. HTTP status, error code and coverage are separate signals. Internal watch admission codes can be suppressed as `unsafe_event`, rather than returned to the caller. ## -32600 Invalid or oversized JSON-RPC request. What to do: Send a supported JSON-RPC request shape and a valid id within transport bounds. Emission sites: `landfeed/mcp/server.mjs:120`, `landfeed/mcp/server.mjs:40`. ## -32601 The JSON-RPC method does not exist. What to do: Use initialize, tools/list, tools/call or another supported protocol method. Emission sites: `landfeed/mcp/server.mjs:79`. ## -32602 JSON-RPC parameters or the requested tool are invalid. What to do: Match the method schema and use a tool returned by tools/list. Emission sites: `landfeed/mcp/server.mjs:55`, `landfeed/mcp/server.mjs:71`. ## -32603 Internal JSON-RPC server failure. What to do: Retain the call context, check billing if a tool started, and retry a read later. Emission sites: `landfeed/mcp/server.mjs:86`, `landfeed/mcp/server.mjs:88`. ## -32700 JSON-RPC parse failure. What to do: Send valid UTF-8 JSON, one stdio message per line. Emission sites: `landfeed/mcp/server.mjs:98`. ## access_denied Authorization was refused or its redirect policy changed. What to do: Start consent again with a registered redirect; ask the operator if it is no longer allowed. Emission sites: `landfeed/api/landfeed_api/oauth.py:95`, `mcp==1.30.0/server/auth/provider.py:64`. ## account_inactive The account is disabled. What to do: Use an active account or ask account support. Emission sites: `landfeed/api/landfeed_api/watch/store.py:35`. ## account_required A static benchmark credential cannot identify an account. What to do: Use an issued account API key. Emission sites: `landfeed/api/landfeed_api/routers/watch.py:39`. ## ambiguous Several parcel or area candidates match; HTTP 200. Candidate discovery is charged. What to do: Ask the user for obręb or choose an explicitly confirmed candidate id; never pick silently. Emission sites: `landfeed/contracts/envelope.json:1`. ## billing_unavailable Ask could not settle its reserved work. New artifacts and factual text are withheld. What to do: Retain meta.request_id, inspect the account and reconcile settlement before replaying work. Emission sites: `landfeed/api/landfeed_api/ask/router.py:228`. ## blocked_destination The webhook destination resolves to an unsafe address. What to do: Use public HTTPS on port 443; correct DNS before reconfiguring the webhook. Emission sites: `landfeed/api/landfeed_api/watch/network.py:100`. ## body_too_large The request body exceeds the endpoint cap. What to do: Reduce the body; watch accepts at most 256 KiB. Emission sites: `landfeed/api/landfeed_api/routers/watch.py:86`. ## cancelled The stdio MCP client cancelled the call; billing is unknown. What to do: Check account usage before repeating a paid operation. Emission sites: `landfeed/mcp/bridge.mjs:127`. ## client_result_required The continuation expects a client tool result. What to do: Resend the signed continuation with matching client_results. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:50`. ## confirmation_required The continuation expects explicit action confirmation. What to do: Ask the user and resend confirmation for the signed step_id. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:55`. ## conflicting_historical_evidence Historical event evidence contradicts the saved change. What to do: Do not treat a suppressed event as no change; operator must repair producer evidence. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:122`, `landfeed/api/landfeed_api/watch/matching.py:207`, `landfeed/api/landfeed_api/watch/matching.py:209`. ## conflicting_version_provenance Event version provenance contradicts its evidence. What to do: Operator must reconcile version/source evidence; do not reconstruct it from current data. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:183`. ## context_too_large Conversation evidence exceeds bounded context limits. What to do: Resend only relevant signed results; at most 40 results and 512,000 bytes total. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:27`, `landfeed/api/landfeed_api/ask/conversation.py:66`. ## duplicate_artifact An artifact identifier occurs more than once. What to do: Send each complete signed artifact once. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:32`. ## event_type_has_no_producer The requested event family has no serving producer. What to do: Use one of the seven supported layer.changed watch filters. Emission sites: `landfeed/api/landfeed_api/watch/validation.py:60`. ## expired_continuation The signed conversation continuation expired. What to do: Start a new turn with fresh context; continuations last one hour. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:25`. ## idempotency_conflict A request key was reused with different watch items. What to do: Use the original items for a retry, or a new key for a new action. Emission sites: `landfeed/api/landfeed_api/watch/store.py:89`. ## incomplete_version_provenance An event lacks the version/source evidence required for delivery. What to do: Operator must repair the producer; never infer a negative from a missing delivery. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:51`. ## insufficient_credits Ask could not reserve the declared budget. What to do: Reduce max_credits within the supported range or fund the account before asking again. Emission sites: `landfeed/api/landfeed_api/ask/router.py:228`. ## internal The server failed to complete the operation; HTTP 500, refunded. What to do: Retain meta.request_id and retry a read later; check billing after an interrupted response. Emission sites: `landfeed/api/landfeed_api/app.py:469`, `landfeed/contracts/envelope.json:1`. ## invalid_arguments The stdio tool received an invalid argument object or path value. What to do: Match the tool inputSchema; path arguments must be nonempty strings. Emission sites: `landfeed/mcp/bridge.mjs:71`, `landfeed/mcp/bridge.mjs:76`, `landfeed/mcp/bridge.mjs:81`. ## invalid_client OAuth client authentication failed. What to do: Check client registration and auth method, then reconnect. Emission sites: `landfeed/api/landfeed_api/oauth.py:365`, `mcp==1.30.0/server/auth/provider.py:81`. ## invalid_client_metadata OAuth registration requested unsupported metadata. What to do: Use authorization_code/refresh_token and a supported client authentication method. Emission sites: `landfeed/api/landfeed_api/oauth.py:83`, `landfeed/api/landfeed_api/oauth.py:85`, `mcp==1.30.0/server/auth/provider.py:50`. ## invalid_client_tool A declared client tool schema or its conversation input is invalid. What to do: Send a self-contained local JSON schema and correctly shaped client results; remote/dynamic references are rejected. Emission sites: `landfeed/api/landfeed_api/ask/router.py:167`. ## invalid_digest Signed evidence or its account binding failed verification. What to do: Send the original signed object unchanged from this account; otherwise start again. Emission sites: `landfeed/api/landfeed_api/ask/signing.py:41`. ## invalid_grant OAuth code or refresh token is expired, consumed or invalid. What to do: Restart authorization; do not replay an old rotated refresh token. Emission sites: `landfeed/api/landfeed_api/oauth.py:165`, `landfeed/api/landfeed_api/oauth.py:194`, `landfeed/api/landfeed_api/oauth.py:298`, `mcp==1.30.0/server/auth/provider.py:81`. ## invalid_id A watch/resource UUID is malformed. What to do: Copy the UUID returned by creation/listing. Emission sites: `landfeed/api/landfeed_api/routers/watch.py:48`. ## invalid_input Request parameters or JSON do not match the operation; generally HTTP 400 and free. What to do: Correct required fields, types and exclusivity; inspect error.hint where present. Emission sites: `landfeed/api/landfeed_api/account/router.py:51`, `landfeed/api/landfeed_api/account/router.py:57`, `landfeed/api/landfeed_api/app.py:460`, `landfeed/api/landfeed_api/app.py:549`, `landfeed/api/landfeed_api/app.py:557`, `landfeed/api/landfeed_api/app.py:577`, `landfeed/api/landfeed_api/mcp_remote.py:39`, `landfeed/api/landfeed_api/routers/billing.py:141`, `landfeed/api/landfeed_api/routers/billing.py:87`, `landfeed/api/landfeed_api/routers/billing.py:93`, `landfeed/api/landfeed_api/routers/watch.py:104`, `landfeed/api/landfeed_api/routers/watch.py:116`, `landfeed/api/landfeed_api/routers/watch.py:183`, `landfeed/api/landfeed_api/routers/watch.py:188`, `landfeed/api/landfeed_api/routers/watch.py:91`, `landfeed/api/landfeed_api/routers/watch.py:99`, `landfeed/api/landfeed_api/watch/store.py:81`, `landfeed/api/landfeed_api/watch/validation.py:48`, `landfeed/contracts/envelope.json:1`. ## invalid_polygon The supplied geometry cannot be admitted. What to do: Use a valid WGS84 Polygon/MultiPolygon within endpoint limits. Emission sites: `landfeed/api/landfeed_api/watch/store.py:65`, `landfeed/api/landfeed_api/watch/validation.py:96`. ## invalid_redirect_uri OAuth callback URI is not allowed by server policy. What to do: Register an exact client callback allowed by the operator. Emission sites: `landfeed/api/landfeed_api/oauth.py:81`, `mcp==1.30.0/server/auth/provider.py:50`. ## invalid_request The OAuth request is incomplete or violates resource/PKCE requirements. What to do: Use S256 PKCE, exact redirect_uri and the discovered MCP resource. Emission sites: `landfeed/api/landfeed_api/oauth.py:290`, `landfeed/api/landfeed_api/oauth.py:307`, `landfeed/api/landfeed_api/oauth.py:367`, `landfeed/api/landfeed_api/oauth.py:93`, `landfeed/api/landfeed_api/oauth.py:97`, `mcp==1.30.0/server/auth/provider.py:64`, `mcp==1.30.0/server/auth/provider.py:81`. ## invalid_response The stdio bridge received invalid JSON, UTF-8 or a non-envelope response. Billing is unknown. What to do: Keep the request context, check usage and report the transport failure. Emission sites: `landfeed/mcp/bridge.mjs:119`, `landfeed/mcp/bridge.mjs:130`. ## invalid_scope OAuth requested a scope other than landfeed:read. What to do: Request landfeed:read. Emission sites: `landfeed/api/landfeed_api/oauth.py:100`, `mcp==1.30.0/server/auth/provider.py:64`, `mcp==1.30.0/server/auth/provider.py:81`. ## invalid_software_statement OAuth registration contains an invalid software statement. What to do: Remove unsupported software metadata or use dynamic client registration with valid client metadata. Emission sites: `mcp==1.30.0/server/auth/provider.py:50`. ## invalid_target The OAuth resource does not identify this MCP server. What to do: Use the resource in protected-resource discovery, ending /mcp. Emission sites: `landfeed/api/landfeed_api/oauth.py:296`. ## invalid_webhook_url Webhook URL syntax, protocol or privacy admission failed. What to do: Use a public HTTPS URL on port 443 with no credentials, fragment or private fields. Emission sites: `landfeed/api/landfeed_api/watch/network.py:63`. ## missing_artifact Conversation history refers to an artifact absent from results. What to do: Resend the full original signed artifact, including data. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:36`. ## missing_historical_evidence Historical event evidence or its dated source is missing. What to do: Operator must repair source evidence; current dates cannot replace historical dates. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:201`, `landfeed/api/landfeed_api/watch/matching.py:42`, `landfeed/api/landfeed_api/watch/matching.py:78`, `landfeed/api/landfeed_api/watch/matching.py:84`, `landfeed/api/landfeed_api/watch/matching.py:87`, `landfeed/api/landfeed_api/watch/matching.py:99`. ## not_covered The input resolved outside the loaded data; this is unknown, not a negative result. What to do: Inspect scope/source/note; use another source. The uncovered work is refunded. Emission sites: `landfeed/api/landfeed_api/app.py:199`, `landfeed/api/landfeed_api/app.py:212`, `landfeed/api/landfeed_api/app.py:216`, `landfeed/api/landfeed_api/app.py:228`, `landfeed/api/landfeed_api/app.py:231`, `landfeed/api/landfeed_api/app.py:344`, `landfeed/api/landfeed_api/app.py:392`, `landfeed/api/landfeed_api/app.py:432`, `landfeed/contracts/envelope.json:1`. ## not_found No matching resource was found; parcel reads refund the work. What to do: Check the id and account ownership; refine q or point where applicable. Emission sites: `landfeed/api/landfeed_api/account/router.py:49`, `landfeed/api/landfeed_api/app.py:193`, `landfeed/api/landfeed_api/app.py:208`, `landfeed/api/landfeed_api/app.py:577`, `landfeed/api/landfeed_api/watch/store.py:114`, `landfeed/api/landfeed_api/watch/store.py:120`, `landfeed/api/landfeed_api/watch/store.py:74`, `landfeed/api/landfeed_api/watch/store.py:91`, `landfeed/contracts/envelope.json:1`. ## note_required A correction event lacks its explanatory note. What to do: Operator must supply the producer correction note before delivery. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:148`. ## private_content Watch input contains forbidden owner or land-register content. What to do: Remove private fields; use only cadastral parcel/area selectors. Emission sites: `landfeed/api/landfeed_api/watch/validation.py:50`. ## provider_unavailable The ask provider failed. What to do: Retry later after checking settled billing; factual output is withheld on failed settlement. Emission sites: `landfeed/api/landfeed_api/ask/providers/codex_pool.py:205`, `landfeed/api/landfeed_api/ask/v2.py:155`. ## rate_limited A rate, concurrency, credit or team quota limit refused admission; HTTP 429. What to do: Inspect balance, plan/quota and any Retry-After; reduce concurrency and retry reads with backoff. Emission sites: `landfeed/api/landfeed_api/account/router.py:53`, `landfeed/api/landfeed_api/ask/router.py:197`, `landfeed/api/landfeed_api/billing/metering.py:110`, `landfeed/api/landfeed_api/mcp_remote.py:114`, `landfeed/api/landfeed_api/routers/billing.py:126`, `landfeed/api/landfeed_api/routers/billing.py:89`, `landfeed/api/landfeed_api/watch/store.py:130`, `landfeed/contracts/envelope.json:1`. ## resolution_unavailable Webhook destination DNS could not be resolved. What to do: Retry later; fix DNS if persistent. Emission sites: `landfeed/api/landfeed_api/watch/network.py:92`, `landfeed/api/landfeed_api/watch/network.py:98`. ## response_too_large The stdio response exceeded 16 MiB; billing is unknown. What to do: Reduce requested data and check usage before replay. Emission sites: `landfeed/mcp/bridge.mjs:103`. ## server_error OAuth could not complete due to a server failure. What to do: Reconnect later; report the failure without sending secrets. Emission sites: `landfeed/api/landfeed_api/oauth.py:369`, `mcp==1.30.0/server/auth/provider.py:64`. ## signing_unavailable Ask conversation signing is unavailable. What to do: Retry later; operator must configure the persistent signing secret. Emission sites: `landfeed/api/landfeed_api/ask/signing.py:30`. ## source_unavailable A required source or accounting/authentication service failed; HTTP 503. What to do: Retry the read later; retain request_id and inspect billing. Do not interpret this as no data. Emission sites: `landfeed/api/landfeed_api/account/router.py:61`, `landfeed/api/landfeed_api/app.py:462`, `landfeed/api/landfeed_api/app.py:464`, `landfeed/api/landfeed_api/app.py:466`, `landfeed/api/landfeed_api/auth.py:45`, `landfeed/api/landfeed_api/billing/metering.py:110`, `landfeed/contracts/envelope.json:1`. ## temporarily_unavailable OAuth endpoint exceeded its per-process request budget. What to do: Respect Retry-After (60 seconds) and restart authorization if necessary. Emission sites: `landfeed/api/landfeed_api/oauth.py:358`, `mcp==1.30.0/server/auth/provider.py:64`. ## timeout The stdio bridge exceeded its 30-second deadline; billing is unknown. What to do: Check usage before retrying; the server may have completed the work. Emission sites: `landfeed/mcp/bridge.mjs:128`. ## transport_error The stdio bridge could not complete HTTP; billing is unknown. What to do: Check service connectivity and account usage before replay. Emission sites: `landfeed/mcp/bridge.mjs:139`. ## unapproved_software_statement The OAuth server does not approve the submitted software statement. What to do: Use supported dynamic registration and contact the operator for an approved client policy. Emission sites: `mcp==1.30.0/server/auth/provider.py:50`. ## unapproved_source Event evidence references a source without the required serving approval. What to do: Operator must review the source; never substitute an unapproved answer. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:28`. ## unauthorized Credentials are missing, invalid or lack account/role authority (401 or 403). What to do: Use a valid account key, reconnect OAuth, or request the required team role. Emission sites: `landfeed/api/landfeed_api/account/router.py:28`, `landfeed/api/landfeed_api/account/router.py:47`, `landfeed/api/landfeed_api/auth.py:38`, `landfeed/api/landfeed_api/routers/billing.py:85`, `landfeed/api/landfeed_api/routers/watch.py:36`, `landfeed/contracts/envelope.json:1`. ## unauthorized_client The OAuth client is not allowed to use this grant. What to do: Register a client supporting authorization_code and refresh_token, then reconnect. Emission sites: `mcp==1.30.0/server/auth/provider.py:64`, `mcp==1.30.0/server/auth/provider.py:81`. ## unavailable Ask cannot finish due to provider, signing or settlement availability. What to do: Keep request_id; inspect billing and retry only when safe. Emission sites: `landfeed/api/landfeed_api/ask/streaming.py:48`, `landfeed/api/landfeed_api/ask/v2.py:151`. ## unexpected_continuation A confirmation/client result does not match the continuation kind. What to do: Resend only the matching signed action/result or start a new turn. Emission sites: `landfeed/api/landfeed_api/ask/conversation.py:58`. ## unknown_tool The stdio MCP tool name is not in the six-tool catalogue. What to do: Call tools/list and use a published tool name. Emission sites: `landfeed/mcp/bridge.mjs:69`. ## unsafe_event Notification evidence failed schema, source or privacy admission. What to do: Operator must correct the producer; a suppressed notification proves no absence. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:141`, `landfeed/api/landfeed_api/watch/matching.py:151`, `landfeed/api/landfeed_api/watch/matching.py:160`, `landfeed/api/landfeed_api/watch/matching.py:167`, `landfeed/api/landfeed_api/watch/matching.py:172`, `landfeed/api/landfeed_api/watch/matching.py:177`, `landfeed/api/landfeed_api/watch/matching.py:185`, `landfeed/api/landfeed_api/watch/matching.py:214`, `landfeed/api/landfeed_api/watch/matching.py:226`, `landfeed/api/landfeed_api/watch/worker.py:67`. ## unsupported_grant_type The OAuth grant type is unsupported. What to do: Use authorization_code or refresh_token; client_credentials is not supported. Emission sites: `mcp==1.30.0/server/auth/provider.py:81`. ## unsupported_legacy_event A stored legacy event has no safe supported notification shape. What to do: Use supported layer.changed events; operator must implement a typed producer for other families. Emission sites: `landfeed/api/landfeed_api/watch/matching.py:114`. ## unsupported_response_type OAuth authorization requested a response type other than code. What to do: Request response_type=code with PKCE S256. Emission sites: `mcp==1.30.0/server/auth/provider.py:64`. ## validation_work_limit Watch validation exceeds item/vertex work bounds (413). What to do: Limit to 100 items and 1024 polygon vertices in aggregate; reduce the request. Emission sites: `landfeed/api/landfeed_api/watch/validation.py:67`, `landfeed/api/landfeed_api/watch/validation.py:79`, `landfeed/api/landfeed_api/watch/validation.py:91`. ## watch_limit The shared plan watch-item quota is exhausted (409). What to do: Remove items or obtain an approved larger limit; zero can mean operator configuration is pending. Emission sites: `landfeed/api/landfeed_api/watch/store.py:46`, `landfeed/api/landfeed_api/watch/store.py:58`. ## watch_unavailable Watch storage or processing is unavailable (503). What to do: Retry reads later; use the creation idempotency key when retrying creation. Emission sites: `landfeed/api/landfeed_api/ask/router.py:204`. ## webhook_unconfigured The watch has no configured webhook to rotate. What to do: Configure the webhook first, then save its one-time secret securely. Emission sites: `landfeed/api/landfeed_api/watch/store.py:157`. # Ask endpoint and SSE streaming Call `POST /v1/ask` with an account API key. `Accept: text/event-stream` selects ask-v2. For JSON, set `version: ask-v2` to receive an `events` array and `continuation`. Plain JSON without conversation fields retains ask-v1 response semantics. The [operation reference](../../operations/ask.md) contains the full schema. The pl-prod planner is `codex-app-server`, with an explicitly configured model and a dedicated service-owned CLI-managed ChatGPT login. The model plans validated tools; public API evidence supplies facts. Missing configuration/login refuses without charging. Anthropic is an optional API-key-only provider; subscription OAuth credentials are refused. ## Minimal streaming client Save as `ask-stream.py`, set `LANDFEED_API_KEY`, and run `python3 ask-stream.py`. Only the Python standard library is needed. It never retries automatically. Pre-admission failures use JSON and an HTTP status rather than an SSE stream. ```python import json import os import urllib.request request = urllib.request.Request( "https://mcp.agentdzialek.pl/v1/ask", method="POST", headers={"X-Api-Key": os.environ["LANDFEED_API_KEY"], "Content-Type": "application/json", "Accept": "text/event-stream"}, data=json.dumps({"question": "Czy działka leży w obszarze zagrożenia powodziowego?", "context": {"parcel_id": "146501_1.0101.12/3"}, "max_credits": 5, "version": "ask-v2"}).encode("utf-8"), ) artifacts, citations, text, continuation = [], [], "", None name, data_lines, done, failed = None, [], False, False with urllib.request.urlopen(request, timeout=30) as response: if not response.headers.get("Content-Type", "").startswith("text/event-stream"): raise RuntimeError("Expected SSE; inspect the JSON admission error") for raw_line in response: line = raw_line.decode("utf-8").rstrip("\r\n") if line.startswith(":"): continue if line.startswith("event:"): name = line[6:].lstrip(" ") elif line.startswith("data:"): data_lines.append(line[5:].lstrip(" ")) elif not line and data_lines: data = json.loads("\n".join(data_lines)) if name == "artifact": artifacts.append(data) # Save the whole signed object, including data. elif name == "answer.delta": text += data["text"] elif name == "answer.citations": citations = data elif name == "error": failed = True print(json.dumps({"error": data}, ensure_ascii=False)) elif name in ("confirm.required", "client_tool.call", "budget.exceeded"): print(json.dumps({"event": name, "data": data}, ensure_ascii=False)) elif name == "done": done, continuation = True, data["continuation"] # With a preceding error, a zero total does not prove successful settlement. if not failed: print(json.dumps({"credits_total": data["credits_total"]})) name, data_lines = None, [] if not done: raise RuntimeError("Stream interrupted; reconcile billing before replay") print(json.dumps({"answer": text, "citations": citations, "artifacts": artifacts, "continuation": continuation, "failed": failed}, ensure_ascii=False)) ``` A frame has `event: name` and JSON `data:`, followed by a blank line. An accepted uninterrupted stream ends exactly once with `done`, even after `error`. A disconnect can lose that frame and does not cancel completed work. Do not buffer or publicly cache the authenticated stream. ## Events and settlement | event | Meaning | | --- | --- | | `answer.citations` | Numbered citations with source/date. | | `answer.delta` | Answer text after settlement. | | `artifact` | Whole signed API result. | | `budget.exceeded` | Unexecuted plan exceeds budget. | | `client_tool.call` | Client UI action request. | | `confirm.required` | Pause for user approval. | | `done` | End and continuation; cost after settlement. | | `error` | Failure; inspect settlement state. | | `step.finished` | Finished step and settled cost. | | `step.started` | Request and estimate before execution. | See the [SSE event reference](../../sse-events.md) for every field and constraint. `step.started` exposes a public request and estimated cost before execution. `step.finished` exposes settled cost after the turn-level decision. `artifact` contains an exact public API body, not model-authored facts. New artifacts and factual answer text wait for settlement and are withheld on settlement failure. Budget defaults to 5 credits, maximum 20. Reserve the whole budget before provider work. Public tools retain their public prices; a completed answer adds 1 credit. A budget-stopped ask-v2 turn is entirely free, including earlier reads; new artifacts and facts are withheld. Client-only and confirmation-only turns add no answer surcharge. `done.credits_total` is authoritative only after successful settlement; a zero following `error` is not proof of a refund. ## Stateless continuation Keep `messages`, entire signed `artifact` objects and the latest `continuation` on the client. Resend them as `messages`, `results`, `continuation` with the next question. Signatures bind exact data and account: never edit artifacts or move them between accounts. Continuations expire after one hour. Resumes still need a nonempty `question`, for example „Kontynuuj.”. Artifact ids are references, not server-side storage lookups. Only the latest 20 messages enter the planner verbatim; older intent is summarized in the current request. `confirm.required` pauses before watch creation/deletion, webhook registration, export or any public step above 3 credits. Obtain user approval, then resend the signed continuation with `confirmation {step_id, approved:true}` for that exact action. Public exports remain unavailable. Confirmation signatures are not one-use storage: replaying webhook registration rotates the secret and resets its cursor. Never replay it automatically. For `client_tool.call`, execute the declared UI action and send `client_results` containing `call_id` and `result` with the continuation. Client results are untrusted UI state, never parcel evidence. See [limits](rate-limits.md) for context/body bounds. The server does not persist questions, answers or artifact payloads as conversations; clients own their own memory and retention. The whole-request Ask budget defaults to 120 seconds; operators may set positive finite `LANDFEED_ASK_REQUEST_SECONDS`. Provider setup/turn waits are clamped to the remaining budget. While open, SSE sends `: keepalive` comments every 10 seconds, including silent model waits. Ignore comments; they are not events or billed steps. Request expiry sends `error` and then `done`; no unfinished public step is charged. Completed public work retains its existing settlement. # API keys and MCP OAuth Authorize REST calls with an account API key in `X-Api-Key`. Issued keys start with `lf_live_`. Keep them out of query strings, questions and bug reports. Account identity, revocation and shared-credit membership are checked on each call. The [quickstart](quickstart.md) supplies an executable header example. REST also accepts the same API key as `Authorization: Bearer`; use one credential method. Duplicate headers or conflicting credentials are rejected. Operator benchmark keys cannot replace account identity for watch, ask or billing management. ## OAuth for Claude and ChatGPT Add `https://mcp.agentdzialek.pl/mcp` in your client and select OAuth. The client discovers metadata, registers and opens browser consent. Enter your account API key on landfeed's consent page and approve access. The client then sends its OAuth token on MCP requests, never an API key inside a question. | Method | Path | | --- | --- | | GET | /.well-known/oauth-protected-resource/mcp | | GET | /.well-known/oauth-protected-resource | | GET | /.well-known/oauth-authorization-server | | POST | /register | | GET | /authorize | | GET, POST | /oauth/consent | | POST | /token | | POST | /revoke | The scope is `landfeed:read`. Authorization uses the authorization-code flow with S256 PKCE, an exact registered redirect URI and the discovered `/mcp` resource. Access tokens last one hour; rotating refresh tokens last 30 days. Used authorization codes and old refresh tokens cannot be replayed. OAuth tokens do not authorize `/v1/ask`; use an account API key there. Revoking the key or account invalidates linked grants. After a leak, revoke the key through account management, issue a replacement and reconnect clients. Do not publish tokens or callback URLs containing authorization codes. ## Troubleshooting 401 means missing or invalid authentication. 403 means missing account identity or permission. `invalid_redirect_uri` requires the client and server operator to agree on an exact allowed callback; adding a server URL in a client UI does not change server policy. On `invalid_grant`, start authorization again. See the [errors catalogue](../../errors.md) and [client setup](mcp-setup.md). ## Account and keys Read `/v1/billing/account`, `/v1/account/ledger` and `/v1/account/usage` for the authenticated account. List/create keys at `/v1/account/keys`, revoke a caller-owned key with DELETE `/v1/account/keys/{key_id}`, and rotate with POST `/v1/account/keys/{key_id}/rotate`. Secret values are returned only on creation/rotation; keep them private. All account operations are free; reads are paginated. The operation reference defines cursor and key-management permission rules. # Changelog ## 2026-10-21 • ask-v2 and documentation Ask adds typed SSE, signed artifacts/continuations, action confirmations and explicit public step requests/costs. A budget-stopped ask-v2 turn is free; new facts/artifacts wait for successful settlement. JSON without v2 selection retains its earlier response format. Documentation adds Polish guides, English agent text, OpenAPI-derived reference, provenance-labelled fixture examples, an extracted error catalogue and executable-example tests. Site publication remains a separate operator action. ## Contract 2.0.0 HTTP paths and `meta.api_version` remain `v1`. A response declaring `meta.contract_version: 2.0.0` must include additional provenance, scope, method, licence and billing fields. Historical unversioned responses do not become v2 merely because a client updates. Four-state coverage semantics remain unchanged. The versioned contract owns exact methods and schemas. Batch checks and their jobs remain runtime-dormant. Before adopting a feature, inspect its availability in the [reference](../../schemas.md) and the running service's `/v1/openapi.json`. # Four coverage states: unknown is never no A missing result cannot establish that a parcel has no plan, hazard or restriction. Read each layer's `coverage`, `source`, `as_of` and `note` together. | State | Evidence | Consumer action | | --- | --- | --- | | `covered` | The source covers the place and provides a result. | Report it with source, date and actual evidence scope. | | `covered_no_data` | Coverage is established but no matching record/object is present. | Say no record was found in the data covering this parcel, limited to that source and scope. | | `not_covered` | Coverage or a reliable evidence basis is absent. | Report unknown, with `value: null`; never render this as false. | | `not_computed` | The result has not been computed. | Say so; do not substitute false or an empty list. | For flood maps, `covered_no_data` means no matching mapped zone at the declared scope, not absence of every possible flood or waterlogging hazard. `not_covered` cannot support even that limited negative. An empty MPZP integration lookup does not establish a plan's legal status. ## Scope, method and date V2 adds `scope`, `method` and `licence`. Scope is `parcel_polygon`, `point`, `obreb` (cadastral precinct), `gmina` (municipality) or `grid`. Point evidence must not become a whole-parcel conclusion. Method distinguishes `official`, `derived`, `computed` and `extracted`. Extraction is a method, not a fifth coverage state; below-threshold extraction becomes `not_covered`. `as_of` is the source data date, not request time. Null means unknown. `meta.generated_at` does not refresh the source. A listed layer or approved licence does not prove coverage for a particular parcel. ## Polish domain glossary A działka ewidencyjna is a cadastral parcel; obręb is its cadastral precinct; gmina is municipality. Plan ogólny (POG) is the municipality's general plan; MPZP is miejscowy plan zagospodarowania przestrzennego (local spatial development plan); WZ is warunki zabudowy (development conditions). Preserve these Polish terms in identifiers and explanations. Plan states `draft`, `adopted`, `in_force`, `none` distinguish stages. Adoption alone does not mean a plan is in force. MPZP legal status can be null when a zone is identified without a known legal status; never translate null to `none`. No plan does not settle buildability; road evidence does not settle legal access. RCN means Rejestr Cen Nieruchomości: its aggregate concerns the entire obręb, not a parcel valuation. See [sources](sources.md) and [answer boundaries](never-answers.md). ## Parcel features, search and place suggestions The card's existing 1 credit includes `result.features`: 20 sourced fields, each with `value`, `unit`, `source`, `as_of`, `method`, `coverage` and `note`. The RCN feature is a municipality cohort, rounded to 50 PLN/m² and suppressed below six sales. It is context rather than an individual parcel valuation. Road geometry never proves legal access. Missing inputs remain explicit unknowns. | Feature | Schema | | --- | --- | | `shape_and_size.area_official_m2` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "m2"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `shape_and_size.area_geometry_m2` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "m2"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `shape_and_size.perimeter_m` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "m"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `shape_and_size.shape_regularity` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "ratio"}, "value": {"anyOf": [{"maximum": 1, "minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `shape_and_size.squareness` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "ratio"}, "value": {"anyOf": [{"maximum": 1, "minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `shape_and_size.elongation` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": "ratio"}, "value": {"anyOf": [{"minimum": 1, "type": "number"}, {"type": "null"}]}}}]}` | | `access_and_roads.public_road_distance_m` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["bdot_roads"]}}}, "unit": {"const": "m"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `access_and_roads.road_access` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["bdot_roads", "egib_dr_parcels", "egib_parcels"]}}}, "unit": {"const": null}, "value": {"anyOf": [{"type": "boolean"}, {"type": "null"}]}}}]}` | | `access_and_roads.frontage_m` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_dr_parcels", "egib_parcels"]}}}, "unit": {"const": "m"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `land_use.land_use_classes` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_parcels"]}}}, "unit": {"const": null}, "value": {"anyOf": [{"items": {"pattern": "^[A-Za-zŁłŻż]{1,5}(?:[IVX]{1,4}[ab]?)?$", "type": "string"}, "maxItems": 100, "type": "array", "uniqueItems": true}, {"type": "null"}]}}}]}` | | `land_use.pog_zone_class` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["pog_sweep", "pog_zones"]}}}, "unit": {"const": null}, "value": {"anyOf": [{"enum": ["SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP"], "type": "string"}, {"type": "null"}]}}}]}` | | `buildings_and_surroundings.buildings_present` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_buildings"]}}}, "unit": {"const": null}, "value": {"anyOf": [{"type": "boolean"}, {"type": "null"}]}}}]}` | | `buildings_and_surroundings.building_count` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_buildings"]}}}, "unit": {"const": "count"}, "value": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}]}}}]}` | | `buildings_and_surroundings.building_footprint_m2` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_buildings"]}}}, "unit": {"const": "m2"}, "value": {"anyOf": [{"minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `buildings_and_surroundings.building_coverage_pct` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_buildings"]}}}, "unit": {"const": "percent"}, "value": {"anyOf": [{"maximum": 100, "minimum": 0, "type": "number"}, {"type": "null"}]}}}]}` | | `buildings_and_surroundings.buildings_500m` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["egib_buildings"]}}}, "unit": {"const": "count"}, "value": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}]}}}]}` | | `prices_nearby.rcn_gmina_median_pln_m2` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["rcn_clean_agg"]}}}, "unit": {"const": "PLN/m2"}, "value": {"anyOf": [{"minimum": 0, "multipleOf": 50, "type": "number"}, {"type": "null"}]}}}]}` | | `prices_nearby.rcn_gmina_sales_count` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["rcn_clean_agg"]}}}, "unit": {"const": "count"}, "value": {"anyOf": [{"minimum": 6, "type": "integer"}, {"type": "null"}]}}}]}` | | `development_activity.gunb_activity_gmina` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["gunb_permits"]}}}, "unit": {"const": "count"}, "value": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}]}}}]}` | | `development_activity.gunb_activity_500m` | `{"allOf": [{"$ref": "#/$defs/FeatureAnswer"}, {"properties": {"source": {"properties": {"id": {"enum": ["gunb_permits"]}}}, "unit": {"const": "count_min"}, "value": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}]}}}]}` | ```json { "shape_and_size": { "area_official_m2": { "value": 1200, "unit": "m2", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "egib_declared_calibrated_m2_v1", "coverage": "covered", "note": "Powierzchnia ewidencyjna z danych EGiB." }, "area_geometry_m2": { "value": 1200.0, "unit": "m2", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "postgis_area_epsg2180_v1", "coverage": "covered", "note": "Wynik obliczony z obrysu działki. Nie określa możliwości zabudowy." }, "perimeter_m": { "value": 140.0, "unit": "m", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "postgis_perimeter_including_holes_epsg2180_v1", "coverage": "covered", "note": "Wynik obliczony z obrysu działki. Nie określa możliwości zabudowy." }, "shape_regularity": { "value": 1, "unit": "ratio", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "area_over_min_rotated_rectangle_v1", "coverage": "covered", "note": "Wynik obliczony z obrysu działki. Nie określa możliwości zabudowy." }, "squareness": { "value": 0.75, "unit": "ratio", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "min_rectangle_short_over_long_v1", "coverage": "covered", "note": "Wynik obliczony z obrysu działki. Nie określa możliwości zabudowy." }, "elongation": { "value": 1.333333, "unit": "ratio", "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "min_rectangle_long_over_short_v1", "coverage": "covered", "note": "Wynik obliczony z obrysu działki. Nie określa możliwości zabudowy." } }, "access_and_roads": { "public_road_distance_m": { "value": 12.0, "unit": "m", "source": { "id": "bdot_roads", "title": "bdot_roads", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "licence": "open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "polygon_to_public_management_road_cap5000m_v1", "coverage": "covered", "note": "Wynik geometryczny. Nie potwierdza prawnego dostępu do drogi publicznej." }, "road_access": { "value": true, "unit": null, "source": { "id": "bdot_roads", "title": "bdot_roads", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "licence": "open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "dr_shared_boundary_or_public_line_within30m_v1", "coverage": "covered", "note": "Wynik geometryczny. Nie potwierdza prawnego dostępu do drogi publicznej.", "sources": [ { "id": "bdot_roads", "title": "bdot_roads", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "licence": "open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, { "id": "egib_dr_parcels", "title": "egib_dr_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" } ] }, "frontage_m": { "value": 40.0, "unit": "m", "source": { "id": "egib_dr_parcels", "title": "egib_dr_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "union_dr_shared_boundary_length_epsg2180_v1", "coverage": "covered", "note": "Długość wspólnej granicy z działkami oznaczonymi jako drogi. Nie potwierdza prawnego dojazdu." } }, "land_use": { "land_use_classes": { "value": [ "R", "dr" ], "unit": null, "source": { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "egib_unique_land_use_symbols_v1", "coverage": "covered", "note": "Nie wczytaliśmy jeszcze klas użytków EGiB dla tej działki." }, "pog_zone_class": { "value": null, "unit": null, "source": { "id": "pog_sweep", "title": "pog_sweep", "publisher": "Fixture only", "attribution": "Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia", "licence": "local_law_no_copyright", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "dominant_qualified_pog_symbol_v1", "coverage": "not_computed", "note": "Nie obliczyliśmy jeszcze tej cechy dla działki." } }, "buildings_and_surroundings": { "buildings_present": { "value": true, "unit": null, "source": { "id": "egib_buildings", "title": "egib_buildings", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "positive_area_footprint_intersection_v1", "coverage": "covered", "note": "Budynki według obrysów EGiB. Powierzchnia zabudowy obejmuje część obrysów położoną na działce." }, "building_count": { "value": 1, "unit": "count", "source": { "id": "egib_buildings", "title": "egib_buildings", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "distinct_positive_area_footprints_v1", "coverage": "covered", "note": "Budynki według obrysów EGiB. Powierzchnia zabudowy obejmuje część obrysów położoną na działce." }, "building_footprint_m2": { "value": 100, "unit": "m2", "source": { "id": "egib_buildings", "title": "egib_buildings", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "area_union_clipped_footprints_epsg2180_v1", "coverage": "covered", "note": "Budynki według obrysów EGiB. Powierzchnia zabudowy obejmuje część obrysów położoną na działce." }, "building_coverage_pct": { "value": 8.333333, "unit": "percent", "source": { "id": "egib_buildings", "title": "egib_buildings", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "100_clipped_union_area_over_parcel_area_v1", "coverage": "covered", "note": "Budynki według obrysów EGiB. Powierzchnia zabudowy obejmuje część obrysów położoną na działce." }, "buildings_500m": { "value": null, "unit": "count", "source": { "id": "egib_buildings", "title": "egib_buildings", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "distinct_footprints_polygon_radius500m_v1", "coverage": "not_computed", "note": "Nie obliczyliśmy jeszcze tej cechy dla działki." } }, "prices_nearby": { "rcn_gmina_median_pln_m2": { "value": 100, "unit": "PLN/m2", "source": { "id": "rcn_clean_agg", "title": "rcn_clean_agg", "publisher": "Fixture only", "attribution": "Źródło: Rejestr Cen Nieruchomości (GUGiK).", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "fixed_gmina_clean_cohort_k6_median_round50_half_even_v1", "coverage": "covered", "note": "Dane RCN dla całej gminy, z co najmniej 6 transakcji. Mediana jest zaokrąglona do 50 zł/m². To nie jest wycena działki.; stan rejestru na 1 października 2026 r." }, "rcn_gmina_sales_count": { "value": 6, "unit": "count", "source": { "id": "rcn_clean_agg", "title": "rcn_clean_agg", "publisher": "Fixture only", "attribution": "Źródło: Rejestr Cen Nieruchomości (GUGiK).", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "fixed_gmina_clean_distinct_sales_k6_v1", "coverage": "covered", "note": "Dane RCN dla całej gminy, z co najmniej 6 transakcji. Mediana jest zaokrąglona do 50 zł/m². To nie jest wycena działki.; stan rejestru na 1 października 2026 r." } }, "development_activity": { "gunb_activity_gmina": { "value": 10, "unit": "count", "source": { "id": "gunb_permits", "title": "gunb_permits", "publisher": "Fixture only", "attribution": "Źródło: rejestr RWDZ GUNB", "licence": "cc0", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "rwdz_exact_administrative_terc_all_loaded_entries_v1", "coverage": "covered", "note": "Liczba wpisów w rejestrze RWDZ GUNB przypisanych do gminy. Nie oznacza liczby rozpoczętych budów.; stan rejestru na 1 października 2026 r." }, "gunb_activity_500m": { "value": 2, "unit": "count_min", "source": { "id": "gunb_permits", "title": "gunb_permits", "publisher": "Fixture only", "attribution": "Źródło: rejestr RWDZ GUNB", "licence": "cc0", "url": "https://example.test/source", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "method": "rwdz_exact_parcel_link_radius500m_lower_bound_v1", "coverage": "covered", "note": "Liczba jednoznacznie przypisanych wpisów GUNB w odległości do 500 m od granicy działki jest dolną granicą. Wpisy bez jednoznacznego przypisania do działek nie są uwzględnione.; stan rejestru na 1 października 2026 r.", "sources": [ { "id": "gunb_permits", "title": "gunb_permits", "publisher": "Fixture only", "attribution": "Źródło: rejestr RWDZ GUNB", "licence": "cc0", "url": "https://example.test/source", "as_of": "2026-10-01" }, { "id": "egib_parcels", "title": "egib_parcels", "publisher": "Fixture only", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "licence": "statutory_open_data", "url": "https://example.test/source", "as_of": "2026-10-01" } ] } }, "amenities": {} } ``` GET `/v1/search` accepts these 12 flat filters with an existing q/id/point/bbox scope or administrative `teryt` (4-digit powiat or 7-digit gmina). POST accepts `polygon`, optional `limit`, `cursor` and the same flat predicates inside `filters`. The separate typed `SearchRequestV2` area shape and exports remain unavailable. | Filter | Schema | Description | | --- | --- | --- | | `area_min_m2` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `area_max_m2` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `land_use_class` | `{"enum": ["R", "Ł", "Ps", "Br", "B", "Ba", "Bi", "Bp", "Bz", "K", "Ls", "Lz", "Lzr", "N", "Wp", "Ws", "Wsr", "W", "dr", "Tk", "Ti", "Tr", "E"], "type": "string"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `shape_regularity_min` | `{"maximum": 1, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `frontage_min_m` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `road_access` | `{"type": "boolean"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `buildings_present` | `{"type": "boolean"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `public_road_max_m` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `rcn_price_min_pln_m2` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `rcn_price_max_pln_m2` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `gunb_activity_min` | `{"maximum": 1000000000000.0, "minimum": 0, "type": "integer"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `pog_zone_class` | `{"enum": ["SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP"], "type": "string"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | `search_facets.scope_count` counts the full scope and `matched_count` the combined AND result. Every active filter reports independent `matched`, `excluded_known` and `excluded_unknown` counts before pagination and other filters. Unknown never passes a predicate, including false; unknown counts overlap and must not be summed. GET `/v1/places?q=War&limit=10` requires a key and costs **0 credits**. Prefixes have 2..100 characters; limit defaults to 10 and is at most 20. Matching ignores case and accents, including ł/l. Results distinguish gmina, powiat, obręb and miejscowość, with parent, id, TERYT and parcel coverage. A locality without SIMC has `teryt: null`; its parent gmina code is not a locality TERYT. See the [places reference](../../operations/places.md). # Credits, prices and refunds Inspect `x-request-cost` and any `x-credit-rule` before calling; read `billing` for actual settlement. One HTTP request can contain multiple billable items, so HTTP request count is not always credit count. ## Plans | Plan | PLN/month | Credits | Seats | Overage | | --- | --- | --- | --- | --- | | `free` (Darmowy) | 0.00 | configured | 1 | - | | `start` (Start) | 79.00 | 300 | 1 | - | | `pro` (Profesjonalny) | 249.00 | 1 500 | 1 | - | | `team` (Zespół) | 799.00 | 6 000 | 5 | - | | `developer` (Developer) | 99.00 | 10 000 | 1 | 0.01 PLN/credit | | `platform` (Platforma) | from 1 499.00 | individual agreement | 1 | - | Prices are generated from the billing implementation's catalogue. [GET /v1/billing/plans](../../operations/billing_plans.md) returns the account-facing current catalogue. This revision's catalogue and Checkout are Stripe test-mode only; these docs do not certify live payments. Recurring subscriptions support cards; recurring Przelewy24 is refused. Do not infer tax or an invoice total from the catalogue table. ## Charging rules | Operation | Credits | Unit | | --- | --- | --- | | `account_keys_list` | 0 | call | | `account_keys_create` | 0 | call | | `account_keys_revoke` | 0 | call | | `account_keys_rotate` | 0 | call | | `account_ledger` | 0 | call | | `account_usage` | 0 | call | | `ask` | 1 | call | | `billing_account_delete` | 0 | call | | `billing_account` | 0 | call | | `billing_checkout` | 0 | call | | `billing_plans` | 0 | call | | `billing_stripe_webhook` | 0 | call | | `billing_team` | 0 | call | | `billing_team_accept` | 0 | call | | `billing_team_invite` | 0 | call | | `billing_team_revoke_invite` | 0 | call | | `billing_team_remove` | 0 | call | | `billing_team_role` | 0 | call | | `check` | 1 | call | | `check_batch` | 0 | call | | `check_job` | 0 | call | | `check_job_results` | 0 | call | | `events` | 1 | call | | `events_query` | 1 | call | | `gmina_planning_lookup` | 1 | call | | `gmina_planning` | 1 | call | | `layer` | 1 | call | | `openapi` | 0 | call | | `parcel` | 1 | call | | `parcel_batch` | 1 | item | | `places` | 0 | call | | `resolve` | 1 | call | | `search` | 1 | call | | `search_polygon` | 1 | call | | `sources` | 0 | call | | `watch_list` | 0 | call | | `watch_create` | 0 | call | | `watch_delete` | 0 | call | | `watch_get` | 0 | call | | `watch_update` | 0 | call | | `watch_attempts` | 0 | call | | `watch_webhook_remove` | 0 | call | | `watch_webhook_configure` | 0 | call | | `watch_secret_rotate` | 0 | call | `billing.cost` is the operation cost or reservation, depending on the operation. `charged` and v2 `credits` are the consumed credits; `refunded` is the refund. Informative `covered_no_data` results and ambiguous candidate lists are charged. Invalid 400, unauthorized 401 and matching ETag 304 responses charge nothing. 4xx, 5xx and uncovered layer responses follow refund rules. One uncovered layer inside a multi-layer parcel card does not necessarily refund the entire card: inspect that response's `billing`. Parcel batches settle per item. Ask reserves `max_credits`, releases the unused part, and charges public tools plus 1 credit for a completed answer. In ask-v2, a budget-stopped turn is entirely free, including earlier reads. See [ask/SSE](ask-sse.md). ## Expiry and uncertain settlement In the current implementation subscription credits expire at the exclusive UTC period end without rollover. Refunds retain original expiry. This describes the mechanism, not additional contractual terms. Zespół (team) shares its pool across at most five seats including the owner. Developer overage counts contract billing units, including batch items. 429 can mean insufficient credits or another limit. Disconnect does not prove a refund. Keep `meta.request_id`, inspect the account and request reconciliation before replaying consequential work. API credit refunds are not a promise of card-payment refunds. # MCP setup: Claude, ChatGPT, Claude Code and Cursor Use `https://mcp.agentdzialek.pl/mcp`, the Streamable HTTP MCP endpoint. The ask SSE stream at `/v1/ask` is a separate interface, not an MCP server URL. MCP uses the same metering as REST. An agent conversation can execute multiple charged tools; establish cost approval before starting. Six tools are exposed: | Tool | REST | Credits | | --- | --- | --- | | check | GET /v1/check | 1 | | parcel | GET /v1/parcel | 1 | | layer | GET /v1/layer/{layer} | 1 | | resolve | GET /v1/resolve | 1 | | search | GET /v1/search | 1 | | events | GET /v1/events | 1 | ## Claude web and Desktop Add a custom remote connector in connector settings, name it landfeed and enter the `/mcp` URL. Select OAuth and automatic client registration when offered. This server supports dynamic registration; do not assume support for newer published-client-identity mechanisms. Finish landfeed consent with your account API key, enable the connector in a conversation and inspect its tools. Claude Desktop can use the same account-level remote connector without a local stdio process. Organization policy can require an owner/admin to add it. UI labels depend on client version. [Official Claude instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ## ChatGPT web Open the plugins directory, add a custom MCP server, enter landfeed and the `/mcp` server URL, then select OAuth. Create the plugin, install it and select it in a conversation using `@`. Workspace permissions and restrictions determine access. If configuration is unavailable, check those permissions first. A custom API key is not a substitute for OAuth in this ChatGPT flow. [Official OpenAI instructions](https://developers.openai.com/api/docs/guides/custom-mcp-server). ## Claude Code With Claude Code installed, run this terminal command, then open `/mcp` in Claude Code and complete browser authentication. ```sh claude mcp add --transport http landfeed https://mcp.agentdzialek.pl/mcp ``` The example test captures CLI arguments without modifying a developer's client configuration. [Official Claude Code instructions](https://code.claude.com/docs/en/mcp). ## Cursor Put this configuration in project `.cursor/mcp.json` or user `~/.cursor/mcp.json`. Enable landfeed in MCP settings and finish OAuth. Do not commit a credential. ```json { "mcpServers": { "landfeed": { "url": "https://mcp.agentdzialek.pl/mcp" } } } ``` [Official Cursor instructions](https://cursor.com/docs/mcp). The server must permit the exact client callback. `invalid_redirect_uri` requires the server operator to review that policy. ## Acceptance and troubleshooting List the six tools after connecting, then ask for one named parcel layer and its source. Check that source, date and coverage survive into the answer. A tool list alone does not prove a successful paid call. Protocol tests are local evidence; each hosted client's actual consent and tool call need separate acceptance. Server OAuth support alone does not certify a connected client. Client instructions checked on 2026-10-21. See [authentication](authentication.md) for tokens and consent failures. # What landfeed never answers landfeed never fetches, stores or serves property owner/holder data or księga wieczysta numbers (KW, land and mortgage register numbers). Do not ask an agent to find them or place them in parameters, custom fields or webhook URLs. Privacy admission rejects or scrubs forbidden content; this is not a way to store secrets safely in a question. The service provides no legal advice. Planning data, layer classifications and zone symbols do not establish buildability rights. An adopted plan may not yet be in force. A mapped road does not establish a legal right of access. An RCN aggregate for an obręb is not a parcel valuation. Address-level individual transaction prices and investor names are never served. `covered_no_data` is bounded to its source, date and evidence scope. `not_covered`, `not_computed`, missing events and source failure never prove no risk. Do not turn these into “safe parcel”, “no plan” or “no restrictions”. On `ambiguous`, obtain clarification instead of choosing a parcel silently. When a decision requires legal status, development rights or property rights, obtain the relevant documents and appropriate specialist help outside landfeed. Preserve sources and dates so the evidence behind any conclusion remains visible. # Quickstart in 3 minutes Use an account API key and an EGiB parcel identifier to read one layer. The API origin is `https://mcp.agentdzialek.pl`; remote MCP uses `/mcp`. This read costs 1 credit and returns its data and billing together. ## 1. Prepare a key Open Konto (account) at `https://app.agentdzialek.pl` and use an issued account API key. Set `LANDFEED_API_KEY` through your secret manager or terminal environment. Keep it out of project files and URLs. If the account has no key or credits, obtain them in the console first. ## 2. Read a layer The parcel id and dates are from a recorded contract fixture, not a promise that this parcel is available live. Replace the id with your parcel. Choose one client. ### curl ```sh curl --silent --show-error --get 'https://mcp.agentdzialek.pl/v1/parcel' \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=146501_1.0101.12/3' \ --data-urlencode 'layers=flood' ``` ### Python 3.10+ Save as `quickstart.py` and run `python3 quickstart.py`. Only the standard library is needed. ```python import json import os import urllib.parse import urllib.request query = urllib.parse.urlencode({"id": "146501_1.0101.12/3", "layers": "flood"}) request = urllib.request.Request( "https://mcp.agentdzialek.pl/v1/parcel?" + query, headers={"X-Api-Key": os.environ["LANDFEED_API_KEY"]}, ) with urllib.request.urlopen(request, timeout=30) as response: body = json.load(response) # A 200 can still be ambiguous or uncovered. Never assume it means usable data. if body["status"] == "ambiguous": print(json.dumps({"candidates": body["candidates"]}, ensure_ascii=False)) elif body["status"] != "ok": print(json.dumps({"status": body["status"], "error": body["error"]}, ensure_ascii=False)) else: print(json.dumps({"layers": body["result"]["layers"], "billing": body["billing"]}, ensure_ascii=False)) ``` ### TypeScript, Node.js 22.18+ Save as `quickstart.ts` and run `node quickstart.ts`. This example needs no extra package. ```typescript const key = process.env.LANDFEED_API_KEY; if (!key) throw new Error("Set LANDFEED_API_KEY"); const url = new URL("https://mcp.agentdzialek.pl/v1/parcel"); url.search = new URLSearchParams({ id: "146501_1.0101.12/3", layers: "flood" }).toString(); const response = await fetch(url, { headers: { "X-Api-Key": key }, signal: AbortSignal.timeout(30_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const body = await response.json(); // Keep ambiguity, unavailable data and successful answers distinct. if (body.status === "ambiguous") { console.log(JSON.stringify({ candidates: body.candidates })); } else if (body.status !== "ok") { console.log(JSON.stringify({ status: body.status, error: body.error })); } else { console.log(JSON.stringify({ layers: body.result.layers, billing: body.billing })); } export {}; ``` ## 3. Interpret the response Read `status` first. On `ambiguous`, show `candidates` and ask the user to identify the parcel; HTTP 200 does not authorize a silent choice. On `ok`, inspect `result.layers.flood.coverage`, `note`, `source`, `as_of` and `scope` when present. Never turn `not_covered` or `not_computed` into a statement that there is no flood hazard. ```json { "status": "ok", "query": { "kind": "id", "input": { "id": "146501_1.0101.12/3" }, "resolved": null }, "result": { "id": "146501_1.0101.12/3", "admin": { "voivodeship": "14", "gmina_teryt": "1465011", "gmina_name": "Warszawa", "obreb_id": "146501_1.0101", "number": "12/3" }, "area": { "official_m2": null, "geometry_m2": 500, "source": "computed", "provenance": { "id": "egib_parcels", "title": "egib_parcels", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "as_of": "2026-10-01" }, "note": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna." }, "layers": { "flood": { "layer": "flood", "coverage": "covered_no_data", "value": { "q10": false, "q100": false, "q500": false }, "note": "Według map zagrożenia powodziowego działka leży poza wskazanymi na nich obszarami zagrożenia w sprawdzonym zakresie. Nie wyklucza to powodzi.", "source": { "id": "mzp_flood", "title": "mzp_flood", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "as_of": "2026-10-01" }, "as_of": "2026-10-01", "layer_version": "flood-national-20261016", "licence": { "position": "cc_by_4_0", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "terms_url": "https://creativecommons.org/licenses/by/4.0/", "review_ref": "seed/attribution_review_2026-10-13.sql#mzp_flood" }, "scope": "parcel_polygon", "method": "official" } }, "record_hash": null, "display_geometry": { "type": "MultiPolygon", "coordinates": [ [ [ [ 21.0, 52.0 ], [ 21.001, 52.0 ], [ 21.001, 52.001 ], [ 21.0, 52.001 ], [ 21.0, 52.0 ] ] ] ] }, "display_simplified": true, "adjacent_parcel_ids": [ "146501_1.0101.12/4" ], "adjacent_parcel_ids_truncated": false }, "candidates": [], "sources": [], "billing": { "cost": 1, "charged": 1, "refunded": 0, "rule": "charged", "credits": 1 }, "error": null, "meta": { "request_id": "fixture", "api_version": "v1", "contract_version": "2.0.0", "operation": "parcel", "generated_at": "2026-10-16T12:00:00Z", "calls": 1 }, "auth": { "kind": "api_key" }, "plan": "free" } ``` This fixture demonstrates v2. Some serving reads retain the compatible v1 shape without `meta.contract_version`; do not invent absent fields. `billing`, `X-Credits-Charged` and `X-Credits-Refunded` report settlement. Python and TypeScript stop on HTTP errors; inspect the error body before replay. Next: [coverage](coverage.md), [authentication](authentication.md), [parcel reference](../../operations/parcel.md). # Rate and size limits HTTP 429 refuses admission because of request rate, concurrency or credits. Inspect the body, account balance and `Retry-After` when present. Back off with jitter and reduce concurrent reads. Never automatically replay payments, confirmed ask actions or webhook registration. | Interface | Limit | | --- | --- | | ask | 6/min/account; 2 concurrent/process | | MCP | 600/min/account/process; 30/min anonymous/process | | watch | 30/min/account; includes invalid requests | | watch body | 256 KiB; 100 items; 1024 vertices total | | ask body | ask-v1: 16 KiB; ask-v2: 1 MiB | | ask results | 40; 512 000 bytes | | ask artifact | 192 000 bytes/artifact; 480 000 bytes/turn | | ask messages | 64 000 bytes; last 20 in planner | | ask continuation | 3600 s | | Ask request budget | 120 s; LANDFEED_ASK_REQUEST_SECONDS | | SSE keepalive | 10 s; : keepalive | | SSE backpressure | 5 s | | MCP body | 64 KiB | | billing body | 64 KiB | | /.well-known/oauth-authorization-server | 600/min/process; 16 KiB | | /register | 30/min/process; 16 KiB | | /authorize | 120/min/process; 16 KiB | | /oauth/consent | 120/min/process; 16 KiB | | /token | 300/min/process; 16 KiB | | /revoke | 300/min/process; 16 KiB | | Stripe webhook | 600/min/process; 64 KiB | | checkout / checkout_reconcile / team_invite | 10/min/pool/operation | Process-local limits are not global throughput guarantees. Shared credit balances and watch-item entitlements can refuse work earlier. There is no single declared requests-per-second promise for all REST reads. The local stdio MCP bridge caps decoded bodies at 16 MiB and total HTTP time at 30 seconds; timeout leaves billing unknown. Search has its own area/cursor/filter bounds. Read the operation schema rather than treating the batch limit as a search limit. The [schema reference](../../schemas.md) and operation availability distinguish definitions from executable runtime features. Operations marked `x-runtime-supported: false` remain unavailable even though their schemas exist. After an interrupted response, retain the request id and reconcile billing before replay. The [errors catalogue](../../errors.md) gives code-specific recovery actions. # Sources, dates, licences and attribution Interpret every answer with its source, date and scope. A source catalogue does not establish coverage for every parcel. [GET /v1/sources](../../operations/sources.md) is free without a place selector; supplying id, point or query bills it like resolution. ## Attribution and freshness `source` identifies the publisher/data used. `as_of` is the source data date; null means unknown. Never replace it with response retrieval time. Preserve each layer's own date and source in combined answers. `source.fallback: true` marks a fallback. Planning prefers Rejestr Urbanistyczny (urban planning register), with Działkopedia's attributed POG sweep as a possible fallback. V2 `licence` contains `position`, `attribution`, `terms_url` and `review_ref`. Retain the attribution in displayed and redistributed results. Null `terms_url` means no terms URL was recorded, not unrestricted rights. Own-computation approval does not replace approval for its inputs. | ID | Attribution | Position | Terms | review_ref | | --- | --- | --- | --- | --- | | `bdot_roads` | Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k | open_data | null | `seed/attribution_review_2026-10-13.sql#bdot_roads` | | `egib_buildings` | Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB) | statutory_open_data | null | `seed/attribution_review_2026-10-13.sql#egib_buildings` | | `egib_dr_parcels` | Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB) | statutory_open_data | null | `seed/attribution_review_2026-10-13.sql#egib_dr_parcels` | | `egib_parcels` | Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB) | statutory_open_data | null | `seed/attribution_review_2026-10-13.sql#egib_parcels` | | `gdos_protected` | Źródło: Generalna Dyrekcja Ochrony Środowiska (GDOŚ), Centralny Rejestr Form Ochrony Przyrody | open_data | null | `seed/attribution_review_2026-10-13.sql#gdos_protected` | | `gmina_planning_status` | Działkopedia, obliczenie własne (plan ogólny, pokrycie MPZP) | own_computation | null | `seed/attribution_review_2026-10-13.sql#gmina_planning_status` | | `gunb_permits` | Źródło: rejestr RWDZ GUNB | cc0 | [URL](https://creativecommons.org/publicdomain/zero/1.0/) | `seed/attribution_review_2026-10-16.sql#gunb_permits` | | `mzp_flood` | Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0 | cc_by_4_0 | [URL](https://creativecommons.org/licenses/by/4.0/) | `seed/attribution_review_2026-10-13.sql#mzp_flood` | | `parcel_check` | Działkopedia, obliczenie własne | own_computation | null | `seed/attribution_review_2026-10-13.sql#parcel_check` | | `parcel_events` | Działkopedia, obliczenie własne | own_computation | null | `seed/attribution_review_2026-10-13.sql#parcel_events` | | `parcel_resolve` | Działkopedia, obliczenie własne | own_computation | null | `seed/attribution_review_2026-10-13.sql#parcel_resolve` | | `pog_sweep` | Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia | local_law_no_copyright | null | `seed/attribution_review_2026-10-13.sql#pog_sweep` | | `prg_addresses` | Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Państwowy Rejestr Granic (PRG) | open_data | null | `seed/attribution_review_2026-10-13.sql#prg_addresses` | | `rcn_clean_agg` | Źródło: Rejestr Cen Nieruchomości (GUGiK). | statutory_open_data | null | `seed/attribution_review_2026-10-16.sql#rcn_clean_agg` | | `sopo_landslides` | Źródło: PIG-PIB (SOPO), CC BY 4.0 | cc_by_4_0 | [URL](https://creativecommons.org/licenses/by/4.0/) | `seed/attribution_review_2026-10-16.sql#sopo_landslides` | | `teryt_units` | Źródło: GUS (TERYT), GUGiK (PRG) | open_data | null | `seed/attribution_review_2026-10-13.sql#teryt_units` | | `wz_possible` | Działkopedia, obliczenie własne na podstawie planu ogólnego i u.p.z.p. | own_computation | null | `seed/attribution_review_2026-10-13.sql#wz_possible` | This table is generated from the licence matrix accepted by the operator on 2026-10-16. It records decisions, not a new legal opinion. `review_ref` identifies an approval decision, not source freshness. Read actual place availability/dates from the response. A new source needs individual approval before serving dependent answers. ## Source boundaries EGiB (Ewidencja Gruntów i Budynków) identifies parcels/buildings without serving owners or KW. MPZP is the local plan, POG the plan ogólny, SOPO the landslide information system, GDOŚ the nature-protection authority, and GUNB the building-permit register. A listed source/layer schema does not imply every runtime query is connected; some layers return `not_computed`. RCN aggregates concern the entire obręb, not parcel value. A physical road does not establish legal access. Point evidence is not a whole-parcel assessment. See [coverage](coverage.md) for the conditions supporting a limited negative answer. # Events, watches and signed webhooks `/v1/events` is a separately metered history read. A watch selects future changes for delivery to your webhook. No notification does not establish no change: entitlement, source evidence or delivery may be unavailable. Use GET `/v1/events` with `q`, `id` or `point` for current history reads. POST `/v1/events/query` has a schema but its body selectors are not yet consumed: a valid `parcel_ids` sample returns 400. V2 `area` and `parcel_ids` on GET are not applied either; do not rely on them as filters. ## Create a watch and receiver [POST /v1/watches](../../operations/watch_create.md) accepts items selecting a `parcel_id`, `gmina_teryt` or polygon with `types` filters. One item consumes one slot; a municipality item is not expanded into billable parcels. Optional `Idempotency-Key` replays the same account/key/items for 24 hours. Changed items return 409; a deleted watch is not recreated. Supported filters: `pog.changed`, `wz.changed`, `mpzp.changed`, `flood.changed`, `landslide.changed`, `protected.changed`, `buildings.changed`. EventV2 types such as `gunb_permit` and `plan_general_adopted` have schemas but no production notification producer in this revision. Registration returns `event_type_has_no_producer`. Detection time does not by itself establish the legal effective date of a change. Configure the URL with [PUT /v1/watches/{watch_id}/webhook](../../operations/watch_webhook_configure.md). Save `result.secret` securely: configuration and rotation reveal it once; reads never do. URLs require public HTTPS port 443, no credentials/fragment and exclusively public DNS answers. Redirects are not followed. Never include owner or KW data in the URL. Configuration starts from the current cursor and cancels the old backlog. [Secret rotation](../../operations/watch_secret_rotate.md) preserves queued work but changes its signing key immediately. Coordinate the receiver's key change to accept new signatures. Removing the webhook cancels pending deliveries. ## Verify raw bytes before JSON `X-Landfeed-Signature` is `t=,v1=`. HMAC-SHA256 signs ASCII timestamp + dot + exact raw body bytes using the returned secret's bytes. Do not reserialize JSON before verification. Reject timestamps older than 300 seconds or over 300 seconds in the future; synchronize receiver clocks. ### Python ```python import hashlib import hmac import json import re def verify_webhook(secret, signature, raw_body, *, now): """Verify before parsing JSON. now is the receiver's Unix time in seconds.""" if not isinstance(signature, str): return False match = re.fullmatch(r"t=([0-9]{1,12}),v1=([0-9a-f]{64})", signature) if not match or abs(now - int(match[1])) > 300: return False expected = hmac.new(secret.encode("ascii"), match[1].encode("ascii") + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, match[2]) def receive(secret, signature, raw_body, delivery_id, *, now, persist_once): if not verify_webhook(secret, signature, raw_body, now=now): raise ValueError("Invalid or stale webhook signature") event = json.loads(raw_body) if event["id"] != delivery_id: raise ValueError("Delivery id mismatch") # Atomically insert a unique delivery id and enqueue processing in one transaction. # persist_once returns False for an already accepted id. Return 2xx in either case. return persist_once(delivery_id, event) ``` `persist_once` must atomically insert a unique `X-Landfeed-Delivery` and a processing job in one transaction. A correctly signed duplicate should also receive 2xx. Do not acknowledge acceptance until durable persistence succeeds. ### TypeScript This function verifies the signature. Run it before JSON parsing, check body id against `X-Landfeed-Delivery`, then use the same durable deduplicated persistence. ```typescript import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyWebhook(secret: string, signature: string, rawBody: Buffer, now: number): boolean { const match = /^t=([0-9]{1,12}),v1=([0-9a-f]{64})$/.exec(signature); if (!match || Math.abs(now - Number(match[1])) > 300) return false; const expected = createHmac("sha256", secret) .update(match[1], "ascii").update(".").update(rawBody).digest(); const received = Buffer.from(match[2], "hex"); return received.length === expected.length && timingSafeEqual(received, expected); } ``` ## Retries and entitlements Retries reuse delivery id/body with a fresh timestamp. Backoff starts at 30 seconds, doubles up to one hour and stops after 24 hours. Ten consecutive failures disable the watch; an unsafe destination disables it immediately. [Delivery attempts](../../operations/watch_attempts.md) expose outcomes without retaining receiver response bodies. Item quotas come from the plan and can remain zero pending operator configuration. Expired entitlements or a shared quota downgrade can pause delivery; renewal does not generate new deliveries for paused-period events. Management and current configured delivery are free; `/v1/events` reads charge separately. Customer notification webhooks and the [Stripe webhook](../../operations/billing_stripe_webhook.md) have different interfaces and secrets. # AddressValue not specified in the source contract Layer keys: `address`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `addresses` | yes | `{"items": {"properties": {"house_number": {"type": "string"}, "locality": {"type": "string"}, "postcode": {"type": ["string", "null"]}, "street": {"type": ["string", "null"]}}, "type": "object"}, "type": "array"}` | not specified in the source contract | ```json { "properties": { "addresses": { "items": { "properties": { "house_number": { "type": "string" }, "locality": { "type": "string" }, "postcode": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "addresses" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # BuildingsValue not specified in the source contract Layer keys: `buildings`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `count` | yes | `{"type": "integer"}` | not specified in the source contract | | `footprint_m2_total` | no | `{"type": ["number", "null"]}` | not specified in the source contract | ```json { "properties": { "count": { "type": "integer" }, "footprint_m2_total": { "type": [ "number", "null" ] } }, "required": [ "count" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # FloodValue covered_no_data oznacza zmapowany obszar i działkę poza wszystkimi strefami: {q10: false, q100: false, q500: false}. Uwagi powodziowe używają polskich nazw miesięcy, wskazują scenariusz Q1% (raz na 100 lat) i odróżniają brak zagrożenia na mapie od nieznanego zakresu danych. Layer keys: `flood`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `map_edition` | no | `{"type": ["string", "null"]}` | Cykl MZP i daty publikacji obiektów z validityPeriod.beginPosition; brakujące daty są wyraźnie wskazane. endPosition metadanych nigdy nie wyznacza zakresu danych. | | `q10` | yes | `{"type": "boolean"}` | not specified in the source contract | | `q100` | yes | `{"type": "boolean"}` | not specified in the source contract | | `q100_share_pct` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `q500` | yes | `{"type": "boolean"}` | not specified in the source contract | ```json { "description": "covered_no_data oznacza zmapowany obszar i działkę poza wszystkimi strefami: {q10: false, q100: false, q500: false}. Uwagi powodziowe używają polskich nazw miesięcy, wskazują scenariusz Q1% (raz na 100 lat) i odróżniają brak zagrożenia na mapie od nieznanego zakresu danych.", "properties": { "map_edition": { "description": "Cykl MZP i daty publikacji obiektów z validityPeriod.beginPosition; brakujące daty są wyraźnie wskazane. endPosition metadanych nigdy nie wyznacza zakresu danych.", "type": [ "string", "null" ] }, "q10": { "type": "boolean" }, "q100": { "type": "boolean" }, "q100_share_pct": { "type": [ "number", "null" ] }, "q500": { "type": "boolean" } }, "required": [ "q10", "q100", "q500" ], "type": "object" } ``` ## Empty answer: covered_no_data The contract states this empty `value`: ```json { "q10": false, "q100": false, "q500": false } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # LandslideValue Punktowe sprawdzenie SOPO. Trafienie ma stan covered; puste identify oznacza covered_no_data z present=false wyłącznie wewnątrz prawidłowego, ukończonego obszaru mapowania, przy dostępnych danych aplikacji. W pozostałych przypadkach not_covered i value=null. Bez twierdzeń o bezpieczeństwie całej działki ani o przecięciu jej geometrii. Layer keys: `landslide`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `count` | no | `{"type": "integer"}` | not specified in the source contract | | `forms` | no | `{"items": {"properties": {"id": {"type": ["string", "null"]}, "kind": {"enum": ["landslide", "threatened_area"], "type": "string"}}, "required": ["kind", "id"], "type": "object"}, "type": "array"}` | not specified in the source contract | | `kinds` | no | `{"items": {"enum": ["landslide", "threatened_area"], "type": "string"}, "type": "array"}` | not specified in the source contract | | `present` | yes | `{"type": "boolean"}` | not specified in the source contract | ```json { "description": "Punktowe sprawdzenie SOPO. Trafienie ma stan covered; puste identify oznacza covered_no_data z present=false wyłącznie wewnątrz prawidłowego, ukończonego obszaru mapowania, przy dostępnych danych aplikacji. W pozostałych przypadkach not_covered i value=null. Bez twierdzeń o bezpieczeństwie całej działki ani o przecięciu jej geometrii.", "properties": { "count": { "type": "integer" }, "forms": { "items": { "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "landslide", "threatened_area" ], "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "type": "array" }, "kinds": { "items": { "enum": [ "landslide", "threatened_area" ], "type": "string" }, "type": "array" }, "present": { "type": "boolean" } }, "required": [ "present" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # MpzpValue covered_no_data oznacza, że źródło obejmuje gminę, ale żaden MPZP nie obejmuje działki: {status: none, symbol: null, plans: [], effective_from: null}. Plan w przygotowaniu ma status draft. Plan lub strefa bez opublikowanego statusu prawnego ma coverage=covered, status=null, effective_from=null i uwagę wyjaśniającą; symbol, przeznaczenie, identyfikator i nazwa planu są zachowywane, jeżeli je opublikowano. Layer keys: `mpzp`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `effective_from` | yes | `{"format": "date", "type": ["string", "null"]}` | not specified in the source contract | | `plans` | yes | `{"items": {"properties": {"adopted_on": {"format": "date", "type": ["string", "null"]}, "effective_from": {"format": "date", "type": ["string", "null"]}, "name": {"type": ["string", "null"]}, "plan_id": {"type": "string"}, "resolution_url": {"type": ["string", "null"]}, "status": {"$ref": "./envelope.json#/$defs/MpzpStatus"}}, "type": "object"}, "type": "array"}` | not specified in the source contract | | `share_pct` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `status` | yes | `{"anyOf": [{"$ref": "#/$defs/PlanStatus"}, {"type": "null"}]}` | Status prawny MPZP; null, gdy integracja wymienia plan lub strefę, ale nie publikuje statusu prawnego. Taki rekord ma coverage=covered i effective_from=null, a note wyjaśnia brak statusu. Statusy draft, adopted i in_force wymagają potwierdzenia w źródle; brak danych nigdy nie oznacza none. | | `symbol` | yes | `{"type": ["string", "null"]}` | Symbol KIMPZP, jeżeli go opublikowano; w przeciwnym razie null z wyjaśnieniem w note. | ```json { "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "description": "covered_no_data oznacza, że źródło obejmuje gminę, ale żaden MPZP nie obejmuje działki: {status: none, symbol: null, plans: [], effective_from: null}. Plan w przygotowaniu ma status draft. Plan lub strefa bez opublikowanego statusu prawnego ma coverage=covered, status=null, effective_from=null i uwagę wyjaśniającą; symbol, przeznaczenie, identyfikator i nazwa planu są zachowywane, jeżeli je opublikowano.", "properties": { "effective_from": { "format": "date", "type": [ "string", "null" ] }, "plans": { "items": { "properties": { "adopted_on": { "format": "date", "type": [ "string", "null" ] }, "effective_from": { "format": "date", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "plan_id": { "type": "string" }, "resolution_url": { "type": [ "string", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/MpzpStatus" } }, "type": "object" }, "type": "array" }, "share_pct": { "type": [ "number", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/MpzpStatus" }, "symbol": { "description": "Symbol KIMPZP, jeżeli go opublikowano; w przeciwnym razie null z wyjaśnieniem w note.", "type": [ "string", "null" ] } }, "required": [ "status", "symbol", "plans", "effective_from" ], "type": "object" } ``` ## Empty answer: covered_no_data The contract states this empty `value`: ```json { "effective_from": null, "plans": [], "status": "none", "symbol": null } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # PermitsValue GUNB RWDZ w promieniu 500 m, odpytywany podczas żądania. Nazwy inwestorów nigdy nie są udostępniane. Layer keys: `permits`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `count_500m` | yes | `{"type": "integer"}` | not specified in the source contract | | `recent` | no | `{"items": {"properties": {"decision_date": {"format": "date", "type": ["string", "null"]}, "distance_m": {"type": "number"}, "kind": {"type": "string"}, "object_category": {"type": ["string", "null"]}}, "type": "object"}, "type": "array"}` | not specified in the source contract | ```json { "description": "GUNB RWDZ w promieniu 500 m, odpytywany podczas żądania. Nazwy inwestorów nigdy nie są udostępniane.", "properties": { "count_500m": { "type": "integer" }, "recent": { "items": { "properties": { "decision_date": { "format": "date", "type": [ "string", "null" ] }, "distance_m": { "type": "number" }, "kind": { "type": "string" }, "object_category": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "count_500m" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # PlanningValue Informacje planistyczne o działce w jednym żądaniu: odpowiedzi o planie ogólnym, MPZP i WZ (każda jako pełne LayerAnswer z własnym coverage, source i note) oraz stan planowania gminy. Bez stwierdzenia „brak planu” bez wskazania rodzaju planu i źródła. Layer keys: `planning`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `gmina` | yes | `{"properties": {"as_of": {"format": "date", "type": "string"}, "gmina_name": {"type": "string"}, "gmina_teryt": {"description": "Kod gminy administracyjnej z ostatnią cyfrą 1, 2 lub 3.", "pattern": "^[0-9]{6}[123]$", "type": "string"}, "mpzp_count": {"type": ["integer", "null"]}, "mpzp_coverage_pct": {"type": ["number", "null"]}, "pog_adopted_on": {"format": "date", "type": ["string", "null"]}, "pog_effective_from": {"format": "date", "type": ["string", "null"]}, "pog_resolution_url": {"type": ["string", "null"]}, "pog_status": {"enum": ["draft", "adopted", "in_force", "none", "unknown"], "type": "string"}, "sources": {"items": {"$ref": "./envelope.json#/$defs/SourceRef"}, "type": "array"}, "studium_expired": {"type": ["boolean", "null"]}, "wz_regime": {"type": ["string", "null"]}}, "required": ["gmina_teryt", "gmina_name", "pog_status", "as_of", "sources"], "type": "object"}` | not specified in the source contract | | `mpzp` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). | | `pog` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). | | `wz` | yes | `{"additionalProperties": false, "allOf": [{"else": {"properties": {"value": {"type": "object"}}}, "if": {"properties": {"coverage": {"enum": ["not_covered", "not_computed"]}}}, "then": {"properties": {"value": {"type": "null"}}}}, {"if": {"properties": {"coverage": {"enum": ["covered", "covered_no_data"]}, "layer": {"const": "mpzp"}}}, "then": {"properties": {"value": {"$ref": "#/$defs/MpzpValue"}}}}], "properties": {"as_of": {"format": "date", "type": ["string", "null"]}, "basis": {"description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": ["string", "null"]}, "confidence": {"maximum": 1, "minimum": 0, "type": "number"}, "coverage": {"$ref": "#/$defs/Coverage"}, "hash": {"description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": ["string", "null"]}, "layer": {"$ref": "#/$defs/LayerKey"}, "layer_version": {"description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string"}, "licence": {"$ref": "#/$defs/Licence"}, "method": {"$ref": "#/$defs/Method"}, "note": {"description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string"}, "scope": {"$ref": "#/$defs/Scope"}, "source": {"$ref": "#/$defs/SourceRef"}, "threshold": {"maximum": 1, "minimum": 0, "type": "number"}, "value": {"description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": ["object", "null"]}}, "required": ["layer", "coverage", "value", "note", "source", "as_of", "layer_version"], "type": "object"}` | Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml). | ```json { "description": "Informacje planistyczne o działce w jednym żądaniu: odpowiedzi o planie ogólnym, MPZP i WZ (każda jako pełne LayerAnswer z własnym coverage, source i note) oraz stan planowania gminy. Bez stwierdzenia „brak planu” bez wskazania rodzaju planu i źródła.", "properties": { "gmina": { "$ref": "#/components/schemas/GminaPlanning" }, "mpzp": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "pog": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "wz": { "$ref": "./envelope.json#/$defs/LayerAnswer" } }, "required": [ "pog", "mpzp", "wz", "gmina" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # PogValue Plan ogólny. Projekty są pokazywane i oznaczane jako projekty. covered_no_data oznacza, że źródło obejmuje gminę, ale nie zawiera rekordu planu ogólnego: {status: none, zone_symbol: null, zones: []}. Layer keys: `pog`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `adopted_on` | no | `{"format": "date", "type": ["string", "null"]}` | not specified in the source contract | | `effective_from` | yes | `{"format": "date", "type": ["string", "null"]}` | Data wejścia planu w życie; null dla draft i none. | | `in_ouz` | no | `{"type": ["boolean", "null"]}` | W granicach obszaru uzupełnienia zabudowy. | | `plan_id` | no | `{"type": ["string", "null"]}` | not specified in the source contract | | `resolution_url` | no | `{"type": ["string", "null"]}` | not specified in the source contract | | `status` | yes | `{"enum": ["draft", "adopted", "in_force", "none"], "type": "string"}` | Status planu ogólnego lub MPZP: draft (projekt, nieuchwalony), adopted (uchwalony, jeszcze nie obowiązuje), in_force (obowiązuje), none (źródło nie zawiera rekordu takiego planu dla tego miejsca). Statusom adopted i in_force towarzyszy effective_from. | | `zone_name` | no | `{"type": ["string", "null"]}` | not specified in the source contract | | `zone_symbol` | yes | `{"type": ["string", "null"]}` | Dominująca strefa o największym udziale, np. SW, SJ, SN, SR, SI, SH, SU, SK, SC, SG, SO, SP. | | `zones` | yes | `{"items": {"properties": {"name": {"type": ["string", "null"]}, "parameters": {"properties": {"max_coverage_pct": {"type": ["number", "null"]}, "max_height_m": {"type": ["number", "null"]}, "max_intensity": {"type": ["number", "null"]}, "min_biologically_active_pct": {"type": ["number", "null"]}, "min_new_plot_area_m2": {"type": ["number", "null"]}}, "type": "object"}, "share_pct": {"type": "number"}, "symbol": {"type": "string"}}, "required": ["symbol", "share_pct"], "type": "object"}, "type": "array"}` | not specified in the source contract | ```json { "description": "Plan ogólny. Projekty są pokazywane i oznaczane jako projekty. covered_no_data oznacza, że źródło obejmuje gminę, ale nie zawiera rekordu planu ogólnego: {status: none, zone_symbol: null, zones: []}.", "properties": { "adopted_on": { "format": "date", "type": [ "string", "null" ] }, "effective_from": { "description": "Data wejścia planu w życie; null dla draft i none.", "format": "date", "type": [ "string", "null" ] }, "in_ouz": { "description": "W granicach obszaru uzupełnienia zabudowy.", "type": [ "boolean", "null" ] }, "plan_id": { "type": [ "string", "null" ] }, "resolution_url": { "type": [ "string", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/PlanStatus" }, "zone_name": { "type": [ "string", "null" ] }, "zone_symbol": { "description": "Dominująca strefa o największym udziale, np. SW, SJ, SN, SR, SI, SH, SU, SK, SC, SG, SO, SP.", "type": [ "string", "null" ] }, "zones": { "items": { "properties": { "name": { "type": [ "string", "null" ] }, "parameters": { "properties": { "max_coverage_pct": { "type": [ "number", "null" ] }, "max_height_m": { "type": [ "number", "null" ] }, "max_intensity": { "type": [ "number", "null" ] }, "min_biologically_active_pct": { "type": [ "number", "null" ] }, "min_new_plot_area_m2": { "type": [ "number", "null" ] } }, "type": "object" }, "share_pct": { "type": "number" }, "symbol": { "type": "string" } }, "required": [ "symbol", "share_pct" ], "type": "object" }, "type": "array" } }, "required": [ "status", "zone_symbol", "zones", "effective_from" ], "type": "object" } ``` ## Empty answer: covered_no_data The contract states this empty `value`: ```json { "status": "none", "zone_symbol": null, "zones": [] } ``` The stated empty value omits required fields `effective_from`; a complete empty value is not specified in the source contract. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # PricesValue Zbiorcze dane porównawcze RCN. Przy mniej niż 5 transakcjach dane zbiorcze nie są udostępniane, a coverage wynosi covered_no_data. Layer keys: `prices`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `comparables_count` | yes | `{"type": "integer"}` | not specified in the source contract | | `median_pln_m2` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `p25_pln_m2` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `p75_pln_m2` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `radius_m` | no | `{"type": "integer"}` | not specified in the source contract | | `window_months` | no | `{"type": "integer"}` | not specified in the source contract | ```json { "description": "Zbiorcze dane porównawcze RCN. Przy mniej niż 5 transakcjach dane zbiorcze nie są udostępniane, a coverage wynosi covered_no_data.", "properties": { "comparables_count": { "type": "integer" }, "median_pln_m2": { "type": [ "number", "null" ] }, "p25_pln_m2": { "type": [ "number", "null" ] }, "p75_pln_m2": { "type": [ "number", "null" ] }, "radius_m": { "type": "integer" }, "window_months": { "type": "integer" } }, "required": [ "comparables_count" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # ProtectedValue not specified in the source contract Layer keys: `protected`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `forms` | yes | `{"items": {"properties": {"code": {"type": ["string", "null"]}, "name": {"type": "string"}, "type": {"description": "Kody form ochrony: park_narodowy, rezerwat, park_krajobrazowy, obszar_chronionego_krajobrazu, natura2000_oso, natura2000_soo, uzytek_ekologiczny, zespol_przyrodniczo_krajobrazowy, stanowisko_dokumentacyjne, pomnik_przyrody.", "type": "string"}}, "required": ["type", "name"], "type": "object"}, "type": "array"}` | not specified in the source contract | | `inside_any` | yes | `{"type": "boolean"}` | not specified in the source contract | ```json { "properties": { "forms": { "items": { "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "description": "Kody form ochrony: park_narodowy, rezerwat, park_krajobrazowy, obszar_chronionego_krajobrazu, natura2000_oso, natura2000_soo, uzytek_ekologiczny, zespol_przyrodniczo_krajobrazowy, stanowisko_dokumentacyjne, pomnik_przyrody.", "type": "string" } }, "required": [ "type", "name" ], "type": "object" }, "type": "array" }, "inside_any": { "type": "boolean" } }, "required": [ "inside_any", "forms" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # RoadAccessValue not specified in the source contract Layer keys: `road_access`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `nearest_public_road_m` | no | `{"type": ["number", "null"]}` | not specified in the source contract | | `verdict` | yes | `{"enum": ["pass", "fail", "unknown"], "type": "string"}` | not specified in the source contract | | `via` | no | `{"enum": ["adjacent_public_road_parcel", "bdot_road_within_30m", null], "type": ["string", "null"]}` | not specified in the source contract | ```json { "properties": { "nearest_public_road_m": { "type": [ "number", "null" ] }, "verdict": { "enum": [ "pass", "fail", "unknown" ], "type": "string" }, "via": { "enum": [ "adjacent_public_road_parcel", "bdot_road_within_30m", null ], "type": [ "string", "null" ] } }, "required": [ "verdict" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # SoilValue not specified in the source contract Layer keys: `soil`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `classes` | yes | `{"items": {"properties": {"share_pct": {"type": "number"}, "symbol": {"type": "string"}}, "type": "object"}, "type": "array"}` | not specified in the source contract | ```json { "properties": { "classes": { "items": { "properties": { "share_pct": { "type": "number" }, "symbol": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "classes" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # WzValue Wynik własnych obliczeń: czy w dniu zapytania można wydać decyzję WZ dla działki. basis wskazuje przepis. Layer keys: `wz`. ## Cost and inputs `x-request-cost`: 1 request per call via [GET /v1/layer/{layer}](../operations/layer.md). Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Value schema | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `possible` | yes | `{"type": ["boolean", "null"]}` | not specified in the source contract | | `reason` | no | `{"type": "string"}` | not specified in the source contract | ```json { "description": "Wynik własnych obliczeń: czy w dniu zapytania można wydać decyzję WZ dla działki. basis wskazuje przepis.", "properties": { "possible": { "type": [ "boolean", "null" ] }, "reason": { "type": "string" } }, "required": [ "possible" ], "type": "object" } ``` ## Empty answer: covered_no_data not specified in the source contract. The contract does not define a complete empty value for this schema. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # Six MCP tools Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ## Cost Costs are `x-request-cost`, in requests per call. | Tool | REST binding | Cost | | --- | --- | --- | | [check](tools/check.md) | GET /v1/check | 1 | | [events](tools/events.md) | GET /v1/events | 1 | | [layer](tools/layer.md) | GET /v1/layer/{layer} | 1 | | [parcel](tools/parcel.md) | GET /v1/parcel | 1 | | [resolve](tools/resolve.md) | GET /v1/resolve | 1 | | [search](tools/search.md) | GET /v1/search | 1 | ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ```json { "AreaV2": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "official_m2": { "exclusiveMinimum": 0, "type": "number" } } }, "if": { "properties": { "source": { "const": "computed" } } }, "then": { "properties": { "note": { "const": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna." }, "official_m2": { "type": "null" } } } } ], "properties": { "geometry_m2": { "exclusiveMinimum": 0, "type": "number" }, "note": { "minLength": 1, "type": "string" }, "official_m2": { "anyOf": [ { "exclusiveMinimum": 0, "type": "number" }, { "type": "null" } ] }, "provenance": { "$ref": "#/$defs/SourceRef" }, "source": { "enum": [ "egib", "computed" ], "type": "string" } }, "required": [ "official_m2", "geometry_m2", "source", "provenance", "note" ], "type": "object" }, "Auth": { "additionalProperties": false, "properties": { "kind": { "enum": [ "api_key", "oauth_connector" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "BatchCheckItem": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "result": { "type": "null" } } }, "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "error": { "type": "null" }, "result": { "$ref": "#/$defs/CheckResultV2" } } } }, { "if": { "properties": { "status": { "const": "error" } } }, "then": { "properties": { "error": { "$ref": "#/$defs/Error" } } } } ], "properties": { "billing": { "allOf": [ { "$ref": "#/$defs/BillingV2" }, { "properties": { "cost": { "const": 1 } } } ] }, "error": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ] }, "parcel_id": { "$ref": "#/$defs/ParcelId" }, "result": { "anyOf": [ { "$ref": "#/$defs/CheckResultV2" }, { "type": "null" } ] }, "status": { "enum": [ "ok", "not_found", "not_covered", "error" ], "type": "string" } }, "required": [ "parcel_id", "status", "result", "billing", "error" ], "type": "object" }, "BatchCheckJob": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "state": { "const": "completed" } } }, "then": { "properties": { "error": { "type": "null" }, "results_url": { "pattern": "^/v1/check/jobs/[^/]+/results$", "type": "string" } } } }, { "if": { "properties": { "state": { "const": "failed" } } }, "then": { "properties": { "error": { "$ref": "#/$defs/Error" } } } } ], "properties": { "completed": { "maximum": 10000, "minimum": 0, "type": "integer" }, "error": { "anyOf": [ { "$ref": "#/$defs/Error" }, { "type": "null" } ] }, "id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "results_url": { "anyOf": [ { "pattern": "^/v1/check/jobs/[^/]+/results$", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "completed", "failed" ], "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" }, "total": { "maximum": 10000, "minimum": 1, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "state", "submitted_at", "updated_at", "total", "completed", "results_url", "error" ], "type": "object" }, "BatchCheckRequest": { "additionalProperties": false, "properties": { "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "parcel_ids" ], "type": "object", "x-runtime-supported": false }, "BatchCheckResults": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/$defs/BatchCheckItem" }, "maxItems": 1000, "type": "array" }, "job_id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "page": { "$ref": "#/$defs/Page" } }, "required": [ "job_id", "items", "page" ], "type": "object" }, "Billing": { "additionalProperties": false, "properties": { "charged": { "minimum": 0, "type": "integer" }, "cost": { "minimum": 0, "type": "integer" }, "credits": { "minimum": 0, "type": "integer" }, "refunded": { "minimum": 0, "type": "integer" }, "rule": { "enum": [ "charged", "free_operation", "free_invalid_input", "free_unauthorized", "free_not_modified", "refunded_client_error", "refunded_server_error", "refunded_not_covered", "refunded_not_computed", "batch_mixed" ], "type": "string" } }, "required": [ "cost", "charged", "refunded", "rule" ], "type": "object" }, "BillingV2": { "allOf": [ { "$ref": "#/$defs/Billing" }, { "required": [ "credits" ] } ] }, "Candidate": { "additionalProperties": false, "properties": { "area_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "#/$defs/LonLat" }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "pattern": "^[0-9]{7}$", "type": "string" }, "held": { "type": "boolean" }, "id": { "type": "string" }, "kind": { "enum": [ "parcel", "obreb", "gmina", "address" ], "type": "string" }, "label": { "type": "string" }, "match_reason": { "type": "string" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": "string" }, "powiat_name": { "type": "string" }, "voivodeship": { "pattern": "^[0-9]{2}$", "type": "string" } }, "required": [ "id", "kind", "label", "confidence" ], "type": "object" }, "CheckResultV2": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "verdict": { "const": "pass" } }, "required": [ "verdict" ] }, "then": { "properties": { "checks": { "items": { "properties": { "result": { "const": "pass" } } }, "maxItems": 8, "minItems": 8 }, "record": { "properties": { "layers": { "properties": { "flood": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "landslide": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "mpzp": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "pog": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "protected": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "road_access": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "wz": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } } }, "required": [ "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access" ] } } } } } } ], "properties": { "checks": { "items": { "additionalProperties": false, "properties": { "basis": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "id": { "enum": [ "pog_zone", "wz_possible", "mpzp_status", "mpzp_params", "flood_q100", "landslide", "protected", "road_access" ], "type": "string" }, "layer": { "$ref": "#/$defs/LayerKey" }, "result": { "enum": [ "pass", "fail", "warn", "unknown" ], "type": "string" }, "source": { "$ref": "#/$defs/SourceRef" }, "value": {} }, "required": [ "id", "layer", "result", "source" ], "type": "object" }, "type": "array" }, "disclaimer": { "type": "string" }, "id": { "$ref": "#/$defs/ParcelId" }, "record": { "$ref": "#/$defs/ParcelRecordV2" }, "verdict": { "enum": [ "pass", "conditional", "fail", "unknown" ], "type": "string" } }, "required": [ "verdict", "checks", "record", "disclaimer" ], "type": "object" }, "ContractV2Marker": { "properties": { "meta": { "properties": { "contract_version": { "const": "2.0.0" } }, "required": [ "contract_version" ] } }, "required": [ "meta" ] }, "CorpusCoverage": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "held_parcels": { "type": "integer" }, "held_pct": { "maximum": 100, "minimum": 0, "type": [ "number", "null" ] }, "note": { "type": "string" }, "scope": { "type": "string" }, "source_parcels": { "type": [ "integer", "null" ] } }, "required": [ "scope", "source_parcels", "held_parcels", "held_pct", "as_of", "note" ], "type": "object" }, "Coverage": { "enum": [ "covered", "covered_no_data", "not_covered", "not_computed" ], "type": "string" }, "CoverageLayerSummary": { "additionalProperties": false, "properties": { "gminas": { "minimum": 0, "type": "integer" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of" ], "type": "object" }, "Envelope": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "const": "error" } }, "required": [ "status" ] }, "then": { "properties": { "error": { "type": "object" } } } }, { "if": { "properties": { "status": { "const": "ambiguous" } }, "required": [ "status" ] }, "then": { "properties": { "candidates": { "minItems": 1 } } } }, { "if": { "properties": { "status": { "not": { "const": "ok" } } }, "required": [ "status" ] }, "then": { "properties": { "result": { "type": "null" } } } }, { "if": { "properties": { "query": { "properties": { "kind": { "const": "invalid" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, "then": { "properties": { "status": { "const": "error" } } } }, { "if": { "$ref": "#/$defs/ContractV2Marker" }, "then": { "properties": { "billing": { "required": [ "credits" ] }, "links": { "properties": { "sheet": { "$ref": "#/$defs/SignedLink" } } }, "meta": { "required": [ "operation" ] }, "query": { "additionalProperties": false, "allOf": [ { "if": { "not": { "required": [ "kind" ] } }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput" } } } }, { "if": { "properties": { "kind": { "const": "q" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "q" ] } } } }, { "if": { "properties": { "kind": { "const": "id" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "id" ] } } } }, { "if": { "properties": { "kind": { "const": "point" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "anyOf": [ { "required": [ "point" ] }, { "required": [ "lat", "lng" ] } ] } } } }, { "if": { "properties": { "kind": { "enum": [ "none", "bbox", "polygon", "path" ] } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/NoQueryInput" } } } }, { "if": { "properties": { "kind": { "const": "bbox" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "bbox" ] } } } }, { "if": { "properties": { "kind": { "const": "polygon" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "polygon" ] } } } }, { "if": { "properties": { "kind": { "const": "path" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "teryt" ] } } } }, { "if": { "properties": { "kind": { "const": "batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "properties": { "items": { "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "items" ] } } } }, { "if": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "events" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/EventsRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" } } } }, { "if": { "properties": { "kind": { "const": "check_batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/BatchCheckRequest" } } } }, { "if": { "properties": { "kind": { "const": "job" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/JobQuery" } } } } ], "properties": { "input": { "additionalProperties": false, "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "bbox": { "items": { "type": "number" }, "type": "array" }, "cursor": { "type": [ "string", "null" ] }, "filters": { "$ref": "#/$defs/SearchFilters" }, "format": { "type": [ "string", "null" ] }, "geometry": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/$defs/QueryInput", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } } }, "type": "array" }, "job_id": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "layer": { "type": [ "string", "null" ] }, "layers": { "items": { "type": "string" }, "type": "array" }, "limit": { "type": "number" }, "listing_url": { "type": [ "string", "null" ] }, "lng": { "type": "number" }, "parcel_ids": { "items": { "type": "string" }, "type": "array" }, "point": { "items": { "type": "number" }, "type": "array" }, "polygon": { "$ref": "#/$defs/SearchPolygon" }, "q": { "type": [ "string", "null" ] }, "radius_m": { "type": "number" }, "results": { "type": "boolean" }, "since": { "type": [ "string", "null" ] }, "teryt": { "type": [ "string", "null" ] }, "types": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "kind": { "enum": [ "q", "id", "point", "none", "bbox", "polygon", "path", "batch", "invalid", "search", "events", "listing", "check_batch", "job" ], "type": "string" }, "resolved": { "oneOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "from": { "enum": [ "q", "id", "point" ], "type": "string" }, "id": { "type": "string" }, "method": { "enum": [ "exact_id", "normalised_id", "text_parcel", "text_parcel_fuzzy", "text_address", "text_gmina", "point_in_polygon" ], "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "from", "method", "id", "confidence" ], "type": "object" } ] } }, "required": [ "input", "resolved" ], "type": "object" } }, "required": [ "auth", "plan" ] } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "parcel" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/ParcelRecordV2", "required": [ "display_geometry", "display_simplified", "adjacent_parcel_ids", "adjacent_parcel_ids_truncated" ] } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "layer" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "additionalProperties": false, "properties": { "answer": { "$ref": "#/$defs/LayerAnswerV2" }, "id": { "$ref": "#/$defs/ParcelId" } }, "required": [ "id", "answer" ], "type": "object" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "check" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/CheckResultV2" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "search" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/SearchResultV2" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "events" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "items": { "$ref": "#/$defs/EventV2" }, "type": "array" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "check_batch" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckJob" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "check_job" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckJob" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "check_results" } }, "required": [ "operation" ] }, "status": { "const": "ok" } } } ] }, "then": { "properties": { "result": { "$ref": "#/$defs/BatchCheckResults" } } } }, { "if": { "allOf": [ { "$ref": "#/$defs/ContractV2Marker" }, { "properties": { "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] } } } ] }, "then": { "allOf": [ { "if": { "properties": { "status": { "const": "ok" } } }, "then": { "properties": { "status": { "const": "ambiguous" } } } } ], "properties": { "candidates": { "items": { "$ref": "#/$defs/ListingCandidate" }, "type": "array" }, "query": { "properties": { "resolved": { "type": "null" } } }, "result": { "type": "null" } } } }, { "if": { "anyOf": [ { "properties": { "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] } }, "required": [ "meta" ] }, { "properties": { "query": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, { "properties": { "query": { "properties": { "input": { "required": [ "listing_url" ] } }, "required": [ "input" ] } }, "required": [ "query" ] } ] }, "then": { "properties": { "candidates": { "items": { "$ref": "#/$defs/ListingCandidate" }, "type": "array" }, "meta": { "properties": { "operation": { "const": "resolve_listing" } }, "required": [ "operation" ] }, "query": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" }, "kind": { "const": "listing" }, "resolved": { "type": "null" } }, "required": [ "kind" ] }, "result": { "type": "null" }, "status": { "enum": [ "ambiguous", "not_found", "error", "not_covered" ] } } } }, { "if": { "anyOf": [ { "properties": { "query": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] } }, "required": [ "query" ] }, { "properties": { "query": { "properties": { "input": { "required": [ "filters" ] } } } } } ] }, "then": { "properties": { "meta": { "properties": { "operation": { "const": "search" } }, "required": [ "operation" ] }, "query": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" }, "kind": { "const": "search" } }, "required": [ "kind" ] } } } } ], "properties": { "auth": { "$ref": "#/$defs/Auth" }, "billing": { "$ref": "#/$defs/Billing" }, "candidates": { "items": { "oneOf": [ { "$ref": "#/$defs/Candidate" }, { "$ref": "#/$defs/ListingCandidate" } ] }, "type": "array" }, "corpus_coverage": { "$ref": "#/$defs/CorpusCoverage" }, "coverage_summary": { "additionalProperties": false, "properties": { "generated_at": { "format": "date-time", "type": "string" }, "gminas": { "minimum": 0, "type": "integer" }, "layers": { "additionalProperties": false, "properties": { "buildings": { "$ref": "#/$defs/CoverageLayerSummary" }, "flood": { "$ref": "#/$defs/CoverageLayerSummary" }, "landslide": { "$ref": "#/$defs/CoverageLayerSummary" }, "mpzp": { "$ref": "#/$defs/CoverageLayerSummary" }, "parcel": { "$ref": "#/$defs/CoverageLayerSummary" }, "pog": { "$ref": "#/$defs/CoverageLayerSummary" }, "protected": { "$ref": "#/$defs/CoverageLayerSummary" }, "wz": { "$ref": "#/$defs/CoverageLayerSummary" } }, "required": [ "parcel", "pog", "wz", "mpzp", "flood", "landslide", "protected", "buildings" ], "type": "object" }, "line": { "minLength": 1, "type": "string" }, "newest_as_of": { "format": "date", "type": [ "string", "null" ] }, "note": { "minLength": 1, "type": "string" }, "oldest_as_of": { "format": "date", "type": [ "string", "null" ] }, "unmeasured_layers": { "items": { "$ref": "#/$defs/LayerKey" }, "type": "array", "uniqueItems": true }, "voivodeships": { "maximum": 16, "minimum": 0, "type": "integer" } }, "required": [ "gminas", "voivodeships", "oldest_as_of", "newest_as_of", "layers", "unmeasured_layers", "generated_at", "line", "note" ], "type": "object" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Error" } ] }, "links": { "additionalProperties": { "$ref": "#/$defs/Link" }, "properties": { "map": { "$ref": "#/$defs/Link" }, "sheet": { "anyOf": [ { "$ref": "#/$defs/Link" }, { "$ref": "#/$defs/SignedLink" } ] }, "tiles": { "$ref": "#/$defs/Link" } }, "type": "object" }, "meta": { "$ref": "#/$defs/Meta" }, "needs_obreb": { "type": "boolean" }, "page": { "$ref": "#/$defs/Page" }, "plan": { "$ref": "#/$defs/Plan" }, "query": { "$ref": "#/$defs/QueryEcho" }, "result": { "type": [ "object", "array", "null" ] }, "search_facets": { "$ref": "#/$defs/FeatureSearchFacets" }, "sources": { "items": { "$ref": "#/$defs/SourceRef" }, "type": "array" }, "status": { "$ref": "#/$defs/Status" } }, "required": [ "status", "query", "result", "candidates", "sources", "billing", "error", "meta" ], "type": "object", "x-contract-version": "2.0.0" }, "Error": { "additionalProperties": false, "properties": { "code": { "enum": [ "invalid_input", "not_found", "ambiguous", "not_covered", "unauthorized", "rate_limited", "source_unavailable", "internal" ], "type": "string" }, "docs": { "type": "string" }, "example_id": { "type": [ "string", "null" ] }, "field": { "type": [ "string", "null" ] }, "hint": { "minLength": 1, "type": "string" }, "message": { "type": "string" }, "signup_url": { "type": [ "string", "null" ] } }, "required": [ "code", "message", "hint", "docs" ], "type": "object" }, "EventTypeV2": { "enum": [ "gunb_permit", "plan_general_adopted", "mpzp_status_changed", "rcn_transaction_aggregate", "listing_seen", "source_refreshed", "coverage_changed" ], "type": "string" }, "EventV2": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "gunb_permit" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "permit_id": { "minLength": 1, "type": "string" }, "status": { "enum": [ "applied", "issued", "refused", "withdrawn" ], "type": "string" } }, "required": [ "permit_id", "status" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "plan_general_adopted" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "gmina_teryt": { "pattern": "^[0-9]{6}[123]$", "type": "string" }, "resolution_id": { "minLength": 1, "type": "string" } }, "required": [ "gmina_teryt", "resolution_id" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "mpzp_status_changed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "properties": { "effective_from": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "plan_id": { "minLength": 1, "type": "string" }, "status": { "$ref": "#/$defs/MpzpStatus" } }, "required": [ "plan_id", "status", "effective_from" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "rcn_transaction_aggregate" } } }, "then": { "not": { "required": [ "parcel_ids" ] }, "properties": { "data": { "$ref": "#/$defs/RcnAggregate" } }, "required": [ "data", "area" ] } }, { "if": { "properties": { "type": { "const": "source_refreshed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "layer_version": { "minLength": 1, "type": "string" }, "source_id": { "minLength": 1, "type": "string" } }, "required": [ "source_id", "layer_version" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "coverage_changed" } } }, "then": { "properties": { "data": { "additionalProperties": false, "properties": { "after": { "$ref": "#/$defs/Coverage" }, "before": { "$ref": "#/$defs/Coverage" }, "layer": { "$ref": "#/$defs/LayerKey" } }, "required": [ "layer", "before", "after" ], "type": "object" } }, "required": [ "data" ] } }, { "if": { "properties": { "type": { "const": "listing_seen" } } }, "then": { "not": { "anyOf": [ { "required": [ "area" ] }, { "required": [ "data" ] } ] }, "required": [ "parcel_ids" ] } } ], "oneOf": [ { "not": { "required": [ "area" ] }, "required": [ "parcel_ids" ] }, { "not": { "required": [ "parcel_ids" ] }, "required": [ "area" ] } ], "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "as_of": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "data": {}, "id": { "minLength": 1, "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "occurred_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true }, "source": { "$ref": "#/$defs/SourceRef" }, "type": { "$ref": "#/$defs/EventTypeV2" } }, "required": [ "id", "type", "occurred_at", "observed_at", "source", "as_of" ], "type": "object" }, "EventsRequestV2": { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "parcel_ids" ] }, "required": [ "area" ] }, { "not": { "required": [ "area" ] }, "required": [ "parcel_ids" ] } ], "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "cursor": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 10000, "minItems": 1, "type": "array", "uniqueItems": true }, "since": { "format": "date-time", "type": "string" }, "types": { "items": { "$ref": "#/$defs/EventTypeV2" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [], "type": "object" }, "ExportV2": { "additionalProperties": false, "properties": { "format": { "enum": [ "csv", "geojson" ], "type": "string" }, "link": { "$ref": "#/$defs/SignedLink" }, "rows": { "maximum": 2000, "minimum": 0, "type": "integer" } }, "required": [ "format", "rows", "link" ], "type": "object" }, "FeatureAnswer": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] } } }, "then": { "properties": { "as_of": { "format": "date", "type": "string" } } } }, { "if": { "properties": { "coverage": { "const": "covered" } } }, "then": { "properties": { "value": { "not": { "type": "null" } } } } } ], "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "coverage": { "$ref": "#/$defs/Coverage" }, "method": { "minLength": 1, "type": "string" }, "note": { "minLength": 1, "type": "string" }, "source": { "$ref": "#/$defs/SourceRef" }, "sources": { "items": { "$ref": "#/$defs/SourceRef" }, "minItems": 1, "type": "array" }, "unit": { "type": [ "string", "null" ] }, "value": {} }, "required": [ "value", "unit", "source", "as_of", "method", "coverage", "note" ], "type": "object" }, "FeatureFilterFacet": { "additionalProperties": false, "properties": { "coverage_semantics": { "const": "unknown_excluded_and_counted; independent_scope_before_other_filters_and_pagination" }, "excluded_known": { "minimum": 0, "type": "integer" }, "excluded_unknown": { "minimum": 0, "type": "integer" }, "matched": { "minimum": 0, "type": "integer" } }, "required": [ "matched", "excluded_unknown", "excluded_known", "coverage_semantics" ], "type": "object" }, "FeatureSearchFacets": { "additionalProperties": false, "properties": { "filters": { "additionalProperties": { "$ref": "#/$defs/FeatureFilterFacet" }, "propertyNames": { "enum": [ "area_min_m2", "area_max_m2", "land_use_class", "shape_regularity_min", "frontage_min_m", "road_access", "buildings_present", "public_road_max_m", "rcn_price_min_pln_m2", "rcn_price_max_pln_m2", "gunb_activity_min", "pog_zone_class" ] }, "type": "object" }, "matched_count": { "minimum": 0, "type": "integer" }, "scope_count": { "minimum": 0, "type": "integer" } }, "required": [ "scope_count", "matched_count", "filters" ], "type": "object" }, "JobQuery": { "additionalProperties": false, "properties": { "cursor": { "minLength": 1, "type": [ "string", "null" ] }, "job_id": { "pattern": "^check_[A-Za-z0-9_-]+$", "type": "string" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" } }, "required": [ "job_id" ], "type": "object" }, "LayerAnswer": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" }, "LayerAnswerV2": { "allOf": [ { "$ref": "#/$defs/LayerAnswer" }, { "required": [ "licence", "scope", "method" ] }, { "if": { "properties": { "method": { "const": "extracted" } }, "required": [ "method" ] }, "then": { "required": [ "confidence", "threshold" ] } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "prices" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/RcnAggregate" } } } } ] }, "LayerKey": { "enum": [ "parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil" ], "type": "string" }, "Licence": { "additionalProperties": false, "properties": { "approved_at": { "const": "2026-10-16" }, "approved_by": { "const": "operator" }, "attribution": { "minLength": 1, "type": "string" }, "position": { "enum": [ "cc0", "cc_by_4_0", "local_law_no_copyright", "open_data", "own_computation", "statutory_open_data" ], "type": "string" }, "review_ref": { "minLength": 1, "type": "string" }, "terms_url": { "anyOf": [ { "format": "uri", "pattern": "^https://", "type": "string" }, { "type": "null" } ] } }, "required": [ "position", "attribution", "terms_url", "review_ref" ], "type": "object" }, "Link": { "additionalProperties": false, "properties": { "cost": { "minimum": 0, "type": "integer" }, "href": { "type": "string" } }, "required": [ "href", "cost" ], "type": "object" }, "ListingCandidate": { "additionalProperties": false, "properties": { "distance_m": { "minimum": 0, "type": "number" }, "parcel_id": { "$ref": "#/$defs/ParcelId" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" }, "score": { "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "parcel_id", "score", "reason", "distance_m" ], "type": "object" }, "ListingResolveRequest": { "additionalProperties": false, "properties": { "listing_url": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" } }, "required": [ "listing_url" ], "type": "object" }, "LonLat": { "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "Meta": { "additionalProperties": false, "properties": { "api_version": { "const": "v1", "type": "string" }, "calls": { "minimum": 1, "type": "integer" }, "contract_version": { "const": "2.0.0" }, "disclaimer": { "type": [ "string", "null" ] }, "etag": { "type": [ "string", "null" ] }, "excluded": { "items": { "type": "string" }, "type": "array" }, "generated_at": { "format": "date-time", "type": "string" }, "operation": { "enum": [ "parcel", "layer", "check", "resolve", "resolve_listing", "search", "events", "check_batch", "check_job", "check_results", "sources", "planning" ], "type": "string" }, "request_id": { "type": "string" } }, "required": [ "request_id", "api_version", "generated_at", "calls" ], "type": "object" }, "Method": { "enum": [ "official", "derived", "computed", "extracted" ], "type": "string" }, "MpzpStatus": { "anyOf": [ { "$ref": "#/$defs/PlanStatus" }, { "type": "null" } ] }, "MpzpValue": { "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "properties": { "effective_from": { "format": "date", "type": [ "string", "null" ] }, "plans": { "items": { "type": "object" }, "type": "array" }, "status": { "$ref": "#/$defs/MpzpStatus" }, "symbol": { "type": [ "string", "null" ] } }, "required": [ "status", "symbol", "plans", "effective_from" ], "type": "object" }, "NoQueryInput": { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "type": "object" }, "Page": { "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "has_more", "next_cursor" ], "type": "object" }, "ParcelFeatures": { "additionalProperties": false, "properties": { "access_and_roads": { "additionalProperties": false, "properties": { "frontage_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_dr_parcels", "egib_parcels" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "public_road_distance_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "bdot_roads" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "road_access": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "bdot_roads", "egib_dr_parcels", "egib_parcels" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } ] } }, "required": [ "public_road_distance_m", "road_access", "frontage_m" ], "type": "object" }, "amenities": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "buildings_and_surroundings": { "additionalProperties": false, "properties": { "building_count": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "building_coverage_pct": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "percent" }, "value": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "building_footprint_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "buildings_500m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "buildings_present": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_buildings" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } ] } }, "required": [ "buildings_present", "building_count", "building_footprint_m2", "building_coverage_pct", "buildings_500m" ], "type": "object" }, "development_activity": { "additionalProperties": false, "properties": { "gunb_activity_500m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "gunb_permits" ] } } }, "unit": { "const": "count_min" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] }, "gunb_activity_gmina": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "gunb_permits" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } ] } }, "required": [ "gunb_activity_gmina", "gunb_activity_500m" ], "type": "object" }, "land_use": { "additionalProperties": false, "properties": { "land_use_classes": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "items": { "pattern": "^[A-Za-zŁłŻż]{1,5}(?:[IVX]{1,4}[ab]?)?$", "type": "string" }, "maxItems": 100, "type": "array", "uniqueItems": true }, { "type": "null" } ] } } } ] }, "pog_zone_class": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "pog_sweep", "pog_zones" ] } } }, "unit": { "const": null }, "value": { "anyOf": [ { "enum": [ "SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP" ], "type": "string" }, { "type": "null" } ] } } } ] } }, "required": [ "land_use_classes", "pog_zone_class" ], "type": "object" }, "prices_nearby": { "additionalProperties": false, "properties": { "rcn_gmina_median_pln_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "rcn_clean_agg" ] } } }, "unit": { "const": "PLN/m2" }, "value": { "anyOf": [ { "minimum": 0, "multipleOf": 50, "type": "number" }, { "type": "null" } ] } } } ] }, "rcn_gmina_sales_count": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "rcn_clean_agg" ] } } }, "unit": { "const": "count" }, "value": { "anyOf": [ { "minimum": 6, "type": "integer" }, { "type": "null" } ] } } } ] } }, "required": [ "rcn_gmina_median_pln_m2", "rcn_gmina_sales_count" ], "type": "object" }, "shape_and_size": { "additionalProperties": false, "properties": { "area_geometry_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "area_official_m2": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m2" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "elongation": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "minimum": 1, "type": "number" }, { "type": "null" } ] } } } ] }, "perimeter_m": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "m" }, "value": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "shape_regularity": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "maximum": 1, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] }, "squareness": { "allOf": [ { "$ref": "#/$defs/FeatureAnswer" }, { "properties": { "source": { "properties": { "id": { "enum": [ "egib_parcels" ] } } }, "unit": { "const": "ratio" }, "value": { "anyOf": [ { "maximum": 1, "minimum": 0, "type": "number" }, { "type": "null" } ] } } } ] } }, "required": [ "area_official_m2", "area_geometry_m2", "perimeter_m", "shape_regularity", "squareness", "elongation" ], "type": "object" } }, "required": [ "shape_and_size", "access_and_roads", "land_use", "buildings_and_surroundings", "prices_nearby", "development_activity", "amenities" ], "type": "object" }, "ParcelId": { "maxLength": 100, "pattern": "^[0-9]{6}_[0-9]\\.[0-9]{1,4}\\.(?=[^\\n]{1,64}$)(?:[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]*\\.)?[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_/]+$", "type": "string" }, "ParcelIdInput": { "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string" }, "ParcelRecordV2": { "additionalProperties": false, "properties": { "adjacent_parcel_ids": { "items": { "$ref": "#/$defs/ParcelId" }, "maxItems": 50, "type": "array", "uniqueItems": true }, "adjacent_parcel_ids_truncated": { "type": "boolean" }, "admin": { "additionalProperties": false, "properties": { "admin_gmina_teryt": { "type": [ "string", "null" ] }, "gmina_name": { "type": "string" }, "gmina_teryt": { "type": "string" }, "gmina_type": { "type": [ "string", "null" ] }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" }, "voivodeship_name": { "type": "string" } }, "required": [ "voivodeship", "gmina_teryt", "gmina_name", "obreb_id", "number" ], "type": "object" }, "area": { "$ref": "#/$defs/AreaV2" }, "centroid": { "$ref": "#/$defs/LonLat" }, "display_geometry": { "additionalProperties": false, "properties": { "coordinates": { "items": { "items": { "items": { "$ref": "#/$defs/LonLat" }, "type": "array" }, "type": "array" }, "type": "array" }, "type": { "const": "MultiPolygon" } }, "required": [ "type", "coordinates" ], "type": "object" }, "display_simplified": { "const": true }, "features": { "$ref": "#/$defs/ParcelFeatures" }, "geometry": { "additionalProperties": false, "properties": { "coordinates": { "items": { "items": { "items": { "$ref": "#/$defs/LonLat" }, "type": "array" }, "type": "array" }, "type": "array" }, "type": { "const": "MultiPolygon" } }, "required": [ "type", "coordinates" ], "type": [ "object", "null" ] }, "id": { "$ref": "#/$defs/ParcelId" }, "layers": { "additionalProperties": { "$ref": "#/$defs/LayerAnswerV2" }, "propertyNames": { "enum": [ "parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil" ] }, "type": "object" }, "record_as_of": { "format": "date", "type": [ "string", "null" ] }, "record_hash": { "type": [ "string", "null" ] } }, "required": [ "id", "admin", "area", "layers", "record_hash" ], "type": "object" }, "Plan": { "enum": [ "free", "start", "pro", "team", "developer", "platform" ], "type": "string" }, "PlanStatus": { "enum": [ "draft", "adopted", "in_force", "none" ], "type": "string" }, "QueryEcho": { "additionalProperties": false, "allOf": [ { "if": { "not": { "required": [ "kind" ] } }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput" } } } }, { "if": { "properties": { "kind": { "const": "q" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "q" ] } } } }, { "if": { "properties": { "kind": { "const": "id" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "required": [ "id" ] } } } }, { "if": { "properties": { "kind": { "const": "point" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/QueryInput", "anyOf": [ { "required": [ "point" ] }, { "required": [ "lat", "lng" ] } ] } } } }, { "if": { "properties": { "kind": { "enum": [ "none", "bbox", "polygon", "path" ] } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/NoQueryInput" } } } }, { "if": { "properties": { "kind": { "const": "bbox" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "bbox" ] } } } }, { "if": { "properties": { "kind": { "const": "polygon" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "polygon" ] } } } }, { "if": { "properties": { "kind": { "const": "path" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "required": [ "teryt" ] } } } }, { "if": { "properties": { "kind": { "const": "batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "properties": { "items": { "maxItems": 1000, "minItems": 1, "type": "array" } }, "required": [ "items" ] } } } }, { "if": { "properties": { "kind": { "const": "search" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/SearchRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "events" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/EventsRequestV2" } } } }, { "if": { "properties": { "kind": { "const": "listing" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/ListingResolveRequest" } } } }, { "if": { "properties": { "kind": { "const": "check_batch" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/BatchCheckRequest" } } } }, { "if": { "properties": { "kind": { "const": "job" } }, "required": [ "kind" ] }, "then": { "properties": { "input": { "$ref": "#/$defs/JobQuery" } } } } ], "properties": { "input": { "additionalProperties": true, "type": "object" }, "kind": { "enum": [ "q", "id", "point", "none", "bbox", "polygon", "path", "batch", "invalid", "search", "events", "listing", "check_batch", "job" ], "type": "string" }, "resolved": { "oneOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "from": { "enum": [ "q", "id", "point" ], "type": "string" }, "id": { "type": "string" }, "method": { "enum": [ "exact_id", "normalised_id", "text_parcel", "text_parcel_fuzzy", "text_address", "text_gmina", "point_in_polygon" ], "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "from", "method", "id", "confidence" ], "type": "object" } ] } }, "required": [ "input", "resolved" ], "type": "object" }, "QueryInput": { "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } }, "type": "object" }, "RcnAggregate": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "unit_id": { "pattern": "^[0-9]{6}_[0-9]\\.[0-9]{1,4}$", "type": "string" } } }, "if": { "properties": { "scope": { "const": "gmina" } } }, "then": { "properties": { "unit_id": { "pattern": "^[0-9]{6}[123]$", "type": "string" } } } } ], "properties": { "count": { "minimum": 6, "type": "integer" }, "k_floor": { "const": 6 }, "median_price_m2": { "minimum": 0, "multipleOf": 50, "type": "number" }, "scope": { "enum": [ "obreb", "gmina" ], "type": "string" }, "unit_id": { "minLength": 1, "type": "string" }, "vintage": { "format": "date", "type": "string" } }, "required": [ "count", "k_floor", "median_price_m2", "scope", "unit_id", "vintage" ], "type": "object" }, "Scope": { "enum": [ "parcel_polygon", "point", "obreb", "gmina", "grid" ], "type": "string" }, "SearchArea": { "oneOf": [ { "$ref": "#/$defs/TerytArea" }, { "$ref": "#/$defs/SearchPolygon" } ] }, "SearchFilterEvidence": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "coverage": { "$ref": "#/$defs/Coverage" }, "note": { "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "value": { "type": [ "boolean", "number", "string", "null" ] } }, "required": [ "coverage", "value", "source", "as_of", "scope", "note" ], "type": "object" }, "SearchFilters": { "additionalProperties": false, "properties": { "area_m2": { "additionalProperties": false, "properties": { "max": { "exclusiveMinimum": 0, "type": "number" }, "min": { "minimum": 0, "type": "number" } }, "required": [], "type": "object" }, "building_present": { "type": "boolean" }, "no_nature_protection": { "type": "boolean" }, "outside_flood_q100": { "type": "boolean" }, "plan_general_zones": { "items": { "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "public_road_access": { "type": "boolean" } }, "required": [], "type": "object" }, "SearchPolygon": { "additionalProperties": false, "properties": { "coordinates": { "items": { "items": { "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "maxItems": 512, "minItems": 4, "type": "array" }, "maxItems": 1, "minItems": 1, "type": "array" }, "type": { "const": "Polygon" } }, "required": [ "type", "coordinates" ], "type": "object" }, "SearchRequestV2": { "additionalProperties": false, "properties": { "area": { "$ref": "#/$defs/SearchArea" }, "cursor": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ] }, "filters": { "$ref": "#/$defs/SearchFilters" }, "format": { "enum": [ "csv", "geojson" ], "type": "string" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" } }, "required": [ "area" ], "type": "object", "x-runtime-supported": false }, "SearchResultV2": { "additionalProperties": false, "properties": { "export": { "$ref": "#/$defs/ExportV2" }, "items": { "items": { "additionalProperties": false, "properties": { "address": { "type": [ "string", "null" ] }, "admin_gmina_teryt": { "type": [ "string", "null" ] }, "area_official_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "#/$defs/LonLat" }, "distance_m": { "type": [ "number", "null" ] }, "filter_evidence": { "additionalProperties": false, "properties": { "area_m2": { "$ref": "#/$defs/SearchFilterEvidence" }, "building_present": { "$ref": "#/$defs/SearchFilterEvidence" }, "no_nature_protection": { "$ref": "#/$defs/SearchFilterEvidence" }, "outside_flood_q100": { "$ref": "#/$defs/SearchFilterEvidence" }, "plan_general_zones": { "$ref": "#/$defs/SearchFilterEvidence" }, "public_road_access": { "$ref": "#/$defs/SearchFilterEvidence" } }, "type": "object" }, "flags": { "additionalProperties": false, "properties": { "building_present": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "no_nature_protection": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "outside_flood_q100": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "plan_general_zone_match": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "public_road_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "outside_flood_q100", "no_nature_protection", "plan_general_zone_match", "public_road_access", "building_present" ], "type": "object" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "type": "string" }, "id": { "$ref": "#/$defs/ParcelId" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" } }, "required": [ "id", "gmina_teryt", "gmina_name", "obreb_name", "number", "centroid", "flags" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "page": { "$ref": "#/$defs/Page" } }, "required": [ "items", "page" ], "type": "object" }, "SignedLink": { "additionalProperties": false, "properties": { "cost": { "minimum": 0, "type": "integer" }, "expires_at": { "format": "date-time", "type": "string" }, "href": { "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "href", "cost", "expires_at" ], "type": "object" }, "SourceRef": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "attribution": { "type": "string" }, "fallback": { "type": "boolean" }, "id": { "type": "string" }, "licence": { "type": "string" }, "publisher": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "attribution", "as_of" ], "type": "object" }, "Status": { "enum": [ "ok", "ambiguous", "not_found", "not_covered", "error" ], "type": "string" }, "TerytArea": { "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "powiat" }, "teryt": { "pattern": "^[0-9]{4}$", "type": "string" } }, "required": [ "kind", "teryt" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "gmina" }, "teryt": { "pattern": "^[0-9]{6}[123]$", "type": "string" } }, "required": [ "kind", "teryt" ], "type": "object" } ] } } ``` ## Tool descriptions (verbatim) ### check Sprawdź jedną działkę: nazwane sprawdzenia, źródła, zakres danych i osadzona karta. Przekazuj niepewność; nigdy nie stwierdzaj prawa do zabudowy. Zadania dla portfela i odpytywanie o zadania są niedostępne. ### events Pobierz zmiany dotyczące działek lub obszaru ze źródłami i datami, używając types, since i cursor. Większe listy parcel_ids przekaż w treści POST (do 10 000); GET dopuszcza 100 identyfikatorów. Zdarzenia RCN zawierają tylko zaokrąglone dane zbiorcze grup transakcji. Zdarzenia dotyczące ogłoszeń zawierają identyfikatory działek bez treści ogłoszenia. ### layer Pobierz wskazaną kategorię danych na podstawie q, id albo point. Odczytuj łącznie coverage, source, as_of i note. Opłaty za not_covered i not_computed są zwracane; covered_no_data oznacza brak rekordu potwierdzony przez źródło. Nie wnioskuj o braku obiektu ani o statusie prawnym z niedostępnych danych. ### parcel Pobierz kartę działki na podstawie q, id albo point: identyfikację, powierzchnię i dostępne dane tematyczne ze źródłem, datą, uwagą i zakresem danych. Niewiadome i niedostępne dane są wyraźnie oznaczone. Odczyt kosztuje jeden kredyt; odnośniki służą do opcjonalnych dalszych wywołań. ### resolve Rozpoznaj działki na podstawie q, id albo point. Niejednoznaczne dane zwracają kandydatów do wyboru. Parametr listing_url, dostępny po włączeniu funkcji, zastępuje pozostałe dane wejściowe i zawsze zwraca kandydatów z result=null. Nie kopiuj treści ogłoszenia ani nie wybieraj kandydata bez wiedzy użytkownika. ### search Wyszukaj według q/id/point, szerokości i długości geograficznej lub bbox do 4 km². Odpowiedź zawiera skróty informacji o działkach i kursor; każda strona kosztuje 1 kredyt. Filtry typowane obszaru i eksport są niedostępne. ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Structured JSON results ```json { "check": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "check" ] } } } }, "type": "object" }, "events": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "events" ] } } } }, "type": "object" }, "layer": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "layer" ] } } } }, "type": "object" }, "parcel": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "parcel" ] } } } }, "type": "object" }, "resolve": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "resolve", "resolve_listing" ] } } } }, "type": "object" }, "search": { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "search" ] } } } }, "type": "object" } } ``` See [Envelope](envelope.md). MCP transport invocation: not specified in the source contract. ## curl example of a REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/check" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` # POST /v1/account/keys Utwórz klucz konta i pokaż jego sekret jeden raz. Operation ID: `account_keys_create`. ## Description Tylko właściciel lub administrator zespołu może zarządzać własnymi kluczami. Maksymalnie 10 ważnych kluczy, łącznie z okresem wymiany. Sekretu nie można pobrać ponownie. Po utracie odpowiedzi unieważnij nowy klucz widoczny na liście i utwórz kolejny. Wszystkie operacje konta są bezpłatne. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Request body ```json { "content": { "application/json": { "example": { "label": "Console" }, "schema": { "$ref": "#/components/schemas/AccountKeyWrite" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Metadane nowego klucza i sekret dostępny jeden raz. Cache-Control: no-store. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyCreatedResponse" } } }, "description": "Metadane nowego klucza i sekret dostępny jeden raz. Cache-Control: no-store." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/account/keys" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"label": "Console"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/account/keys Lista ważnych kluczy tego konta; tylko dla właściciela lub administratora zespołu. Operation ID: `account_keys_list`. ## Description Maksymalnie 10 aktywnych kluczy, łącznie z kluczami ważnymi podczas wymiany. Bez sekretu i skrótu. Unieważnione i wygasłe klucze są pomijane. Ostatnie użycie oznacza udane bezpośrednie uwierzytelnienie kluczem. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wyłącznie metadane klucza. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyListResponse" } } }, "description": "Wyłącznie metadane klucza." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/account/keys" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/account/keys/{key_id} Natychmiast unieważnij klucz tego konta; tylko dla właściciela lub administratora zespołu. Operation ID: `account_keys_revoke`. ## Description Po zatwierdzeniu zmiany bezpośrednie uwierzytelnienie i powiązane OAuth natychmiast przestają działać. Klucz innego konta zwraca 404. Można unieważnić używany obecnie klucz. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `key_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `key_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Klucz unieważniony; bez sekretu. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyRevokedResponse" } } }, "description": "Klucz unieważniony; bez sekretu." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/account/keys/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/account/keys/{key_id}/rotate Wymień klucz z 24-godzinnym okresem wspólnej ważności; pokaż nowy sekret jeden raz. Operation ID: `account_keys_rotate`. ## Description Tylko właściciel lub administrator zespołu. Stary klucz zachowuje ważność dokładnie przez 24 godziny, chyba że wcześniej go unieważniono; powiązane OAuth wygasa w tym samym momencie. Ponowna wymiana klucza w okresie wspólnej ważności zwraca 409. Oba klucze wliczają się do limitu 10; przy pełnym limicie najpierw unieważnij inny klucz. Pominięta etykieta jest dziedziczona ze starego klucza. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `key_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `key_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "example": { "label": "Console" }, "schema": { "$ref": "#/components/schemas/AccountKeyWrite" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Nowy klucz z sekretem dostępnym jeden raz, identyfikator poprzedniego klucza i termin wygaśnięcia w UTC. Cache-Control: no-store. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountKeyRotatedResponse" } } }, "description": "Nowy klucz z sekretem dostępnym jeden raz, identyfikator poprzedniego klucza i termin wygaśnięcia w UTC. Cache-Control: no-store." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/account/keys/00000000-0000-4000-8000-000000000001/rotate" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"label": "Console"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/account/ledger Odczytaj zaksięgowane zmiany kredytów we wspólnej puli. Operation ID: `account_ledger`. ## Description Liczby ze znakiem; opłaty są ujemne. Saldo po wpisie obejmuje rezerwacje i przyszłe przyznania kredytów, więc nie jest saldem dostępnym do wydania. Kursor wyklucza wpisy zatwierdzone po pierwszej stronie. Kolejność jest malejąca według czasu i numeru w puli. Powtórz period, jeśli podano go na pierwszej stronie. Korekty są pokazywane jako charge lub grant zależnie od znaku. Każda operacja konta kosztuje zero kredytów; limit wynosi 30 wywołań na konto na minutę. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `period` | `cursor` | `limit`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `period` | query | false | `{"format": "date", "type": "string"}` | Data ISO w UTC wybiera zawierający ją okres płatny albo miesiąc kalendarzowy, gdy takiego okresu nie ma. Domyślnie wybierana jest bieżąca data. Początek włącznie, koniec wyłącznie; maksymalnie 366 dni. | | `cursor` | query | false | `{"maxLength": 1024, "type": "string"}` | not specified in the source contract | | `limit` | query | false | `{"default": 50, "maximum": 100, "minimum": 1, "type": "integer"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Strona historii rozliczeń ze stałym zakresem wpisów; bez danych osobowych. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLedgerResponse" } } }, "description": "Strona historii rozliczeń ze stałym zakresem wpisów; bez danych osobowych." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/account/ledger" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/account/usage Rozliczone zużycie netto kredytów według operacji i dnia UTC w okresie rozliczeniowym. Operation ID: `account_usage`. ## Description Ta sama pula i wybór okresu co w historii rozliczeń. Kredyty są liczone w chwili rozliczenia, po zwrotach; oczekujące rezerwacje i ręczne korekty są pomijane. Dni bez zużycia mają zero. Niesklasyfikowane dawne operacje mają kod other. Każdy członek konta może odczytać historię i zużycie bieżącej puli. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `period`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `period` | query | false | `{"format": "date", "type": "string"}` | Data ISO w UTC wybiera zawierający ją okres płatny albo miesiąc kalendarzowy, gdy takiego okresu nie ma. Domyślnie wybierana jest bieżąca data. Początek włącznie, koniec wyłącznie; maksymalnie 366 dni. | ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Granice okresu i łączne rozliczone zużycie. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsageResponse" } } }, "description": "Granice okresu i łączne rozliczone zużycie." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/account/usage" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Podaj ważny klucz API konta, aby wykonać tę operację.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/ask Odpowiedz na pytanie o działkę po polsku na podstawie płatnych odczytów landfeed. Operation ID: `ask`. ## Description Operacja jest wyłączona bez LANDFEED_ASK_PROVIDER i uwierzytelnienia dostawcy. Wtedy zwraca stan niedostępności bez opłaty. Domyślny budżet wynosi 5 kredytów, maksymalny 20. Budżet jest rezerwowany przed pracą modelu; rozliczenie obejmuje publiczne ceny wywołań narzędzi i 1 kredyt za ukończoną odpowiedź. billing.cost oznacza rezerwację, a billing.refunded obejmuje niewykorzystany budżet. calls podaje opłatę za każde wywołanie. max_credits nigdy nie jest przekraczane. W JSON v1 po wyczerpaniu budżetu odpowiedź zawiera zebrane dowody i wskazuje brakujące dane. Nieznany zakres danych nigdy nie oznacza braku ryzyka. Dane właścicieli i numery KW nie są pobierane ani podawane. Pytania, uwagi źródłowe i rozmowy z modelem nie są zapisywane ani logowane. Cytowania wskazują konkretną odpowiedź źródłową przez wywołanie, wskaźnik JSON i SHA-256 oraz datę i zakres danych. Uwagi źródłowe są niezaufane; tekst modelu nigdy nie jest udostępniany jako dowód faktów. Nagłówek Accept: text/event-stream wybiera zdarzenia SSE według AskEvent. Każde zdarzenie zawiera nazwę i dane JSON. Przed wykonaniem kroku podawane są metoda, ścieżka, parametry, treść żądania i koszt publicznej operacji. Wyniki i kontynuacje są podpisane HMAC-SHA256, związane z kontem i sprawdzane przed naliczeniem opłat. LANDFEED_ASK_HMAC_SECRET wymaga co najmniej 32 bajtów. Zmienione, wygasłe lub należące do innego konta dane są odrzucane. Prześlij ponownie messages, podpisane results z pełną treścią oraz continuation. Do modelu trafia ostatnich 20 wiadomości; wcześniejszy zamiar jest streszczany w bieżącym żądaniu. Wywołania narzędzi aplikacji i oczekiwanie na potwierdzenie nie mają dopłaty za odpowiedź. Tworzenie i usuwanie obserwacji, konfiguracja webhooka, eksport i krok powyżej 3 kredytów wymagają potwierdzenia. Wznowienie wymaga podpisanej kontynuacji oraz pasującego confirmation lub client_results. Zatrzymanie z powodu budżetu zwalnia całą turę z opłat, także wcześniejsze odczyty. Zdarzenia z rozliczeniem kroku są wysyłane po ostatecznym rozliczeniu. W v2 przed rozliczeniem ujawniana jest tylko aktywność kroków; nowe wyniki i fakty są wstrzymywane po zatrzymaniu z powodu budżetu lub błędzie rozliczenia. Rozłączenie nie powoduje automatycznego powtórzenia operacji. Rozmowa nie jest przechowywana. Protokół konsoli opisuje ask/README-v2.md. ## Cost `x-request-cost`: 1 request per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Accept` | header | false | `{"enum": ["application/json", "text/event-stream"], "type": "string"}` | SSE wybiera ask-v2; JSON zachowuje v1, chyba że podano version=ask-v2 lub pola rozmowy. | ## Request body ```json { "content": { "application/json": { "example": { "context": { "parcel_id": "141803_2.0001.12/3" }, "max_credits": 5, "question": "Czy działka leży w obszarze zagrożenia powodziowego?" }, "schema": { "$ref": "#/components/schemas/AskRequest" } } }, "required": true } ``` ## Operation credit rule ask: public tool charges + 1 answer; reserve max_credits, default 5, max 20; disabled/invalid/refusal free ## Authentication ```json [ { "ApiKey": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Stan answered, incomplete, budget_exhausted, refused albo stan niedostępności przy wyłączonej lub niedostępnej usłudze; sprawdź status i billing. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Nieprawidłowe dane wejściowe; bez opłaty. | free_invalid_input | | 401 | Wymagany ważny klucz konta; bez opłaty. | free_unauthorized | | 403 | Wymagany klucz przypisany do konta; bez opłaty. | refunded_client_error | | 413 | Treść przekracza 1 MiB (v2) lub 16 KiB (v1); bez opłaty. | refunded_client_error | | 429 | Za mało kredytów lub przekroczony limit żądań; bez opłaty. | refunded_client_error | | 503 | Dostawca lub rozliczenia są niedostępne; sprawdź wywołania i rozliczone kredyty. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/AskEvent" } } }, "description": "Stan answered, incomplete, budget_exhausted, refused albo stan niedostępności przy wyłączonej lub niedostępnej usłudze; sprawdź status i billing." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Nieprawidłowe dane wejściowe; bez opłaty." } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Wymagany ważny klucz konta; bez opłaty." } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Wymagany klucz przypisany do konta; bez opłaty." } ``` ### HTTP 413: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Treść przekracza 1 MiB (v2) lub 16 KiB (v1); bez opłaty." } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Za mało kredytów lub przekroczony limit żądań; bez opłaty." } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } }, "description": "Dostawca lub rozliczenia są niedostępne; sprawdź wywołania i rozliczone kredyty." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/ask" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"question": "Czy działka leży w obszarze zagrożenia powodziowego?", "context": {"parcel_id": "141803_2.0001.12/3"}, "max_credits": 5}' ``` ```json { "answer": "Nie udało się przyjąć pytania. Sprawdź jego treść i podany kontekst.", "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_unauthorized" }, "calls": [], "citations": [], "max_credits": 5, "meta": { "contract_version": "2.0.0", "prompt_version": "ask-v1", "request_id": "00000000-0000-4000-8000-000000000000", "tools_version": "ask-tools-v1" }, "missing": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/AskResponse.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "answer": "Źródło nie wskazuje zagrożenia powodziowego w badanym zakresie. [c1]", "billing": { "charged": 2, "cost": 2, "credits": 2, "refunded": 0, "rule": "charged" }, "calls": [ { "arguments": { "id": "141803_2.0001.12/3", "layers": [ "flood" ] }, "charged": 1, "cost": 1, "id": "t1", "operation": "parcel", "refunded": 0, "status": "ok", "tool": "parcel" } ], "citations": [ { "answer_sha256": "0000000000000000000000000000000000000000000000000000000000000000", "as_of": "2026-10-01", "call_id": "t1", "coverage": "covered_no_data", "id": "c1", "layer_key": "flood", "method": "official", "pointer": "/result/layers/flood", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" } } ], "max_credits": 5, "meta": { "contract_version": "2.0.0", "prompt_version": "ask-v1", "request_id": "00000000-0000-4000-8000-000000000001", "tools_version": "ask-tools-v1" }, "missing": [], "status": "answered" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/billing/account Wspólna pula kont, rola i obliczone saldo kredytów. Operation ID: `billing_account`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/billing/account" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/billing/account Unieważnij dane uwierzytelniające i usuń pola osobowe; trwale anuluj testową subskrypcję i usuń klienta Stripe. Zachowaj pseudonimowe rekordy księgowe. Operation ID: `billing_account_delete`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/billing/account" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/billing/checkout Utwórz testową subskrypcję Stripe Checkout z ochroną przed powtórnym utworzeniem. Operation ID: `billing_checkout`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | true | `{"maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "payment_method": { "default": "card", "description": "Płatności cykliczne Przelewy24 nie są obsługiwane; osobny produkt na jeden okres wymaga decyzji operatora.", "enum": [ "card" ], "type": "string" }, "plan": { "enum": [ "start", "pro", "team", "developer" ], "type": "string" } }, "required": [ "plan" ], "type": "object" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/billing/checkout" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Idempotency-Key: docs-example-001' \ -H 'Content-Type: application/json' \ --data '{"plan": "developer"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/billing/plans Katalog planów abonamentowych w trybie testowym. Operation ID: `billing_plans`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/billing/plans" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/billing/stripe/webhook Testowe zdarzenia Stripe z weryfikacją podpisu i ochroną przed ponownym przetworzeniem. Dane trybu produkcyjnego nie są przyjmowane. Operation ID: `billing_stripe_webhook`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Stripe-Signature` | header | true | `{"maxLength": 4096, "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true } ``` ## Authentication ```json [] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami. billing.credits zawsze wynosi zero." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 400. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/billing/stripe/webhook" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{}' ``` ```json { "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_invalid_input" }, "candidates": [], "error": { "code": "invalid_input", "docs": "https://landfeed.pl/docs", "hint": "Sprawdź wymagane pola w dokumentacji tej operacji i ponów żądanie.", "message": "Nie udało się potwierdzić zdarzenia płatności." }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/billing/team Lista członków uwierzytelnionej wspólnej puli kont. Operation ID: `billing_team`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/billing/team" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/billing/team/accept Przyjmij zaproszenie przypisane do uwierzytelnionego, istniejącego konta. Operation ID: `billing_team_accept`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Request body ```json { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/billing/team/accept" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/billing/team/invitations Właściciel tworzy zaproszenie ważne siedem dni, rezerwując jedno z pięciu miejsc. Operation ID: `billing_team_invite`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | true | `{"maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "account_id": { "format": "uuid", "type": "string" }, "role": { "enum": [ "admin", "member" ], "type": "string" } }, "required": [ "account_id", "role" ], "type": "object" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/billing/team/invitations" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Idempotency-Key: docs-example-001' \ -H 'Content-Type: application/json' \ --data '{"account_id": "00000000-0000-4000-8000-000000000001", "role": "member"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/billing/team/members/{account_id} Właściciel lub administrator usuwa miejsce; członek może zrezygnować z własnego miejsca. Właściciela nie można usunąć. Operation ID: `billing_team_remove`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `account_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `account_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/billing/team/members/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/billing/team/invitations/{invitation_id} Właściciel lub administrator unieważnia nieprzyjęte zaproszenie. Operation ID: `billing_team_revoke_invite`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `invitation_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `invitation_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/billing/team/invitations/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # PATCH /v1/billing/team/members/{account_id} Właściciel ustawia rolę admin lub member. Nie można zmienić właściciela. Operation ID: `billing_team_role`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `account_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `account_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "role": { "enum": [ "admin", "member" ], "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów. | free_operation | | 400 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 403 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 429 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope z wynikiem zarządzania rozliczeniami; zero kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 403: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 429: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request PATCH "https://mcp.agentdzialek.pl/v1/billing/team/members/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"role": "member"}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/check Czy można tu budować? Wynik według stałych reguł, ze wskazaniem sprawdzeń, źródeł i pełnej karty działki. Operation ID: `check`. ## Description Nie jest to porada prawna: wartości logiczne wynikają ze źródeł, tak jak oznaczenie zagrożenia powodziowego. Sprawdzenie danych, których państwo nie publikuje maszynowo, ma wynik unknown, bez zgadywania. result.record zawiera pełną kartę działki, aby jedno wywołanie odpowiadało także na dalsze pytania. Sprawdzanie obejmuje planowanie: pog_zone ze statusem planu i effective_from, wz_possible oraz mpzp_status. ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `If-None-Match` | header | false | `{"type": "string"}` | ETag z wcześniejszego GET według id. Dopasowanie zwraca bezpłatne HTTP 304. | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to CheckResult z pełną kartą działki. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 304 | If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified). | free_not_modified | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CheckResult" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to CheckResult z pełną kartą działki.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 304: headers and body schemas ```json { "description": "If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/check" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-check.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "check", "request_id": "fixture" }, "plan": "free", "query": { "input": { "id": "146501_1.0101.12/3" }, "kind": "id", "resolved": null }, "result": { "checks": [], "disclaimer": "Wynik przedstawia informacje ze źródeł; nie potwierdza prawa do zabudowy.", "id": "146501_1.0101.12/3", "record": { "admin": { "gmina_name": "Warszawa", "gmina_teryt": "1465011", "number": "12/3", "obreb_id": "146501_1.0101", "voivodeship": "14" }, "area": { "geometry_m2": 500, "note": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna.", "official_m2": null, "provenance": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, "source": "computed" }, "id": "146501_1.0101.12/3", "layers": { "flood": { "as_of": "2026-10-01", "coverage": "covered_no_data", "layer": "flood", "layer_version": "flood-national-20261016", "licence": { "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "position": "cc_by_4_0", "review_ref": "seed/attribution_review_2026-10-13.sql#mzp_flood", "terms_url": "https://creativecommons.org/licenses/by/4.0/" }, "method": "official", "note": "Według map zagrożenia powodziowego działka leży poza wskazanymi na nich obszarami zagrożenia w sprawdzonym zakresie. Nie wyklucza to powodzi.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": { "q10": false, "q100": false, "q500": false } } }, "record_hash": null }, "verdict": "unknown" }, "sources": [], "status": "ok" } ``` ## Matching MCP tool [check](../tools/check.md) # POST /v1/check Zbiorcze sprawdzenie check. Operation ID: `check_batch`. ## Description Operacja jest niedostępna w tej usłudze, bez rezerwacji i opłaty. Zarezerwowany kontrakt POST /v1/check z Idempotency-Key przewiduje 1 kredyt za identyfikator po zakończeniu, z dotychczasowym zwrotem za każdą pozycję. Zgłoszenie i sprawdzanie stanu nie mają opłaty. To samo konto, klucz i treść żądania zwracają to samo zadanie bez ponownej opłaty; zmieniona treść z tym samym kluczem daje 409 i zwrot. Klucze są przechowywane co najmniej 24 godziny po zakończeniu zadania. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | true | `{"maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json#/$defs/BatchCheckRequest" } } }, "required": true } ``` ## Runtime availability Dormant: defined by the contract but omitted from runtime discovery; do not call in production. ## Operation credit rule Submission and poll free; on completion meter 1 per id with per-item refunds, once per idempotent job. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 202 | Odpowiedź Envelope z wynikiem v2 o określonym typie. | free_operation | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 202: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "anyOf": [ { "type": "null" }, { "$ref": "./envelope.json#/$defs/BatchCheckJob" } ] } } } ] } } }, "description": "Odpowiedź Envelope z wynikiem v2 o określonym typie.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/check" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Idempotency-Key: docs-example-001' \ -H 'Content-Type: application/json' \ --data '{"parcel_ids": ["141803_2.0001.12/3"]}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-check_batch.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_operation" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "check_batch", "request_id": "fixture" }, "plan": "free", "query": { "input": { "parcel_ids": [ "146501_1.0101.12/3" ] }, "kind": "check_batch", "resolved": null }, "result": { "completed": 1, "error": null, "id": "check_fixture", "results_url": "/v1/check/jobs/check_fixture/results", "state": "completed", "submitted_at": "2026-10-16T12:00:00Z", "total": 1, "updated_at": "2026-10-16T12:00:00Z" }, "sources": [], "status": "ok" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/check/jobs/{job_id} Zadanie sprawdzenia check. Operation ID: `check_job`. ## Description Operacja jest niedostępna w tej usłudze. Zarezerwowany zasób zadania jest związany z kontem; inne konto nie ma do niego dostępu. Wyniki są dostępne tylko po zakończeniu zadania; wcześniej odpowiedź 409 jest bezpłatna. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `job_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `job_id` | path | true | `{"pattern": "^check_[A-Za-z0-9_-]+$", "type": "string"}` | not specified in the source contract | ## Runtime availability Dormant: defined by the contract but omitted from runtime discovery; do not call in production. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem v2 o określonym typie. | free_operation | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "anyOf": [ { "type": "null" }, { "$ref": "./envelope.json#/$defs/BatchCheckJob" } ] } } } ] } } }, "description": "Odpowiedź Envelope z wynikiem v2 o określonym typie.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/check/jobs/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-check_job.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_operation" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "check_job", "request_id": "fixture" }, "plan": "free", "query": { "input": { "job_id": "check_fixture" }, "kind": "job", "resolved": null }, "result": { "completed": 1, "error": null, "id": "check_fixture", "results_url": "/v1/check/jobs/check_fixture/results", "state": "completed", "submitted_at": "2026-10-16T12:00:00Z", "total": 1, "updated_at": "2026-10-16T12:00:00Z" }, "sources": [], "status": "ok" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/check/jobs/{job_id}/results Wyniki zadania check. Operation ID: `check_job_results`. ## Description Operacja jest niedostępna w tej usłudze. Zarezerwowany zasób zadania jest związany z kontem; inne konto nie ma do niego dostępu. Wyniki są dostępne tylko po zakończeniu zadania; wcześniej odpowiedź 409 jest bezpłatna. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `job_id` | `limit` | `cursor`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `job_id` | path | true | `{"pattern": "^check_[A-Za-z0-9_-]+$", "type": "string"}` | not specified in the source contract | | `limit` | query | false | `{"default": 100, "maximum": 1000, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `cursor` | query | false | `{"type": "string"}` | not specified in the source contract | ## Runtime availability Dormant: defined by the contract but omitted from runtime discovery; do not call in production. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope z wynikiem v2 o określonym typie. | free_operation | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | | 409 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "anyOf": [ { "type": "null" }, { "$ref": "./envelope.json#/$defs/BatchCheckResults" } ] } } } ] } } }, "description": "Odpowiedź Envelope z wynikiem v2 o określonym typie.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 409: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/check/jobs/00000000-0000-4000-8000-000000000001/results" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-check_results.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 0, "cost": 0, "credits": 0, "refunded": 0, "rule": "free_operation" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "check_results", "request_id": "fixture" }, "plan": "free", "query": { "input": { "job_id": "check_fixture" }, "kind": "job", "resolved": null }, "result": { "items": [ { "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "error": null, "parcel_id": "146501_1.0101.12/3", "result": { "checks": [], "disclaimer": "Wynik przedstawia informacje ze źródeł; nie potwierdza prawa do zabudowy.", "id": "146501_1.0101.12/3", "record": { "admin": { "gmina_name": "Warszawa", "gmina_teryt": "1465011", "number": "12/3", "obreb_id": "146501_1.0101", "voivodeship": "14" }, "area": { "geometry_m2": 500, "note": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna.", "official_m2": null, "provenance": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, "source": "computed" }, "id": "146501_1.0101.12/3", "layers": { "flood": { "as_of": "2026-10-01", "coverage": "covered_no_data", "layer": "flood", "layer_version": "flood-national-20261016", "licence": { "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "position": "cc_by_4_0", "review_ref": "seed/attribution_review_2026-10-13.sql#mzp_flood", "terms_url": "https://creativecommons.org/licenses/by/4.0/" }, "method": "official", "note": "Według map zagrożenia powodziowego działka leży poza wskazanymi na nich obszarami zagrożenia w sprawdzonym zakresie. Nie wyklucza to powodzi.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": { "q10": false, "q100": false, "q500": false } } }, "record_hash": null }, "verdict": "unknown" }, "status": "ok" } ], "job_id": "check_fixture", "page": { "has_more": false, "limit": 100, "next_cursor": null } }, "sources": [], "status": "ok" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/events Zmiany dotyczące działki, otoczenia punktu albo gminy wskazanej w q, od najnowszych. Operation ID: `events`. ## Description Zdarzenia v2 korzystają z EventV2: siedmiu rodzajów zmian ze źródłem i datą. Dane zbiorcze RCN wymagają k>=6, mediany zaokrąglonej do 50 zł/m² i obszaru; nigdy nie opisują sprzedaży pojedynczej działki. listing_seen zawiera wyłącznie identyfikatory działek. Stronicowanie kursorem korzysta z Page. observed_at oznacza czas wykrycia, a occurred_at może być null, gdy źródło nie publikuje czasu zdarzenia. ## Current runtime boundary The current serving path resolves q, id or point and reads that parcel/gmina history. V2 area and parcel_ids query selectors are declared by the contract but are not applied by this dispatcher; do not rely on them to narrow or expand a read. Typed EventV2 fixtures demonstrate the future schema, not an active producer guarantee. ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng` | `since` | `types` | `limit` | `cursor` | `area` | `parcel_ids`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | | `since` | query | false | `{"anyOf": [{"format": "date", "type": "string"}, {"format": "date-time", "type": "string"}]}` | not specified in the source contract | | `types` | query | false | `{"type": "string"}` | Nazwy EventTypeV2 oddzielone przecinkami; tryb v1 przyjmuje także dotychczasowe nazwy zdarzeń. | | `limit` | query | false | `{"default": 100, "maximum": 1000, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `cursor` | query | false | `{"type": "string"}` | not specified in the source contract | | `area` | query | false | `{}` | Zastępuje q\|id\|point; obszar EventsRequestV2 w v2. | | `parcel_ids` | query | false | `{"description": "Mała lista działek w GET zdarzeń; większe listy korzystają z POST /v1/events/query (do 10 000 identyfikatorów).", "items": {"$ref": "#/$defs/ParcelId"}, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true}` | Do 100 różnych identyfikatorów działek; większe listy przekaż przez POST /v1/events/query. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to tablica Event; pole page jest wypełnione. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to tablica Event; pole page jest wypełnione.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/events" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-events.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "events", "request_id": "fixture" }, "plan": "free", "query": { "input": { "parcel_ids": [ "146501_1.0101.12/3" ] }, "kind": "events", "resolved": null }, "result": [ { "as_of": "2026-10-01", "data": { "permit_id": "permit_fixture", "status": "issued" }, "id": "event_fixture", "observed_at": "2026-10-16T12:00:00Z", "occurred_at": "2026-10-16T12:00:00Z", "parcel_ids": [ "146501_1.0101.12/3" ], "source": { "as_of": "2026-10-01", "attribution": "Działkopedia, obliczenie własne", "id": "parcel_events", "title": "parcel_events" }, "type": "gunb_permit" } ], "sources": [], "status": "ok" } ``` ## Matching MCP tool [events](../tools/events.md) # POST /v1/events/query Pobierz zdarzenia określonych typów, przekazując w treści żądania do 10 000 identyfikatorów działek albo obszar. Operation ID: `events_query`. ## Description Zastępuje parametry GET dla dużych list i wielokątów. Te same zdarzenia, kursory i koszt odczytu jednego kredytu; operacja nie tworzy subskrypcji. ## Current runtime boundary Contract-defined and registered, but POST body selectors are not consumed by this revision's dispatcher: a schema-valid parcel_ids body receives HTTP 400 invalid_input. Do not use this operation yet. Use GET /v1/events with q, id or point. Runtime discovery alone does not prove this request shape executes. ## Cost `x-request-cost`: 1 request per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Request body ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json#/$defs/EventsRequestV2" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to tablica Event; pole page jest wypełnione. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "items": { "$ref": "#/components/schemas/Event" }, "type": "array" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to tablica Event; pole page jest wypełnione.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/events/query" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"parcel_ids": ["146501_1.0101.12/3"]}' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-events.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "events", "request_id": "fixture" }, "plan": "free", "query": { "input": { "parcel_ids": [ "146501_1.0101.12/3" ] }, "kind": "events", "resolved": null }, "result": [ { "as_of": "2026-10-01", "data": { "permit_id": "permit_fixture", "status": "issued" }, "id": "event_fixture", "observed_at": "2026-10-16T12:00:00Z", "occurred_at": "2026-10-16T12:00:00Z", "parcel_ids": [ "146501_1.0101.12/3" ], "source": { "as_of": "2026-10-01", "attribution": "Działkopedia, obliczenie własne", "id": "parcel_events", "title": "parcel_events" }, "type": "gunb_permit" } ], "sources": [], "status": "ok" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/gminy/{teryt}/planning Stan planowania w gminie: plan ogólny, zakres MPZP i zasady wydawania WZ w dniu zapytania. Operation ID: `gmina_planning`. ## Description not specified in the source contract ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `teryt`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `teryt` | path | true | `{"pattern": "^[0-9]{7}$", "type": "string"}` | Siedmioznakowy kod gminy administracyjnej z ostatnią cyfrą 1, 2 lub 3 (np. 1465011 Warszawa, 1418032 Lesznowola), będący kluczem gmina_planning. Kod jednostki z identyfikatora działki z ostatnią cyfrą 4, 5, 8 lub 9 jest przypisywany do gminy administracyjnej tak jak parcel_record.admin_gmina_teryt (nagłówek parcel_record.sql), co opisuje query.resolved.note. Dla nazwy, działki albo punktu użyj /v1/gminy/planning. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to GminaPlanning. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GminaPlanning" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to GminaPlanning.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/gminy/1418032/planning" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/gminy/planning Jak /v1/gminy/{teryt}/planning, z gminą rozpoznaną na podstawie q (nazwa gminy lub tekst opisujący działkę), id albo point. Operation ID: `gmina_planning_lookup`. ## Description not specified in the source contract ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to GminaPlanning. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GminaPlanning" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to GminaPlanning.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/gminy/planning" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/layer/{layer} Jedna odpowiedź tematyczna dla jednej działki. Operation ID: `layer`. ## Description not specified in the source contract ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `layer` | `q` | `id` | `point` | `lat` | `lng`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `layer` | path | true | `{"description": "planning zwraca w jednym żądaniu informacje planistyczne: plan ogólny, MPZP, WZ i stan planowania w gminie.", "enum": ["parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil"], "type": "string"}` | not specified in the source contract | | `If-None-Match` | header | false | `{"type": "string"}` | ETag z wcześniejszego GET według id. Dopasowanie zwraca bezpłatne HTTP 304. | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to jedna odpowiedź LayerAnswer i identyfikator działki. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 304 | If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified). | free_not_modified | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "properties": { "answer": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "id": { "type": "string" } }, "required": [ "id", "answer" ], "type": "object" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to jedna odpowiedź LayerAnswer i identyfikator działki.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 304: headers and body schemas ```json { "description": "If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-layer.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "layer", "request_id": "fixture" }, "plan": "free", "query": { "input": { "id": "146501_1.0101.12/3" }, "kind": "id", "resolved": null }, "result": { "answer": { "as_of": "2026-10-01", "coverage": "covered_no_data", "layer": "flood", "layer_version": "flood-national-20261016", "licence": { "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "position": "cc_by_4_0", "review_ref": "seed/attribution_review_2026-10-13.sql#mzp_flood", "terms_url": "https://creativecommons.org/licenses/by/4.0/" }, "method": "official", "note": "Według map zagrożenia powodziowego działka leży poza wskazanymi na nich obszarami zagrożenia w sprawdzonym zakresie. Nie wyklucza to powodzi.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": { "q10": false, "q100": false, "q500": false } }, "id": "146501_1.0101.12/3" }, "sources": [], "status": "ok" } ``` ## Matching MCP tool [layer](../tools/layer.md) # GET /v1/openapi.json Ta specyfikacja w postaci udostępnianej przez usługę. Operation ID: `openapi`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Authentication ```json [] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Dokument OpenAPI 3.1. | free_operation | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": {} }, "description": "Dokument OpenAPI 3.1." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 200. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/openapi.json" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` Response: the bundled OpenAPI document, available as [openapi.json](../openapi.json). ## Matching MCP tool not specified in the source contract # GET /v1/parcel Pełna karta jednej działki z danymi źródłowymi. Operation ID: `parcel`. ## Description Karta za 1 kredyt obejmuje display_geometry, display_simplified=true i adjacent_parcel_ids (do 50 aktywnych wczytanych działek ze wspólnym odcinkiem granicy). adjacent_parcel_ids_truncated wskazuje dalszych sąsiadów. Granica jest upraszczana do 0,5 m w EPSG:2180 i zwracana w EPSG:4326. geometry=full pozostaje osobnym płatnym odczytem dokładnej geometrii do eksportu. ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng` | `layers` | `geometry`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | | `layers` | query | false | `{"type": "string"}` | Lista LayerKey oddzielona przecinkami; domyślnie wszystkie kategorie v1. | | `geometry` | query | false | `{"default": "centroid", "enum": ["none", "centroid", "full"], "type": "string"}` | not specified in the source contract | | `If-None-Match` | header | false | `{"type": "string"}` | ETag z wcześniejszego GET według id. Dopasowanie zwraca bezpłatne HTTP 304. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to ParcelRecord (null przy ambiguous lub not_covered). | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 304 | If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified). | free_not_modified | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ParcelRecord", "required": [ "display_geometry", "display_simplified", "adjacent_parcel_ids", "adjacent_parcel_ids_truncated" ] } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to ParcelRecord (null przy ambiguous lub not_covered).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 304: headers and body schemas ```json { "description": "If-None-Match odpowiada faktycznemu bieżącemu ETag. Sama gwiazdka jest pomijana i zwraca zwykle płatną reprezentację. Faktyczna zgodność oznacza brak treści i brak opłaty (reguła free_not_modified).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/parcel" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-parcel.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 1, "cost": 1, "credits": 1, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "parcel", "request_id": "fixture" }, "plan": "free", "query": { "input": { "id": "146501_1.0101.12/3" }, "kind": "id", "resolved": null }, "result": { "adjacent_parcel_ids": [ "146501_1.0101.12/4" ], "adjacent_parcel_ids_truncated": false, "admin": { "gmina_name": "Warszawa", "gmina_teryt": "1465011", "number": "12/3", "obreb_id": "146501_1.0101", "voivodeship": "14" }, "area": { "geometry_m2": 500, "note": "Powierzchnię obliczono z geometrii działki; powierzchnia urzędowa EGiB jest niedostępna.", "official_m2": null, "provenance": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, "source": "computed" }, "display_geometry": { "coordinates": [ [ [ [ 21.0, 52.0 ], [ 21.001, 52.0 ], [ 21.001, 52.001 ], [ 21.0, 52.001 ], [ 21.0, 52.0 ] ] ] ], "type": "MultiPolygon" }, "display_simplified": true, "id": "146501_1.0101.12/3", "layers": { "flood": { "as_of": "2026-10-01", "coverage": "covered_no_data", "layer": "flood", "layer_version": "flood-national-20261016", "licence": { "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "position": "cc_by_4_0", "review_ref": "seed/attribution_review_2026-10-13.sql#mzp_flood", "terms_url": "https://creativecommons.org/licenses/by/4.0/" }, "method": "official", "note": "Według map zagrożenia powodziowego działka leży poza wskazanymi na nich obszarami zagrożenia w sprawdzonym zakresie. Nie wyklucza to powodzi.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": { "q10": false, "q100": false, "q500": false } } }, "record_hash": null }, "sources": [], "status": "ok" } ``` ## Matching MCP tool [parcel](../tools/parcel.md) # POST /v1/parcel/batch Do 1 000 działek w jednym żądaniu; każdy element to q, id albo point. Operation ID: `parcel_batch`. ## Description not specified in the source contract ## Cost `x-request-cost`: 1 request per item. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Request body ```json { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "geometry": { "default": "centroid", "enum": [ "none", "centroid", "full" ], "type": "string" }, "items": { "items": { "$ref": "./envelope.json#/$defs/QueryInput" }, "maxItems": 1000, "minItems": 1, "type": "array" }, "layers": { "items": { "$ref": "./envelope.json#/$defs/LayerKey" }, "type": "array" } }, "required": [ "items" ], "type": "object" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | result to tablica odpowiedzi dla poszczególnych elementów, każda z własnym statusem i kandydatami. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "result to tablica odpowiedzi dla poszczególnych elementów, każda z własnym statusem i kandydatami." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/parcel/batch" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"items": [{"id": "141803_2.0001.12/3"}]}' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/places Bezpłatne podpowiedzi nazw polskich gmin, powiatów, obrębów i miejscowości na podstawie początku nazwy. Operation ID: `places`. ## Description Podpowiedzi ignorują wielkość liter i znaki diakrytyczne, w tym ł/l. Zakres danych wskazuje działki dostępne do wyszukiwania, a nie kompletność rejestru. Miejscowości bez SIMC mają teryt=null. Maksymalnie 20 wyników; kolejność jest stała i uwzględnia dokładną nazwę, długość pozostałego fragmentu, typ, nazwę oraz identyfikator. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `q` | `limit`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | true | `{"maxLength": 100, "minLength": 2, "type": "string"}` | not specified in the source contract | | `limit` | query | false | `{"default": 10, "maximum": 20, "minimum": 1, "type": "integer"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź zawiera PlacesResult; koszt wynosi 0 kredytów. | free_operation | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 503 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_server_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "$ref": "./envelope.json#/$defs/PlacesResult" } } } ] } } }, "description": "Odpowiedź zawiera PlacesResult; koszt wynosi 0 kredytów." } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 503: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/places" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'q=War' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "War" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/resolve Rozpoznaj kandydatów na działkę na podstawie tekstu użytkownika, identyfikatora albo punktu. Operation ID: `resolve`. ## Description Zawsze zwracane są candidates (także z jednym kandydatem) i corpus_coverage. Status ok oznacza dokładnie jednego pewnego kandydata: pewność co najmniej 0,85 i przewaga co najmniej 0,15 nad kolejnym. W przeciwnym razie zwracany jest status ambiguous, a needs_obreb=true wskazuje numer występujący w kilku obrębach gminy. Nazwy miejscowości i gmin są dopasowywane w przybliżeniu, z uwzględnieniem diakrytyków i jednej lub dwóch literówek, np. „Lesnowola” znajduje Lesznowolę. Pewność jest wtedy obniżana, a założenie opisują query.resolved.note i match_reason. Identyfikatory są przyjmowane z ukośnikiem lub łącznikiem. Kandydat ze zbioru, którego jeszcze nie załadowano, ma held=false; informuje o tym także corpus_coverage. ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng` | `limit` | `listing_url`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | | `limit` | query | false | `{"default": 5, "maximum": 20, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `listing_url` | query | false | `{"format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string"}` | Zastępuje q\|id\|point. Wymaga LANDFEED_LISTING_LOOKUP_ENABLED (domyślnie false). Odpowiedź zawiera status ambiguous i wyłącznie candidates[], także przy jednym kandydacie. Bez treści, zdjęć i cen z ogłoszenia. Pusta lista oznacza not_found i zwrot opłaty. | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to najlepszy kandydat albo null; candidates jest zawsze obecne. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "$ref": "./envelope.json#/$defs/Candidate" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to najlepszy kandydat albo null; candidates jest zawsze obecne.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/resolve" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool [resolve](../tools/resolve.md) # GET /v1/search Działki według adresu lub tekstu (q), w pobliżu działki (id) albo punktu lub w obszarze bbox. Operation ID: `search`. ## Description q: adres z PRG („Marcinowice 221”, „Warszawa, Puławska 1”) albo tekst opisujący działkę; zwraca działki pod danym adresem. id lub point: działki w odległości radius_m (0 oznacza wskazaną działkę i sąsiadów ze wspólną granicą). bbox: działki przecinające obszar do 4 km². Wyszukiwanie według wielokąta odbywa się przez POST /v1/search z wielokątem GeoJSON do 4 km². ## Cost `x-request-cost`: 1 request per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng` | `teryt` | `area_min_m2` | `area_max_m2` | `land_use_class` | `shape_regularity_min` | `frontage_min_m` | `road_access` | `buildings_present` | `public_road_max_m` | `rcn_price_min_pln_m2` | `rcn_price_max_pln_m2` | `gunb_activity_min` | `pog_zone_class` | `bbox` | `radius_m` | `limit` | `cursor`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | | `teryt` | query | false | `{"pattern": "^(?:[0-9]{4}\|[0-9]{6}[123])$", "type": "string"}` | Administracyjny kod powiatu (4 cyfry) lub gminy (7 cyfr); zastępuje parcel/point/bbox. | | `area_min_m2` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `area_max_m2` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `land_use_class` | query | false | `{"enum": ["R", "Ł", "Ps", "Br", "B", "Ba", "Bi", "Bp", "Bz", "K", "Ls", "Lz", "Lzr", "N", "Wp", "Ws", "Wsr", "W", "dr", "Tk", "Ti", "Tr", "E"], "type": "string"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `shape_regularity_min` | query | false | `{"maximum": 1, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `frontage_min_m` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `road_access` | query | false | `{"type": "boolean"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `buildings_present` | query | false | `{"type": "boolean"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `public_road_max_m` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `rcn_price_min_pln_m2` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `rcn_price_max_pln_m2` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `gunb_activity_min` | query | false | `{"maximum": 1000000000000.0, "minimum": 0, "type": "integer"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `pog_zone_class` | query | false | `{"enum": ["SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP"], "type": "string"}` | Nieznane wartości są wykluczane i liczone w search_facets. Filtr obejmuje wartość graniczną. | | `bbox` | query | false | `{"type": "string"}` | min_lon,min_lat,max_lon,max_lat w układzie WGS84. Zastępuje q\|id\|point. | | `radius_m` | query | false | `{"default": 0, "maximum": 2000, "minimum": 0, "type": "integer"}` | not specified in the source contract | | `limit` | query | false | `{"default": 100, "maximum": 1000, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `cursor` | query | false | `{"type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to tablica ParcelSummary; pole page jest wypełnione. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | | 404 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | refunded_client_error | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "items": { "$ref": "#/components/schemas/ParcelSummary" }, "type": "array" }, { "$ref": "./envelope.json#/$defs/SearchResultV2" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to tablica ParcelSummary; pole page jest wypełnione.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 404: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/search" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-search.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 2, "cost": 2, "credits": 2, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "search", "request_id": "fixture" }, "plan": "free", "query": { "input": { "area": { "kind": "gmina", "teryt": "1465011" }, "cursor": null, "filters": { "area_m2": { "max": 1000, "min": 100 }, "building_present": false, "no_nature_protection": true, "outside_flood_q100": true, "plan_general_zones": [ "SJ", "SW" ], "public_road_access": true }, "format": "csv", "limit": 100 }, "kind": "search", "resolved": null }, "result": { "export": { "format": "csv", "link": { "cost": 1, "expires_at": "2026-10-16T13:00:00Z", "href": "https://api.landfeed.pl/sheets/a?signature=fixture-signature" }, "rows": 101 }, "items": [ { "area_official_m2": 500, "centroid": [ 21, 52 ], "filter_evidence": { "area_m2": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, "value": 500 }, "building_present": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_buildings", "title": "egib_buildings" }, "value": false }, "no_nature_protection": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Generalna Dyrekcja Ochrony Środowiska (GDOŚ), Centralny Rejestr Form Ochrony Przyrody", "id": "gdos_protected", "title": "gdos_protected" }, "value": true }, "outside_flood_q100": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": true }, "plan_general_zones": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia", "id": "pog_sweep", "title": "pog_sweep" }, "value": "SJ" }, "public_road_access": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "id": "bdot_roads", "title": "bdot_roads" }, "value": true } }, "flags": { "building_present": false, "no_nature_protection": true, "outside_flood_q100": true, "plan_general_zone_match": true, "public_road_access": true }, "gmina_name": "Warszawa", "gmina_teryt": "1465011", "id": "146501_1.0101.12/3", "number": "12/3", "obreb_name": "0101" } ], "page": { "has_more": false, "limit": 100, "next_cursor": null } }, "sources": [ { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, { "as_of": "2026-10-01", "attribution": "Źródło: Generalna Dyrekcja Ochrony Środowiska (GDOŚ), Centralny Rejestr Form Ochrony Przyrody", "id": "gdos_protected", "title": "gdos_protected" }, { "as_of": "2026-10-01", "attribution": "Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia", "id": "pog_sweep", "title": "pog_sweep" }, { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "id": "bdot_roads", "title": "bdot_roads" }, { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_buildings", "title": "egib_buildings" } ], "status": "ok" } ``` ## Matching MCP tool [search](../tools/search.md) # POST /v1/search Wyszukaj w powiecie, gminie lub obszarze Polygon z filtrami o określonych typach i stronicowaniem kursorem; dotychczasowe zapytania wielokątowe pozostają poprawne. Operation ID: `search_polygon`. ## Description Wyszukiwanie wielokątem obsługuje płaskie filtry cech w obiekcie filters. GET przyjmuje te same filtry oraz administracyjny teryt. Nieznany wynik nigdy nie spełnia filtra; jest liczony w search_facets przed stronicowaniem. Format SearchRequestV2 i eksport pozostają niedostępne; opłata za eksport nie jest naliczana. ## Current runtime boundary Polygon search accepts polygon, limit, cursor and 12 flat feature predicates in filters. GET search accepts the same flat predicates and administrative teryt. search_facets counts matches, known exclusions and unknown exclusions across the full scope before pagination. Typed SearchRequestV2 area/filters and CSV/GeoJSON exports are rejected before source work. ## Cost `x-request-cost`: 1 request per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters No parameters declared. ## Request body ```json { "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "cursor": { "type": [ "string", "null" ] }, "filters": { "$ref": "./envelope.json#/$defs/FeatureSearchFilters" }, "limit": { "default": 100, "maximum": 1000, "minimum": 1, "type": "integer" }, "polygon": { "WGS84": null, "description": "Obiekt GeoJSON typu Polygon lub MultiPolygon.", "type": "object" } }, "required": [ "polygon" ], "type": "object" } ] } } }, "required": true } ``` ## Operation credit rule page: 1; export: ceil(rows/100), replaces page cost; max 2000 results; no charge for refused/unavailable answers ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to tablica ParcelSummary; pole page jest wypełnione. | See billing.rule and the verbatim Billing policy below (answers, coverage, ambiguity, and batch). | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "oneOf": [ { "type": "null" }, { "items": { "$ref": "#/components/schemas/ParcelSummary" }, "type": "array" }, { "$ref": "./envelope.json#/$defs/SearchResultV2" } ] } } } ] } } }, "description": "Odpowiedź Envelope; result to tablica ParcelSummary; pole page jest wypełnione.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/search" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"polygon": {"type": "Polygon", "coordinates": [[[20.92, 52.07], [20.93, 52.07], [20.93, 52.08], [20.92, 52.07]]]}}' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "q": "[nieprawidłowe dane]" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ### Successful contract fixture Recorded contract output, not a live service observation. Provenance: `landfeed/contracts/fixtures/v2/valid/envelope-search.json`. The parcel and dates belong to this fixture. Dormant operations remain unavailable. ```json { "auth": { "kind": "api_key" }, "billing": { "charged": 2, "cost": 2, "credits": 2, "refunded": 0, "rule": "charged" }, "candidates": [], "error": null, "meta": { "api_version": "v1", "calls": 1, "contract_version": "2.0.0", "generated_at": "2026-10-16T12:00:00Z", "operation": "search", "request_id": "fixture" }, "plan": "free", "query": { "input": { "area": { "kind": "gmina", "teryt": "1465011" }, "cursor": null, "filters": { "area_m2": { "max": 1000, "min": 100 }, "building_present": false, "no_nature_protection": true, "outside_flood_q100": true, "plan_general_zones": [ "SJ", "SW" ], "public_road_access": true }, "format": "csv", "limit": 100 }, "kind": "search", "resolved": null }, "result": { "export": { "format": "csv", "link": { "cost": 1, "expires_at": "2026-10-16T13:00:00Z", "href": "https://api.landfeed.pl/sheets/a?signature=fixture-signature" }, "rows": 101 }, "items": [ { "area_official_m2": 500, "centroid": [ 21, 52 ], "filter_evidence": { "area_m2": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, "value": 500 }, "building_present": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_buildings", "title": "egib_buildings" }, "value": false }, "no_nature_protection": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Generalna Dyrekcja Ochrony Środowiska (GDOŚ), Centralny Rejestr Form Ochrony Przyrody", "id": "gdos_protected", "title": "gdos_protected" }, "value": true }, "outside_flood_q100": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, "value": true }, "plan_general_zones": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia", "id": "pog_sweep", "title": "pog_sweep" }, "value": "SJ" }, "public_road_access": { "as_of": "2026-10-01", "coverage": "covered", "note": "Syntetyczne dane w zakresie tego filtra; przykład nie opisuje stanu rzeczywistej działki.", "scope": "parcel_polygon", "source": { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "id": "bdot_roads", "title": "bdot_roads" }, "value": true } }, "flags": { "building_present": false, "no_nature_protection": true, "outside_flood_q100": true, "plan_general_zone_match": true, "public_road_access": true }, "gmina_name": "Warszawa", "gmina_teryt": "1465011", "id": "146501_1.0101.12/3", "number": "12/3", "obreb_name": "0101" } ], "page": { "has_more": false, "limit": 100, "next_cursor": null } }, "sources": [ { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_parcels", "title": "egib_parcels" }, { "as_of": "2026-10-01", "attribution": "Źródło: Państwowe Gospodarstwo Wodne Wody Polskie, mapy zagrożenia powodziowego (ISOK), licencja CC BY 4.0", "id": "mzp_flood", "title": "mzp_flood" }, { "as_of": "2026-10-01", "attribution": "Źródło: Generalna Dyrekcja Ochrony Środowiska (GDOŚ), Centralny Rejestr Form Ochrony Przyrody", "id": "gdos_protected", "title": "gdos_protected" }, { "as_of": "2026-10-01", "attribution": "Źródło: uchwały rad gmin w sprawie planu ogólnego, wojewódzkie dzienniki urzędowe; zestawienie: Działkopedia", "id": "pog_sweep", "title": "pog_sweep" }, { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), BDOT10k", "id": "bdot_roads", "title": "bdot_roads" }, { "as_of": "2026-10-01", "attribution": "Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Ewidencja Gruntów i Budynków (EGiB)", "id": "egib_buildings", "title": "egib_buildings" } ], "status": "ok" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/sources Wszystkie źródła udostępniane przez API, z licencją, wskazaniem pochodzenia, as_of, aktualnością i zakresem danych. Operation ID: `sources`. ## Description Bez wskazania działki katalog i zakres danych na poziomie gminy są bezpłatne. Parametr q, id, point, lat lub lng podlega tym samym zasadom rezerwacji jednego kredytu, rozliczenia i zwrotu co GET /v1/resolve. Konto bez kredytów jest odrzucane przed rozpoznawaniem i ustalaniem zakresu danych w czasie żądania. ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `q` | `id` | `point` | `lat` | `lng` | `layer`. Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `q` | query | false | `{"maxLength": 300, "minLength": 1, "type": "string"}` | Tekst wpisany przez użytkownika (działka, adres, gmina). Dokładnie jeden parametr: q, id albo point. | | `id` | query | false | `{"description": "Identyfikator EGiB id_dzialki w postaci przyjmowanej od wywołującego. Wzorzec apps/web/src/lib/schemas/validation.ts sprawdzono na zbiorze danych: przyjmuje 38 339 611 z 38 339 612 rekordów parcel_inventory; pominięty rekord ma pusty numer. Zapis \\\\p{L}\\\\p{N} zastąpiono literami łacińskimi z diakrytykami i cyframi, aby wzorzec działał w ECMA-262, Python re i PostgreSQL. Postać: sześciocyfrowy prefiks TERYT, następnie „_” lub „.” (np. „020207.5.0004.345” w przychodzących odnośnikach), cyfra jednostki, obręb złożony z 1-4 cyfr i numer zawierający do 64 liter, cyfr, znaków „_”, „.”, „/”, „-” i spacji. Arkusze AR_, np. „247701_1.0003.AR_4.734/113” i „240702_2.0001.AR_10BORONÓW LAS.310/121”, są poprawnymi identyfikatorami. Dopuszczalne są spacje na początku i końcu wklejonego identyfikatora. landfeed.normalize_parcel_id() zamienia każdą przyjmowaną postać na ParcelId: usuwa skrajne spacje, zamienia „.” po prefiksie na „_” oraz „-” w ostatnim członie na „/” („146501_1.0101.12-3” na „146501_1.0101.12/3”). API zwraca wyłącznie identyfikatory w ujednoliconej postaci. Przykłady: fixtures/real_ids.txt, fixtures/id_forms.jsonl.", "maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | EGiB id_dzialki z ukośnikiem, łącznikiem lub kropką jako separatorem, np. 146501_1.0101.12/3, 146501_1.0101.12-3, 247701_1.0003.AR_4.734/113. landfeed.normalize_parcel_id normalizuje zapis; odpowiedzi zawierają ujednoliconą postać z ukośnikiem. Dokładnie jeden parametr: q, id albo point. | | `point` | query | false | `{"type": "string"}` | WGS84 lat,lng, np. 52.2297,21.0122. Dokładnie jeden parametr q, id albo point lub para lat i lng. | | `lat` | query | false | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | Szerokość geograficzna WGS84; wraz z lng odpowiada point. | | `lng` | query | false | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | Długość geograficzna WGS84; wraz z lat odpowiada point. | | `layer` | query | false | `{"description": "planning zwraca w jednym żądaniu informacje planistyczne: plan ogólny, MPZP, WZ i stan planowania w gminie.", "enum": ["parcel", "admin", "address", "buildings", "planning", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil"], "type": "string"}` | not specified in the source contract | ## Operation credit rule No parcel input: free; any parcel input: meter as resolve. ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Odpowiedź Envelope; result to tablica Source. | free_operation | | 400 | Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}. | free_invalid_input | | 401 | Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401. | free_unauthorized | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "result": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array" } } } ] } } }, "description": "Odpowiedź Envelope; result to tablica Source.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 400: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Bezpłatne HTTP 400. Odpowiedź Envelope ze statusem error, error.code=invalid_input, error.hint, error.example_id i billing {charged 0, rule free_invalid_input}.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ### HTTP 401: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "./envelope.json" } } }, "description": "Odpowiedź Envelope ze statusem not_found lub error, result=null i wypełnionym error (hint, docs, example_id przy danych wejściowych dotyczących działki; signup_url przy HTTP 401). Zwrot opłaty albo bezpłatne przy HTTP 401.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControl" }, "ETag": { "$ref": "#/components/headers/ETag" }, "X-Credits-Charged": { "$ref": "#/components/headers/XCreditsCharged" }, "X-Credits-Refunded": { "$ref": "#/components/headers/XCreditsRefunded" }, "X-Request-Cost": { "$ref": "#/components/headers/XRequestCost" } } } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/sources" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` ```json { "billing": { "charged": 0, "cost": 1, "refunded": 0, "rule": "free_unauthorized" }, "candidates": [], "error": { "code": "unauthorized", "docs": "https://landfeed.pl/docs", "example_id": "141803_2.0001.12/3", "hint": "Podaj wydany klucz w nagłówku Authorization: Bearer lub X-Api-Key albo połącz się z MCP przez OAuth.", "message": "Wymagany jest ważny klucz API lub token dostępu. Podaj go i ponów żądanie.", "signup_url": "https://landfeed.pl/signup" }, "meta": { "api_version": "v1", "calls": 1, "generated_at": "2026-10-21T00:00:00Z", "request_id": "00000000-0000-4000-8000-000000000000" }, "needs_obreb": false, "query": { "input": { "id": "141803_2.0001.12/3" }, "resolved": null }, "result": null, "sources": [], "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/watches/{watch_id}/attempts Dziennik wysyłek tego konta, bez adresów URL i treści odpowiedzi. Operation ID: `watch_attempts`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id` | `after` | `limit`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | | `after` | query | false | `{"minimum": 0, "type": "integer"}` | not specified in the source contract | | `limit` | query | false | `{"default": 100, "maximum": 100, "minimum": 1, "type": "integer"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001/attempts" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/watches Utwórz obserwację przyszłych zdarzeń przypisaną do konta. Operation ID: `watch_create`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Path/query inputs: none declared. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | false | `{"maxLength": 200, "minLength": 1, "type": "string"}` | To samo konto, klucz i elementy zwracają tę samą obserwację przez 24 godziny; inne elementy zwracają 409. Usunięta obserwacja nie jest tworzona ponownie. | ## Request body ```json { "content": { "application/json": { "example": { "items": [ { "parcel_id": "146501_1.0101.12/3", "types": [ "mpzp.changed", "flood.changed" ] } ] }, "schema": { "$ref": "#/components/schemas/WatchWrite" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/watches" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Idempotency-Key: docs-example-001' \ -H 'Content-Type: application/json' \ --data '{"items": [{"parcel_id": "146501_1.0101.12/3", "types": ["mpzp.changed", "flood.changed"]}]}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/watches/{watch_id} Usuń obserwację tego konta i anuluj oczekujące wysyłki. Operation ID: `watch_delete`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/watches/{watch_id} Odczytaj obserwację tego konta. Operation ID: `watch_get`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # GET /v1/watches Lista obserwowanych wyników tego konta. Operation ID: `watch_list`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `after` | `limit`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `after` | query | false | `{"format": "uuid", "type": "string"}` | not specified in the source contract | | `limit` | query | false | `{"default": 100, "maximum": 100, "minimum": 1, "type": "integer"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/watches" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # POST /v1/watches/{watch_id}/webhook/rotate Zmień sekret konta do podpisywania i ujawnij go jednokrotnie. Oczekujące wysyłki korzystają z nowego klucza. Operation ID: `watch_secret_rotate`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request POST "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001/webhook/rotate" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # PUT /v1/watches/{watch_id} Zastąp elementy obserwacji tego konta; powiadomienia w kolejce zachowują pierwotny zestaw dopasowań. Operation ID: `watch_update`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "example": { "items": [ { "parcel_id": "146501_1.0101.12/3", "types": [ "mpzp.changed", "flood.changed" ] } ] }, "schema": { "$ref": "#/components/schemas/WatchWrite" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request PUT "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"items": [{"parcel_id": "146501_1.0101.12/3", "types": ["mpzp.changed", "flood.changed"]}]}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # PUT /v1/watches/{watch_id}/webhook Zarejestruj lub zastąp webhook HTTPS; operacja jednorazowo zwraca nowy sekret do podpisywania i anuluje poprzednią kolejkę. Operation ID: `watch_webhook_configure`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Request body ```json { "content": { "application/json": { "example": { "enabled": true, "url": "https://example.org/landfeed-hook" }, "schema": { "$ref": "#/components/schemas/WatchWebhookWrite" } } }, "required": true } ``` ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request PUT "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001/webhook" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ -H 'Content-Type: application/json' \ --data '{"url": "https://example.org/landfeed-hook", "enabled": true}' ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # DELETE /v1/watches/{watch_id}/webhook Usuń webhook i anuluj jego oczekujące wysyłki. Operation ID: `watch_webhook_remove`. ## Description not specified in the source contract ## Cost `x-request-cost`: 0 requests per call. ## Inputs Declared path/query inputs: `watch_id`. `q | id | point | lat+lng` at operation level: not specified in the source contract. See declared parameters and request body. ## Parameters | Name | In | Required | Schema | Description | | --- | --- | --- | --- | --- | | `watch_id` | path | true | `{"format": "uuid", "type": "string"}` | not specified in the source contract | ## Authentication ```json [ { "ApiKey": [] }, { "OAuthConnector": [] } ] ``` ```json { "ApiKey": { "description": "Klucz API konta korzystający z tych samych kredytów co wywołania przez połączenie OAuth.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "OAuthConnector": { "bearerFormat": "OAuth 2.1 access token", "description": "Autoryzacja połączenia OAuth ze wspólnymi kredytami konta. Wykrywanie konfiguracji i zgodę obsługuje usługa uwierzytelniania.", "scheme": "bearer", "type": "http" } } ``` ## Responses | Status | Description | Billing rule | | --- | --- | --- | | 200 | Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi. | free_watch | | 400 | Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne. | free_watch | | 401 | Wymagany poprawny klucz API konta; bezpłatne. | free_watch | | 403 | Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne. | free_watch | | 404 | Brak obserwacji należącej do tego konta; bezpłatne. | free_watch | | 409 | Osiągnięto limit obserwowanych elementów; bezpłatne. | free_watch | | 413 | Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne. | free_watch | | 429 | Limit 30 operacji zarządzania na konto na minutę; bezpłatne. | free_watch | | 503 | Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne. | free_watch | ### HTTP 200: headers and body schemas ```json { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Wynik ograniczony do konta. Sekrety utworzone lub zmienione w tej operacji są ujawniane wyłącznie w jej odpowiedzi." } ``` ### HTTP 400: headers and body schemas ```json { "description": "Błędne dane wejściowe lub event_type_has_no_producer; bezpłatne." } ``` ### HTTP 401: headers and body schemas ```json { "description": "Wymagany poprawny klucz API konta; bezpłatne." } ``` ### HTTP 403: headers and body schemas ```json { "description": "Statyczne dane uwierzytelniające lub nieaktywne konto; bezpłatne." } ``` ### HTTP 404: headers and body schemas ```json { "description": "Brak obserwacji należącej do tego konta; bezpłatne." } ``` ### HTTP 409: headers and body schemas ```json { "description": "Osiągnięto limit obserwowanych elementów; bezpłatne." } ``` ### HTTP 413: headers and body schemas ```json { "description": "Treść przekracza 256 KiB lub łączny limit pracy walidatora; bezpłatne." } ``` ### HTTP 429: headers and body schemas ```json { "description": "Limit 30 operacji zarządzania na konto na minutę; bezpłatne." } ``` ### HTTP 503: headers and body schemas ```json { "description": "Magazyn obserwacji lub rozpoznawanie adresu odbiorcy są niedostępne; bezpłatne." } ``` ## Layer answers and value schemas When a response includes layer answers, their common frame is: ```json { "additionalProperties": false, "allOf": [ { "else": { "properties": { "value": { "type": "object" } } }, "if": { "properties": { "coverage": { "enum": [ "not_covered", "not_computed" ] } } }, "then": { "properties": { "value": { "type": "null" } } } }, { "if": { "properties": { "coverage": { "enum": [ "covered", "covered_no_data" ] }, "layer": { "const": "mpzp" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/MpzpValue" } } } } ], "description": "Wspólny format każdej odpowiedzi tematycznej. Pola właściwe dla danej kategorii znajdują się w value (schematy *Value w openapi.yaml).", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "basis": { "description": "Przepis lub reguła będąca podstawą wyliczonej odpowiedzi, np. „u.p.z.p. art. 59 ust. 3”.", "type": [ "string", "null" ] }, "confidence": { "maximum": 1, "minimum": 0, "type": "number" }, "coverage": { "$ref": "#/$defs/Coverage" }, "hash": { "description": "Skrót sha256 w zapisie szesnastkowym z coverage + ':' + canonical(value) (nagłówek parcel_record.sql). Wartość null dla danych ustalanych podczas żądania.", "type": [ "string", "null" ] }, "layer": { "$ref": "#/$defs/LayerKey" }, "layer_version": { "description": "Identyfikator obliczenia dla wcześniej obliczonych danych; live dla danych ustalanych podczas żądania.", "type": "string" }, "licence": { "$ref": "#/$defs/Licence" }, "method": { "$ref": "#/$defs/Method" }, "note": { "description": "Jedno zdanie prostym językiem do przytoczenia przez agenta w każdym stanie: co oznacza wartość lub dlaczego jej brakuje. Bez określenia „bezpieczna” i bez „brak planu”, jeżeli nie wskazano rodzaju planu i źródła.", "minLength": 1, "type": "string" }, "scope": { "$ref": "#/$defs/Scope" }, "source": { "$ref": "#/$defs/SourceRef" }, "threshold": { "maximum": 1, "minimum": 0, "type": "number" }, "value": { "description": "Wartość null wtedy i tylko wtedy, gdy coverage wynosi not_covered lub not_computed.", "type": [ "object", "null" ] } }, "required": [ "layer", "coverage", "value", "note", "source", "as_of", "layer_version" ], "type": "object" } ``` Schema names correspond to the layer keys below. A schema dispatch constraint in `LayerAnswer` is not specified in v1. | Layer key | LayerAnswer.value schema | | --- | --- | | `address` | [AddressValue](../layers/AddressValue.md) | | `admin` | not specified in the source contract | | `buildings` | [BuildingsValue](../layers/BuildingsValue.md) | | `flood` | [FloodValue](../layers/FloodValue.md) | | `landslide` | [LandslideValue](../layers/LandslideValue.md) | | `mpzp` | [MpzpValue](../layers/MpzpValue.md) | | `parcel` | not specified in the source contract | | `permits` | [PermitsValue](../layers/PermitsValue.md) | | `planning` | [PlanningValue](../layers/PlanningValue.md) | | `pog` | [PogValue](../layers/PogValue.md) | | `prices` | [PricesValue](../layers/PricesValue.md) | | `protected` | [ProtectedValue](../layers/ProtectedValue.md) | | `road_access` | [RoadAccessValue](../layers/RoadAccessValue.md) | | `soil` | [SoilValue](../layers/SoilValue.md) | | `wz` | [WzValue](../layers/WzValue.md) | Referenced response definitions from `openapi.yaml`: See [Schemas](../schemas.md) for all operation-specific definitions. Envelope references are defined in [Envelope](../envelope.md). ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## Recorded example No valid key supplied. Request UUID and response clock normalized. No database, socket, paid call or live coverage claim. Recorded HTTP status: 401. The curl example reproduces this admission response with an unset API key. For supported authenticated operations, supply an account key and required permissions; data and billing then depend on that account. The Stripe receiver additionally requires a provider signature. ```sh curl --silent --show-error --request DELETE "https://mcp.agentdzialek.pl/v1/watches/00000000-0000-4000-8000-000000000001/webhook" \ -H "X-Api-Key: ${LANDFEED_API_KEY}" ``` ```json { "billing": { "charged": 0, "cost": 0, "refunded": 0, "rule": "free_watch" }, "error": "unauthorized", "result": null, "status": "error" } ``` ## Matching MCP tool not specified in the source contract # OpenAPI schemas ```json { "AccountKey": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "label": { "maxLength": 80, "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "prefix": { "pattern": "^lf_live_[A-Za-z0-9_-]{0,8}$", "type": "string" } }, "required": [ "id", "prefix", "label", "created_at", "last_used_at", "expires_at" ], "type": "object" }, "AccountKeyCreated": { "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/AccountKey" }, "secret": { "pattern": "^lf_live_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "key", "secret" ], "type": "object" }, "AccountKeyCreatedResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountKeyCreated" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AccountKeyList": { "additionalProperties": false, "properties": { "keys": { "items": { "$ref": "#/components/schemas/AccountKey" }, "maxItems": 10, "type": "array" }, "limit": { "const": 10 } }, "required": [ "keys", "limit" ], "type": "object" }, "AccountKeyListResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountKeyList" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AccountKeyRevoked": { "additionalProperties": false, "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "type": "object" }, "AccountKeyRevokedResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountKeyRevoked" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AccountKeyRotated": { "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/AccountKey" }, "previous_key_id": { "format": "uuid", "type": "string" }, "previous_valid_until": { "format": "date-time", "type": "string" }, "secret": { "pattern": "^lf_live_[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "key", "secret", "previous_key_id", "previous_valid_until" ], "type": "object" }, "AccountKeyRotatedResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountKeyRotated" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AccountKeyWrite": { "additionalProperties": false, "default": {}, "properties": { "label": { "maxLength": 80, "pattern": "^[^\\x00-\\x1f\\x7f]*$", "type": "string" } }, "type": "object" }, "AccountLedger": { "additionalProperties": false, "properties": { "entries": { "items": { "$ref": "#/components/schemas/AccountLedgerEntry" }, "maxItems": 100, "type": "array" }, "next_cursor": { "maxLength": 1024, "type": [ "string", "null" ] }, "period": { "$ref": "#/components/schemas/AccountPeriod" } }, "required": [ "period", "entries", "next_cursor" ], "type": "object" }, "AccountLedgerEntry": { "additionalProperties": false, "allOf": [ { "else": { "properties": { "credits": { "minimum": 1 } } }, "if": { "properties": { "type": { "enum": [ "charge", "expiry" ] } } }, "then": { "properties": { "credits": { "maximum": -1 } } } } ], "properties": { "balance_after": { "type": "integer" }, "credits": { "type": "integer" }, "id": { "pattern": "^[1-9][0-9]*$", "type": "string" }, "operation": { "type": [ "string", "null" ] }, "request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "timestamp": { "format": "date-time", "type": "string" }, "type": { "enum": [ "charge", "refund", "grant", "expiry" ] } }, "required": [ "id", "type", "credits", "operation", "request_id", "timestamp", "balance_after" ], "type": "object" }, "AccountLedgerResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountLedger" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AccountPeriod": { "additionalProperties": false, "properties": { "ends_at": { "format": "date-time", "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "timezone": { "const": "UTC" } }, "required": [ "starts_at", "ends_at", "timezone" ], "type": "object" }, "AccountUsage": { "additionalProperties": false, "properties": { "by_day": { "items": { "$ref": "#/components/schemas/AccountUsageDay" }, "maxItems": 367, "type": "array" }, "by_operation": { "items": { "$ref": "#/components/schemas/AccountUsageOperation" }, "maxItems": 32, "type": "array" }, "credits_used": { "minimum": 0, "type": "integer" }, "period": { "$ref": "#/components/schemas/AccountPeriod" } }, "required": [ "period", "credits_used", "by_operation", "by_day" ], "type": "object" }, "AccountUsageDay": { "additionalProperties": false, "properties": { "credits_used": { "minimum": 0, "type": "integer" }, "date": { "format": "date", "type": "string" } }, "required": [ "date", "credits_used" ], "type": "object" }, "AccountUsageOperation": { "additionalProperties": false, "properties": { "credits_used": { "minimum": 0, "type": "integer" }, "operation": { "type": "string" } }, "required": [ "operation", "credits_used" ], "type": "object" }, "AccountUsageResponse": { "allOf": [ { "$ref": "./envelope.json" }, { "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "credits": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_operation" } }, "required": [ "cost", "charged", "refunded", "credits", "rule" ], "type": "object" }, "result": { "$ref": "#/components/schemas/AccountUsage" }, "status": { "const": "ok" } }, "type": "object" } ] }, "AddressValue": { "properties": { "addresses": { "items": { "properties": { "house_number": { "type": "string" }, "locality": { "type": "string" }, "postcode": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "addresses" ], "type": "object" }, "AreaV2": { "$ref": "./envelope.json#/$defs/AreaV2" }, "AskCall": { "$ref": "./envelope.json#/$defs/AskCall" }, "AskCitation": { "$ref": "./envelope.json#/$defs/AskCitation" }, "AskClientTool": { "$ref": "./envelope.json#/$defs/AskClientTool" }, "AskContinuation": { "$ref": "./envelope.json#/$defs/AskContinuation" }, "AskEvent": { "$ref": "./envelope.json#/$defs/AskEvent" }, "AskRequest": { "$ref": "./envelope.json#/$defs/AskRequest" }, "AskResponse": { "$ref": "./envelope.json#/$defs/AskResponse" }, "AskSignedResult": { "$ref": "./envelope.json#/$defs/AskSignedResult" }, "AskTurn": { "$ref": "./envelope.json#/$defs/AskTurn" }, "Auth": { "$ref": "./envelope.json#/$defs/Auth" }, "BatchCheckJob": { "$ref": "./envelope.json#/$defs/BatchCheckJob" }, "BatchCheckRequest": { "$ref": "./envelope.json#/$defs/BatchCheckRequest" }, "BatchCheckResults": { "$ref": "./envelope.json#/$defs/BatchCheckResults" }, "BatchCheckSubmission": { "$ref": "./envelope.json#/$defs/BatchCheckSubmission" }, "BillingV2": { "$ref": "./envelope.json#/$defs/BillingV2" }, "BuildingsValue": { "properties": { "count": { "type": "integer" }, "footprint_m2_total": { "type": [ "number", "null" ] } }, "required": [ "count" ], "type": "object" }, "CheckResult": { "properties": { "checks": { "items": { "properties": { "basis": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "id": { "enum": [ "pog_zone", "wz_possible", "mpzp_status", "mpzp_params", "flood_q100", "landslide", "protected", "road_access" ], "type": "string" }, "layer": { "$ref": "./envelope.json#/$defs/LayerKey" }, "result": { "enum": [ "pass", "fail", "warn", "unknown" ], "type": "string" }, "source": { "$ref": "./envelope.json#/$defs/SourceRef" }, "value": {} }, "required": [ "id", "layer", "result", "source" ], "type": "object" }, "type": "array" }, "disclaimer": { "type": "string" }, "record": { "$ref": "#/components/schemas/ParcelRecord" }, "verdict": { "description": "Reguła przeniesiona z bezpłatnego sprawdzania (geofeed/resolve). pass: wszystkie sprawdzenia zakończone pomyślnie. fail: negatywny wynik sprawdzenia rozstrzygającego (brak ścieżki WZ i MPZP dopuszczającego zabudowę). conditional: możliwość zabudowy zależy od wskazanego warunku (dojazd, powódź, forma ochrony). unknown: wynik sprawdzenia rozstrzygającego jest nieznany.", "enum": [ "pass", "conditional", "fail", "unknown" ], "type": "string" } }, "required": [ "verdict", "checks", "record", "disclaimer" ], "type": "object" }, "CheckResultV2": { "$ref": "./envelope.json#/$defs/CheckResultV2" }, "Event": { "anyOf": [ { "properties": { "after": {}, "as_of": { "format": "date", "type": [ "string", "null" ] }, "before": {}, "detected_at": { "format": "date-time", "type": "string" }, "event": { "type": "string" }, "id": { "type": "string" }, "layer": { "type": [ "string", "null" ] }, "source": { "$ref": "./envelope.json#/$defs/SourceRef" } }, "required": [ "id", "event", "detected_at" ], "type": "object" }, { "$ref": "./envelope.json#/$defs/EventV2" } ] }, "EventTypeV2": { "$ref": "./envelope.json#/$defs/EventTypeV2" }, "EventV2": { "$ref": "./envelope.json#/$defs/EventV2" }, "EventsRequestV2": { "$ref": "./envelope.json#/$defs/EventsRequestV2" }, "ExportV2": { "$ref": "./envelope.json#/$defs/ExportV2" }, "FeatureSearchFacets": { "$ref": "./envelope.json#/$defs/FeatureSearchFacets" }, "FeatureSearchFilters": { "$ref": "./envelope.json#/$defs/FeatureSearchFilters" }, "FloodValue": { "description": "covered_no_data oznacza zmapowany obszar i działkę poza wszystkimi strefami: {q10: false, q100: false, q500: false}. Uwagi powodziowe używają polskich nazw miesięcy, wskazują scenariusz Q1% (raz na 100 lat) i odróżniają brak zagrożenia na mapie od nieznanego zakresu danych.", "properties": { "map_edition": { "description": "Cykl MZP i daty publikacji obiektów z validityPeriod.beginPosition; brakujące daty są wyraźnie wskazane. endPosition metadanych nigdy nie wyznacza zakresu danych.", "type": [ "string", "null" ] }, "q10": { "type": "boolean" }, "q100": { "type": "boolean" }, "q100_share_pct": { "type": [ "number", "null" ] }, "q500": { "type": "boolean" } }, "required": [ "q10", "q100", "q500" ], "type": "object" }, "GminaPlanning": { "properties": { "as_of": { "format": "date", "type": "string" }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Kod gminy administracyjnej z ostatnią cyfrą 1, 2 lub 3.", "pattern": "^[0-9]{6}[123]$", "type": "string" }, "mpzp_count": { "type": [ "integer", "null" ] }, "mpzp_coverage_pct": { "type": [ "number", "null" ] }, "pog_adopted_on": { "format": "date", "type": [ "string", "null" ] }, "pog_effective_from": { "format": "date", "type": [ "string", "null" ] }, "pog_resolution_url": { "type": [ "string", "null" ] }, "pog_status": { "enum": [ "draft", "adopted", "in_force", "none", "unknown" ], "type": "string" }, "sources": { "items": { "$ref": "./envelope.json#/$defs/SourceRef" }, "type": "array" }, "studium_expired": { "type": [ "boolean", "null" ] }, "wz_regime": { "type": [ "string", "null" ] } }, "required": [ "gmina_teryt", "gmina_name", "pog_status", "as_of", "sources" ], "type": "object" }, "IdempotencyKey": { "$ref": "./envelope.json#/$defs/IdempotencyKey" }, "LandslideValue": { "description": "Punktowe sprawdzenie SOPO. Trafienie ma stan covered; puste identify oznacza covered_no_data z present=false wyłącznie wewnątrz prawidłowego, ukończonego obszaru mapowania, przy dostępnych danych aplikacji. W pozostałych przypadkach not_covered i value=null. Bez twierdzeń o bezpieczeństwie całej działki ani o przecięciu jej geometrii.", "properties": { "count": { "type": "integer" }, "forms": { "items": { "properties": { "id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "landslide", "threatened_area" ], "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "type": "array" }, "kinds": { "items": { "enum": [ "landslide", "threatened_area" ], "type": "string" }, "type": "array" }, "present": { "type": "boolean" } }, "required": [ "present" ], "type": "object" }, "LayerAnswerV2": { "$ref": "./envelope.json#/$defs/LayerAnswerV2" }, "Licence": { "$ref": "./envelope.json#/$defs/Licence" }, "ListingCandidate": { "$ref": "./envelope.json#/$defs/ListingCandidate" }, "ListingResolution": { "$ref": "./envelope.json#/$defs/ListingResolution" }, "ListingResolveRequest": { "$ref": "./envelope.json#/$defs/ListingResolveRequest" }, "Method": { "$ref": "./envelope.json#/$defs/Method" }, "MpzpValue": { "allOf": [ { "if": { "properties": { "status": { "type": "null" } } }, "then": { "properties": { "effective_from": { "type": "null" } } } } ], "description": "covered_no_data oznacza, że źródło obejmuje gminę, ale żaden MPZP nie obejmuje działki: {status: none, symbol: null, plans: [], effective_from: null}. Plan w przygotowaniu ma status draft. Plan lub strefa bez opublikowanego statusu prawnego ma coverage=covered, status=null, effective_from=null i uwagę wyjaśniającą; symbol, przeznaczenie, identyfikator i nazwa planu są zachowywane, jeżeli je opublikowano.", "properties": { "effective_from": { "format": "date", "type": [ "string", "null" ] }, "plans": { "items": { "properties": { "adopted_on": { "format": "date", "type": [ "string", "null" ] }, "effective_from": { "format": "date", "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "plan_id": { "type": "string" }, "resolution_url": { "type": [ "string", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/MpzpStatus" } }, "type": "object" }, "type": "array" }, "share_pct": { "type": [ "number", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/MpzpStatus" }, "symbol": { "description": "Symbol KIMPZP, jeżeli go opublikowano; w przeciwnym razie null z wyjaśnieniem w note.", "type": [ "string", "null" ] } }, "required": [ "status", "symbol", "plans", "effective_from" ], "type": "object" }, "ParcelFeatures": { "$ref": "./envelope.json#/$defs/ParcelFeatures" }, "ParcelRecord": { "properties": { "adjacent_parcel_ids": { "$ref": "./envelope.json#/$defs/ParcelRecordV2/properties/adjacent_parcel_ids" }, "adjacent_parcel_ids_truncated": { "$ref": "./envelope.json#/$defs/ParcelRecordV2/properties/adjacent_parcel_ids_truncated" }, "admin": { "properties": { "admin_gmina_teryt": { "description": "Gmina administracyjna (parcel_record.admin_gmina_teryt), której kod przyjmuje /v1/gminy/{teryt}/planning.", "type": [ "string", "null" ] }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Jednostka TERYT w identyfikatorze działki (parcel_record.gmina_teryt).", "type": "string" }, "gmina_type": { "type": [ "string", "null" ] }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" }, "voivodeship_name": { "type": "string" } }, "required": [ "voivodeship", "gmina_teryt", "gmina_name", "obreb_id", "number" ], "type": "object" }, "area": { "oneOf": [ { "properties": { "geometry_m2": { "type": "number" }, "official_m2": { "description": "Powierzchnia deklarowana w EGiB w m², nigdy w hektarach.", "type": [ "number", "null" ] }, "source": { "$ref": "./envelope.json#/$defs/SourceRef" } }, "required": [ "official_m2", "geometry_m2", "source" ], "type": "object" }, { "$ref": "./envelope.json#/$defs/AreaV2" } ] }, "centroid": { "$ref": "./envelope.json#/$defs/LonLat" }, "display_geometry": { "$ref": "./envelope.json#/$defs/ParcelRecordV2/properties/display_geometry" }, "display_simplified": { "$ref": "./envelope.json#/$defs/ParcelRecordV2/properties/display_simplified" }, "features": { "$ref": "./envelope.json#/$defs/ParcelFeatures" }, "geometry": { "description": "GeoJSON MultiPolygon w układzie WGS84 przy geometry=full.", "type": [ "object", "null" ] }, "id": { "type": "string" }, "layers": { "additionalProperties": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "description": "Jedna odpowiedź LayerAnswer na żądaną kategorię; poniżej schematy value według klucza kategorii.", "type": "object" }, "record_as_of": { "format": "date", "type": [ "string", "null" ] }, "record_hash": { "type": [ "string", "null" ] } }, "required": [ "id", "admin", "area", "layers", "record_hash" ], "type": "object" }, "ParcelRecordV2": { "$ref": "./envelope.json#/$defs/ParcelRecordV2" }, "ParcelSummary": { "properties": { "address": { "description": "Adres PRG przy wyszukiwaniu według adresu.", "type": [ "string", "null" ] }, "admin_gmina_teryt": { "description": "Gmina administracyjna (parcel_record.admin_gmina_teryt), której kod przyjmuje /v1/gminy/{teryt}/planning.", "type": [ "string", "null" ] }, "area_official_m2": { "type": [ "number", "null" ] }, "centroid": { "$ref": "./envelope.json#/$defs/LonLat" }, "distance_m": { "type": [ "number", "null" ] }, "gmina_name": { "type": "string" }, "gmina_teryt": { "description": "Jednostka TERYT w identyfikatorze działki (parcel_record.gmina_teryt).", "type": "string" }, "id": { "type": "string" }, "number": { "type": "string" }, "obreb_id": { "type": "string" }, "obreb_name": { "type": [ "string", "null" ] }, "powiat_name": { "type": "string" }, "voivodeship": { "type": "string" } }, "required": [ "id", "gmina_teryt", "gmina_name", "obreb_name", "number", "centroid" ], "type": "object" }, "PermitsValue": { "description": "GUNB RWDZ w promieniu 500 m, odpytywany podczas żądania. Nazwy inwestorów nigdy nie są udostępniane.", "properties": { "count_500m": { "type": "integer" }, "recent": { "items": { "properties": { "decision_date": { "format": "date", "type": [ "string", "null" ] }, "distance_m": { "type": "number" }, "kind": { "type": "string" }, "object_category": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "count_500m" ], "type": "object" }, "PlaceSuggestion": { "$ref": "./envelope.json#/$defs/PlaceSuggestion" }, "PlacesResult": { "$ref": "./envelope.json#/$defs/PlacesResult" }, "Plan": { "$ref": "./envelope.json#/$defs/Plan" }, "PlanningValue": { "description": "Informacje planistyczne o działce w jednym żądaniu: odpowiedzi o planie ogólnym, MPZP i WZ (każda jako pełne LayerAnswer z własnym coverage, source i note) oraz stan planowania gminy. Bez stwierdzenia „brak planu” bez wskazania rodzaju planu i źródła.", "properties": { "gmina": { "$ref": "#/components/schemas/GminaPlanning" }, "mpzp": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "pog": { "$ref": "./envelope.json#/$defs/LayerAnswer" }, "wz": { "$ref": "./envelope.json#/$defs/LayerAnswer" } }, "required": [ "pog", "mpzp", "wz", "gmina" ], "type": "object" }, "PogValue": { "description": "Plan ogólny. Projekty są pokazywane i oznaczane jako projekty. covered_no_data oznacza, że źródło obejmuje gminę, ale nie zawiera rekordu planu ogólnego: {status: none, zone_symbol: null, zones: []}.", "properties": { "adopted_on": { "format": "date", "type": [ "string", "null" ] }, "effective_from": { "description": "Data wejścia planu w życie; null dla draft i none.", "format": "date", "type": [ "string", "null" ] }, "in_ouz": { "description": "W granicach obszaru uzupełnienia zabudowy.", "type": [ "boolean", "null" ] }, "plan_id": { "type": [ "string", "null" ] }, "resolution_url": { "type": [ "string", "null" ] }, "status": { "$ref": "./envelope.json#/$defs/PlanStatus" }, "zone_name": { "type": [ "string", "null" ] }, "zone_symbol": { "description": "Dominująca strefa o największym udziale, np. SW, SJ, SN, SR, SI, SH, SU, SK, SC, SG, SO, SP.", "type": [ "string", "null" ] }, "zones": { "items": { "properties": { "name": { "type": [ "string", "null" ] }, "parameters": { "properties": { "max_coverage_pct": { "type": [ "number", "null" ] }, "max_height_m": { "type": [ "number", "null" ] }, "max_intensity": { "type": [ "number", "null" ] }, "min_biologically_active_pct": { "type": [ "number", "null" ] }, "min_new_plot_area_m2": { "type": [ "number", "null" ] } }, "type": "object" }, "share_pct": { "type": "number" }, "symbol": { "type": "string" } }, "required": [ "symbol", "share_pct" ], "type": "object" }, "type": "array" } }, "required": [ "status", "zone_symbol", "zones", "effective_from" ], "type": "object" }, "PricesValue": { "description": "Zbiorcze dane porównawcze RCN. Przy mniej niż 5 transakcjach dane zbiorcze nie są udostępniane, a coverage wynosi covered_no_data.", "properties": { "comparables_count": { "type": "integer" }, "median_pln_m2": { "type": [ "number", "null" ] }, "p25_pln_m2": { "type": [ "number", "null" ] }, "p75_pln_m2": { "type": [ "number", "null" ] }, "radius_m": { "type": "integer" }, "window_months": { "type": "integer" } }, "required": [ "comparables_count" ], "type": "object" }, "ProtectedValue": { "properties": { "forms": { "items": { "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "description": "Kody form ochrony: park_narodowy, rezerwat, park_krajobrazowy, obszar_chronionego_krajobrazu, natura2000_oso, natura2000_soo, uzytek_ekologiczny, zespol_przyrodniczo_krajobrazowy, stanowisko_dokumentacyjne, pomnik_przyrody.", "type": "string" } }, "required": [ "type", "name" ], "type": "object" }, "type": "array" }, "inside_any": { "type": "boolean" } }, "required": [ "inside_any", "forms" ], "type": "object" }, "RoadAccessValue": { "properties": { "nearest_public_road_m": { "type": [ "number", "null" ] }, "verdict": { "enum": [ "pass", "fail", "unknown" ], "type": "string" }, "via": { "enum": [ "adjacent_public_road_parcel", "bdot_road_within_30m", null ], "type": [ "string", "null" ] } }, "required": [ "verdict" ], "type": "object" }, "Scope": { "$ref": "./envelope.json#/$defs/Scope" }, "SearchRequestV2": { "$ref": "./envelope.json#/$defs/SearchRequestV2" }, "SearchResultV2": { "$ref": "./envelope.json#/$defs/SearchResultV2" }, "SoilValue": { "properties": { "classes": { "items": { "properties": { "share_pct": { "type": "number" }, "symbol": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "classes" ], "type": "object" }, "Source": { "properties": { "approved_at": { "format": "date", "type": [ "string", "null" ] }, "approved_by": { "description": "Operator, który zatwierdził źródło; niezależne od aktualności danych.", "type": [ "string", "null" ] }, "as_of": { "format": "date", "type": [ "string", "null" ] }, "attribution": { "type": "string" }, "band": { "type": "string" }, "category": { "type": "string" }, "coverage_here": { "description": "Ustawiane wyłącznie po przekazaniu q|id|point.", "oneOf": [ { "type": "null" }, { "$ref": "./envelope.json#/$defs/Coverage" } ] }, "coverage_pct": { "type": [ "number", "null" ] }, "coverage_unit": { "type": [ "string", "null" ] }, "freshness": { "enum": [ "fresh", "stale", "unknown" ], "type": "string" }, "id": { "type": "string" }, "last_success_at": { "format": "date-time", "type": [ "string", "null" ] }, "layers": { "items": { "type": "string" }, "type": "array" }, "licence": { "type": "string" }, "licence_url": { "type": [ "string", "null" ] }, "publisher": { "type": "string" }, "refresh_target": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "publisher", "licence", "attribution", "as_of", "freshness" ], "type": "object" }, "WatchAttempt": { "additionalProperties": false, "properties": { "attempt": { "minimum": 1, "type": "integer" }, "attempted_at": { "format": "date-time", "type": "string" }, "delivery_id": { "format": "uuid", "type": "string" }, "id": { "minimum": 1, "type": "integer" }, "latency_ms": { "minimum": 0, "type": "integer" }, "outcome": { "enum": [ "delivered", "http_failure", "network_failure", "blocked_destination", "response_too_large", "unsafe_event", "secret_unavailable", "expired" ] }, "status": { "maximum": 599, "minimum": 100, "type": [ "integer", "null" ] } }, "required": [ "id", "delivery_id", "attempt", "attempted_at", "status", "latency_ms", "outcome" ], "type": "object" }, "WatchAttemptList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WatchAttempt" }, "maxItems": 100, "type": "array" }, "next_cursor": { "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "WatchConfigured": { "additionalProperties": false, "allOf": [ { "required": [ "id", "items", "created_at", "updated_at", "enabled", "disabled_reason", "consecutive_failures", "secret_version" ] } ], "properties": { "consecutive_failures": { "minimum": 0, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "disabled_reason": { "enum": [ null, "unconfigured", "operator_disabled", "blocked_destination", "consecutive_failures" ] }, "enabled": { "type": "boolean" }, "entitlement_paused": { "description": "Konfiguracja jest zachowana, gdy plan lub członkostwo w zespole nie uprawnia do wysyłki.", "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "items": { "$ref": "#/components/schemas/WatchWrite/properties/items" }, "secret": { "pattern": "^lf_whsec_[A-Za-z0-9_-]{43}$", "type": "string" }, "secret_version": { "minimum": 0, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "secret" ], "type": "object" }, "WatchDelivery": { "additionalProperties": false, "description": "POST z niezmienioną treścią JSON UTF-8. X-Landfeed-Delivery jest stałym identyfikatorem. X-Landfeed-Signature: t=unix_seconds,v1=hex_hmac_sha256(secret, ASCII(timestamp) + dot + raw_body). Zweryfikuj podpis w ciągu 300 sekund, a przed wykonaniem skutków trwale wyklucz ponowne przetworzenie id. Ponowienia zachowują treść i id oraz aktualizują czas podpisu. Zmiana sekretu natychmiast unieważnia poprzedni. Limit połączenia: 3 sekundy, odczytu: 5 sekund, całej odpowiedzi: 10 sekund, nagłówków i treści łącznie: 65 536 bajtów. Ponowienia zaczynają się od 30 sekund, odstęp rośnie wykładniczo do godziny, przez 24 godziny od dodania do kolejki; dziesięć kolejnych niepowodzeń wyłącza subskrypcję. Zablokowany adres wyłącza ją natychmiast. Dzienniki nigdy nie zapisują treści odpowiedzi. Po awarii HTTP może dostarczyć więcej niż raz; dodanie do kolejki następuje dokładnie raz na parę obserwacja/zdarzenie.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "notification": { "$ref": "#/components/schemas/WatchNotification" }, "subscription_id": { "format": "uuid", "type": "string" } }, "required": [ "id", "subscription_id", "created_at", "notification" ], "type": "object" }, "WatchEventType": { "description": "Można rejestrować tylko rodziny zdarzeń, dla których działają produkcyjne ścieżki zapisu i obsługi. Rodziny EventV2 nie mają jeszcze producenta i zwracają event_type_has_no_producer. Zaufane adaptery o określonych typach nie oznaczają obsługi produkcyjnej.", "enum": [ "pog.changed", "wz.changed", "mpzp.changed", "flood.changed", "landslide.changed", "protected.changed", "buildings.changed" ], "type": "string" }, "WatchItem": { "additionalProperties": false, "oneOf": [ { "required": [ "parcel_id" ] }, { "required": [ "gmina_teryt" ] }, { "required": [ "polygon" ] } ], "properties": { "gmina_teryt": { "pattern": "^[0-9]{6}[123]$", "type": "string" }, "parcel_id": { "$ref": "./envelope.json#/$defs/ParcelId" }, "polygon": { "$ref": "./envelope.json#/$defs/SearchPolygon" }, "types": { "items": { "$ref": "#/components/schemas/WatchEventType" }, "maxItems": 32, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "types" ], "type": "object" }, "WatchLayerEvidence": { "additionalProperties": false, "allOf": [ { "$ref": "./envelope.json#/$defs/LayerAnswer" } ], "description": "Historyczny zakres danych potwierdza zapisany skrót coverage/value, a daty źródeł potwierdza zapis wersji. Pierwotna treść uwagi i podstawa są niedostępne i wyraźnie oznaczone jako nieznane. Brak dowodów wstrzymuje powiadomienie; bieżące metadane źródła nigdy nie zastępują historycznych dat.", "properties": { "as_of": { "format": "date", "type": [ "string", "null" ] }, "coverage": { "$ref": "./envelope.json#/$defs/Coverage" }, "hash": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "layer": { "enum": [ "pog", "wz", "mpzp", "flood", "landslide", "protected", "buildings" ], "type": "string" }, "layer_version": { "minLength": 1, "type": "string" }, "note": { "maxLength": 4000, "minLength": 1, "type": "string" }, "source": { "$ref": "./envelope.json#/$defs/SourceRef" }, "value": {} }, "required": [ "layer", "coverage", "value", "source", "as_of", "layer_version", "hash", "note" ], "type": "object" }, "WatchLegacyEvent": { "additionalProperties": false, "description": "Zapisana różnica z wcześniejszych obliczeń. Typ jest zachowany; nie wnioskuje się o uchwaleniu, statusie prawnym ani dacie zdarzenia. Dopuszczalne są tylko zwalidowane wartości kategorii; dotychczasowe pojedyncze sprzedaże są pomijane. Starsze identyfikatory źródeł muszą należeć do zapisanej macierzy zaakceptowanej przez operatora i mieć prawidłowy stan w v_sources. Obecny zapis WZ korzysta z gmina_planning_status i zachowuje to pochodzenie. EventV2 zachowuje dodatkowo wymagania dotyczące sprawdzonej licencji.", "properties": { "after": {}, "after_evidence": { "$ref": "#/components/schemas/WatchLayerEvidence" }, "as_of": { "format": "date", "type": [ "string", "null" ] }, "before": {}, "before_evidence": { "$ref": "#/components/schemas/WatchLayerEvidence" }, "detected_at": { "format": "date-time", "type": "string" }, "event": { "enum": [ "pog.changed", "wz.changed", "mpzp.changed", "flood.changed", "landslide.changed", "protected.changed", "buildings.changed" ], "type": "string" }, "from_version": { "type": [ "string", "null" ] }, "id": { "pattern": "^parcel_events:[0-9]+$", "type": "string" }, "layer": { "enum": [ "pog", "wz", "mpzp", "flood", "landslide", "protected", "buildings" ], "type": "string" }, "parcel_id": { "$ref": "./envelope.json#/$defs/ParcelId" }, "source": { "$ref": "./envelope.json#/$defs/SourceRef" }, "to_version": { "type": [ "string", "null" ] } }, "required": [ "id", "event", "parcel_id", "layer", "before", "after", "before_evidence", "after_evidence", "from_version", "to_version", "detected_at", "source", "as_of" ], "type": "object" }, "WatchList": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WatchRecord" }, "maxItems": 100, "type": "array" }, "next_cursor": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ], "type": "object" }, "WatchMpzpPlanMetadata": { "description": "Sprawdzone metadane zwracane przez precompute.run.compile_answer, obok dotychczasowych otwartych pól planu MpzpValue.", "properties": { "share_pct": { "type": [ "number", "null" ] } }, "type": "object" }, "WatchNotification": { "additionalProperties": false, "description": "Zachowaj typ zdarzenia i uwagę o korekcie lub regule. Zapisana różnica nigdy nie staje się dowodem zmiany w rzeczywistości. Dopuszczalne są tylko źródła zatwierdzone przez operatora; wspólne listy zakazów dotyczących prywatności i ogłoszeń obowiązują przed zapisem i ponownie przed wysyłką.", "properties": { "classification": { "enum": [ "observation_change", "source_correction", "source_refresh" ], "type": "string" }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WatchLegacyEvent" }, { "$ref": "./envelope.json#/$defs/EventV2" } ] }, "note": { "maxLength": 4000, "minLength": 1, "type": "string" }, "rule_version": { "type": [ "string", "null" ] } }, "required": [ "event", "classification", "note", "rule_version" ], "type": "object" }, "WatchPogZoneMetadata": { "description": "Sprawdzone metadane zwracane przez precompute.model.pog_value, obok dotychczasowych otwartych pól strefy PogValue.", "properties": { "designation": { "minLength": 1, "type": "string" } }, "type": "object" }, "WatchRecord": { "additionalProperties": false, "properties": { "consecutive_failures": { "minimum": 0, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "disabled_reason": { "enum": [ null, "unconfigured", "operator_disabled", "blocked_destination", "consecutive_failures" ] }, "enabled": { "type": "boolean" }, "entitlement_paused": { "description": "Konfiguracja jest zachowana, gdy plan lub członkostwo w zespole nie uprawnia do wysyłki.", "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "items": { "$ref": "#/components/schemas/WatchWrite/properties/items" }, "secret_version": { "minimum": 0, "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "items", "created_at", "updated_at", "enabled", "disabled_reason", "consecutive_failures", "secret_version" ], "type": "object" }, "WatchResponse": { "additionalProperties": false, "description": "Format zarządzania kontem; zapytanie i rozpoznawanie nie mają zastosowania. Koszty są wartościami zastępczymi do decyzji operatora. Cache-Control: private, max-age=0, must-revalidate. Bez zastępczego przypisywania konta według klucza statycznego.", "properties": { "billing": { "additionalProperties": false, "properties": { "charged": { "const": 0 }, "cost": { "const": 0 }, "refunded": { "const": 0 }, "rule": { "const": "free_watch" } }, "required": [ "cost", "charged", "refunded", "rule" ], "type": "object" }, "error": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WatchRecord" }, { "$ref": "#/components/schemas/WatchConfigured" }, { "$ref": "#/components/schemas/WatchList" }, { "$ref": "#/components/schemas/WatchAttemptList" } ] }, "status": { "enum": [ "ok", "error" ], "type": "string" } }, "required": [ "status", "result", "error", "billing" ], "type": "object" }, "WatchWebhookWrite": { "additionalProperties": false, "description": "Wyłącznie HTTPS na porcie 443, bez danych użytkownika w adresie, fragmentów, znaków sterujących oraz prywatnych lub niepublicznych odpowiedzi DNS. Zdekodowane pola zapytania, także powtórzone i puste, muszą przejść kontrolę prywatności kontraktu i wspólne listy zakazów usuwania danych podczas obsługi. Odrzucenie następuje przed zapisem, a kontrola jest powtarzana przy każdej próbie; połączenie jest przypięte do dopuszczonej odpowiedzi DNS. Awaria rozpoznawania adresów powoduje ponowienie, niebezpieczny adres blokadę. TLS weryfikuje pierwotną nazwę hosta. Bez przekierowań i pośredników z konfiguracji środowiska.", "properties": { "enabled": { "default": true, "type": "boolean" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" } }, "required": [ "url" ], "type": "object" }, "WatchWrite": { "additionalProperties": false, "description": "Kontrola dopuszczenia poprzedza parsowanie i walidację poza głównym wątkiem. Treść do 256 KiB; łącznie do 100 elementów i 1 024 wierzchołków wielokątów na żądanie. Przekroczenie limitu pracy walidatora zwraca validation_work_limit (413).", "properties": { "items": { "items": { "$ref": "#/components/schemas/WatchItem" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "items" ], "type": "object" }, "WzValue": { "description": "Wynik własnych obliczeń: czy w dniu zapytania można wydać decyzję WZ dla działki. basis wskazuje przepis.", "properties": { "possible": { "type": [ "boolean", "null" ] }, "reason": { "type": "string" } }, "required": [ "possible" ], "type": "object" } } ``` # SSE event reference Format SSE: event: \ndata: \n\n. Każdy przyjęty strumień kończy dokładnie jedno done; może je poprzedzać error. Kroki są zapowiadane przed wykonaniem publicznej operacji. Wyniki zawierają dokładne treści publicznych odpowiedzi. | event | Meaning | | --- | --- | | `answer.citations` | Numbered citations with source/date. | | `answer.delta` | Answer text after settlement. | | `artifact` | Whole signed API result. | | `budget.exceeded` | Unexecuted plan exceeds budget. | | `client_tool.call` | Client UI action request. | | `confirm.required` | Pause for user approval. | | `done` | End and continuation; cost after settlement. | | `error` | Failure; inspect settlement state. | | `step.finished` | Finished step and settled cost. | | `step.started` | Request and estimate before execution. | ## step.started ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "step.started" }, "data": { "type": "object", "additionalProperties": false, "properties": { "step_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "tool": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 300 }, "request": { "type": "object", "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "type": "string", "pattern": "^/v1/" }, "query": { "type": "object" }, "body": { "type": [ "object", "null" ] } }, "required": [ "method", "path", "query", "body" ] }, "estimated_credits": { "type": "integer", "minimum": 0, "maximum": 20 } }, "required": [ "step_id", "tool", "label", "request", "estimated_credits" ] } }, "required": [ "event", "data" ] } ``` ## step.finished ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "step.finished" }, "data": { "type": "object", "additionalProperties": false, "properties": { "step_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "minLength": 1, "maxLength": 80 }, "credits_charged": { "type": "integer", "minimum": 0, "maximum": 20 }, "duration_ms": { "type": "integer", "minimum": 0 }, "artifact_id": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "step_id", "status", "credits_charged", "duration_ms" ] } }, "required": [ "event", "data" ] } ``` ## artifact ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "artifact" }, "data": { "$ref": "#/$defs/AskSignedResult" } }, "required": [ "event", "data" ] } ``` ## answer.delta ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "answer.delta" }, "data": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 24000 } }, "required": [ "text" ] } }, "required": [ "event", "data" ] } ``` ## answer.citations ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "answer.citations" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "citation_id": { "type": "integer", "minimum": 1 }, "artifact_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "layer": { "type": "string", "minLength": 1, "maxLength": 80 }, "source": { "$ref": "#/$defs/SourceRef" }, "as_of": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "citation_id", "artifact_id", "source", "as_of" ] }, "maxItems": 40 } }, "required": [ "event", "data" ] } ``` ## client_tool.call ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "client_tool.call" }, "data": { "type": "object", "additionalProperties": false, "properties": { "call_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "arguments": { "type": "object" } }, "required": [ "call_id", "name", "arguments" ] } }, "required": [ "event", "data" ] } ``` ## confirm.required ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "confirm.required" }, "data": { "type": "object", "additionalProperties": false, "properties": { "step_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "action": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 300 }, "credits": { "type": "integer", "minimum": 0, "maximum": 20 } }, "required": [ "step_id", "action", "label", "credits" ] } }, "required": [ "event", "data" ] } ``` ## budget.exceeded ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "budget.exceeded" }, "data": { "type": "object", "additionalProperties": false, "properties": { "needed": { "type": "integer", "minimum": 1, "maximum": 1000 }, "max_credits": { "type": "integer", "minimum": 0, "maximum": 20 }, "plan": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "step_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "tool": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string", "minLength": 1, "maxLength": 300 }, "request": { "type": "object", "additionalProperties": false, "properties": { "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "type": "string", "pattern": "^/v1/" }, "query": { "type": "object" }, "body": { "type": [ "object", "null" ] } }, "required": [ "method", "path", "query", "body" ] }, "estimated_credits": { "type": "integer", "minimum": 0, "maximum": 20 } }, "required": [ "step_id", "tool", "label", "request", "estimated_credits" ] }, "maxItems": 12 } }, "required": [ "needed", "max_credits", "plan" ] } }, "required": [ "event", "data" ] } ``` ## done ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "done" }, "data": { "type": "object", "additionalProperties": false, "properties": { "credits_total": { "type": "integer", "minimum": 0, "maximum": 20 }, "continuation": { "anyOf": [ { "$ref": "#/$defs/AskContinuation" }, { "type": "null" } ] } }, "required": [ "credits_total", "continuation" ] } }, "required": [ "event", "data" ] } ``` ## error ```json { "type": "object", "additionalProperties": false, "properties": { "event": { "const": "error" }, "data": { "type": "object", "additionalProperties": false, "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "message", "code" ] } }, "required": [ "event", "data" ] } ``` References resolve against [Envelope](envelope.md). See [ask guide](guides/en/ask-sse.md) for sequencing and settlement. # MCP tool: check Czy na tej działce można budować? ## Description (verbatim) Sprawdź jedną działkę: nazwane sprawdzenia, źródła, zakres danych i osadzona karta. Przekazuj niepewność; nigdy nie stwierdzaj prawa do zabudowy. Zadania dla portfela i odpytywanie o zadania są niedostępne. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/check](../operations/check.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `id` | no | `{"maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | not specified in the source contract | | `lat` | no | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | not specified in the source contract | | `lng` | no | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | not specified in the source contract | | `point` | no | `{"pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string"}` | not specified in the source contract | | `q` | no | `{"maxLength": 300, "minLength": 1, "type": "string"}` | not specified in the source contract | ```json { "inputSchema": { "allOf": [ { "additionalProperties": false, "not": { "anyOf": [ { "required": [ "area" ] }, { "required": [ "parcel_ids" ] }, { "required": [ "job_id" ] }, { "required": [ "idempotency_key" ] } ] }, "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } }, "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "check" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/check" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract. # MCP tool: events Co się zmieniło ## Description (verbatim) Pobierz zmiany dotyczące działek lub obszaru ze źródłami i datami, używając types, since i cursor. Większe listy parcel_ids przekaż w treści POST (do 10 000); GET dopuszcza 100 identyfikatorów. Zdarzenia RCN zawierają tylko zaokrąglone dane zbiorcze grup transakcji. Zdarzenia dotyczące ogłoszeń zawierają identyfikatory działek bez treści ogłoszenia. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/events](../operations/events.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. not specified in the source contract ```json { "inputSchema": { "allOf": [ { "anyOf": [ { "not": { "anyOf": [ { "required": [ "area" ] }, { "required": [ "parcel_ids" ] }, { "required": [ "job_id" ] }, { "required": [ "idempotency_key" ] } ] }, "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "cursor": { "type": "string" }, "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" }, "since": { "format": "date", "type": "string" }, "types": { "type": "string" } }, "type": "object" }, { "$ref": "#/$defs/EventsRequestV2" } ], "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "events" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/events" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract. # MCP tool: layer Jedna kategoria danych o działce ## Description (verbatim) Pobierz wskazaną kategorię danych na podstawie q, id albo point. Odczytuj łącznie coverage, source, as_of i note. Opłaty za not_covered i not_computed są zwracane; covered_no_data oznacza brak rekordu potwierdzony przez źródło. Nie wnioskuj o braku obiektu ani o statusie prawnym z niedostępnych danych. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/layer/{layer}](../operations/layer.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `id` | no | `{"maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | not specified in the source contract | | `lat` | no | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | not specified in the source contract | | `layer` | yes | `{"enum": ["planning", "parcel", "admin", "address", "buildings", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil"], "type": "string"}` | not specified in the source contract | | `lng` | no | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | not specified in the source contract | | `point` | no | `{"pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string"}` | not specified in the source contract | | `q` | no | `{"maxLength": 300, "minLength": 1, "type": "string"}` | not specified in the source contract | ```json { "inputSchema": { "allOf": [ { "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "layer": { "enum": [ "planning", "parcel", "admin", "address", "buildings", "pog", "wz", "mpzp", "flood", "landslide", "protected", "road_access", "permits", "prices", "soil" ], "type": "string" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "layer" ], "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "layer" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/layer/flood" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract. # MCP tool: parcel Karta działki ## Description (verbatim) Pobierz kartę działki na podstawie q, id albo point: identyfikację, powierzchnię i dostępne dane tematyczne ze źródłem, datą, uwagą i zakresem danych. Niewiadome i niedostępne dane są wyraźnie oznaczone. Odczyt kosztuje jeden kredyt; odnośniki służą do opcjonalnych dalszych wywołań. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/parcel](../operations/parcel.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `geometry` | no | `{"enum": ["none", "centroid", "full"], "type": "string"}` | not specified in the source contract | | `id` | no | `{"maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | not specified in the source contract | | `lat` | no | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | not specified in the source contract | | `layers` | no | `{"type": "string"}` | not specified in the source contract | | `lng` | no | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | not specified in the source contract | | `point` | no | `{"pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string"}` | not specified in the source contract | | `q` | no | `{"maxLength": 300, "minLength": 1, "type": "string"}` | not specified in the source contract | ```json { "inputSchema": { "allOf": [ { "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] } ] }, "required": [ "lat", "lng" ] } ], "properties": { "geometry": { "enum": [ "none", "centroid", "full" ], "type": "string" }, "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "layers": { "type": "string" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } }, "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "parcel" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/parcel" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract. # MCP tool: resolve Znajdź działkę wskazaną przez użytkownika ## Description (verbatim) Rozpoznaj działki na podstawie q, id albo point. Niejednoznaczne dane zwracają kandydatów do wyboru. Parametr listing_url, dostępny po włączeniu funkcji, zastępuje pozostałe dane wejściowe i zawsze zwraca kandydatów z result=null. Nie kopiuj treści ogłoszenia ani nie wybieraj kandydata bez wiedzy użytkownika. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/resolve](../operations/resolve.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `id` | no | `{"maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | not specified in the source contract | | `lat` | no | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | not specified in the source contract | | `limit` | no | `{"maximum": 20, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `listing_url` | no | `{"format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string"}` | not specified in the source contract | | `lng` | no | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | not specified in the source contract | | `point` | no | `{"pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string"}` | not specified in the source contract | | `q` | no | `{"maxLength": 300, "minLength": 1, "type": "string"}` | not specified in the source contract | ```json { "inputSchema": { "allOf": [ { "oneOf": [ { "not": { "anyOf": [ { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] }, { "required": [ "listing_url" ] } ] }, "required": [ "q" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] }, { "required": [ "listing_url" ] } ] }, "required": [ "id" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] }, { "required": [ "listing_url" ] } ] }, "required": [ "point" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "listing_url" ] } ] }, "required": [ "lat", "lng" ] }, { "not": { "anyOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat" ] }, { "required": [ "lng" ] } ] }, "required": [ "listing_url" ] } ], "properties": { "id": { "$ref": "#/$defs/ParcelIdInput" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "limit": { "maximum": 20, "minimum": 1, "type": "integer" }, "listing_url": { "format": "uri", "maxLength": 2048, "pattern": "^https://", "type": "string" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" } }, "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "resolve", "resolve_listing" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/resolve" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract. # MCP tool: search Znajdź działki według adresu, w pobliżu punktu lub na obszarze ## Description (verbatim) Wyszukaj według q/id/point, szerokości i długości geograficznej lub bbox do 4 km². Odpowiedź zawiera skróty informacji o działkach i kursor; każda strona kosztuje 1 kredyt. Filtry typowane obszaru i eksport są niedostępne. ## Cost and binding `x-request-cost`: 1 request per call. REST binding: [GET /v1/search](../operations/search.md). ## Inputs Dokładnie jeden z parametrów q, id, point (lat i lng razem liczą się jako point). Wszystkie punkty odczytu API i wszystkie narzędzia obsługują te trzy warianty. | Field | Required | Schema / constraints | Description | | --- | --- | --- | --- | | `area_max_m2` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `area_min_m2` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `bbox` | no | `{"type": "string"}` | not specified in the source contract | | `buildings_present` | no | `{"type": "boolean"}` | not specified in the source contract | | `cursor` | no | `{"type": "string"}` | not specified in the source contract | | `frontage_min_m` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `gunb_activity_min` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "integer"}` | not specified in the source contract | | `id` | no | `{"maxLength": 100, "pattern": "^\\s*[0-9]{6}[._][0-9]\\.[0-9]{1,4}\\.[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./ -]{0,63}[0-9A-Za-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u024F_./-]\\s*$", "type": "string"}` | not specified in the source contract | | `land_use_class` | no | `{"enum": ["R", "Ł", "Ps", "Br", "B", "Ba", "Bi", "Bp", "Bz", "K", "Ls", "Lz", "Lzr", "N", "Wp", "Ws", "Wsr", "W", "dr", "Tk", "Ti", "Tr", "E"], "type": "string"}` | not specified in the source contract | | `lat` | no | `{"maximum": 55.0, "minimum": 49.0, "type": "number"}` | not specified in the source contract | | `limit` | no | `{"maximum": 1000, "minimum": 1, "type": "integer"}` | not specified in the source contract | | `lng` | no | `{"maximum": 24.5, "minimum": 14.0, "type": "number"}` | not specified in the source contract | | `pog_zone_class` | no | `{"enum": ["SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP"], "type": "string"}` | not specified in the source contract | | `point` | no | `{"pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string"}` | not specified in the source contract | | `public_road_max_m` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `q` | no | `{"maxLength": 300, "minLength": 1, "type": "string"}` | not specified in the source contract | | `radius_m` | no | `{"maximum": 2000, "minimum": 0, "type": "integer"}` | not specified in the source contract | | `rcn_price_max_pln_m2` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `rcn_price_min_pln_m2` | no | `{"maximum": 1000000000000.0, "minimum": 0, "type": "number"}` | not specified in the source contract | | `road_access` | no | `{"type": "boolean"}` | not specified in the source contract | | `shape_regularity_min` | no | `{"maximum": 1, "minimum": 0, "type": "number"}` | not specified in the source contract | | `teryt` | no | `{"pattern": "^(?:[0-9]{4}\|[0-9]{6}[123])$", "type": "string"}` | not specified in the source contract | ```json { "inputSchema": { "allOf": [ { "additionalProperties": false, "not": { "anyOf": [ { "required": [ "area" ] }, { "required": [ "parcel_ids" ] }, { "required": [ "job_id" ] }, { "required": [ "idempotency_key" ] } ] }, "oneOf": [ { "required": [ "q" ] }, { "required": [ "id" ] }, { "required": [ "point" ] }, { "required": [ "lat", "lng" ] }, { "required": [ "bbox" ] }, { "required": [ "teryt" ] } ], "properties": { "area_max_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "area_min_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "bbox": { "type": "string" }, "buildings_present": { "type": "boolean" }, "cursor": { "type": "string" }, "frontage_min_m": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "gunb_activity_min": { "maximum": 1000000000000.0, "minimum": 0, "type": "integer" }, "id": { "$ref": "#/$defs/ParcelIdInput" }, "land_use_class": { "enum": [ "R", "Ł", "Ps", "Br", "B", "Ba", "Bi", "Bp", "Bz", "K", "Ls", "Lz", "Lzr", "N", "Wp", "Ws", "Wsr", "W", "dr", "Tk", "Ti", "Tr", "E" ], "type": "string" }, "lat": { "maximum": 55.0, "minimum": 49.0, "type": "number" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "lng": { "maximum": 24.5, "minimum": 14.0, "type": "number" }, "pog_zone_class": { "enum": [ "SW", "SJ", "SN", "SU", "SH", "SI", "SZ", "SC", "SG", "SO", "SR", "SK", "SP" ], "type": "string" }, "point": { "pattern": "^-?[0-9]{1,2}(\\.[0-9]+)?, ?-?[0-9]{1,3}(\\.[0-9]+)?$", "type": "string" }, "public_road_max_m": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "q": { "maxLength": 300, "minLength": 1, "type": "string" }, "radius_m": { "maximum": 2000, "minimum": 0, "type": "integer" }, "rcn_price_max_pln_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "rcn_price_min_pln_m2": { "maximum": 1000000000000.0, "minimum": 0, "type": "number" }, "road_access": { "type": "boolean" }, "shape_regularity_min": { "maximum": 1, "minimum": 0, "type": "number" }, "teryt": { "pattern": "^(?:[0-9]{4}|[0-9]{6}[123])$", "type": "string" } }, "type": "object" } ], "type": "object" } } ``` ## Structured results Tools return `structuredContent (JSON)` using canonical definitions in `envelope.json`. Compact shared local schemas. Bundle reachable $defs per tool before use; never fetch refs. Examples and detailed guidance: mcp-examples.md. ```json { "allOf": [ { "$ref": "#/$defs/Envelope" } ], "properties": { "meta": { "properties": { "operation": { "enum": [ "search" ] } } } }, "type": "object" } ``` Shared catalog-local `$defs` are published once in [MCP catalogue](../mcp.md). See [Envelope](../envelope.md) and the bound operation for responses. ## Server instructions (verbatim) Źródłowe informacje o polskich działkach ewidencyjnych. Przekazuj w q tekst wpisany przez użytkownika. Każde narzędzie samodzielnie rozpoznaje działkę, więc wcześniejsze wywołanie resolve nie jest potrzebne. Przy statusie ambiguous pokaż kandydatów albo ponów wywołanie z id wybranego kandydata; nigdy nie wybieraj samodzielnie bez wiedzy użytkownika. Każda odpowiedź dotycząca danych tematycznych zawiera coverage i note: covered oznacza obecność rekordu, covered_no_data oznacza brak rekordu w źródle obejmującym to miejsce, not_covered oznacza brak publikacji przez państwo lub brak danych w tym miejscu, a not_computed oznacza, że wyniku jeszcze nie obliczono. Cytując fakt, przytocz note, source.attribution i as_of. Nie określaj działki jako „bezpiecznej”: podaj, co wynika z każdego źródła i czego ono nie obejmuje. Nie pisz „brak planu” bez wskazania, czy chodzi o plan ogólny czy MPZP, jego statusu (draft, adopted, in_force, none; dla MPZP status może być null, gdy źródło go nie publikuje) i źródła. Jeżeli źródło wymienia strefę MPZP bez statusu prawnego, coverage wynosi covered, a status i effective_from mają wartość null; przytocz note i nie ustalaj statusu samodzielnie. Nie zwracamy numerów ksiąg wieczystych ani danych właścicieli. Pole billing pokazuje koszt wywołania; opłaty za odpowiedzi not_covered i błędy są zwracane. Każda odpowiedź v2 zawiera licencję, zakres i metodę. extracted oznacza metodę pozyskania, a nie stan coverage; wynik poniżej progu ma stan not_covered. Powierzchnia z area.source równym computed nie jest urzędową powierzchnią działki. Klucze API i połączenie OAuth korzystają z kredytów tego samego konta. Wyszukiwanie na podstawie ogłoszenia zwraca wyłącznie identyfikatory kandydatów i wymaga włączenia LANDFEED_LISTING_LOOKUP_ENABLED. ## Annotations ```json { "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true } ``` ## Coverage states Cztery stany zakresu danych dla jednej kategorii w danym miejscu. covered: źródło obejmuje to miejsce i zawiera rekord; value zawiera ten rekord. covered_no_data: źródło obejmuje to miejsce, lecz nie zawiera rekordu; value ma określoną dla danej kategorii pustą wartość (false, 0, [], none), nigdy null; jest to potwierdzony brak rekordu, za który naliczana jest opłata. not_covered: źródło nie obejmuje miejsca albo państwo nie publikuje tych danych w postaci do odczytu maszynowego; value=null, agent nie może wyciągać wniosków, a opłata jest zwracana, gdy zapytanie dotyczy tych danych. not_computed: posiadamy źródło, lecz nie obliczyliśmy jeszcze wyniku dla tego miejsca, np. trwa ładowanie zbioru; value=null, opłata jest zwracana. Każdy stan zawiera uwagę napisaną prostym językiem. States: `covered` | `covered_no_data` | `not_covered` | `not_computed`. `LayerAnswer` required fields: `layer`, `coverage`, `value`, `note`, `source`, `as_of`, `layer_version`. ## Billing rule Koszt żądania. charged: liczba naliczonych wywołań po zwrotach. refunded: liczba wywołań naliczonych, a następnie zwróconych. rule: zastosowana reguła. Płatne są odpowiedzi, potwierdzone braki rekordów (covered_no_data) i niejednoznaczne listy kandydatów. Bezpłatne są błędne dane wejściowe (400), brak uwierzytelnienia (401), odpowiedzi bez zmiany danych (304) i operacje bezpłatne. Zwrot obejmuje pozostałe 4xx, każde 5xx, status not_covered oraz odpowiedź dotyczącą jednej kategorii ze stanem not_covered lub not_computed. W operacjach zbiorczych liczby dotyczą poszczególnych elementów. Rule values: `charged` | `free_operation` | `free_invalid_input` | `free_unauthorized` | `free_not_modified` | `refunded_client_error` | `refunded_server_error` | `refunded_not_covered` | `refunded_not_computed` | `batch_mixed`. ## curl example of the REST binding ```sh curl --silent --show-error --request GET "https://mcp.agentdzialek.pl/v1/search" --get \ -H "X-Api-Key: ${LANDFEED_API_KEY}" \ --data-urlencode 'id=141803_2.0001.12/3' ``` MCP transport invocation: not specified in the source contract.