API Documentation

Overview

A machine-readable description of everything below is served at /openapi.json and linked from every page as rel="service-desc". The endpoints the website's own pages call are not part of this contract: they authenticate with a session cookie, change whenever the interface does, and are not supported for integrations.

Base URL: https://stanovina.me/api/v1. All requests and responses are JSON (photo upload also accepts multipart/form-data). The API operates strictly on your own resources: your profile and the listings you own. Agencies and paid promotions are not accessible through the API.

curl https://stanovina.me/api/v1/me \
  -H "Authorization: Bearer stv_YOUR_KEY"

Using an AI assistant? Skip the HTTP calls and connect it to the MCP server.

AI agents (MCP)

The same API is available as a Model Context Protocol server, so an AI assistant — Claude, Cursor, ChatGPT/Codex, your own agent — can create, edit and publish your listings in conversation. There is nothing to install: it is one URL and the API key you already use.

URL:      https://stanovina.me/mcp
Header:   Authorization: Bearer stv_YOUR_KEY
Protocol: MCP Streamable HTTP (stateless, JSON responses)

Create a key as described under Authentication. Give it only the scopes the assistant needs: a key with listings:read lets it look but not change anything. The server does nothing a REST call with the same key could not do — scopes, rate limits, validation and moderation are the same.

Public search server (no key)

A second, read-only MCP server lets an assistant search the live listings for a user. It needs no key and no account. It has four tools: search_listings, get_listing, find_places and get_market_summary. It never returns seller names, phone numbers or email addresses. The limit is 60 tool calls per minute per IP address.

URL:      https://stanovina.me/mcp/search
Auth:     none
Protocol: MCP Streamable HTTP (stateless, JSON responses)
Card:     https://stanovina.me/.well-known/mcp/server-card.json

Connect

claude mcp add --transport http stanovina https://stanovina.me/mcp \
  --header "Authorization: Bearer stv_YOUR_KEY"

{
  "mcpServers": {
    "stanovina": {
      "url": "https://stanovina.me/mcp",
      "headers": { "Authorization": "Bearer stv_YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "stanovina": {
      "serverUrl": "https://stanovina.me/mcp",
      "headers": { "Authorization": "Bearer stv_YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "stanovina": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://stanovina.me/mcp",
               "--header", "Authorization:${STANOVINA_AUTH}"],
      "env": { "STANOVINA_AUTH": "Bearer stv_YOUR_KEY" }
    }
  }
}

[mcp_servers.stanovina]
url = "https://stanovina.me/mcp"
bearer_token_env_var = "STANOVINA_API_KEY"

curl -X POST https://stanovina.me/mcp \
  -H "Authorization: Bearer stv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Clients that only accept OAuth sign-in (for example the “custom connector” form in the Claude and ChatGPT web apps) cannot send a bearer header and are not supported yet. Use one of the clients above.

What to ask

Create a listing on Stanovina: 2-bedroom apartment for sale in Budva,
62 m², €185,000, description and photos from the files in this folder.
Save it as a draft and show me before you publish.

The server tells the assistant the order of operations when it connects, so you do not need to explain the API. Photos are attached from public https URLs; an assistant cannot upload files through MCP, so host the images first (or use the multipart upload over REST). The assistant cannot publish what the account cannot: a verified phone number and at least one photo are still required.

Tools

A failed call comes back as a tool result marked as an error, with the usual error body. A wrong or revoked key is refused when the client connects, and counts toward the same 1-hour IP ban as REST requests.

Authentication

Every request must carry an API key in the Authorization header:Bearer stv_.... Keys are created in your dashboard → API keys section. API access is enabled per account (or per agency) by our team on request — if you don't have it yet, email [email protected] with a short description of your integration.

• The full key is shown once, at creation. Only its hash is stored.
• Keys act with the identity and permissions of the account that created them.
• Agency keys. A key created by a member of an agency belongs to the agency. Every member sees the same keys in the dashboard and can revoke any of them, and a key keeps working after the member who created it leaves. It reaches all of the agency's listings, not only the creator's own. A listing created with it is filed under the agency and owned by the member who made the key — or by the agency owner once that member has left. API access for an agency key is switched on for the agency as a whole. Users who are not in an agency keep personal keys, which reach only their own listings. GET /api/v1/me returns a scope field that tells the two apart.
• Revoking a key (dashboard) is immediate and permanent.
• If API access is switched off for the account, existing keys stop working (HTTP 403, code api_access_disabled) but are not deleted; they resume if access is re-enabled.

Scopes

Each key carries a set of scopes chosen at creation. A write scope implies the matching read scope. A request outside the key's scopes answers 403 insufficient_scope.

The reference-data endpoints accept any valid key regardless of scopes.

Rate limits

Exceeding a budget answers 429 rate_limited with a Retry-After header (seconds).

Errors

Every error has one shape. field appears on validation errors and names the offending field; retryAfter (seconds) appears on 429s.

{
  "error": {
    "code": "validation_error",
    "message": "price must be a finite number greater than zero",
    "field": "price"
  }
}

Listing lifecycle

A listing is created as a DRAFT — invisible to everyone but you. When you publish it, it either goes live immediately (ACTIVE, for accounts marked trusted) or enters review (PENDING_MODERATION) exactly as on the website. Publishing requires at least one photo and a verified phone number on the account — the number is displayed publicly on the listing.

DRAFT ──publish──▶ PENDING_MODERATION ──approved──▶ ACTIVE
                     │                                 │
                     └──rejected──▶ REJECTED ──publish─┘ (resubmit)

ACTIVE ⇄ SOLD / RENTED   (owner, via /status)

• Editing a DRAFT keeps it a draft — publishing is always explicit.
• Editing a live listing keeps it live; editing one still in review re-queues it (unless the account is trusted).
• If a listing is rejected, moderationNote carries the reason; fix and publish again.
• Only DRAFT listings can be deleted via the API.

Profile

curl -X PATCH https://stanovina.me/api/v1/me \
  -H "Authorization: Bearer stv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Ana", "hasWhatsapp": true}'

Listings

curl -X POST https://stanovina.me/api/v1/listings \
  -H "Authorization: Bearer stv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Dvosoban stan, Budva",
    "description": "Stan od 55 m2 na 200 m od mora...",
    "propertyType": "APARTMENT",
    "listingType": "SALE",
    "countryId": "COUNTRY_ID",
    "cityId": "CITY_ID",
    "price": 120000,
    "area": 55,
    "rooms": 2,
    "buildStage": "UNDER_CONSTRUCTION",
    "completionYear": 2027,
    "completionQuarter": 2,
    "hasBalcony": true,
    "imageUrls": ["https://example.com/photo1.jpg"],
    "publish": true
  }'

Photos

A listing holds up to 20 photos, each up to 10 MB, in image/jpeg, image/png, image/webp or image/avif. Photos are ordered; the photo at order 0 is the main photo — it fronts the listing everywhere. At least one photo is required to publish.

curl -X POST https://stanovina.me/api/v1/listings/LISTING_ID/images \
  -H "Authorization: Bearer stv_YOUR_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

curl -X POST https://stanovina.me/api/v1/listings/LISTING_ID/images \
  -H "Authorization: Bearer stv_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/a.jpg", "https://example.com/b.jpg"]}'

Reference data

Location ids for listing payloads. Any valid key may call these. Hierarchy: country → municipality → city → district; cityId and districtId are optional on a listing, countryId is required.

Enums