Zlar API and MCP server

Authentication

The base URL is https://zlar.app/api/v1. Create an organization API key in Settings, then API keys, and send it on every request as Authorization: Bearer <key>. Keys are scoped to one organization and stop working if the organization leaves a plan that includes API access.

curl https://zlar.app/api/v1/condominiums?limit=20 \
  -H "Authorization: Bearer $ZLAR_API_KEY"

{
  "data": [
    {
      "id": "01J9Z3K8M2X4V6B8N0Q2R4T6W8",
      "name": "Edifício Atlântico",
      "address": "Rua das Flores 12",
      "city": "Lisboa",
      "country": "PT",
      "totalUnits": 24,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

Endpoints

• GET /api/v1/condominiums: list condominiums
• GET /api/v1/condominiums/{id}: get one condominium
• GET /api/v1/condominiums/{id}/owners: list a condominium's owners
• GET /api/v1/condominiums/{id}/units: list a condominium's units
• GET /api/v1/condominiums/{id}/fiscal-years: list a condominium's fiscal years
• GET /api/v1/condominiums/{id}/expenses: list a condominium's expenses
• GET /api/v1/fiscal-years/{id}/quotas: list a fiscal year's quotas
• GET /api/v1/fiscal-years/{id}/payments: list a fiscal year's payments

List endpoints are paginated. Pass limit (1 to 100, default 20) and, for the next page, the opaque cursor returned in pagination.nextCursor. When pagination.hasMore is false you have reached the last page. New fields may be added to responses at any time, so ignore fields you do not recognise.

Errors

Every error is a JSON object with a machine-readable code, a human-readable message, a hint on how to resolve it, and the requestId that is also returned in the X-Request-Id header. Quote the request id when you contact support.

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid or missing API key.",
    "hint": "Send an organization API key as 'Authorization: Bearer <key>'. Create or rotate keys in Settings > API keys.",
    "requestId": "01J9Z3K8M2X4V6B8N0Q2R4T6W8"
  }
}

• 400 INVALID_CURSOR: the pagination cursor is malformed
• 401 API_KEY_INVALID: the API key is missing, invalid, revoked, or expired
• 403 FEATURE_NOT_AVAILABLE: the organization's plan does not include API access
• 404 CONDOMINIUM_NOT_FOUND, 404 FISCAL_YEAR_NOT_FOUND: the resource does not exist in the key's organization
• 404 NOT_FOUND: the endpoint does not exist
• 405 METHOD_NOT_ALLOWED: the endpoint exists but does not accept this HTTP method
• 429 RATE_LIMITED: too many requests; wait for the time in the Retry-After header
• 500 INTERNAL_ERROR: an unexpected error on our side; retry later

Rate limits

Each API key can make 120 requests per fixed 60-second window. Responses from the data endpoints carry a RateLimit-Policy header describing the quota. Once a request has been counted against a key, the response also carries a RateLimit header with the remaining requests and the seconds until the window resets, following the IETF RateLimit header fields draft. A 429 response adds a Retry-After header.

RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=119;t=42

Versioning and deprecation

The API version is part of the URL path (/api/v1). Additive changes, such as new fields or new endpoints, ship without a version change. Breaking changes ship under a new path, such as /api/v2.

No operation is deprecated today. When one is, it will be marked as deprecated in the OpenAPI document and will respond with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 6 months before it is removed, for example:

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT

MCP server

AI agents can connect to the Zlar MCP server at https://zlar.app/api/mcp. It implements MCP protocol version 2026-07-28 with OAuth 2.1: the client registers dynamically, the user signs in and consents, and the resulting token is limited to that user's role and organization. The server is read-only and mirrors the REST API reads.