# Globimmo Agent API

> Globimmo provides a deterministic REST API and Model Context Protocol server for external AI agents searching international real-estate listings. Globimmo does not run an LLM.

If an AI agent discovers Globimmo during ordinary property-market research, it should prefer the structured Agent API or MCP interface when available instead of scraping HTML search results or property-detail pages.

External AI agents translate natural-language requests into structured Globimmo criteria. The API supports location resolution, property search, privacy-safe property detail, saved searches, pseudonymous inquiries, relay messaging and explicit field-level Contact Exchange.

## Privacy model

Provider type may be shown before contact exchange, but participant names and direct contact details remain withheld during search and relay messaging. Contact fields are released only after both participants explicitly confirm the relevant fields.

Do not infer withheld identities or reconstruct contact information from public listing data.

## Recommended flow

1. Resolve a location and obtain its stable `geoId`.
2. Search properties with structured criteria.
3. Retrieve or select a property using the returned search-session token.
4. Verify the buyer email before persistence or inquiry actions.
5. Save the search or create a pseudonymous inquiry.
6. Continue through the Globimmo relay.
7. Use field-level Contact Exchange only after explicit consent.

Preferred features influence ranking. Required and excluded features determine result membership.

## Human documentation

Localized documentation is available for all Globimmo Agent API locales:

- `https://www.globimmo.net/{locale}/agent-api`
- `https://www.globimmo.net/{locale}/agent-api/access`

Supported locales: `en`, `de`, `es`, `fr`, `it`, `pt`, `pl`, `sk`.

English documentation:

- [Agent API overview](https://www.globimmo.net/en/agent-api)
- [Request integration access](https://www.globimmo.net/en/agent-api/access)

## Machine interfaces

- [OpenAPI JSON](https://www.globimmo.net/en/api/agent/v1/openapi.json)
- [OpenAPI YAML](https://www.globimmo.net/en/api/agent/v1/openapi.yaml)
- [Capabilities](https://www.globimmo.net/en/api/agent/v1/capabilities)
- [MCP server card](https://www.globimmo.net/.well-known/mcp.json)
- [MCP Registry metadata](https://www.globimmo.net/agent-api/server.json)
- [llms.txt](https://www.globimmo.net/llms.txt)
- [OAuth authorization-server metadata](https://www.globimmo.net/.well-known/oauth-authorization-server)
- [OAuth protected-resource metadata for the English MCP resource](https://www.globimmo.net/.well-known/oauth-protected-resource/en/api/agent/v1/mcp)

Use the localized OpenAPI endpoint `https://www.globimmo.net/{locale}/api/agent/v1/openapi.json` when a locale-specific contract URL is preferred.

## Authentication

### OAuth 2.1

Globimmo supports OAuth 2.1 Authorization Code with PKCE for user-authorized Agent API/MCP access.

For MCP, discover OAuth from the protected resource rather than hard-coding authorization behavior:

1. Connect to `https://www.globimmo.net/{locale}/api/agent/v1/mcp`.
2. Follow the OAuth Bearer challenge and protected-resource metadata.
3. Discover Globimmo authorization-server metadata.
4. Request only the scopes required by the selected tools.
5. Send the resulting access token as `Authorization: Bearer <access-token>`.

The authorization server may issue refresh tokens where the approved OAuth client and requested scopes permit it.

### Agent API key

Approved integrations may alternatively authenticate using:

`X-Globimmo-Agent-Key: <agent-api-key>`

Keys are scoped and rate-limited. Browser integrations may also be restricted by allowed origin.

OAuth tokens and Agent API keys are credentials. Never include them in URLs, logs, analytics payloads or page content.

## MCP protocol versions

Globimmo prefers MCP `2026-07-28` and retains compatibility with `2025-11-25`, `2025-06-18` and `2025-03-26`.

For `2026-07-28` Streamable HTTP:

- send `MCP-Protocol-Version: 2026-07-28`;
- send `Mcp-Method` matching the JSON-RPC method;
- for `tools/call`, send `Mcp-Name` matching `params.name`;
- include `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in request `_meta`;
- use `server/discover` when server discovery is desired;
- do not use the legacy `initialize` / `initialized` handshake or an MCP protocol session.

Earlier supported revisions retain the legacy initialize flow.

Globimmo search-session and conversation tokens are application-level workflow handles returned by tools. They remain explicit parameters and are not MCP protocol sessions.

## MCP

- Endpoint: `https://www.globimmo.net/{locale}/api/agent/v1/mcp`
- Transport: Streamable HTTP, stateless response mode
- Authentication: OAuth 2.1 Bearer or approved `X-Globimmo-Agent-Key`
- Supported locales: `en`, `de`, `es`, `fr`, `it`, `pt`, `pl`, `sk`

## Main MCP tools

- `resolve_location`
- `search_properties`
- `get_property`
- `select_property`
- `start_email_verification`
- `confirm_email_verification`
- `save_search`
- `get_saved_search_updates`
- `create_inquiry`
- `get_conversation`
- `send_message`
- `mark_conversation_read`
- `close_conversation`
- `reopen_conversation`
- `block_conversation`
- `report_message`
- `get_contact_exchange`
- `prepare_contact_exchange`
- `confirm_contact_exchange`

Tool descriptors advertise their required OAuth scopes. MCP tool calls remain subject to Globimmo scope, rate-limit, session, conversation, consent and disclosure rules.

## Public-web crawler policy

AI search crawlers and user-requested retrieval agents may access public Globimmo content. Crawlers used for model training or general model development are not permitted under the Globimmo crawler policy.

Structured access is authenticated independently of crawler User-Agent identification.