{"openapi":"3.1.0","info":{"title":"Poselok API","version":"1","description":"Публичное API. Версия v1 объявлена нестабильной: пока нет внешнего потребителя, который не может обновиться синхронно с нами, ломающие изменения выходят в v1 и попадают в changelog документации."},"servers":[{"url":"https://poselkovo.ru"}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://poselkovo.ru/oauth/authorize","tokenUrl":"https://poselkovo.ru/oauth/token","scopes":{"mcp:read":"read","mcp:write":"write","mcp:private":"private_data"}}}}}},"paths":{"/api/v1/devices/mine":{"get":{"operationId":"list_my_devices","summary":"Lists the devices the current account has connected to its own plots, with the latest reading of every sensor and when it was taken. Reach for this to answer what the internet, the signal or the temperature on somebody's plot is doing now. A sensor marked not fresh has not reported recently — the device is off or out of touch — and its value is the last one seen rather than the current one. A sensor with no kind is one the product has no meaning for yet; its raw name is what the device called it.","tags":["Device"],"parameters":[{"name":"settlement","in":"query","required":false,"description":"One settlement, by the identifier from list_settlements. Omit to list the devices in every settlement the person belongs to.","schema":{"description":"One settlement, by the identifier from list_settlements. Omit to list the devices in every settlement the person belongs to.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":"7331894216458301","parcel_id":"7331894216458240","name":"Роутер","provider":"keenetic","state":"active","has_secret":true,"last_error":null,"failure_count":0,"polled_at":"2026-09-14T12:35:00+03:00","devices":[{"id":"7331894216458302","connection_id":"7331894216458301","key":"UsbQmi0","name":"Mobile operator","manufacturer":null,"model":null,"firmware":null,"operator":"MegaFon","category":"internet","access_kind":"mobile","sensors":[{"id":"7331894216458303","device_id":"7331894216458302","key":"rsrp","raw_key":"rsrp","kind":"rsrp","value_type":"number","aggregation":"gauge","unit":"dBm","number":-86,"text":null,"is_enabled":true,"visibility":"private","is_fresh":true,"measured_at":"2026-09-14T12:35:00+03:00"}]}]}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/knowledge/articles":{"get":{"operationId":"list_knowledge_articles","summary":"Lists published articles of the shared knowledge base — general advice that holds in any settlement, such as how to mow a lawn or choose a septic tank — newest first, or ranked by relevance when words to search for are given. Use it for a question about the subject rather than about one settlement; list_articles reads what a particular settlement wrote, and show_knowledge_article returns the full text of one of these.","tags":["Knowledge"],"parameters":[{"name":"search","in":"query","required":false,"description":"Words to look for in the title and the body. Omit to read the section newest first.","schema":{"description":"Words to look for in the title and the body. Omit to read the section newest first.","maxLength":200,"type":["string","null"]}},{"name":"category","in":"query","required":false,"description":"One section of the base — «Коммуникации» — or one category inside it, by name.","schema":{"description":"One section of the base — «Коммуникации» — or one category inside it, by name.","enum":["land_and_garden","lawn","planting","trees_and_shrubs","beds_and_greenhouse","soil_and_drainage","pests_and_disease","seasonal_work","house_and_building","foundation","walls_and_roof","insulation","windows_and_doors","bathhouse_and_shed","terrace_and_gazebo","repair_and_finishing","utilities","water_and_well","septic_and_drains","electricity","gas_and_heating","internet_and_signal","waste","fence_and_gate","fencing","gates_and_barriers","paths_and_driveway","lighting","security_and_cameras","documents","cadastre_and_borders","ownership","permissions_and_notices","taxes_and_benefits","utilities_contracts","neighbours_and_community","association","shared_costs","disputes","contractors","winter_and_absence"],"type":["string","null"]}},{"name":"tag","in":"query","required":false,"description":"One tag, by name as articles show it — «трубы пнд». Omit for any.","schema":{"description":"One tag, by name as articles show it — «трубы пнд». Omit for any.","maxLength":100,"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page; ignored when searching, which returns one ranked page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page; ignored when searching, which returns one ranked page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"articles":[{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"published","views_count":128,"published_at":"2026-09-21T18:30:00+03:00","created_at":"2026-09-21T18:10:00+03:00"}],"cursor":"7331894216458250"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}},"post":{"operationId":"write_knowledge_article","summary":"Writes an article for the shared knowledge base — advice that holds in any settlement, rather than a record about one plot. Use it when the person wants to share something general; write_article is the one for a diary entry about their own parcel.","tags":["Knowledge"],"parameters":[],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"draft","views_count":0,"published_at":null,"created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-21T18:10:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The title.","maxLength":200,"type":"string"},"body":{"description":"The text, as markdown.","maxLength":300000,"type":"string"},"category":{"description":"What the article is for, by name — the section a reader browses it under.","enum":["land_and_garden","lawn","planting","trees_and_shrubs","beds_and_greenhouse","soil_and_drainage","pests_and_disease","seasonal_work","house_and_building","foundation","walls_and_roof","insulation","windows_and_doors","bathhouse_and_shed","terrace_and_gazebo","repair_and_finishing","utilities","water_and_well","septic_and_drains","electricity","gas_and_heating","internet_and_signal","waste","fence_and_gate","fencing","gates_and_barriers","paths_and_driveway","lighting","security_and_cameras","documents","cadastre_and_borders","ownership","permissions_and_notices","taxes_and_benefits","utilities_contracts","neighbours_and_community","association","shared_costs","disputes","contractors","winter_and_absence"],"type":["string","null"]},"publish":{"description":"Whether to publish it at once. A draft by default, so an unfinished text is not read by strangers.","type":["boolean","null"]},"tags":{"description":"Free-form tags, as words — what the article is about, so the section can be browsed by subject.","type":["array","null"]}},"required":["title","body"]},"example":{"title":"title","body":"body","category":"land_and_garden","publish":true,"tags":[]}}}}}},"/api/v1/knowledge/articles/{article}":{"patch":{"operationId":"edit_knowledge_article","summary":"Changes the title, the text or the section of an article of the shared knowledge base. Only what is sent changes, and the address stays as it was so links keep working. Changing a published article sends it back for review unless the caller may moderate the base. Name the version you read in base_revision_id and the change is refused, rather than written, when the article has moved on since.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier, as its address carries it.","schema":{"description":"The article, by its identifier, as its address carries it.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"published","views_count":128,"published_at":"2026-09-21T18:30:00+03:00","created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-21T18:10:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The title.","maxLength":200,"type":"string"},"body":{"description":"The text, as markdown.","maxLength":300000,"type":"string"},"category":{"description":"What the article is for, by name.","enum":["land_and_garden","lawn","planting","trees_and_shrubs","beds_and_greenhouse","soil_and_drainage","pests_and_disease","seasonal_work","house_and_building","foundation","walls_and_roof","insulation","windows_and_doors","bathhouse_and_shed","terrace_and_gazebo","repair_and_finishing","utilities","water_and_well","septic_and_drains","electricity","gas_and_heating","internet_and_signal","waste","fence_and_gate","fencing","gates_and_barriers","paths_and_driveway","lighting","security_and_cameras","documents","cadastre_and_borders","ownership","permissions_and_notices","taxes_and_benefits","utilities_contracts","neighbours_and_community","association","shared_costs","disputes","contractors","winter_and_absence"],"type":["string","null"]},"tags":{"description":"The full set of tags; replaces the current one.","type":["array","null"]},"note":{"description":"What you changed and why, for whoever decides on it.","maxLength":500,"type":["string","null"]},"base_revision_id":{"description":"The version your text was written against, by identifier: the approved one, or your own waiting one. When the article has moved past it the change is refused rather than written over what changed meanwhile.","type":"string"}},"required":[]},"example":{"title":"title","body":"body","category":"land_and_garden","tags":[],"note":"note","base_revision_id":"base_revision_id"}}}}},"delete":{"operationId":"remove_knowledge_article","summary":"Removes an article of the shared knowledge base for good. Its author may remove their own; a platform moderator may remove any.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier, as its address carries it.","schema":{"description":"The article, by its identifier, as its address carries it.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"removed":true}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}},"get":{"operationId":"show_knowledge_article","summary":"Returns the full text of one article of the shared knowledge base, by the identifier list_knowledge_articles gave. Use it once a listing or a search has named the article worth reading in full.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier, as its address carries it.","schema":{"description":"The article, by its identifier, as its address carries it.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"published","views_count":128,"published_at":"2026-09-21T18:30:00+03:00","created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-21T18:30:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/knowledge/articles/{article}/cover":{"post":{"operationId":"set_knowledge_article_cover","summary":"Chooses which photograph of a knowledge base article stands on its tile in the list. The picture has to be one of the article's own; sending null returns the tile to the first picture of the article's library. Only the author and the moderators may.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier.","schema":{"description":"The article, by its identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"published","cover_media_id":"7331894216458300","views_count":12,"published_at":"2026-09-21T18:10:00+03:00","created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-23T10:00:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"media":{"description":"A picture from the article's library, or null to fall back to the first one.","type":["string","null"]}},"required":[]},"example":{"media":"media"}}}}}},"/api/v1/knowledge/articles/{article}/publish":{"post":{"operationId":"publish_knowledge_article","summary":"Sends a draft article of the shared knowledge base for review, or publishes it outright when the caller may moderate the base. An article is readable by everybody only once a moderator has passed it. Doing this twice changes nothing, so it is safe to retry.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier, as its address carries it.","schema":{"description":"The article, by its identifier, as its address carries it.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"pending","views_count":0,"published_at":null,"created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-21T18:10:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/knowledge/articles/{article}/roll-back":{"post":{"operationId":"roll_back_knowledge_article","summary":"Restores the text an article of the shared knowledge base had at an earlier version, listed in its history. The old text is written as a new change rather than replacing anything, so it goes for review unless the caller may moderate the base.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article, by its identifier, as its address carries it.","schema":{"description":"The article, by its identifier, as its address carries it.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458250","author_user_id":"7331894216458100","slug":"kogda-strich-gazon","title":"Когда стричь газон","body":"## Первая стрижка\n\nКогда трава поднимется до восьми сантиметров.","excerpt":"Первый раз — когда трава поднимется до восьми сантиметров.","tags":["газон"],"category":"lawn","status":"published","views_count":128,"published_at":"2026-09-21T18:30:00+03:00","created_at":"2026-09-21T18:10:00+03:00","updated_at":"2026-09-22T11:05:00+03:00"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision":{"description":"The version to restore, by its identifier, as the article's history lists it.","type":"string"}},"required":["revision"]},"example":{"revision":"revision"}}}}}},"/api/v1/knowledge/passages/{passage}":{"get":{"operationId":"quote_knowledge_article","summary":"Quotes a passage of the shared knowledge base word for word, drawn as a quotation with a link to its article. Name the passage by the id search_knowledge returned for a `shared_article` result. Use it when the answer rests on what an article says — a norm, a number, a procedure — so the reader sees the source rather than a retelling.","tags":["Knowledge"],"parameters":[{"name":"passage","in":"path","required":true,"description":"The passage, by the `id` search_knowledge returned for it. Only passages of the shared knowledge base (`shared_article`) can be quoted.","schema":{"description":"The passage, by the `id` search_knowledge returned for it. Only passages of the shared knowledge base (`shared_article`) can be quoted.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458411","text":"Для дренажа нормы требуют уклон не меньше 0,002–0,003, то есть 2–3 мм на метр; на практике берут 5–10 мм.","article":{"id":"7331894216451200","title":"Как сделать дренаж участка","url":"/knowledge/7331894216451200/kak-sdelat-drenazh"}}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/knowledge/search":{"get":{"operationId":"search_shared_knowledge","summary":"Searches the shared knowledge base — practical guides on drainage, wells, septics, pipes, fences, lawns, heating, registering a house, the law on plots — and returns the passages themselves. Reach for it first for any question about how to do, build, choose or fix something, or what a rule or a norm says: the articles are written for this product and correct where general knowledge often is not. Besides the passages it lists the diagrams of those articles that fit the question — show one with show_knowledge_figure when the person would understand it faster than words.","tags":["Knowledge"],"parameters":[{"name":"question","in":"query","required":true,"description":"What you want to know, in ordinary words — «как задать уклон дренажа», «можно ли продать участок без межевания».","schema":{"description":"What you want to know, in ordinary words — «как задать уклон дренажа», «можно ли продать участок без межевания».","maxLength":500,"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many passages to bring back, 1 to 20. Eight by default.","schema":{"description":"How many passages to bring back, 1 to 20. Eight by default.","type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"passages":[{"id":"7331894216458411","source_id":"7331894216451200","parcel_id":null,"kind":"shared_article","title":"Как сделать дренаж участка","text":"Для дренажа нормы требуют уклон не меньше 0,002–0,003, то есть 2–3 мм на метр; на практике берут 5–10 мм.","link":"/knowledge/7331894216451200","indexed_at":"2026-09-27T10:00:00+03:00"}],"figures":[{"id":"7331894216458301","article":"7331894216451200","article_title":"Как сделать дренаж участка","caption":"Двухметровый уровень с подкладкой под нижним концом"}]}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/knowledge/{article}/figures/{figure}":{"get":{"operationId":"show_knowledge_figure","summary":"Shows a diagram from the shared knowledge base — a section through a drainage trench, the way a pump is set in a well — as a picture with its caption and a link to its article. search_knowledge marks a diagram in a passage as `[figure:…]` followed by the words on it; when those words answer the question better than the paragraph around them, show the figure.","tags":["Knowledge"],"parameters":[{"name":"article","in":"path","required":true,"description":"The article the figure is in: the `source_id` of the search result that named it.","schema":{"description":"The article the figure is in: the `source_id` of the search result that named it.","type":"string"}},{"name":"figure","in":"path","required":true,"description":"The figure, by the number in its `[figure:…]` marker in the search result's text.","schema":{"description":"The figure, by the number in its `[figure:…]` marker in the search result's text.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458301","url":"/image/knowledge/ab/cd/figure.webp","caption":"Подкладка под двухметровый уровень для уклона 5 мм, 1 и 2 см на метр","text":"Подкладка под уровень 2 м · 1 см · 5 мм на метр · 2 см · 1 см на метр","article":{"id":"7331894216451200","title":"Как сделать дренаж участка","url":"/knowledge/7331894216451200/kak-sdelat-drenazh"}}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/notifications":{"get":{"operationId":"list_notifications","summary":"Lists what the platform has told the current account — a decision on a correction they proposed, and in time a claim reviewed or an import finished — newest first, with keyset pagination and a count of the unread ones. Each entry carries a translation key and its replacements rather than a ready sentence, because the wording lives in the interface and changes with it: render the key, or say what the topic and the subject are. Use read_notification once the person has been told.","tags":["Notification"],"parameters":[{"name":"cursor","in":"query","required":false,"description":"The identifier of the last notification of the previous page. Omit for the first page; the response returns the next one.","schema":{"description":"The identifier of the last notification of the previous page. Omit for the first page; the response returns the next one.","minimum":1,"type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"notifications":[{"id":"7331894216458240","topic":"my_requests","key":"notifications.proposal_approved","replacements":{"subject":"Кровля Плюс"},"url":"/settlements/sosnovy-bereg/contacts/krovlya-plyus","created_at":"2026-09-08T14:12:00+03:00","read":false}],"cursor":null,"unread":1}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/notifications/preferences":{"post":{"operationId":"set_notification_preferences","summary":"Chooses which notifications the current account gets and through which ways. A topic is the account's part in the story: my_requests is what became of what it filed, review_queue is what waits for its decision, reminders is what the product reminds it of on its own schedule. A way is how: in_app is the bell in the interface, mail is a letter. Letters the account needs — a password reset, the address confirmation — are not topics and cannot be switched off here. Everything is on until it is switched off, and what is not named is left as it was. Answers with the whole set of preferences as they now stand.","tags":["Notification"],"parameters":[],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"channels":{"in_app":true},"topics":{"my_requests":{"in_app":true}}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"description":"A way, everywhere: {\"in_app\": true}. Names come from the notification_channel enum.","type":"array"},"topics":{"description":"A topic's own answer per way: {\"my_requests\": {\"in_app\": false}}. Names come from the notification_topic enum.","type":"array"}},"required":[]},"example":{"channels":[],"topics":[]}}}}}},"/api/v1/notifications/{notification}/read":{"post":{"operationId":"read_notification","summary":"Marks one of the current account's notifications as seen, by the identifier list_notifications returned, and answers with how many are left unread. Use it after telling the person what a notification said, so the bell in their browser stops counting it. Marking one that is already read changes nothing and is not an error.","tags":["Notification"],"parameters":[{"name":"notification","in":"path","required":true,"description":"The notification, as the feed returned it.","schema":{"description":"The notification, as the feed returned it.","minimum":1,"type":"integer"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"read":true,"unread":0}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/parcels/mine":{"get":{"operationId":"list_my_parcels","summary":"Lists the plots the current account is on the register for, across every settlement it belongs to. Start here whenever a person says «мой участок» or asks anything about their own land: every other parcel tool needs the parcel and settlement identifiers this one returns, and there is no other way to learn them.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"query","required":false,"description":"One settlement, by the identifier from list_settlements. Omit to list the plots in every settlement the person belongs to.","schema":{"description":"One settlement, by the identifier from list_settlements. Omit to list the plots in every settlement the person belongs to.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"parcel_id":"7331894216458240","plot_number":"12а","settlement":"7331894216458112","settlement_name":"Сосновый Берег","role":"owner","is_primary":true},{"parcel_id":"7331894216458241","plot_number":"13","settlement":"7331894216458112","settlement_name":"Сосновый Берег","role":"owner","is_primary":false}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settings/interface":{"post":{"operationId":"save_interface_settings","summary":"Changes how the product is drawn for the account making the call: which parts of the shell stay on screen while a page scrolls, and which set of colours it is drawn in. Reach for it when somebody asks to change the look of the interface rather than the data in it.","tags":["User"],"parameters":[],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"sticky_header":true,"sticky_sidebar":true,"assistant_width":420,"skin":"grey","objects_view":"tiles"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sticky_header":{"description":"Whether the header stays on screen while a page scrolls.","type":"boolean"},"sticky_sidebar":{"description":"Whether the sidebar stays on screen while a page scrolls.","type":"boolean"},"assistant_width":{"description":"The assistant panel's width in pixels, null for the component's own.","minimum":360,"maximum":720,"type":["integer","null"]},"skin":{"description":"The skin this account prefers, null while it has never chosen.","type":["string","null"]},"objects_view":{"description":"How the plot's inventory is read: `table` or `tiles`, null while never chosen.","type":["string","null"]}},"required":[]},"example":{"sticky_header":true,"sticky_sidebar":true,"assistant_width":1,"skin":"skin","objects_view":"objects_view"}}}}}},"/api/v1/settlements":{"get":{"operationId":"list_settlements","summary":"Lists the settlements published on the platform, oldest first, with keyset pagination. Use it to find the settlement a person is talking about before asking anything else about parcels, works or residents — every other tool needs the settlement identifier this one returns.","tags":["Settlement"],"parameters":[{"name":"place","in":"query","required":false,"description":"A node of the address hierarchy — a region, a district, a rural settlement. Narrows to everything published inside it, at any depth.","schema":{"description":"A node of the address hierarchy — a region, a district, a rural settlement. Narrows to everything published inside it, at any depth.","minimum":1,"type":["integer","null"]}},{"name":"kind","in":"query","required":false,"description":"What sort of settlement: a cottage village, a dacha partnership and so on.","schema":{"description":"What sort of settlement: a cottage village, a dacha partnership and so on.","enum":["cottage_village","snt","dnp","tsn","village"],"type":["string","null"]}},{"name":"status","in":"query","required":false,"description":"Where the settlement is in its life: under construction, populated, and so on.","schema":{"description":"Where the settlement is in its life: under construction, populated, and so on.","enum":["planned","building","completed","populating","populated"],"type":["string","null"]}},{"name":"q","in":"query","required":false,"description":"Part of the settlement's name, matched case-insensitively.","schema":{"description":"Part of the settlement's name, matched case-insensitively.","maxLength":120,"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"The identifier of the last settlement of the previous page. Omit for the first page; the response returns the next one.","schema":{"description":"The identifier of the last settlement of the previous page. Omit for the first page; the response returns the next one.","minimum":1,"type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"settlements":[{"id":"7331894216458112","slug":"sosnovy-bereg","name":"Сосновый Берег","kind":"cottage_village","status":"populating","region":"Ленинградская область","address":"Ленинградская область, Всеволожский район, Сосновый Берег","parcels_total":184}],"cursor":"7331894216458240"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/articles":{"get":{"operationId":"list_articles","summary":"Lists published articles newest first, with keyset pagination: one parcel's diary when a parcel is given, otherwise the settlement's own blog, guides or announcements. Use it to read what has been written about a plot or by the settlement; each entry carries an excerpt, and show_article returns the full text with the map of what it mentions.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"query","required":false,"description":"One parcel's diary, by the parcel's identifier. Omit for the settlement's own feeds.","schema":{"description":"One parcel's diary, by the parcel's identifier. Omit for the settlement's own feeds.","type":["string","null"]}},{"name":"kind","in":"query","required":false,"description":"Which of the settlement's feeds: `post`, `guide` or `announcement`. Ignored when a parcel is given, whose feed is its diary.","schema":{"description":"Which of the settlement's feeds: `post`, `guide` or `announcement`. Ignored when a parcel is given, whose feed is its diary.","enum":["diary","post","guide","announcement"],"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"articles":[{"id":"7331894216458250","settlement_id":"7331894216458240","parcel_id":"7331894216458241","author_user_id":"7331894216458100","slug":"pervyy-den-na-uchastke","title":"Первый день на участке","excerpt":"Разметили фундамент, привезли песок.","kind":"diary","status":"published","visibility":"residents","mentions_count":2,"photos_count":4,"published_at":"2026-09-09T18:30:00+03:00","created_at":"2026-09-09T18:10:00+03:00"}],"cursor":"1789324200:7331894216458250"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}},"post":{"operationId":"write_article","summary":"Writes a new article as a draft: a diary entry about the caller's own parcel, or — for the settlement's editors — a post, guide or announcement of the settlement. The body is markdown and may mention things on the parcel with `[type:id]` tokens, such as `[object:123]` for an object from list_parcel_objects or `[media:456]` for a photograph; the product indexes them so the object's history shows the article. Nothing is published until publish_article is called.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458250","settlement_id":"7331894216458240","parcel_id":"7331894216458241","author_user_id":"7331894216458100","slug":"pervyy-den-na-uchastke","title":"Первый день на участке","excerpt":"Разметили фундамент, привезли песок.","kind":"diary","status":"draft","visibility":"residents","mentions_count":0,"photos_count":0,"published_at":null,"created_at":"2026-09-09T18:10:00+03:00","body":"Разметили фундамент, привезли песок.","mentions":[],"tags":[]}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parcel_id":{"description":"The parcel a diary entry is about, by identifier. Required for `diary`, and not allowed for the settlement's own kinds.","type":["string","null"]},"kind":{"description":"Which feed: `diary` for a resident's own record about their parcel, which is the default; `post`, `guide` or `announcement` for the settlement's blog, which its editors write.","enum":["diary","post","guide","announcement"],"type":["string","null"]},"title":{"description":"The title.","maxLength":200,"type":"string"},"body":{"description":"The text, as markdown with `[type:id]` tokens where things on the parcel are mentioned.","maxLength":60000,"type":"string"},"visibility":{"description":"Who may read it; `residents` by default. `private` is for the settlement's editors only.","enum":["private","residents","settlement","public"],"type":["string","null"]},"tags":{"description":"Free-form tags, as words.","type":["array","null"]},"cover_media_id":{"description":"The photograph on the entry's tile, one of the plot's own; null for the first one the text names.","type":["string","null"]},"about_on":{"description":"The day the entry is about, `Y-m-d` — not the day it is written. Left out, the earliest photograph in the text names it, else the day it was written.","type":["string","null"]},"photo_subjects":{"description":"What each photograph in the text is of: the object's identifier by the photograph's, null for the plot as a whole. A photograph left out keeps its subject — or, when the text names exactly one object, becomes that object's.","type":["array","null"]}},"required":["title","body"]},"example":{"parcel_id":"parcel_id","kind":"diary","title":"title","body":"body","visibility":"private","tags":[],"cover_media_id":"cover_media_id","about_on":"about_on","photo_subjects":[]}}}}}},"/api/v1/settlements/{settlement}/articles/{article}":{"patch":{"operationId":"edit_article","summary":"Changes an entry in a settlement's diary or blog. Send only the fields to change: anything left out keeps its value, and sending \"tags\" replaces that whole list. The kind and the parcel cannot be changed — an entry that belongs in another feed is a different entry — and neither can the address, so links to it keep working. A published entry stays published: fixing a typo is not republishing.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"article","in":"path","required":true,"description":"The entry, by its identifier.","schema":{"description":"The entry, by its identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458270","slug":"skvazhina-probita","title":"Скважина пробита","excerpt":"Сорок два метра, вода пошла на третий день.","kind":"diary","status":"published","visibility":"residents","tags":["вода"],"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"The title.","maxLength":200,"type":"string"},"body":{"description":"The text, as markdown with `[type:id]` tokens where things on the parcel are mentioned.","maxLength":60000,"type":"string"},"visibility":{"description":"Who may read it. `private` is for the settlement's editors only.","enum":["private","residents","settlement","public"],"type":["string","null"]},"tags":{"description":"The full set of tags; replaces the current one.","type":["array","null"]},"cover_media_id":{"description":"The photograph on the entry's tile, one of the plot's own; null for the first one the text names.","type":["string","null"]},"about_on":{"description":"The day the entry is about, `Y-m-d` — not the day it is written. Null hands the question back to the photographs in the text: the earliest shutter date among them, else the day it was written.","type":["string","null"]},"photo_subjects":{"description":"What each photograph in the text is of: the object's identifier by the photograph's, null for the plot as a whole. A photograph left out keeps its subject — or, when the text names exactly one object, becomes that object's.","type":["array","null"]}},"required":[]},"example":{"title":"title","body":"body","visibility":"private","tags":[],"cover_media_id":"cover_media_id","about_on":"about_on","photo_subjects":[]}}}}},"delete":{"operationId":"remove_article","summary":"Removes an entry from a settlement's diary or blog for good. The things it mentioned and the photographs it referred to with a [media:id] token are untouched — those belong to the plot. Refused while a photograph is owned by the entry itself: move it with set_media_subject first. To take an entry out of a feed while keeping the text, change its visibility with edit_article instead.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"article","in":"path","required":true,"description":"The entry, by its own slug.","schema":{"description":"The entry, by its own slug.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"removed":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}},"get":{"operationId":"show_article","summary":"Returns one published article in full: the text as markdown, and a map of what its `[type:id]` tokens point at — the object, photograph, task or gallery each one names, with its current title. Read the map rather than parsing the tokens.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"article","in":"path","required":true,"description":"The article, by the identifier from list_articles.","schema":{"description":"The article, by the identifier from list_articles.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458250","settlement_id":"7331894216458240","parcel_id":"7331894216458241","author_user_id":"7331894216458100","slug":"pervyy-den-na-uchastke","title":"Первый день на участке","excerpt":"Разметили фундамент, привезли песок.","kind":"diary","status":"published","visibility":"residents","mentions_count":1,"photos_count":0,"published_at":"2026-09-09T18:30:00+03:00","created_at":"2026-09-09T18:10:00+03:00","body":"Разметили фундамент, привезли песок.\n\nСкважину [object:7331894216458260] бурили два дня.","mentions":{"object:7331894216458260":{"type":"object","id":"7331894216458260","title":"Скважина"}},"tags":["стройка"]}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/articles/{article}/publish":{"post":{"operationId":"publish_article","summary":"Publishes a draft written with write_article, so it appears in its feed — the parcel's diary or the settlement's blog — to whoever its visibility admits. The author or the settlement's editors may do it; an article already published is refused.","tags":["Journal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"article","in":"path","required":true,"description":"The article, by the identifier write_article returned.","schema":{"description":"The article, by the identifier write_article returned.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458250","settlement_id":"7331894216458240","parcel_id":"7331894216458241","author_user_id":"7331894216458100","slug":"pervyy-den-na-uchastke","title":"Первый день на участке","excerpt":"Разметили фундамент, привезли песок.","kind":"diary","status":"published","visibility":"residents","mentions_count":0,"photos_count":0,"published_at":"2026-09-09T18:30:00+03:00","created_at":"2026-09-09T18:10:00+03:00","body":"Разметили фундамент, привезли песок.","mentions":[],"tags":[]}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/boundary":{"patch":{"operationId":"set_settlement_boundary","summary":"Sets the outline of a settlement and applies it: every cadastral parcel whose centre falls inside becomes a parcel of the settlement, and every parcel outside is unlinked — except one that anything refers to (residents, photographs, tasks, the developer's listing), which stays and is counted in `kept`. No history is lost. Use it when a settlement has picked up land that is not its own — the cadastre records no boundary for a commercial development, so this is the only thing that says where one ends. Parcels named in `parcels` are taken in whatever the outline says, which is how a plot behind the gate or the strip of road at the entrance is added — by naming it rather than by moving points; parcels named in `exclude` are cut out the same way. With `snap` the drawn line is treated as a rough selection and the boundary becomes the true outline of the parcels it encloses. The reply says how many parcels were linked, unlinked and kept.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"ring":[{"latitude":60.4096,"longitude":28.6781},{"latitude":60.4131,"longitude":28.6802},{"latitude":60.4128,"longitude":28.6874},{"latitude":60.4092,"longitude":28.6851}],"parcels":["7331894216458241"],"exclude":[],"snap":true,"source":"manual"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ring":{"description":"The outline, in order, at least three points. The last point need not repeat the first. May be left out when `parcels` is given: the boundary is then the outline of the parcels named.","type":["array","null"]},"parcels":{"description":"Parcels to include whatever the outline says, by identifier. The boundary grows to take each of them in, so a plot or a stretch of road left out by the outline is added by naming it rather than by moving points.","type":["array","null"]},"exclude":{"description":"Parcels to cut out whatever the outline says, by identifier. The mirror of `parcels`: a plot the outline swallowed that is not the settlement's is taken out by naming it.","type":["array","null"]},"snap":{"description":"Whether to lay the outline onto the parcels it encloses instead of keeping it as drawn. A hand-drawn line is a rough ring around the plots somebody means, not a survey: with this the boundary becomes the true outline of every parcel whose centre falls inside it. Off by default, so a line drawn deliberately stays where it was put.","type":["boolean","null"]},"source":{"description":"Where the outline came from: `manual` when somebody drew it, `developer` when they accepted the one proposed from the developer's plots, `egrn` when it is a registry boundary. Defaults to `manual`.","enum":["manual","developer","egrn"],"type":["string","null"]}},"required":[]},"example":{"ring":[],"parcels":[],"exclude":[],"snap":true,"source":"manual"}}}}}},"/api/v1/settlements/{settlement}/boundary/shape":{"post":{"operationId":"shape_settlement_boundary","summary":"Works out a settlement boundary from an outline and the parcels named with it, and returns the resulting contour without storing it. Takes exactly what `set_settlement_boundary` takes: parcels in `parcels` are joined to the outline, parcels in `exclude` are cut out of it, and with `snap` the outline is laid onto the true edges of the parcels it encloses. Use it to preview a correction — «а вот этот участок тоже наш» — before applying it, since applying excludes and restores parcels by the hundred.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"ring":[{"latitude":60.4096,"longitude":28.6781},{"latitude":60.4131,"longitude":28.6802},{"latitude":60.4128,"longitude":28.6874},{"latitude":60.4092,"longitude":28.6851}],"parcels":["7331894216458241"],"exclude":[],"snap":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ring":{"description":"The outline, in order, at least three points. The last point need not repeat the first. May be left out when `parcels` is given: the boundary is then the outline of the parcels named.","type":["array","null"]},"parcels":{"description":"Parcels to include whatever the outline says, by identifier. The boundary grows to take each of them in, so a plot or a stretch of road left out by the outline is added by naming it rather than by moving points.","type":["array","null"]},"exclude":{"description":"Parcels to cut out whatever the outline says, by identifier. The mirror of `parcels`: a plot the outline swallowed that is not the settlement's is taken out by naming it.","type":["array","null"]},"snap":{"description":"Whether to lay the outline onto the parcels it encloses instead of keeping it as drawn. A hand-drawn line is a rough ring around the plots somebody means, not a survey: with this the boundary becomes the true outline of every parcel whose centre falls inside it. Off by default, so a line drawn deliberately stays where it was put.","type":["boolean","null"]},"source":{"description":"Where the outline came from: `manual` when somebody drew it, `developer` when they accepted the one proposed from the developer's plots, `egrn` when it is a registry boundary. Defaults to `manual`.","enum":["manual","developer","egrn"],"type":["string","null"]}},"required":[]},"example":{"ring":[],"parcels":[],"exclude":[],"snap":true,"source":"manual"}}}}}},"/api/v1/settlements/{settlement}/buildings":{"get":{"operationId":"list_buildings","summary":"Lists the buildings the cadastre knows in a settlement — the houses, the garages — as rows: purpose, area in square metres, the plot each stands on, and `setback_m`, how far it keeps from that plot's border. Across the whole settlement or on one plot, by purpose, with keyset pagination. Use it for any question about the houses as a whole: how many, which stand closer than some metres to a border, which is the largest. `measure_shapes` measures one building against anything else.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel","in":"query","required":false,"description":"Only the buildings on this plot, by its number as people say it or by its identifier; omit for the whole settlement.","schema":{"description":"Only the buildings on this plot, by its number as people say it or by its identifier; omit for the whole settlement.","type":["string","null"]}},{"name":"purpose","in":"query","required":false,"description":"Only buildings of this purpose — `dwelling`, `garage`, `outbuilding`; omit for all.","schema":{"description":"Only buildings of this purpose — `dwelling`, `garage`, `outbuilding`; omit for all.","enum":["dwelling","garden_house","garage","outbuilding","non_residential","structure","unknown"],"type":["string","null"]}},{"name":"limit","in":"query","required":false,"description":"How many to bring back, 1 to 100. Thirty by default.","schema":{"description":"How many to bring back, 1 to 100. Thirty by default.","type":["integer","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","maxLength":40,"type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"buildings":[{"id":"7331894216458270","purpose":"Жилой дом","area_m2":96,"has_geometry":true,"parcel":{"id":"7331894216458241","number":"105"},"setback_m":4.3}],"cursor":"7331894216458270"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/change-proposals":{"get":{"operationId":"list_change_proposals","summary":"Lists the corrections residents have proposed to a settlement's records — today its directory of contacts — newest first, with keyset pagination and a count of the ones still waiting. Each entry names the fields it would change and gives three versions of each: what is proposed, what the record held when the proposal was written, and what it holds now. Where the last two differ somebody else has edited the record in the meantime, and applying the proposal will be refused until that is resolved. Use it to find the identifier approve_change_proposal and reject_change_proposal need. Only for somebody who may decide: it carries the names of the neighbours who proposed the corrections.","tags":["Proposal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement whose queue to read, by the identifier from list_settlements.","schema":{"description":"The settlement whose queue to read, by the identifier from list_settlements.","type":"string"}},{"name":"open","in":"query","required":false,"description":"Only the ones still waiting for a decision, which is the default. Pass false to see what has already been decided as well.","schema":{"description":"Only the ones still waiting for a decision, which is the default. Pass false to see what has already been decided as well.","type":["boolean","null"]}},{"name":"cursor","in":"query","required":false,"description":"The identifier of the last proposal of the previous page. Omit for the first page; the response returns the next one.","schema":{"description":"The identifier of the last proposal of the previous page. Omit for the first page; the response returns the next one.","minimum":1,"type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"proposals":[{"id":"7331894216458240","subject_type":"contact","subject_id":"7331894216458241","subject_name":"Кровля Плюс","subject_slug":"krovlya-plyus","author":"Сергей","note":"Позвонил по старому номеру, ответили, что переехали.","status":"pending","reject_reason":null,"proposed":{"name":"Кровля Плюс и сыновья"},"before":{"name":"Кровля Плюс"},"now":{"name":"Кровля Плюс"},"created_at":"2026-09-08T14:12:00+03:00"}],"cursor":null,"open":1}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/change-proposals/{proposal}":{"delete":{"operationId":"withdraw_change_proposal","summary":"Takes back a change the current account proposed, while nobody has decided it yet. Only the author may; a proposal already approved or refused stays as it is, because the decision is part of the record's history.","tags":["Proposal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, out of the path.","schema":{"description":"The settlement, out of the path.","type":"string"}},{"name":"proposal","in":"path","required":true,"description":"Which proposal, out of the path.","schema":{"description":"Which proposal, out of the path.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"withdrawn":true}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/change-proposals/{proposal}/approve":{"post":{"operationId":"approve_change_proposal","summary":"Approves a proposed change to a record in a settlement, which applies it at once. Refuses if the record changed while the proposal was waiting: the proposal is then marked stale and has to be looked at again, because applying it would overwrite whatever changed in the meantime. A proposal cannot be approved by its own author.","tags":["Proposal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, out of the path.","schema":{"description":"The settlement, out of the path.","type":"string"}},{"name":"proposal","in":"path","required":true,"description":"Which proposal, out of the path.","schema":{"description":"Which proposal, out of the path.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"approved":true}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/change-proposals/{proposal}/reject":{"post":{"operationId":"reject_change_proposal","summary":"Refuses a proposed change to a record in a settlement, optionally with a reason the author will see. The record is left exactly as it was. A proposal cannot be refused by its own author — they withdraw it instead.","tags":["Proposal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, out of the path.","schema":{"description":"The settlement, out of the path.","type":"string"}},{"name":"proposal","in":"path","required":true,"description":"Which proposal, out of the path.","schema":{"description":"Which proposal, out of the path.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"rejected":true}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"description":"Why it is refused, for whoever proposed it to read.","maxLength":1000,"type":["string","null"]}},"required":[]},"example":{"reason":"reason"}}}}}},"/api/v1/settlements/{settlement}/chats":{"post":{"operationId":"connect_settlement_chat","summary":"Connects a messenger group chat to a settlement, so the bot answers the people in it. The bot has to already be a member of that group — its identifier is only visible from inside — and a group can belong to one settlement only. A freshly connected chat keeps nothing that was not written to the bot; changing that is a separate step with a reason attached.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458271","settlement_id":"7331894216458001","external_chat_id":"-1001234567890","title":"Тишь да Гладь","legal_basis":null,"answers_count":128,"chunks_count":0,"provider":"telegram","indexing":"addressed","state":"active","may_keep_unaddressed":false,"connected_at":"2026-09-12T10:00:00+03:00","last_update_at":"2026-09-12T18:41:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"description":"Which messenger the group lives in. Only `telegram` and `max` can be served today.","enum":["telegram","max","vk","whatsapp"],"type":"string"},"external_chat_id":{"description":"The platform's own identifier for the chat. In Telegram a supergroup's is negative; the bot must already be a member, because the identifier is only visible from inside.","type":"string"},"title":{"description":"What the group calls itself, for the settlement's own screen. Refreshed from the platform afterwards.","maxLength":200,"type":["string","null"]}},"required":["provider","external_chat_id"]},"example":{"provider":"telegram","external_chat_id":"external_chat_id","title":"title"}}}}},"get":{"operationId":"list_settlement_chats","summary":"Lists the messenger group chats a settlement has connected the bot to, with the terms each is served on: which platform, whether it is still being served, and how much of what is written there may become part of the settlement's knowledge. Use it to find out why the bot is or is not answering in a particular group.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":"7331894216458271","settlement_id":"7331894216458001","external_chat_id":"-1001234567890","title":"Тишь да Гладь","legal_basis":null,"answers_count":128,"chunks_count":0,"provider":"telegram","indexing":"addressed","state":"active","may_keep_unaddressed":false,"connected_at":"2026-09-12T10:00:00+03:00","last_update_at":"2026-09-12T18:41:00+03:00"}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/chats/candidates":{"get":{"operationId":"list_chat_contact_candidates","summary":"Lists the telephone numbers and web addresses found in a chat export that the settlement uploaded, each with the signature its sender gave it and the message it appeared in. These are suggestions and nothing more: none of them is in the settlement's directory until somebody accepts it with accept_chat_contact_candidate. Read the label and the context before deciding — «А. Экскаватор ТДГ» is a name, a trade and a settlement run together, and a number in a sentence may be an emergency service rather than a contractor.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"state","in":"query","required":false,"description":"Only the ones in this state, by name: `pending`, `accepted`, `dismissed`. Undecided ones by default, which is what a review means.","schema":{"description":"Only the ones in this state, by name: `pending`, `accepted`, `dismissed`. Undecided ones by default, which is what a review means.","enum":["pending","accepted","dismissed"],"type":["string","null"]}},{"name":"source","in":"query","required":false,"description":"Only one of the forms a number arrived in, by name: `card` is a forwarded contact card and carries the signature its sender wrote, `pinned` came out of a pinned message, `text` was written inside a sentence, `link` is a web address rather than a number.","schema":{"description":"Only one of the forms a number arrived in, by name: `card` is a forwarded contact card and carries the signature its sender wrote, `pinned` came out of a pinned message, `text` was written inside a sentence, `link` is a web address rather than a number.","enum":["card","text","pinned","link"],"type":["string","null"]}},{"name":"limit","in":"query","required":false,"description":"How many to bring back, 1 to 100. Fifty by default.","schema":{"description":"How many to bring back, 1 to 100. Fifty by default.","type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":"7331894216458271","archive_id":"7331894216458002","contact_id":null,"label":"А. Экскаватор ТДГ","value":"79210000000","context":"Кому нужен мини-экскаватор — вот контакт, приезжал ко мне в июле.","seen_count":3,"source":"card","state":"pending","first_seen_at":"2024-07-14T10:00:00+03:00","last_seen_at":"2026-05-02T19:12:00+03:00"}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/chats/candidates/accept":{"post":{"operationId":"accept_chat_contact_candidate","summary":"Adds one finding from an uploaded chat export to the settlement's directory of contacts, as a proper entry with the telephone number the file carried. Use it after reading the finding's label and context with list_chat_contact_candidates and deciding what the number actually is. One call is one entry: say who they are and what they do, and the number comes from the file rather than from you.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216451102","slug":"a-ekskavator","name":"Алексей, мини-экскаватор","kind":"person","description":"Копал траншею под воду в июле, приезжал на своей технике.","categories":["excavation"],"visibility":"residents"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidate":{"description":"Which finding, by the identifier from list_chat_contact_candidates.","minimum":1,"type":"integer"},"name":{"description":"Who this is: a person's name, a company's short name, or what the crew is known as. The finding's own label is usually a good start — it is what the sender wrote — but it is a signature and not a name: «И. Сантехник ТДГ» is a name, a trade and a settlement run together.","maxLength":160,"type":"string"},"kind":{"description":"Whether this is a private person, a registered company, or an unregistered crew.","enum":["person","company","crew"],"type":"string"},"position":{"description":"What the person is at their company — «прораб», «диспетчер».","maxLength":120,"type":["string","null"]},"description":{"description":"Anything from the chat worth knowing that the other fields do not cover.","maxLength":4000,"type":["string","null"]},"categories":{"description":"Sections of the directory this belongs to, by name — `roofing`, `plumbing`, `excavation`. The signature usually says which.","type":["array","null"]},"place":{"description":"A node of the address hierarchy — the town or village they work out of.","minimum":1,"type":["integer","null"]},"visibility":{"description":"Who may see the entry. Residents of this settlement by default, which is the safe answer for a number a neighbour shared.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"required":["candidate","name","kind"]},"example":{"candidate":1,"name":"name","kind":"person","position":"position","description":"description","categories":[],"place":1,"visibility":"private"}}}}}},"/api/v1/settlements/{settlement}/chats/candidates/dismiss":{"post":{"operationId":"dismiss_chat_contact_candidate","summary":"Marks one finding from an uploaded chat export as not being a contact — an emergency number, somebody's personal mobile, a number quoted in passing. The finding stays on record as refused so that re-reading the same export does not propose it again.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458271","archive_id":"7331894216458002","contact_id":null,"label":null,"value":"112","context":"Если что — звоните в 112.","seen_count":1,"source":"text","state":"dismissed","first_seen_at":"2025-02-03T08:40:00+03:00","last_seen_at":"2025-02-03T08:40:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"candidate":{"description":"Which finding, by the identifier from list_chat_contact_candidates.","minimum":1,"type":"integer"}},"required":["candidate"]},"example":{"candidate":1}}}}}},"/api/v1/settlements/{settlement}/chats/{chat_id}":{"patch":{"operationId":"configure_settlement_chat","summary":"Sets how much of what is written in a connected group chat may be kept and searched by the settlement's assistant. The default keeps only what people address to the bot. Keeping more is refused outright on platforms whose terms forbid it, and elsewhere requires the settlement to record why it may — that reason is stored and read by people, not checked by us.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"chat_id","in":"path","required":true,"description":"The connected chat, by identifier.","schema":{"description":"The connected chat, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458271","settlement_id":"7331894216458001","external_chat_id":"-1001234567890","title":"Тишь да Гладь","legal_basis":null,"answers_count":128,"chunks_count":0,"provider":"telegram","indexing":"marked","state":"active","may_keep_unaddressed":false,"connected_at":"2026-09-12T10:00:00+03:00","last_update_at":"2026-09-12T18:41:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"indexing":{"description":"How much of the chat may become knowledge. `addressed` keeps only what is written to the bot; `marked` adds what an author marked as keepable; `everything` keeps the conversation, is refused where the platform forbids it, and requires a legal basis.","enum":["addressed","marked","everything"],"type":"string"},"legal_basis":{"description":"Why this settlement may keep more than what was addressed to the bot — «согласия собраны при заселении, договор от 12.03.2024». Required for `everything` and ignored otherwise.","maxLength":1000,"type":["string","null"]}},"required":["indexing"]},"example":{"indexing":"addressed","legal_basis":"legal_basis"}}}}},"delete":{"operationId":"disconnect_settlement_chat","summary":"Stops the bot answering in a connected group chat. The connection is remembered rather than erased, so the same group can be switched back on later without losing what is known about it, and so that nobody else can claim it in the meantime. Removing the bot from the group itself is done in the messenger, not here.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"chat_id","in":"path","required":true,"description":"The connected chat, by identifier.","schema":{"description":"The connected chat, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458271","settlement_id":"7331894216458001","external_chat_id":"-1001234567890","title":"Тишь да Гладь","legal_basis":null,"answers_count":128,"chunks_count":0,"provider":"telegram","indexing":"addressed","state":"disconnected","may_keep_unaddressed":false,"connected_at":"2026-09-12T10:00:00+03:00","last_update_at":"2026-09-12T18:41:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/chats/{chat_id}/forget":{"delete":{"operationId":"forget_settlement_chat","summary":"Removes a group from the settlement entirely, so that it leaves the list and the identifier becomes free for anybody to connect again. Reach for this when the group should never have been here — a mistyped identifier naming a group that does not exist, or one connected to the wrong settlement. To pause a real group instead, use disconnect_settlement_chat: that keeps the connection and lets it be switched back on. Uploads and conversations read out of them are kept; the archive screen removes those.","tags":["Messenger"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"chat_id","in":"path","required":true,"description":"The connected chat, by identifier.","schema":{"description":"The connected chat, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458271","settlement_id":"7331894216458001","external_chat_id":"-1001234567890","title":"Тишь да Гладь","legal_basis":null,"answers_count":0,"chunks_count":0,"provider":"telegram","indexing":"addressed","state":"disconnected","may_keep_unaddressed":false,"connected_at":"2026-09-12T10:00:00+03:00","last_update_at":null}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/collections":{"post":{"operationId":"create_collection","summary":"Creates a photograph collection on a parcel, or on the settlement for its staff. Give rules — tags, a subject, a span of dates, an uploader — for a smart collection that keeps itself up to date as photographs arrive, or a list of photograph identifiers for one arranged by hand; not both. Put `[gallery:id]` in an article to show it there.","tags":["Media"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458290","settlement_id":"7331894216458240","parcel_id":"7331894216458241","cover_media_id":null,"title":"Стройка","description":null,"is_smart":true,"rules":{"tags":["стройка"],"taken_from":"2026-05-01"},"media_count":12,"visibility":"residents","created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parcel_id":{"description":"The parcel the collection belongs to, by identifier. Omit for a collection of the settlement itself, which its staff keep.","type":["string","null"]},"title":{"description":"What it is called.","maxLength":200,"type":"string"},"description":{"description":"What it is about.","maxLength":5000,"type":["string","null"]},"visibility":{"description":"Who may see it; `residents` by default.","enum":["private","residents","settlement","public"],"type":["string","null"]},"rules":{"description":"Rules for a smart collection. Omit for one arranged by hand.","properties":{"tags":{"description":"Photographs carrying any of these tags.","type":["array","null"]},"subject_type":{"description":"Photographs of one thing — `parcel_object`, `building`, `parcel`, `article`, `task` — with its identifier in subjectId.","enum":["contact","review","parcel_object","building","parcel","article","task","knowledge_article"],"type":["string","null"]},"subject_id":{"description":"The identifier of the thing, with subjectType.","type":["string","null"]},"taken_from":{"description":"Photographs shot on or after this day, as `YYYY-MM-DD`.","type":["string","null"]},"taken_to":{"description":"Photographs shot on or before this day, as `YYYY-MM-DD`.","type":["string","null"]},"uploaded_by_user_id":{"description":"Photographs one person uploaded, by user identifier.","type":["string","null"]}},"type":["object","null"]},"media_ids":{"description":"Photographs to place in a hand-made collection, in order, by identifier.","type":["array","null"]}},"required":["title"]},"example":{"parcel_id":"parcel_id","title":"title","description":"description","visibility":"private","rules":{"tags":[],"subject_type":"contact","subject_id":"subject_id","taken_from":"taken_from","taken_to":"taken_to","uploaded_by_user_id":"uploaded_by_user_id"},"media_ids":[]}}}}},"get":{"operationId":"list_collections","summary":"Lists the photograph collections of a parcel — or, without a parcel, of the settlement itself — newest first with keyset pagination. A collection with rules keeps itself up to date; one without holds what was placed in it. Either is shown inside an article with a `[gallery:id]` token.","tags":["Media"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"query","required":false,"description":"One parcel's collections, by identifier. Omit for the settlement's own.","schema":{"description":"One parcel's collections, by identifier. Omit for the settlement's own.","type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"collections":[{"id":"7331894216458290","settlement_id":"7331894216458240","parcel_id":"7331894216458241","cover_media_id":null,"title":"Стройка","description":"От котлована до крыши.","is_smart":true,"rules":{"tags":["стройка"]},"media_count":48,"visibility":"residents","created_at":"2026-09-09T18:10:00+03:00"}],"cursor":"7331894216458290"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/companies":{"post":{"operationId":"record_settlement_company","summary":"Records which company plays a given role in a settlement — who built it, who manages it, a contractor, a supplier, or the association of owners — so residents and the public page can see it. The brand name alone is enough; the tax number is optional and only worth sending when it is known from a contract, because nothing verifies it. A company already in our directory with that tax number is reused rather than added again. A settlement has one managing company and one association, so naming another replaces it and keeps the previous one as history — a work recorded years ago still reads against whoever ran the place then. Developers, contractors and suppliers accumulate instead: phases of one settlement are often sold by different companies. Do not guess: a settlement may genuinely have no developer, and a garden association never does.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458243","company_id":"7331894216458242","name":"СтройДом","role":"developer","started_on":null,"ended_on":null}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"description":"What the company is here: developer, management for the managing company, contractor, vendor, or association for a тсн or снт.","enum":["developer","management","contractor","vendor","association"],"type":"string"},"name":{"description":"What the company is called — the brand on the gate or in the contract is enough. Omit only when correcting the tax number of a company already recorded in this role.","maxLength":255,"type":["string","null"]},"inn":{"description":"The company's Russian tax number, ИНН, when it is known from a contract. Ten digits for a company, twelve for a sole trader. Omit rather than guess: it is the field everything else is reconciled by.","type":["string","null"]}},"required":["role"]},"example":{"role":"developer","name":"name","inn":"inn"}}}}}},"/api/v1/settlements/{settlement}/company-proposals":{"post":{"operationId":"propose_settlement_company","summary":"Suggests which company plays a given role in a settlement — who built it, who manages it, a contractor, a supplier, or the association of owners — for the people who run the place to confirm. Use this when the account is a resident rather than staff: the answer is not written straight away, it waits for a decision, and the reply says which of the two happened. The brand name on the gate is enough; send the tax number only when it is known from a contract, and say in the note where the information comes from — somebody reads it before agreeing. Do not guess: a settlement may genuinely have no developer, and a garden association never does.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"applied":false,"proposal":"7331894216458244"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"description":"What the company is here: developer, management for the managing company, contractor, vendor, or association for a тсн or снт.","enum":["developer","management","contractor","vendor","association"],"type":"string"},"name":{"description":"What the company is called — the brand on the gate or in the contract is enough.","maxLength":255,"type":["string","null"]},"inn":{"description":"The company's Russian tax number, ИНН, when it is known from a contract. Ten digits for a company, twelve for a sole trader. Omit rather than guess.","type":["string","null"]},"note":{"description":"Why you think so, in your own words — where you read it, which document it is from.","maxLength":2000,"type":["string","null"]}},"required":["role"]},"example":{"role":"developer","name":"name","inn":"inn","note":"note"}}}}}},"/api/v1/settlements/{settlement}/contact-by-channel":{"get":{"operationId":"find_contact_by_channel","summary":"Finds the entry in a settlement's directory that already holds a given telephone number, email or site, and says whether the current account may correct it. Use it before add_contact: a number already in the directory is refused, because the entry to correct exists — and names do not identify anybody, since the same crew is filed under three spellings of a nickname while the number is one. A telephone matches however it is punctuated, and 8… and +7… are the same number. The value is looked up whatever kind of channel holds it: the same digits are a telephone to one person and a WhatsApp to another, and it is one crew either way — so `taken` can be true for a value add_contact would still accept under a different kind. When the holder is an entry this account may not see, the answer says only that the value is taken.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement whose directory to search, by the identifier from list_settlements.","schema":{"description":"The settlement whose directory to search, by the identifier from list_settlements.","type":"string"}},{"name":"kind","in":"query","required":true,"description":"What sort of channel the value is: a telephone, a WhatsApp, an email, a site.","schema":{"description":"What sort of channel the value is: a telephone, a WhatsApp, an email, a site.","enum":["phone","email","site","telegram","whatsapp","vk","other"],"type":"string"}},{"name":"value","in":"query","required":true,"description":"The value as a person would write it. A telephone matches however it is punctuated, and 8… and +7… are one number; an address matches case-insensitively.","schema":{"description":"The value as a person would write it. A telephone matches however it is punctuated, and 8… and +7… are one number; an address matches case-insensitively.","maxLength":320,"type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"taken":true,"entry":{"slug":"krovlya-plyus","name":"Кровля Плюс","kind":"crew","position":null,"channels":[{"kind":"phone","value":"+7 (921) 000-00-00","label":"бригадир"}]},"may_correct":true,"applies_at_once":false}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/contacts":{"post":{"operationId":"add_contact","summary":"Adds somebody to a settlement's directory of contacts: a company, a private tradesperson, or an unregistered crew. Any confirmed resident of the settlement may add one. Give the sections from the closed list rather than as free text, because that is what makes the entry findable: they cover both what a contact does — `roofing`, `well_drilling` — and what one is, such as `pharmacy` or `management_company`. Free-form tags are for whatever the sections do not cover. A number already in the directory is refused, so the same crew is not listed twice.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement the entry belongs to, by the identifier from list_settlements.","schema":{"description":"The settlement the entry belongs to, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458242","settlement_id":"7331894216458240","slug":"brigada-krovlya-plus","name":"Кровля Плюс","kind":"crew","company_id":null,"company_name":null,"position":null,"description":"Кроют скатные крыши.","address":"Ленинградская область, Всеволожск","place_id":"4417","latitude":60.0192,"longitude":30.6417,"channels":[{"kind":"phone","value":"+7 (921) 000-00-00","label":"прораб, после 10:00","is_primary":true,"visibility":"residents"}],"categories":[{"name":"roofing","is_primary":true}],"tags":["работает по выходным"],"rating":{"grade":null,"score":0,"count":0},"visibility":"residents","moderation_status":"published","created_at":"2026-09-07T12:30:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Who this is: a person's name, a company's short name, or what the crew is known as.","maxLength":160,"type":"string"},"kind":{"description":"Whether this is a private person, a registered company, or an unregistered crew.","enum":["person","company","crew"],"type":"string"},"position":{"description":"What the person is at their company — «прораб», «диспетчер». Only meaningful for a person.","maxLength":120,"type":["string","null"]},"description":{"description":"Anything worth knowing that the other fields do not cover.","maxLength":4000,"type":["string","null"]},"address":{"description":"The address as it is normally written. There is no requirement that a contact have one.","maxLength":500,"type":["string","null"]},"place":{"description":"A node of the address hierarchy — the town or village the contact works out of. Lets residents of a settlement find whoever is nearby.","minimum":1,"type":["integer","null"]},"latitude":{"description":"Where the contact is, so distance from a settlement can be measured. Give both coordinates or neither.","type":["number","null"]},"longitude":{"description":"The other half of the coordinate pair.","type":["number","null"]},"categories":{"description":"Sections of the directory this entry belongs to, by name — what they do, or what they are: `roofing`, `pharmacy`, `management_company`. The work sections are the same vocabulary work records on parcels use, which is what makes «who dug the wells here» answerable.","type":["array","null"]},"tags":{"description":"Free-form words for anything the tree does not cover: «работает по выходным», «берёт наличными». Existing tags are reused case-insensitively.","type":["array","null"]},"channels":{"description":"How to reach them. An entry with no channel at all is allowed — a name and a trade is already worth having — but it is rarely what is meant.","items":{"properties":{"kind":{"description":"What sort of channel this is: a phone, an email, a site, a messenger.","enum":["phone","email","site","telegram","whatsapp","vk","other"],"type":"string"},"value":{"description":"The number, address or handle, written however it is normally written.","maxLength":320,"type":"string"},"label":{"description":"What to say next to it — «диспетчер», «после 18:00», «только СМС».","maxLength":120,"type":["string","null"]},"visibility":{"description":"Who may see this particular channel. Defaults to the entry's own, which keeps a director's mobile from being more public than the entry.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"type":"object","required":["kind","value"]},"type":["array","null"]},"visibility":{"description":"Who may see the entry. Defaults to the settlement's residents, which is the safe default for anything a neighbour wrote.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"required":["name","kind"]},"example":{"name":"name","kind":"person","position":"position","description":"description","address":"address","place":1,"latitude":1.5,"longitude":1.5,"categories":[],"tags":[],"channels":[],"visibility":"private"}}}}},"get":{"operationId":"list_contacts","summary":"Lists a settlement's directory of contacts — companies, private tradespeople, unregistered crews, and the reference numbers a resident needs: the management company, the duty desk, the gatehouse, the nearest pharmacy — with how the neighbours graded each of them. Use it to answer who does a particular kind of work near a settlement, and who is worth calling: filter by section to get everybody in it and in anything under it, by place to get a whole district, or by distance to get only those recorded as being nearby. The sections cover both what a contact does and what one is, so the settlement's own offices, the nearest pharmacy and whoever delivers gravel are in the same directory. Grades are gold, silver, bronze and a fourth grade, and a contact with fewer than three of them carries no overall grade at all.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement whose directory to read, by the identifier from list_settlements.","schema":{"description":"The settlement whose directory to read, by the identifier from list_settlements.","type":"string"}},{"name":"category","in":"query","required":false,"description":"A section of the directory, by name. Narrows to that section and everything under it, so asking for `engineering_systems` also returns whoever only does `heating`. Sections cover both what a contact does — `roofing` — and what one is: `pharmacy`, `management_company`.","schema":{"description":"A section of the directory, by name. Narrows to that section and everything under it, so asking for `engineering_systems` also returns whoever only does `heating`. Sections cover both what a contact does — `roofing` — and what one is: `pharmacy`, `management_company`.","enum":["settlement_governance","management_company","settlement_manager","director","chairman","board","accounting","duty_desk","emergency_service","utilities_service","gatehouse","security_service","street_warden","medicine_and_emergency","ambulance","emergency_room","hospital","clinic","pharmacy","vet","fire_station","police","gas_emergency","children_and_education","school","kindergarten","clubs_and_sports","tutors","childcare","construction","turnkey_house","foundation","frame_and_walls","roofing","facade","windows_and_doors","door_and_window_fitting","bathhouse","pool","outbuildings","engineering_systems","plumbing","electrics","grid_connection","heating","gas_connection","stoves_and_fireplaces","ventilation_and_air_conditioning","low_voltage_systems","water_and_sewerage","well_drilling","dug_wells","septic_systems","water_purification","land_and_plot","survey_and_boundaries","clearing_and_stump_removal","drainage","ground_levelling","demolition","fencing_and_paving","fence","gates_and_automation","paths_and_paved_areas","road_gravelling","landscaping","lawn","tree_and_shrub_planting","tree_surgery","gardener","irrigation","garden_structures","finishing","rough_finishing","final_finishing","plastering_and_painting","tiling","bespoke_furniture","furniture_assembly","maintenance","snow_clearing","grounds_upkeep","waste_removal","septic_servicing","well_servicing","handyman_repairs","general_labourer","appliance_repair","pest_control","weed_control","cleaning","shops","groceries","building_materials","hardware","garden_centre","pet_supplies","car_parts","petrol_station","parcel_pickup","supply_and_delivery","sand_and_gravel","road_aggregate","soil_and_peat","manure_and_compost","ready_mix_concrete","timber","firewood","bottled_gas","drinking_water","haulage","heavy_machinery","communications","internet_provider","mobile_internet","television","other_services","legal_services","taxi"],"type":["string","null"]}},{"name":"place","in":"query","required":false,"description":"A node of the address hierarchy — a district, a rural settlement, a town. Narrows to contacts recorded as being inside it, at any depth. Contacts with no recorded place are left out, since there is no way to tell whether they are in it.","schema":{"description":"A node of the address hierarchy — a district, a rural settlement, a town. Narrows to contacts recorded as being inside it, at any depth. Contacts with no recorded place are left out, since there is no way to tell whether they are in it.","minimum":1,"type":["integer","null"]}},{"name":"tag","in":"query","required":false,"description":"A free-form tag, by its slug or as a person would type it. Matched case-insensitively.","schema":{"description":"A free-form tag, by its slug or as a person would type it. Matched case-insensitively.","maxLength":80,"type":["string","null"]}},{"name":"kind","in":"query","required":false,"description":"Only private people, only registered companies, or only unregistered crews.","schema":{"description":"Only private people, only registered companies, or only unregistered crews.","enum":["person","company","crew"],"type":["string","null"]}},{"name":"within_km","in":"query","required":false,"description":"Only contacts whose recorded location is within this many kilometres of the settlement. Contacts with no location are left out when this is set, since there is no way to tell whether they are near.","schema":{"description":"Only contacts whose recorded location is within this many kilometres of the settlement. Contacts with no location are left out when this is set, since there is no way to tell whether they are near.","type":["number","null"]}},{"name":"q","in":"query","required":false,"description":"Part of a name, matched case-insensitively.","schema":{"description":"Part of a name, matched case-insensitively.","maxLength":120,"type":["string","null"]}},{"name":"sort","in":"query","required":false,"description":"In what order to read: `added` in the order entries were added, which is the default and is stable while paging, or `rating` best graded first. A contact regraded between two pages moves under `rating`, so a caller walking the whole directory wants `added`.","schema":{"description":"In what order to read: `added` in the order entries were added, which is the default and is stable while paging, or `rating` best graded first. A contact regraded between two pages moves under `rating`, so a caller walking the whole directory wants `added`.","enum":["added","rating"],"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page. Its shape belongs to the order and is not to be built by hand.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page. Its shape belongs to the order and is not to be built by hand.","maxLength":48,"type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"contacts":[{"id":"7331894216458242","slug":"brigada-krovlya-plus","name":"Кровля Плюс","kind":"crew","company_name":null,"position":null,"description":"Кроют скатные крыши, работают с металлочерепицей и гибкой черепицей.","address":"Ленинградская область, Всеволожск","place":"г. Всеволожск","channels":[{"kind":"phone","value":"+7 (921) 000-00-00","label":"прораб, после 10:00","is_primary":true}],"categories":[{"name":"roofing","is_primary":true}],"section":"construction","tags":["работает по выходным","берёт наличными"],"photo":{"id":"7331894216458243","path":"image/directory/a1/b2/roof-crew.webp","caption":"Крыша у Ивановых"},"rating":{"grade":"gold","score":4.1,"count":5,"breakdown":{"gold":4,"silver":1,"bronze":0,"dung":0}}}],"cursor":"7331894216458242"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/contacts/{contact}":{"patch":{"operationId":"edit_contact","summary":"Changes an entry in a settlement's directory of contacts. Send only the fields to change: anything left out keeps its current value, and a field sent as null is cleared. Sending \"channels\", \"categories\" or \"tags\" replaces that whole list, so read the entry first and send the list you want to end up with. The slug cannot be changed — it is the entry's address. The entry's author and the settlement's staff change it immediately; any other confirmed resident of the settlement files the same call as a proposal, which the staff then approve or refuse — the answer says which of the two happened in \"applied\".","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, out of the path.","schema":{"description":"The settlement, out of the path.","type":"string"}},{"name":"contact","in":"path","required":true,"description":"The entry being changed, out of the path.","schema":{"description":"The entry being changed, out of the path.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"applied":false,"proposal":"7331894216458244"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"What they are called.","maxLength":160,"type":["string","null"]},"kind":{"description":"A company, a crew or a person.","enum":["person","company","crew"],"type":["string","null"]},"position":{"description":"Their role, when they have one.","maxLength":120,"type":["string","null"]},"description":{"description":"What the neighbours should know.","maxLength":4000,"type":["string","null"]},"address":{"description":"Where they are, in words.","maxLength":500,"type":["string","null"]},"place":{"description":"The locality, as one of our places.","minimum":1,"type":["integer","null"]},"latitude":{"description":"Where they are, precisely.","type":["number","null"]},"longitude":{"description":"The other half of the pair.","type":["number","null"]},"categories":{"description":"The sections, by name.","type":["array","null"]},"tags":{"description":"The free vocabulary.","type":["array","null"]},"channels":{"description":"How to reach them.","items":{"properties":{"kind":{"description":"What sort of channel this is: a phone, an email, a site, a messenger.","enum":["phone","email","site","telegram","whatsapp","vk","other"],"type":"string"},"value":{"description":"The number, address or handle, written however it is normally written.","maxLength":320,"type":"string"},"label":{"description":"What to say next to it — «диспетчер», «после 18:00», «только СМС».","maxLength":120,"type":["string","null"]},"visibility":{"description":"Who may see this particular channel. Defaults to the entry's own, which keeps a director's mobile from being more public than the entry.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"type":"object","required":["kind","value"]},"type":["array","null"]},"visibility":{"description":"Who may see the entry.","enum":["private","residents","settlement","public"],"type":["string","null"]},"note":{"description":"Why the change is proposed, for whoever reviews it.","maxLength":1000,"type":["string","null"]}},"required":[]},"example":{"name":"name","kind":"person","position":"position","description":"description","address":"address","place":1,"latitude":1.5,"longitude":1.5,"categories":[],"tags":[],"channels":[],"visibility":"private","note":"note"}}}}},"get":{"operationId":"show_contact","summary":"Reads one entry of a settlement's directory in full: how to reach them, what they do, where they are, how the neighbours graded them, and every photograph attached to the entry rather than only the first. Use it after list_contacts, with the slug it returned, when a particular contact is the answer and the listing's summary is not enough. What comes back depends on who is asking: a channel or a picture published to the settlement's residents is not in an anonymous answer.","tags":["Company"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"contact","in":"path","required":true,"description":"The entry, by the identifier from list_contacts.","schema":{"description":"The entry, by the identifier from list_contacts.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"id":"7331894216458242","slug":"brigada-krovlya-plus","name":"Кровля Плюс","kind":"crew","company_name":null,"position":null,"description":"Кроют скатные крыши, работают с металлочерепицей и гибкой черепицей.","address":"Ленинградская область, Всеволожск","place":"г. Всеволожск","channels":[{"kind":"phone","value":"+7 (921) 000-00-00","label":"прораб, после 10:00","is_primary":true}],"categories":[{"name":"roofing","is_primary":true}],"section":"construction","tags":["работает по выходным","берёт наличными"],"photo":{"id":"7331894216458243","path":"image/directory/a1/b2/roof-crew.webp","caption":"Крыша у Ивановых"},"photos":[{"id":"7331894216458243","path":"image/directory/a1/b2/roof-crew.webp","caption":"Крыша у Ивановых"},{"id":"7331894216458246","path":"image/directory/a1/b2/roof-crew-2.webp","caption":null}],"rating":{"grade":"gold","score":4.1,"count":5,"breakdown":{"gold":4,"silver":1,"bronze":0,"dung":0}},"latitude":60.0212,"longitude":30.6451}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/devices":{"get":{"operationId":"list_settlement_devices","summary":"Lists the devices of one settlement whose owners have shared their readings, with the latest value of every shared sensor. Reach for this to answer what the internet, the mobile signal or the weather is like in a settlement as a whole, or how one operator performs there against another — the operator and the kind of link are on the device rather than on a reading. Only what each owner published is here, so a settlement may answer with nothing at all; a sensor marked not fresh has not reported recently and its value is the last one seen rather than the current one.","tags":["Device"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":"7331894216458302","connection_id":"7331894216458301","parcel_id":"7331894216458240","key":"UsbQmi0","name":"Mobile operator","manufacturer":null,"model":null,"firmware":null,"operator":"MegaFon","category":"internet","access_kind":"mobile","sensors":[{"id":"7331894216458303","device_id":"7331894216458302","key":"rsrp","raw_key":"rsrp","kind":"rsrp","value_type":"number","aggregation":"gauge","unit":"dBm","number":-86,"text":null,"is_enabled":true,"visibility":"residents","is_fresh":true,"measured_at":"2026-09-14T12:35:00+03:00"}],"headline":{"availability":null,"signal":{"id":"7331894216458303","device_id":"7331894216458302","key":"rsrp","raw_key":"rsrp","kind":"rsrp","value_type":"number","aggregation":"gauge","unit":"dBm","number":-86,"text":null,"is_enabled":true,"visibility":"residents","is_fresh":true,"measured_at":"2026-09-14T12:35:00+03:00"},"quality":null,"received":null}}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/devices/keenetic":{"post":{"operationId":"connect_keenetic","summary":"Connects a Keenetic router to one of the account's own plots so the product can read what it measures — signal, operator, traffic, the state of the link. Reading only: nothing here can change a setting on the router or restart it. Give connection_id to change an existing connection — its login, its password or its name; leave the password out to keep the stored one. The address of a named connection may not change, because a different address is a different router: correcting a mistyped one means connecting again and removing the mistyped connection with disconnect_device. Without connection_id the same address edits the connection that already has it, and a new address becomes a new connection. The first poll is queued immediately, so the answer to whether the credentials were right arrives within a minute rather than at the next interval.","tags":["Device"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458301","parcel_id":"7331894216458240","name":"Роутер","provider":"keenetic","state":"active","has_secret":true,"last_error":null,"failure_count":0,"polled_at":null,"devices":[]}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parcel_id":{"description":"The plot the router stands on, by the identifier from list_my_parcels. A connection belongs to a plot, because one person can own several.","type":"string"},"endpoint_url":{"description":"The HTTPS address of the router's web interface, as KeenDNS shows it — for example https://name.keenetic.link. The path is added by us. It cannot be changed on an existing connection: a different address is a different router.","maxLength":255,"type":"string"},"connection_id":{"description":"The connection being edited, by the identifier from list_my_devices. Leave it out to connect a router; give it to change the login, the password or the name of one already connected.","type":["string","null"]},"username":{"description":"The login of a router account allowed to use the HTTP Proxy service. A separate account with the fewest rights is strongly preferred to the administrator's own.","maxLength":64,"type":"string"},"password":{"description":"That account's password. Leave it out when changing an existing connection to keep the stored one.","maxLength":128,"type":["string","null"]},"name":{"description":"What to call this connection on the page. The router's own model is used when omitted.","maxLength":160,"type":["string","null"]}},"required":["parcel_id","endpoint_url","username"]},"example":{"parcel_id":"parcel_id","endpoint_url":"endpoint_url","connection_id":"connection_id","username":"username","password":"password","name":"name"}}}}}},"/api/v1/settlements/{settlement}/devices/sensors/{sensor_id}":{"patch":{"operationId":"set_sensor_visibility","summary":"Decides who may see one sensor of the caller's own device. Private is the default and means nobody but the owner; residents opens it to the confirmed residents of that settlement; public opens it to anybody, including people with no account. Only a sensor opened at least to residents can be put on a settlement's widget by its manager, and lowering it again takes it off immediately. Consider what the sensor actually says before opening it: an outdoor temperature is one thing, the number of devices connected inside a house is another.","tags":["Device"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"sensor_id","in":"path","required":true,"description":"The sensor, by the identifier from list_my_devices.","schema":{"description":"The sensor, by the identifier from list_my_devices.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458304","device_id":"7331894216458302","key":"temperature","raw_key":"temperature","kind":"temperature","value_type":"number","aggregation":"gauge","unit":"°C","number":12.5,"text":null,"is_enabled":true,"visibility":"residents","is_fresh":true,"measured_at":"2026-09-14T12:35:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visibility":{"description":"Who may see it: `private` for nobody but the owner, `residents` for the confirmed residents of this settlement, `public` for anybody. `settlement` is refused — despite its name it means every signed-in account on the platform rather than the people of this settlement.","enum":["private","residents","settlement","public"],"type":"string"}},"required":["visibility"]},"example":{"visibility":"private"}}}}}},"/api/v1/settlements/{settlement}/devices/{connection_id}":{"delete":{"operationId":"disconnect_device","summary":"Removes one device connection along with its devices, its sensors and everything they ever measured. This cannot be undone and there is no archive: reconnecting the same router afterwards starts its history again from nothing. To stop the readings without losing what is already stored, set the sensors to private instead.","tags":["Device"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"connection_id","in":"path","required":true,"description":"The connection, by the identifier from list_my_devices.","schema":{"description":"The connection, by the identifier from list_my_devices.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"removed":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/devices/{connection_id}/poll":{"post":{"operationId":"poll_device","summary":"Asks one connected device for a fresh reading straight away, instead of waiting for its next scheduled poll. The work is queued and this returns as soon as it is accepted, so the readings themselves arrive a little later — read them back with list_my_devices. Refused when the same connection was already asked moments ago, because the far side is somebody's own router and repeating the question does not make it answer sooner.","tags":["Device"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"connection_id","in":"path","required":true,"description":"The connection, by the identifier from list_my_devices.","schema":{"description":"The connection, by the identifier from list_my_devices.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"queued":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/domains":{"post":{"operationId":"connect_settlement_domain","summary":"Points a settlement at a domain its owners hold, so the settlement answers on tish-da-glad.ru instead of a page under ours. Records the intent and returns the DNS record to create; the domain does not start working until that record appears and a certificate is issued, which is checked automatically and takes anywhere from minutes to a day. Read the status that comes back to see which step it is on.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement the domain will serve, by the identifier from list_settlements.","schema":{"description":"The settlement the domain will serve, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458242","settlement_id":"7331894216458240","host":"tish-da-glad.ru","mode":"records","status":"pending_dns","is_primary":false,"verification_record":{"type":"TXT","name":"_poselkovo-verify.tish-da-glad.ru","value":"kZ8qf2mXrC4tLpB1vN7hJdY6sW0aEuG3iR5oT9xQ"},"certificate_expires_at":null,"registration_expires_at":null,"checked_at":null,"verified_at":null}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"description":"The domain itself, as a visitor would type it: tish-da-glad.ru, with no scheme and no path. A subdomain such as poselok.tish-da-glad.ru is equally fine.","maxLength":253,"type":"string"},"mode":{"description":"How the domain is wired. `delegated` hands us the nameservers and lets us make every record, which is simplest but moves the whole zone — mail included. `records` leaves the zone where it is and asks for a TXT record to prove ownership.","enum":["delegated","records"],"type":"string"}},"required":["host","mode"]},"example":{"host":"host","mode":"delegated"}}}}}},"/api/v1/settlements/{settlement}/domains/{domain}/primary":{"post":{"operationId":"make_settlement_domain_primary","summary":"Chooses which of a settlement's working domains it is known by, so that links in letters, in the chat bot and in anything the assistant hands out are built on that name. Every connected domain keeps answering either way — this decides which one is written down, not which one works. Reach for it when a settlement has more than one domain; the first one to start working is already canonical on its own.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"domain","in":"path","required":true,"description":"The domain to make canonical, by the identifier from the settlement's domain list. It has to be working already: a name still waiting on its DNS records is not an address anybody can be sent to.","schema":{"description":"The domain to make canonical, by the identifier from the settlement's domain list. It has to be working already: a name still waiting on its DNS records is not an address anybody can be sent to.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458242","settlement_id":"7331894216458240","host":"tish-da-glad.ru","mode":"records","status":"live","is_primary":true,"verification_record":null,"certificate_expires_at":"2026-12-21T09:00:00+03:00","registration_expires_at":"2027-04-02T00:00:00+03:00","checked_at":"2026-09-23T09:00:00+03:00","verified_at":"2026-09-16T12:40:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/features":{"post":{"operationId":"add_settlement_feature","summary":"Puts a new thing on a settlement's map — an entrance, a checkpoint, a play area, a fire reservoir. A kind, a name and a place are enough; a rectangle or a circle also takes its size in metres, and a bearing for anything that stands along a fence rather than along a meridian. Use this for a thing nobody has recorded yet; a thing that exists but sits in the wrong place is place_settlement_feature.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458270","title":"Детская площадка","title_raw":null,"kind":"playground","section":"recreation","placement":"placed","needs_placing":false,"longitude":30.6417,"latitude":60.0192}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"What people call it: «Въезд со стороны Мысового».","maxLength":200,"type":"string"},"kind":{"description":"What it is, from the closed list. A section heading such as `recreation` is not a kind.","enum":["movement","road","pedestrian_path","parking","turning_area","bridge","entry_and_safety","entrance","entrance_group","checkpoint","barrier","pedestrian_gate","perimeter_fence","cctv","lighting","fire_reservoir","fire_lane","recreation","playground","sports_ground","workout_area","dog_area","recreation_area","fire_pit","park","beach","pier","utilities","substation","gas_distribution","boiler_house","water_intake","water_tower","treatment_plant","waste_area","utility_yard","public_places","administration","community_centre","shop","mail_point","nature","forest","lake","pond","stream","green_area","miscellaneous","other"],"type":"string"},"latitude":{"description":"Where it is. The map is the input: a coordinate typed by hand is a number nobody can check.","type":"number"},"longitude":{"description":"Where it is.","type":"number"},"shape":{"description":"How it is drawn: a `point`, a `rectangle` of a width by a length, or a `circle` of a diameter. A point by default.","enum":["point","rectangle","circle","line","area"],"type":["string","null"]},"width":{"description":"Across, in metres. A circle reads it as its diameter.","type":["number","null"]},"length":{"description":"Along, in metres. A rectangle only.","type":["number","null"]},"bearing":{"description":"Which way it stands, in degrees clockwise from north.","type":["number","null"]},"visibility":{"description":"Who may see it; public by default, because a settlement's own things are what its map is for.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"required":["title","kind","latitude","longitude"]},"example":{"title":"title","kind":"movement","latitude":1.5,"longitude":1.5,"shape":"point","width":1.5,"length":1.5,"bearing":1.5,"visibility":"private"}}}}}},"/api/v1/settlements/{settlement}/features/{feature}":{"delete":{"operationId":"remove_settlement_feature","summary":"Takes one of a settlement's things off its map for good. The land it stood on is untouched: a feature that marks a parcel is removed without affecting the parcel. Use it for a thing added by mistake or a provider's marker for something that is not there.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"feature","in":"path","required":true,"description":"The thing, by identifier.","schema":{"description":"The thing, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"removed":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/features/{feature}/place":{"post":{"operationId":"place_settlement_feature","summary":"Moves one of a settlement's things to where it actually is, and redraws it when a shape or a size comes with the place. A move on its own carries the whole outline, so a twenty-by-forty play area stays twenty by forty. Refused for a thing whose outline is a cadastral parcel's — a road marked on a surveyed driveway is moved by correcting the parcel, not the marker. Use this for the markers imported from a developer, which are recognisably right and commonly eighty to a hundred metres out.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"feature","in":"path","required":true,"description":"The thing, by identifier.","schema":{"description":"The thing, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458270","title":"Въезд","title_raw":"Въезд","kind":"entrance","section":"entry_and_safety","placement":"placed","needs_placing":false,"longitude":30.6417,"latitude":60.0192}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"description":"Where it is.","type":"number"},"longitude":{"description":"Where it is.","type":"number"},"shape":{"description":"A new shape, when it is being redrawn rather than only moved. Left out, the outline travels unchanged and keeps its size and bearing.","enum":["point","rectangle","circle","line","area"],"type":["string","null"]},"width":{"description":"Across, in metres. A circle reads it as its diameter.","type":["number","null"]},"length":{"description":"Along, in metres. A rectangle only.","type":["number","null"]},"bearing":{"description":"Which way it stands, in degrees clockwise from north.","type":["number","null"]}},"required":["latitude","longitude"]},"example":{"latitude":1.5,"longitude":1.5,"shape":"point","width":1.5,"length":1.5,"bearing":1.5}}}}}},"/api/v1/settlements/{settlement}/knowledge/search":{"get":{"operationId":"search_knowledge","summary":"Searches what people have written — a settlement's diary entries, reviews, notes on plots and tasks, and the shared knowledge base that holds in any settlement — by meaning rather than by field, and returns the passages themselves. Reach for it when the question is about what was said or why something was done, and the answer would be in somebody's words: «хорошие ли у него отзывы», «что тут писали про воду», «что делать, если септик замёрз». When the question has a filter the data already has — a category, a rating, a status — use the tool that lists those rows instead, and use this one afterwards to find out what was said about them.","tags":["Knowledge"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement to ask about, by the identifier from list_settlements.","schema":{"description":"The settlement to ask about, by the identifier from list_settlements.","type":"string"}},{"name":"question","in":"query","required":true,"description":"What you want to know, in ordinary words — «хорошие ли отзывы у кровельщиков», «что писали про воду».","schema":{"description":"What you want to know, in ordinary words — «хорошие ли отзывы у кровельщиков», «что писали про воду».","maxLength":500,"type":"string"}},{"name":"parcel","in":"query","required":false,"description":"One plot's own knowledge, by its identifier. What belongs to the settlement as a whole is still included; leave it out to search everything.","schema":{"description":"One plot's own knowledge, by its identifier. What belongs to the settlement as a whole is still included; leave it out to search everything.","minimum":1,"type":["integer","null"]}},{"name":"kind","in":"query","required":false,"description":"Only one sort of source, by name: `article`, `review`, `contact`, `task`, `parcel_object`, `media`, `change_proposal`, `chat_thread`, `infrastructure`, `shared_article` for the shared knowledge base, `document` for the product's own help.","schema":{"description":"Only one sort of source, by name: `article`, `review`, `contact`, `task`, `parcel_object`, `media`, `change_proposal`, `chat_thread`, `infrastructure`, `shared_article` for the shared knowledge base, `document` for the product's own help.","enum":["article","review","contact","task","parcel_object","media","change_proposal","chat_thread","infrastructure","shared_article","document"],"type":["string","null"]}},{"name":"limit","in":"query","required":false,"description":"How many pieces to bring back, 1 to 20. Eight by default, which is what fits an answer without crowding out the question.","schema":{"description":"How many pieces to bring back, 1 to 20. Eight by default, which is what fits an answer without crowding out the question.","type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":[{"id":"7331894216458271","source_id":"7331894216451102","parcel_id":null,"kind":"review","title":"Отзыв: Житель поселка","text":"золото: Ставили кровлю в июле, приехали в срок и убрали за собой. Через год ни одной протечки.","link":null,"indexed_at":"2026-09-12T10:00:00+03:00"}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/map":{"get":{"operationId":"show_settlement_map","summary":"Shows the map of a settlement: every plot with its number, coloured by status, inside the settlement boundary, with how many plots there are and how many are built on. Use it whenever somebody asks to see the settlement, its plan or its map; for one plot use `show_parcel`.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458240","slug":"tish-da-glad","name":"Тишь да Гладь","parcels_total":312,"parcels_built":140,"map":{"bounds":[[30.63,60.01],[30.66,60.03]],"tiles":{"parcels":"/tiles/parcels_public/{z}/{x}/{y}?settlement_id=7331894216458240&v=3","settlements":"/tiles/settlements_public/{z}/{x}/{y}"}}},"artifact":"settlement_map"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/measure":{"get":{"operationId":"measure_shapes","summary":"Measures things on the settlement map in metres: for each subject its area, perimeter or length, every side with its length and bearing, its centre and box; for every pair the shortest distance, the distance between centres and the length of any shared border. Use it for any question about sizes, distances, sides, fences, borders or footprints — of plots and of the things on them.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"subjects","in":"query","required":true,"description":"One to twelve references — `parcel:105`; `buildings:105` for every registry building on the plot (the house, the garage) or `building:<id>` for one; `objects:105` for everything the resident named on it or `object:<id>` for one. Every subject is measured on its own, and every pair against each other.","schema":{"description":"One to twelve references — `parcel:105`; `buildings:105` for every registry building on the plot (the house, the garage) or `building:<id>` for one; `objects:105` for everything the resident named on it or `object:<id>` for one. Every subject is measured on its own, and every pair against each other.","type":"array"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"subjects":[{"ref":"parcel:105","type":"parcel","id":"7331894216458241","title":"№ 105","geometry":"polygon","area_m2":1240.5,"area_sotkas":12.41,"perimeter_m":141.2,"length_m":null,"centre":{"lon":30.6417,"lat":60.0192},"bounds":[[30.641,60.0188],[30.6424,60.0196]],"sides":[{"n":1,"from":[30.641,60.0188],"to":[30.6424,60.0188],"length_m":38.4,"bearing_deg":90},{"n":2,"from":[30.6424,60.0188],"to":[30.6424,60.0196],"length_m":32.2,"bearing_deg":0}],"longest_side_m":38.4},{"ref":"object:7331894216458260","type":"object","id":"7331894216458260","title":"Баня","geometry":"polygon","area_m2":24,"area_sotkas":0.24,"perimeter_m":20,"length_m":null,"centre":{"lon":30.6415,"lat":60.019},"bounds":[[30.6414,60.019],[30.6416,60.0191]],"sides":[],"longest_side_m":6}],"pairs":[{"a":"object:7331894216458260","b":"parcel:105","distance_m":0,"border_distance_m":4.3,"centre_distance_m":18.7,"shared_border_m":0,"touching":true,"inside":"a"}],"missing":["parcel:999"]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/media/{media}/subject":{"post":{"operationId":"set_media_subject","summary":"Says what a photograph is of: an object of the parcel, a building, the parcel as a whole, an article or a task — by type and identifier — or a new object created on the spot from a kind and a title. The picture then appears in that thing's history while staying in the parcel's gallery. Prefer the most specific thing: the well over the parcel, the parcel over the article.","tags":["Media"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"media","in":"path","required":true,"description":"The photograph, by identifier.","schema":{"description":"The photograph, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458280","url":"image/parcel/a1/b2/well.webp","caption":null,"shot_at":"2026-09-08T14:20:00+03:00","from_camera":true,"camera":"Apple iPhone 15","place":null,"owner_type":"parcel_object","owner_id":"7331894216458260","parcel_id":"7331894216458241","kind":"photo","visibility":"residents","width":1600,"height":1200}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_type":{"description":"What the picture is of — `parcel_object`, `building`, `parcel`, `article`, `task` — with the identifier in subjectId.","enum":["contact","review","parcel_object","building","parcel","article","task","knowledge_article"],"type":["string","null"]},"subject_id":{"description":"The identifier of the thing, with subjectType.","type":["string","null"]},"new_object_kind":{"description":"Instead of an existing thing: create an object of this kind on the photograph's parcel and make the picture its.","enum":["structures","house","garden_house","bathhouse","garage","carport","utility_block","shed","greenhouse","gazebo","summer_kitchen","workshop","guest_house","water_and_drainage","borehole","dug_well","septic_tank","cesspool","water_treatment","storage_tank","irrigation","drainage","storm_drain","drainage_well","energy_and_connectivity","power_supply","switchboard","generator","solar_panels","gas_supply","gas_holder","boiler","heating","internet","cctv","boundaries_and_surfaces","fence","gate","wicket","path","paved_area","driveway","fill","retaining_wall","terrace","garden","lawn","flower_bed","vegetable_bed","hedge","orchard","pond","compost","fruit_tree","woodland","miscellaneous","playground","pool","barbecue_area","sports_ground","parking","other"],"type":["string","null"]},"new_object_title":{"description":"What to call the new object, with newObjectKind.","maxLength":200,"type":["string","null"]}},"required":[]},"example":{"subject_type":"contact","subject_id":"subject_id","new_object_kind":"structures","new_object_title":"new_object_title"}}}}}},"/api/v1/settlements/{settlement}/objects/{object}":{"patch":{"operationId":"edit_parcel_object","summary":"Changes an object on a parcel: its title, description, characteristics, kind, place, visibility, the dates it appeared and was taken down, or its tags. Send only the fields that change; the rest stay as they are. An object standing for a building keeps the building's contour and takes no point of its own.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"object","in":"path","required":true,"description":"The object, by identifier.","schema":{"description":"The object, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458260","settlement_id":"7331894216458240","parcel_id":"7331894216458241","building_id":null,"cover_media_id":null,"title":"Скважина у бани","description":"Пробурена в 2024, 42 метра.","attributes":{"depth_m":42,"yield_m3h":1.5},"latitude":60.0192,"longitude":30.6417,"kind":"borehole","section":"water_and_drainage","articles_count":2,"media_count":5,"open_tasks_count":1,"visibility":"residents","installed_on":"2024-06-12","retired_on":null,"tags":["вода"],"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"What the person calls it.","maxLength":200,"type":"string"},"description":{"description":"Anything worth knowing about it; null clears it.","maxLength":5000,"type":["string","null"]},"attributes":{"description":"Characteristics, by the kind's schema; replaces the whole set.","type":["array","null"]},"kind":{"description":"What it is, from the closed list. A section heading is not a kind.","enum":["structures","house","garden_house","bathhouse","garage","carport","utility_block","shed","greenhouse","gazebo","summer_kitchen","workshop","guest_house","water_and_drainage","borehole","dug_well","septic_tank","cesspool","water_treatment","storage_tank","irrigation","drainage","storm_drain","drainage_well","energy_and_connectivity","power_supply","switchboard","generator","solar_panels","gas_supply","gas_holder","boiler","heating","internet","cctv","boundaries_and_surfaces","fence","gate","wicket","path","paved_area","driveway","fill","retaining_wall","terrace","garden","lawn","flower_bed","vegetable_bed","hedge","orchard","pond","compost","fruit_tree","woodland","miscellaneous","playground","pool","barbecue_area","sports_ground","parking","other"],"type":["string","null"]},"latitude":{"description":"A new place, with the longitude. Not for an object that stands for a building.","type":["number","null"]},"longitude":{"description":"A new place, with the latitude.","type":["number","null"]},"shape":{"description":"How it is drawn where it stands: a `point`, a `rectangle` of a width by a length, or a `circle` of a diameter. A point by default.","enum":["point","rectangle","circle","line","area"],"type":["string","null"]},"width":{"description":"Across, in metres. A circle reads it as its diameter. Required by anything but a point.","type":["number","null"]},"length":{"description":"Along, in metres. A rectangle only.","type":["number","null"]},"bearing":{"description":"Which way it stands, in degrees clockwise from north, for a thing that lies along a fence rather than along a meridian.","type":["number","null"]},"axis":{"description":"Where a `line` runs or what an `area` is traced as, as `[[longitude, latitude], …]` — two points or more for a line, three or more for an area. Ignored by every other shape, which is placed by its centre.","type":["array","null"]},"visibility":{"description":"Who may see it.","enum":["private","residents","settlement","public"],"type":["string","null"]},"colour_primary":{"description":"What it is drawn in, as `#rrggbb`; omit to draw it as its kind says.","type":["string","null"]},"colour_secondary":{"description":"Its outline, likewise.","type":["string","null"]},"installed_on":{"description":"When it appeared, as `YYYY-MM-DD`; null clears it.","type":["string","null"]},"retired_on":{"description":"When it stopped existing, as `YYYY-MM-DD`; null clears it.","type":["string","null"]},"tags":{"description":"The full set of tags; replaces the current one.","type":["array","null"]}},"required":[]},"example":{"title":"title","description":"description","attributes":[],"kind":"structures","latitude":1.5,"longitude":1.5,"shape":"point","width":1.5,"length":1.5,"bearing":1.5,"axis":[],"visibility":"private","colour_primary":"colour_primary","colour_secondary":"colour_secondary","installed_on":"installed_on","retired_on":"retired_on","tags":[]}}}}},"delete":{"operationId":"remove_parcel_object","summary":"Removes an object from a parcel's inventory. Refused while photographs, diary entries or open tasks are attached to it — retire it with edit_parcel_object instead, which keeps the history and takes it off the current plan.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"object","in":"path","required":true,"description":"The object, by identifier.","schema":{"description":"The object, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"removed":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/objects/{object}/cover":{"post":{"operationId":"set_parcel_object_cover","summary":"Chooses which photograph of an object on a parcel stands for it on its tile. The picture has to be one of the object's own; sending null returns the tile to the first of them. Whoever may change the object may choose.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"object","in":"path","required":true,"description":"The object, by identifier.","schema":{"description":"The object, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458260","settlement_id":"7331894216458240","parcel_id":"7331894216458241","building_id":null,"cover_media_id":"7331894216458300","title":"Скважина у бани","description":"Пробурена в 2024, 42 метра.","attributes":{"depth_m":42,"yield_m3h":1.5},"latitude":60.0192,"longitude":30.6417,"kind":"borehole","section":"water_and_drainage","articles_count":2,"media_count":5,"open_tasks_count":1,"visibility":"residents","installed_on":"2024-06-12","retired_on":null,"tags":["вода"],"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"media":{"description":"One of the object's own photographs, by identifier; null returns the tile to the first of them.","type":["string","null"]}},"required":[]},"example":{"media":"media"}}}}}},"/api/v1/settlements/{settlement}/objects/{object}/history":{"get":{"operationId":"list_object_history","summary":"Returns the history of one object on a parcel — the well, the fence, the bathhouse: the published articles that mention it, newest first; its tasks, open and closed, for callers who may see tasks; and its photographs, newest shot first. Twenty of each. Use it before writing about a thing, so the new entry continues its story rather than restarting it.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"object","in":"path","required":true,"description":"The object, by identifier from list_parcel_objects.","schema":{"description":"The object, by identifier from list_parcel_objects.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"object":{"id":"7331894216458260","settlement_id":"7331894216458240","parcel_id":"7331894216458241","building_id":null,"title":"Скважина","description":null,"attributes":{"depth_m":42},"latitude":60.0192,"longitude":30.6417,"kind":"borehole","section":"water_and_drainage","articles_count":1,"media_count":1,"open_tasks_count":1,"visibility":"residents","installed_on":"2024-06-12","retired_on":null,"tags":[],"created_at":"2026-09-09T18:10:00+03:00"},"articles":[{"id":"7331894216458250","settlement_id":"7331894216458240","parcel_id":"7331894216458241","author_user_id":"7331894216458100","slug":"pervyy-den-na-uchastke","title":"Первый день на участке","excerpt":"Скважину бурили два дня.","kind":"diary","status":"published","visibility":"residents","mentions_count":1,"photos_count":0,"published_at":"2026-09-09T18:30:00+03:00","created_at":"2026-09-09T18:10:00+03:00"}],"tasks":[{"id":"7331894216458270","settlement_id":"7331894216458240","parcel_id":"7331894216458241","parent_task_id":null,"previous_task_id":null,"subject_type":"object","subject_id":"7331894216458260","assignee_user_id":null,"created_by_user_id":"7331894216458100","title":"Прокачать скважину","notes":null,"children_count":0,"children_done_count":0,"repeat_after_days":180,"kind":"maintenance","status":"todo","visibility":"residents","blocked_by":[],"starts_on":null,"due_on":"2026-09-20","completed_at":null,"created_at":"2026-09-09T18:10:00+03:00"}],"photos":[{"id":"7331894216458280","url":"image/parcel/a1/b2/well.webp","caption":null,"shot_at":"2026-09-08T14:20:00+03:00","from_camera":true,"camera":"Apple iPhone 15","place":null,"owner_type":"parcel_object","owner_id":"7331894216458260","parcel_id":"7331894216458241","kind":"photo","visibility":"residents","width":1600,"height":1200}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/parcel-claims":{"post":{"operationId":"file_parcel_claim","summary":"Asks a settlement to recognise the current account as a resident of one of its plots. Read the status that comes back: a plot nobody is attached to yet has nobody to ask, so the claim is settled on the spot and comes back approved — the account is a resident immediately, with the link marked unconfirmed until somebody in the settlement vouches for it. A plot that already has people on it comes back pending and waits for one of them to decide. File one claim per plot — a second claim for a plot already asked about is refused.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement being asked, by the identifier from list_settlements.","schema":{"description":"The settlement being asked, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458241","settlement_id":"7331894216458240","parcel_id":null,"claimed_role":"owner","method":"declaration","status":"approved","comment":null,"reject_reason":null,"filed_at":"2026-09-07T12:30:00+03:00","reviewed_at":"2026-09-07T12:30:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plot_number":{"description":"The plot's number on the master plan, as it appears on the sign at the gate and in the contract. Omit when the plot is not on the map yet.","maxLength":20,"type":["string","null"]},"claimed_role":{"description":"On what footing the person says they are attached to the plot.","enum":["owner","co_owner","resident","tenant"],"type":"string"},"comment":{"description":"Anything supporting the claim, in the person's own words.","maxLength":2000,"type":["string","null"]}},"required":["claimed_role"]},"example":{"plot_number":"plot_number","claimed_role":"owner","comment":"comment"}}}}}},"/api/v1/settlements/{settlement}/parcels":{"get":{"operationId":"list_parcels","summary":"Lists the plots of a settlement as rows — number, status, area in square metres, whether there is a house — narrowed by the beginning of a number or by status, ordered by identifier or by area, with keyset pagination. Use it for any question about the plots as a whole: the largest, how many are free, which are for sale, or to find a plot when only part of its number is known. `show_parcel` shows one plot in full.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"q","in":"query","required":false,"description":"The first characters of a plot number, the settlement's own or the developer's; omit for every plot.","schema":{"description":"The first characters of a plot number, the settlement's own or the developer's; omit for every plot.","type":["string","null"]}},{"name":"status","in":"query","required":false,"description":"Only plots in this status — `free`, `sold`, `built`; omit for all.","schema":{"description":"Only plots in this status — `free`, `sold`, `built`; omit for all.","enum":["free","reserved","sold","built","merged","split","common"],"type":["string","null"]}},{"name":"sort","in":"query","required":false,"description":"`id` for the settlement's own order, `area` to order by declared area in square metres; plots with no area are left out of an area order.","schema":{"description":"`id` for the settlement's own order, `area` to order by declared area in square metres; plots with no area are left out of an area order.","type":["string","null"]}},{"name":"order","in":"query","required":false,"description":"`asc` or `desc`; `desc` with `sort=area` puts the largest plot first.","schema":{"description":"`asc` or `desc`; `desc` with `sort=area` puts the largest plot first.","type":["string","null"]}},{"name":"limit","in":"query","required":false,"description":"How many to bring back, 1 to 100. Thirty by default.","schema":{"description":"How many to bring back, 1 to 100. Thirty by default.","type":["integer","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","maxLength":80,"type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"parcels":[{"id":"7331894216458241","number":"105","plot_number":"105","cadastral_number":"47:01:1314001:3327","status":"built","area":1240,"has_house":true,"has_geometry":true}],"cursor":"1240:7331894216458241"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/parcels/{parcel_id}/media":{"get":{"operationId":"list_media","summary":"Lists a parcel's photographs newest shot first, with keyset pagination: pictures of the plot itself and of everything on it — objects, buildings, articles, tasks — in one list, each saying what it is of through owner_type and owner_id. Use the identifiers as `[media:id]` tokens in an article, or with set_media_subject to say what a picture shows.","tags":["Media"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The parcel, by identifier.","schema":{"description":"The parcel, by identifier.","type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"photos":[{"id":"7331894216458280","url":"image/parcel/a1/b2/well.webp","caption":"Скважина после обсадки","shot_at":"2026-09-08T14:20:00+03:00","from_camera":true,"camera":"Apple iPhone 15","place":{"lat":60.0192,"lng":30.6417},"owner_type":"parcel_object","owner_id":"7331894216458260","parcel_id":"7331894216458241","kind":"photo","visibility":"residents","width":1600,"height":1200}],"cursor":"1789215600:7331894216458280"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/parcels/{parcel_id}/number":{"patch":{"operationId":"rename_parcel","summary":"Changes what a plot is called in a settlement — its plot number, the name on the gate: \"93а\", \"105\", \"12/2\". This is not the cadastral number and does not touch the registry. The settlement's staff change it immediately; the plot's own resident files the same call as a proposal for them to approve, because the number is read by every neighbour and no two plots may share one. The answer says which happened in \"applied\".","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The plot, by identifier.","schema":{"description":"The plot, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"applied":false,"proposal":"7331894216458262"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plot_number":{"description":"What the plot is actually called: `93а`, `105`, `12/2`.","maxLength":32,"type":"string"},"note":{"description":"Why, for whoever decides.","maxLength":2000,"type":["string","null"]}},"required":["plot_number"]},"example":{"plot_number":"plot_number","note":"note"}}}}}},"/api/v1/settlements/{settlement}/parcels/{parcel_id}/objects":{"post":{"operationId":"add_parcel_object","summary":"Adds an object to a parcel's inventory — a borehole, a fence, a greenhouse — so that photographs, diary entries and tasks can be about it. A kind from the closed list and a title are enough; a point, characteristics and tags may come later through edit_parcel_object. For a house or an outbuilding already on the map, give the building's identifier instead of a point.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The parcel the object stands on, by identifier.","schema":{"description":"The parcel the object stands on, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458260","settlement_id":"7331894216458240","parcel_id":"7331894216458241","building_id":null,"title":"Скважина","description":null,"attributes":null,"latitude":60.0192,"longitude":30.6417,"kind":"borehole","section":"water_and_drainage","articles_count":0,"media_count":0,"open_tasks_count":0,"visibility":"residents","installed_on":null,"retired_on":null,"tags":[],"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"description":"What it is, from the closed list: `borehole`, `fence`, `bathhouse`. A section heading such as `structures` is not a kind.","enum":["structures","house","garden_house","bathhouse","garage","carport","utility_block","shed","greenhouse","gazebo","summer_kitchen","workshop","guest_house","water_and_drainage","borehole","dug_well","septic_tank","cesspool","water_treatment","storage_tank","irrigation","drainage","storm_drain","drainage_well","energy_and_connectivity","power_supply","switchboard","generator","solar_panels","gas_supply","gas_holder","boiler","heating","internet","cctv","boundaries_and_surfaces","fence","gate","wicket","path","paved_area","driveway","fill","retaining_wall","terrace","garden","lawn","flower_bed","vegetable_bed","hedge","orchard","pond","compost","fruit_tree","woodland","miscellaneous","playground","pool","barbecue_area","sports_ground","parking","other"],"type":"string"},"title":{"description":"What the person calls it.","maxLength":200,"type":"string"},"description":{"description":"Anything worth knowing about it.","maxLength":5000,"type":["string","null"]},"attributes":{"description":"Characteristics, by the kind's schema: depth and yield for a borehole, length and material for a fence.","type":["array","null"]},"latitude":{"description":"Where it stands, with the longitude. Omit for an object that stands for a building — the building has the contour.","type":["number","null"]},"longitude":{"description":"Where it stands, with the latitude.","type":["number","null"]},"shape":{"description":"How it is drawn where it stands: a `point`, a `rectangle` of a width by a length, or a `circle` of a diameter. A point by default.","enum":["point","rectangle","circle","line","area"],"type":["string","null"]},"width":{"description":"Across, in metres. A circle reads it as its diameter. Required by anything but a point.","type":["number","null"]},"length":{"description":"Along, in metres. A rectangle only.","type":["number","null"]},"bearing":{"description":"Which way it stands, in degrees clockwise from north, for a thing that lies along a fence rather than along a meridian.","type":["number","null"]},"axis":{"description":"Where a `line` runs or what an `area` is traced as, as `[[longitude, latitude], …]` — two points or more for a line, three or more for an area. Ignored by every other shape, which is placed by its centre.","type":["array","null"]},"building_id":{"description":"The cadastral building this object stands for, by identifier, when it is a house or an outbuilding from the registry.","type":["string","null"]},"visibility":{"description":"Who may see it; `residents` by default.","enum":["private","residents","settlement","public"],"type":["string","null"]},"colour_primary":{"description":"What it is drawn in, as `#rrggbb`; omit to draw it as its kind says.","type":["string","null"]},"colour_secondary":{"description":"Its outline, likewise.","type":["string","null"]},"installed_on":{"description":"When it appeared, as `YYYY-MM-DD`.","type":["string","null"]},"tags":{"description":"Free-form tags, as words.","type":["array","null"]}},"required":["kind","title"]},"example":{"kind":"structures","title":"title","description":"description","attributes":[],"latitude":1.5,"longitude":1.5,"shape":"point","width":1.5,"length":1.5,"bearing":1.5,"axis":[],"building_id":"building_id","visibility":"private","colour_primary":"colour_primary","colour_secondary":"colour_secondary","installed_on":"installed_on","tags":[]}}}}},"get":{"operationId":"list_parcel_objects","summary":"Lists the objects on a parcel — the house, the borehole, the fence, the greenhouse — as its resident named them, newest first with keyset pagination. Use it to find what a diary entry or a task is about: the identifiers it returns are what `[object:id]` tokens and task subjects refer to. Narrow to one section, such as `water_and_drainage`, or to one kind. The buildings the registry knows on the plot — the house, the garage — come alongside as `buildings` whether or not anybody named them, so an empty `objects` list is not an empty plot.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The parcel, by identifier.","schema":{"description":"The parcel, by identifier.","type":"string"}},{"name":"kind","in":"query","required":false,"description":"Only one section — `structures`, `water_and_drainage` — with everything in it, or only one kind, such as `borehole`.","schema":{"description":"Only one section — `structures`, `water_and_drainage` — with everything in it, or only one kind, such as `borehole`.","enum":["structures","house","garden_house","bathhouse","garage","carport","utility_block","shed","greenhouse","gazebo","summer_kitchen","workshop","guest_house","water_and_drainage","borehole","dug_well","septic_tank","cesspool","water_treatment","storage_tank","irrigation","drainage","storm_drain","drainage_well","energy_and_connectivity","power_supply","switchboard","generator","solar_panels","gas_supply","gas_holder","boiler","heating","internet","cctv","boundaries_and_surfaces","fence","gate","wicket","path","paved_area","driveway","fill","retaining_wall","terrace","garden","lawn","flower_bed","vegetable_bed","hedge","orchard","pond","compost","fruit_tree","woodland","miscellaneous","playground","pool","barbecue_area","sports_ground","parking","other"],"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"objects":[{"id":"7331894216458260","settlement_id":"7331894216458240","parcel_id":"7331894216458241","building_id":null,"title":"Скважина","description":"Пробурена в 2024, 42 метра.","attributes":{"depth_m":42},"latitude":60.0192,"longitude":30.6417,"kind":"borehole","section":"water_and_drainage","articles_count":2,"media_count":5,"open_tasks_count":1,"visibility":"residents","installed_on":"2024-06-12","retired_on":null,"tags":["вода"],"created_at":"2026-09-09T18:10:00+03:00"}],"cursor":"7331894216458260","buildings":[{"id":"7331894216458270","purpose":"Жилой дом","area_m2":96,"has_geometry":true}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/parcels/{parcel_id}/tasks":{"post":{"operationId":"add_task","summary":"Adds a task to a parcel: what wants doing, by when, about which object, and after which other tasks. A task with steps is a milestone — give the milestone's identifier as the parent, two levels at most. The kind chooses the repeat suggestion the person will see when closing it; nothing is scheduled by itself.","tags":["Task"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The parcel the task is on, by identifier.","schema":{"description":"The parcel the task is on, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458270","settlement_id":"7331894216458240","parcel_id":"7331894216458241","parent_task_id":null,"previous_task_id":null,"subject_type":"object","subject_id":"7331894216458260","assignee_user_id":null,"created_by_user_id":"7331894216458100","title":"Прокачать скважину","notes":null,"children_count":0,"children_done_count":0,"repeat_after_days":180,"kind":"maintenance","status":"todo","visibility":"residents","blocked_by":[],"starts_on":null,"due_on":"2026-09-20","completed_at":null,"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"What wants doing.","maxLength":200,"type":"string"},"notes":{"description":"Details, as text.","maxLength":5000,"type":["string","null"]},"kind":{"description":"What sort of work; `other` by default. The kind sets the default repeat suggestion: `mowing` suggests two weeks, `pruning` a year, `planting` nothing.","enum":["watering","mowing","feeding","treatment","pruning","planting","cleaning","repair","maintenance","inspection","purchase","paperwork","other"],"type":["string","null"]},"parent_task_id":{"description":"The milestone this task is a step of, by identifier. A step cannot have steps of its own.","type":["string","null"]},"subject_type":{"description":"What the task is about — `object`, `media`, `parcel`, `task`, `contact`, `gallery` — with the identifier in subjectId.","enum":["media","object","parcel","task","contact","gallery","article"],"type":["string","null"]},"subject_id":{"description":"The identifier of what the task is about, with subjectType.","type":["string","null"]},"assignee_user_id":{"description":"Who does it, by user identifier. Omit for nobody in particular.","type":["string","null"]},"starts_on":{"description":"When it may start, as `YYYY-MM-DD`.","type":["string","null"]},"due_on":{"description":"When it is due, as `YYYY-MM-DD`.","type":["string","null"]},"visibility":{"description":"Who may see it; `residents` by default.","enum":["private","residents","settlement","public"],"type":["string","null"]},"repeat_after_days":{"description":"How many days after closing it the next one should be suggested for. Omit to take the kind's default; null for no suggestion.","type":["integer","null"]},"depends_on":{"description":"Tasks this one waits for, by identifier, on the same parcel.","type":["array","null"]}},"required":["title"]},"example":{"title":"title","notes":"notes","kind":"watering","parent_task_id":"parent_task_id","subject_type":"media","subject_id":"subject_id","assignee_user_id":"assignee_user_id","starts_on":"starts_on","due_on":"due_on","visibility":"private","repeat_after_days":1,"depends_on":[]}}}}},"get":{"operationId":"list_tasks","summary":"Lists a parcel's tasks newest first with keyset pagination: the open ones by default, or only those in one state. Each task says what it is about, which milestone it is a step of, and which open tasks it is still waiting for — `blocked_by` is read off the dependencies, not stored. Use it to see what is planned on a parcel before adding or closing anything.","tags":["Task"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel_id","in":"path","required":true,"description":"The parcel, by identifier.","schema":{"description":"The parcel, by identifier.","type":"string"}},{"name":"status","in":"query","required":false,"description":"Only tasks in one state. Omit for the open ones — `todo` and `in_progress` together.","schema":{"description":"Only tasks in one state. Omit for the open ones — `todo` and `in_progress` together.","enum":["todo","in_progress","done","cancelled"],"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"tasks":[{"id":"7331894216458270","settlement_id":"7331894216458240","parcel_id":"7331894216458241","parent_task_id":null,"previous_task_id":null,"subject_type":"object","subject_id":"7331894216458260","assignee_user_id":null,"created_by_user_id":"7331894216458100","title":"Прокачать скважину","notes":null,"children_count":0,"children_done_count":0,"repeat_after_days":90,"kind":"maintenance","status":"todo","visibility":"residents","blocked_by":["7331894216458271"],"starts_on":null,"due_on":"2026-09-20","completed_at":null,"created_at":"2026-09-09T18:10:00+03:00"}],"cursor":"7331894216458270"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/parcels/{parcel}":{"get":{"operationId":"show_parcel","summary":"Shows one plot of a settlement as a card with a map: its number, status, area, cadastral number and where it lies. Name the plot the way people do — `105`, `Б-12` or a cadastral number; the row identifier works too. Use it whenever somebody asks where a plot is or what it is.","tags":["Parcel"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel","in":"path","required":true,"description":"The plot as people name it — «105», «Б-12», a cadastral number — or its identifier.","schema":{"description":"The plot as people name it — «105», «Б-12», a cadastral number — or its identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458241","number":"105","plot_number":"105","cadastral_number":"47:01:1314001:3327","status":"built","area":1240,"has_house":true,"has_geometry":true,"settlement":{"slug":"tish-da-glad","name":"Тишь да Гладь"},"buildings":[{"id":"7331894216458300","purpose":"Жилой дом","area_m2":118.4,"has_geometry":true}],"map":{"centre":{"lon":30.6417,"lat":60.0192},"bounds":[[30.641,60.0188],[30.6424,60.0196]],"settlement_bounds":[[30.63,60.01],[30.66,60.03]],"tiles":{"parcels":"/tiles/parcels_public/{z}/{x}/{y}?settlement_id=7331894216458240&v=3","settlements":"/tiles/settlements_public/{z}/{x}/{y}"}}},"artifact":"parcel_card"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/parcels/{parcel}/correct":{"patch":{"operationId":"correct_settlement_parcel","summary":"Corrects one parcel of a settlement from its map: marks a driveway or shared land as `common` so it stops being counted and offered as a plot, and sets the plot number people actually use. Whether the land is the settlement's at all is decided by the boundary, see `set_settlement_boundary`.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"parcel","in":"path","required":true,"description":"The parcel, by identifier.","schema":{"description":"The parcel, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458241","plot_number":"105","status":"common"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"What the parcel is: `common` for a driveway or shared land, `free` for an ordinary plot on offer.","enum":["free","reserved","sold","built","merged","split","common"],"type":["string","null"]},"plot_number":{"description":"What the plot is called here — the number on the gate, not the cadastral one.","maxLength":32,"type":["string","null"]}},"required":[]},"example":{"status":"free","plot_number":"plot_number"}}}}}},"/api/v1/settlements/{settlement}/record-changes":{"get":{"operationId":"list_record_changes","summary":"Lists what has already been changed about one record of a settlement — today a contact in its directory — newest first: which fields, from what to what, who proposed it and who let it in. Use it to answer «who edited this and when», and to see an earlier version of a field. Only what actually happened is here: a correction that was refused or withdrawn changed nothing, so it is not in this list, and there is no list of those for a resident to read either — whoever runs the settlement sees the undecided ones. Visible to whoever may take part in the record — a confirmed resident of the settlement or its staff — because it carries the names of the neighbours who corrected it.","tags":["Proposal"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement whose shard the record lives on, by the identifier from list_settlements.","schema":{"description":"The settlement whose shard the record lives on, by the identifier from list_settlements.","type":"string"}},{"name":"subject_type","in":"query","required":true,"description":"What sort of record: today only a directory contact.","schema":{"description":"What sort of record: today only a directory contact.","enum":["contact","parcel","settlement"],"type":"string"}},{"name":"subject_id","in":"query","required":true,"description":"The record, as list_contacts or show_contact returned it.","schema":{"description":"The record, as list_contacts or show_contact returned it.","minimum":1,"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"How many changes at most, newest first. Twenty by default, fifty at most.","schema":{"description":"How many changes at most, newest first. Twenty by default, fifty at most.","minimum":1,"maximum":50,"type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"changes":[{"id":"7331894216458240","author":"Сергей","reviewer":"Анна","own":false,"note":"Позвонил по старому номеру, ответили, что переехали.","before":{"name":"Кровля Плюс"},"proposed":{"name":"Кровля Плюс и сыновья"},"at":"2026-09-08T14:19:00+03:00"}]}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:read"]}]}},"/api/v1/settlements/{settlement}/reviews":{"get":{"operationId":"list_reviews","summary":"Lists what residents wrote about one directory contact or one registered company: the grade each of them gave, in their own words where they wrote any, and the photographs of the work where they attached any. Use it after list_contacts, with the same identifier, to answer why a contact is graded as they are. Every verdict says whether its author claims to have hired the contact — their own claim — and whether we confirmed them as a resident of the settlement, which is ours. Most verdicts are published to the settlement's residents rather than publicly, so a call without an account may come back empty on a contact that has grades.","tags":["Review"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement whose shard the verdicts live on, by the identifier from list_settlements.","schema":{"description":"The settlement whose shard the verdicts live on, by the identifier from list_settlements.","type":"string"}},{"name":"subject_type","in":"query","required":true,"description":"What sort of subject: a directory contact, or a company from the register.","schema":{"description":"What sort of subject: a directory contact, or a company from the register.","enum":["contact","company"],"type":"string"}},{"name":"subject_id","in":"query","required":true,"description":"The subject, as the directory returned it.","schema":{"description":"The subject, as the directory returned it.","minimum":1,"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The identifier of the last verdict of the previous page. Omit for the first page; the response returns the next one.","schema":{"description":"The identifier of the last verdict of the previous page. Omit for the first page; the response returns the next one.","minimum":1,"type":["integer","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"reviews":[{"id":"7331894216458244","medal":"gold","body":"Крыли крышу в июне, уложились в срок, за год ни одной протечки.","author":"Пётр С.","has_used_service":true,"is_verified_resident":true,"is_verified_work":false,"visibility":"residents","photos":[{"id":"7331894216458245","path":"image/directory/c3/d4/roof-june.webp","caption":"Через год после работы"}],"created_at":"2026-09-07T12:30:00+03:00"},{"id":"7331894216458243","medal":"silver","body":null,"author":"Ирина М.","has_used_service":true,"is_verified_resident":true,"is_verified_work":false,"visibility":"residents","photos":[],"created_at":"2026-09-05T09:14:00+03:00"}],"cursor":"7331894216458243"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}},"post":{"operationId":"post_review","summary":"Records the current account's verdict on a directory contact or a registered company, as one of four grades: gold, silver, bronze, or a fourth grade for \"do not\". Gold and the fourth grade are worth ten times silver and silver ten times bronze, because the top and bottom grades mean conviction and the middle ones mean hesitation. Words are optional — a grade on its own is a complete verdict. Only a confirmed resident of the settlement may grade, one grade per subject: posting again replaces the earlier one rather than adding to it.","tags":["Review"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement this verdict is written in, by the identifier from list_settlements.","schema":{"description":"The settlement this verdict is written in, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458244","settlement_id":"7331894216458240","subject_type":"contact","subject_id":"7331894216458242","medal":"gold","weight":1,"body":"Крыли крышу в июне, уложились в срок, за год ни одной протечки.","has_used_service":true,"is_verified_resident":true,"is_verified_work":false,"visibility":"residents","moderation_status":"published","created_at":"2026-09-07T12:30:00+03:00","updated_at":"2026-09-07T12:30:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_type":{"description":"What is being graded: a directory contact, or a company from the register.","enum":["contact","company"],"type":"string"},"subject_id":{"description":"The identifier of the thing being graded, as the directory returned it.","minimum":1,"type":"integer"},"medal":{"description":"The verdict. Gold and the fourth grade mean conviction; silver and bronze mean \"good, but I am not signing my name to more than that\".","enum":["gold","silver","bronze","dung"],"type":"string"},"body":{"description":"Why, in the person's own words. Optional — a medal alone is a complete verdict.","maxLength":4000,"type":["string","null"]},"has_used_service":{"description":"Whether the person actually hired this contact rather than only having heard about them. Shown as their own claim, not as anything we checked.","type":["boolean","null"]},"visibility":{"description":"Who may read it. Defaults to the settlement's residents.","enum":["private","residents","settlement","public"],"type":["string","null"]}},"required":["subject_type","subject_id","medal"]},"example":{"subject_type":"contact","subject_id":1,"medal":"gold","body":"body","has_used_service":true,"visibility":"private"}}}}},"delete":{"operationId":"withdraw_review","summary":"Removes the current account's own verdict on a directory contact or a registered company, and rewinds the subject's rating as though it had never been given. Use it for a grade that should not have been given at all — the wrong contact, a mistake. To change a grade rather than remove it, call post_review again: it replaces the standing one. Only the author's own verdict can be reached, so this cannot be used on somebody else's.","tags":["Review"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement the verdict was written in, by the identifier from list_settlements.","schema":{"description":"The settlement the verdict was written in, by the identifier from list_settlements.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"withdrawn":true}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_type":{"description":"What sort of subject: a directory contact, or a company from the register.","enum":["contact","company"],"type":"string"},"subject_id":{"description":"The subject, as the directory returned it.","minimum":1,"type":"integer"}},"required":["subject_type","subject_id"]},"example":{"subject_type":"contact","subject_id":1}}}}}},"/api/v1/settlements/{settlement}/tagged/{tag}":{"get":{"operationId":"list_tagged","summary":"Lists everything in a settlement carrying one tag — articles, photographs, objects, tasks, contacts, parcels — newest first with keyset pagination, each with its type, identifier and current title. Tags are the residents' own words: the same «стройка» on a photograph and on a diary entry is what ties them together. Narrow to one type when only, say, the photographs are wanted.","tags":["Common"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"tag","in":"path","required":true,"description":"The tag, as its slug or as typed — «туи», «стройка».","schema":{"description":"The tag, as its slug or as typed — «туи», «стройка».","maxLength":80,"type":"string"}},{"name":"type","in":"query","required":false,"description":"Only things of one type: `article`, `media`, `parcel_object`, `task`, `contact`, `parcel`.","schema":{"description":"Only things of one type: `article`, `media`, `parcel_object`, `task`, `contact`, `parcel`.","enum":["contact","company","article","media","parcel_object","task","parcel","knowledge_article"],"type":["string","null"]}},{"name":"cursor","in":"query","required":false,"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","schema":{"description":"Where the previous page ended, exactly as the previous response returned it. Omit for the first page.","type":["string","null"]}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"tag":{"slug":"стройка","name":"Стройка"},"items":[{"type":"article","id":"7331894216458250","title":"Первый день на участке"},{"type":"media","id":"7331894216458280","title":"Котлован"},{"type":"parcel_object","id":"7331894216458260","title":"Скважина"}],"cursor":"7331894216458300"}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"}}}},"/api/v1/settlements/{settlement}/tasks/{task}":{"patch":{"operationId":"edit_task","summary":"Changes a task on a parcel: its title, notes, kind, assignee, dates, visibility or the repeat it suggests when closed. Send only the fields to change. The parcel, the milestone above it and the thing it is about cannot be changed — a task that belongs elsewhere is a different task. Closing one is complete_task, which also offers the next occurrence.","tags":["Task"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"task","in":"path","required":true,"description":"The task, by identifier.","schema":{"description":"The task, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458280","title":"Покосить у забора","kind":"other","status":"todo","due_on":"2026-09-20","visibility":"residents"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"What is to be done.","maxLength":200,"type":"string"},"notes":{"description":"Anything worth knowing about it; null clears it.","maxLength":5000,"type":["string","null"]},"kind":{"description":"What sort of work it is.","enum":["watering","mowing","feeding","treatment","pruning","planting","cleaning","repair","maintenance","inspection","purchase","paperwork","other"],"type":["string","null"]},"assignee_user_id":{"description":"Who does it, by user identifier; null for nobody in particular.","type":["string","null"]},"starts_on":{"description":"When it may start, as `YYYY-MM-DD`; null clears it.","type":["string","null"]},"due_on":{"description":"When it is due, as `YYYY-MM-DD`; null clears it.","type":["string","null"]},"visibility":{"description":"Who may see it.","enum":["private","residents","settlement","public"],"type":["string","null"]},"repeat_after_days":{"description":"How many days after closing it the next one should be suggested for; null for no suggestion.","type":["integer","null"]}},"required":[]},"example":{"title":"title","notes":"notes","kind":"watering","assignee_user_id":"assignee_user_id","starts_on":"starts_on","due_on":"due_on","visibility":"private","repeat_after_days":1}}}}},"delete":{"operationId":"remove_task","summary":"Removes a task from a parcel for good. Use it for a task that should never have been written — a duplicate, or a plan that changed. A task whose work actually happened is closed with complete_task instead, which records it and offers the next occurrence. Refused while the task has steps of its own, or photographs owned by it.","tags":["Task"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"task","in":"path","required":true,"description":"The task, by identifier.","schema":{"description":"The task, by identifier.","type":"string"}}],"responses":{"200":{"description":"Успех","content":{"application/json":{"example":{"data":{"removed":true}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":[]}}}}},"/api/v1/settlements/{settlement}/tasks/{task}/complete":{"post":{"operationId":"complete_task","summary":"Marks a task done. Pass repeat_after_days to also create the next task of the same kind that many days from today — the task's own repeat_after_days is the suggestion to offer the person, and it is their call each time; omit it for no follow-up. A task already closed is refused. Photographs of the result belong to the task's subject, not to the task.","tags":["Task"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement, by the identifier from list_settlements.","schema":{"description":"The settlement, by the identifier from list_settlements.","type":"string"}},{"name":"task","in":"path","required":true,"description":"The task, by identifier.","schema":{"description":"The task, by identifier.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"task":{"id":"7331894216458270","settlement_id":"7331894216458240","parcel_id":"7331894216458241","parent_task_id":null,"previous_task_id":null,"subject_type":null,"subject_id":null,"assignee_user_id":null,"created_by_user_id":"7331894216458100","title":"Покосить газон","notes":null,"children_count":0,"children_done_count":0,"repeat_after_days":14,"kind":"mowing","status":"done","visibility":"residents","blocked_by":[],"starts_on":null,"due_on":"2026-09-09","completed_at":"2026-09-09T18:10:00+03:00","created_at":"2026-08-26T09:00:00+03:00"},"next":{"id":"7331894216458272","settlement_id":"7331894216458240","parcel_id":"7331894216458241","parent_task_id":null,"previous_task_id":"7331894216458270","subject_type":null,"subject_id":null,"assignee_user_id":null,"created_by_user_id":"7331894216458100","title":"Покосить газон","notes":null,"children_count":0,"children_done_count":0,"repeat_after_days":14,"kind":"mowing","status":"todo","visibility":"residents","blocked_by":[],"starts_on":null,"due_on":"2026-09-23","completed_at":null,"created_at":"2026-09-09T18:10:00+03:00"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"repeat_after_days":{"description":"Create the next task of the same kind this many days from today. Omit or send null for none; the task's own `repeat_after_days` is the suggestion to offer the person.","type":["integer","null"]}},"required":[]},"example":{"repeat_after_days":1}}}}}},"/api/v1/settlements/{settlement}/transfer":{"post":{"operationId":"transfer_settlement","summary":"Moves a settlement into one of the caller's accounts, for a company taking over a settlement somebody else brought in. Allowed only when that company is already recorded on the settlement as its developer or management company, and the settlement's enrichment binding to the company's own website is confirmed — three matched parcels or more. Everything of the settlement moves with it and the residents keep their plots; the previous account's staff do not come along. Refused in words when nothing proves the claim, so read the message rather than retrying.","tags":["Settlement"],"parameters":[{"name":"settlement","in":"path","required":true,"description":"The settlement to take over, by the identifier from list_settlements.","schema":{"description":"The settlement to take over, by the identifier from list_settlements.","type":"string"}}],"responses":{"201":{"description":"Успех","content":{"application/json":{"example":{"data":{"id":"7331894216458240","tenant_id":"7331894216458100","slug":"example-settlement","name":"Пример"}}}}},"422":{"description":"Входные данные не прошли валидацию"},"429":{"description":"Превышен лимит запросов"},"401":{"description":"Нет токена или он недействителен"},"403":{"description":"Токен не несёт нужный скоуп, либо политика отказала"}},"security":[{"oauth2":["mcp:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"description":"The account it moves into, which the caller must own or administer.","maxLength":20,"type":"string"}},"required":["tenant_id"]},"example":{"tenant_id":"tenant_id"}}}}}}}}