Developer portal

EVLO.AZ API, OAuth 2.1 и MCP — официальный канал для AI-агентов и интеграций

REST API (v1)

Версионированный OpenAPI-контракт. Все ответы — JSON, ошибки в машиночитаемом формате:

Все примеры используют реальный публичный API (через same-origin proxy). Внутренние адреса не показываются.

GET /api/evlo/v1/catalog/listings?transactionType=sale&priceMax=200000

# Пример ответа:
{ "items": [ /* ... */ ], "total": <n>, "page": 1, "limit": 20 }

OpenAPI-спецификация (openapi.json)Интерактивный Swagger UI

Авторизация OAuth 2.1

Для всех write-операций обязателен authorization-code + PKCE (S256). Access-токены короткоживущие, refresh-токены ротируются. Пользователь видит режим и полномочия на экране согласия и подтверждает по OTP.

Эндпоинты:

POST /api/evlo/v1/oauth/register        # dynamic client registration (RFC 7591)
GET  /api/evlo/v1/oauth/authorize       # consent screen (response_type=code, PKCE S256 required)
POST /api/evlo/v1/oauth/token           # authorization_code | refresh_token
GET  /api/evlo/v1/.well-known/oauth-authorization-server
GET  /api/evlo/v1/.well-known/oauth-protected-resource

# Autonomy mode is chosen by the user on the consent screen:
#   READ_ONLY | DRAFT_ONLY | CONFIRM_PUBLISH (default) | DELEGATED_AUTONOMY

Remote MCP endpoint

Model Context Protocol (JSON-RPC 2.0, Streamable HTTP). Те же domain-сервисы, что и REST — без параллельной бизнес-логики. Auth: OAuth Bearer token.

POST /api/evlo/v1/mcp
Authorization: Bearer <access_token>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search_listings","arguments":{"transactionType":"rent","limit":5}}}

17 tools

`search_listings`	Search active listings with filters
`get_listing`	Get one public listing card
`compare_listings`	Compare 2–5 listings side by side
`get_taxonomy`	Valid types, renovation values, place slugs
`get_listing_requirements`	Required fields, media limits, moderation rules
`get_my_listings`	Listings of the connected user
`create_listing_draft`	Create a draft for the connected user
`get_listing_draft`	Get a draft with version and validation
`update_listing_draft`	Update a draft (optimistic concurrency)
`validate_listing_draft`	Missing fields and warnings
`preview_listing`	Preview the card exactly as users will see it
`submit_listing_for_review`	Submit to moderation (mode-aware)
`publish_listing`	Publish (DELEGATED_AUTONOMY; same moderation)
`pause_listing`	Pause an active listing (reversible)
`mark_listing_closed`	Mark as sold or rented
`get_agent_grant`	Current grant: mode, scopes, limits
`get_agent_action_status`	Status of an async operation

Формат ошибок

Все ошибки имеют структуру {code, message}; отказы по scope/лимитам возвращаются отдельными кодами (scope_denied, daily_action_limit, version_conflict и др.).

HTTP 403
{"code":"scope_denied","message":"Scope listings:publish is not granted","requiredScope":"listings:publish"}

HTTP 409
{"code":"version_conflict","message":"Listing was modified concurrently","currentVersion":4}

Changelog

v1 (2026-08) — первый релиз: каталог, черновики объявлений, медиа, модерация, AI-agent access (OAuth 2.1 + PKCE, 4 режима, MCP, идемпотентная запись)

Контакт

По вопросам интеграции: info@aimarket.az · AI agents