Skip to main content
Version: 1.0.0

Uysot Open API

Public contract for the Uysot Open API. Every endpoint lives under the /v1/open-api/* path and is authenticated with the X-Open-Api-Token header.

This specification is the source of truth for integrators: it lists every Open API endpoint, the authority each one requires, the request/response payloads and all enums you may receive.

Endpoints that are not under /v1/open-api/* (internal read endpoints, the admin/CRM UI APIs, etc.) are intentionally out of scope and not documented here.

Authentication & rate limiting​

Every /v1/open-api/** endpoint is authenticated with the X-Open-Api-Token request header. An invalid, revoked or expired token returns 401 Unauthorized. Tokens are rate limited to 60 requests per minute — exceeding the limit returns 429 Too Many Requests.

A token is either a personal access token a company issues for its own integration, or an OAuth 2.0 access token a third-party application obtains per company through POST /v1/open-api/oauth/token. The OAuth endpoints (/oauth/token, /oauth/revoke, /oauth/register), the two /.well-known/* discovery documents and the MCP endpoint POST /v1/mcp take no X-Open-Api-Token, and their responses are not wrapped in the standard envelope — each follows the shape its own RFC prescribes.

MCP (Model Context Protocol)​

POST /v1/mcp exposes the company's data to MCP clients such as Claude. It is a Streamable-HTTP JSON-RPC endpoint authenticated with Authorization: Bearer <access token> — the one place in this API that uses Authorization rather than X-Open-Api-Token. A client discovers how to authenticate on its own: the 401 carries a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource, which in turn names the authorization server described by /.well-known/oauth-authorization-server. A client with no credentials of its own registers one with POST /v1/open-api/oauth/register (RFC 7591); such a client is always public (no client_secret, PKCE required) and can only ever hold the single grant PERMISSION_OPEN_API_MCP:READ.

Host​

https://api.service.app.uysot.uz serves everything in this reference — the resource endpoints, the OAuth endpoints, the /.well-known/* discovery documents and the MCP endpoint alike. There is no second host to configure.

An MCP client needs nothing but POST /v1/mcp: the discovery documents it reads from there advertise this same host for authorization, token exchange and registration.

Authorization (permissions & scopes)​

Authorization is expressed as grants — a pair of (permission, scope). A request is authorized when the token holds the specific permission:scope required by the endpoint. A request that lacks the required grant returns 403 Forbidden.

Permissions (resource domains):

  • PERMISSION_OPEN_API_LEAD — leads (also gates pipe, CRM-field and refusal-reason reads)
  • PERMISSION_OPEN_API_LEAD_NOTE — lead notes
  • PERMISSION_OPEN_API_LEAD_TASK — lead tasks
  • PERMISSION_OPEN_API_CONTRACT — contracts (also gates contract-field, monthly-payment, house and flat reads)
  • PERMISSION_OPEN_API_CONTRACT_PAYMENT — contract payments
  • PERMISSION_OPEN_API_BOOKING — bookings (reservations), read-only
  • PERMISSION_OPEN_API_CALL — conversation records (calls & meetings) and their analyses
  • PERMISSION_OPEN_API_MCP — the MCP endpoint POST /v1/mcp (READ only)

Scopes (actions): READ, SAVE, DELETE.

The reference endpoints require no grant at all — any valid, non-expired token may call them: POST /v1/open-api/employee/filter (and its deprecated GET /v1/open-api/employee predecessor), GET /v1/open-api/currency, and the four /v1/open-api/address/* endpoints.

Response envelope​

Every successful response is wrapped in a ResponseData object. Paginated list endpoints return a PageableData object as data.

Asynchronous writes (requestId)​

Lead / lead-note / lead-task write endpoints (create, update, close, delete) and both call-history writes (submitting a conversation, uploading an analysis) are processed asynchronously. The endpoint validates the request, enqueues it, and immediately responds 200 with a requestId — the data is not persisted yet at that point. Poll GET /v1/open-api/request/{requestId} until the status is SUCCESS or FAILED.

Authentication​

Your raw Open API token. Required on every endpoint.

Security Scheme Type:

apiKey

Header parameter name:

X-Open-Api-Token