{ "openapi": "3.1.0", "info": { "title": "MOVA public API", "version": "1.0.0", "description": "Personal access keys (`Authorization: Bearer mova_pat_...`) created in the MOVA app (Settings › Integrations). Each key only reaches the routes of its scopes; nothing can be deleted. Money is an integer in the currency's minor unit, as a string, plus the ISO 4217 code. Create with PUT and an id you generate (UUID)." }, "servers": [ { "url": "https://api.movapro.app" } ], "paths": { "/appointments": { "get": { "operationId": "getAppointments", "summary": "GET /appointments", "description": "Scope: `agenda:read` — Read the schedule (appointments).", "tags": [ "agenda" ], "security": [ { "bearer": [] }, { "oauth2": [ "agenda:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "startsAt": { "type": "string", "format": "date-time" }, "startsLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "localDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "durationMinutes": { "type": "integer" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "price": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "tip": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commission": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "commissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "commissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "commissionOnTip": { "type": "boolean" }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "reminderMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "bookedBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] }, "version": { "type": "integer", "minimum": 1 }, "missingPrice": { "type": "boolean" }, "partnerClient": { "type": "object", "properties": { "label": { "type": "string" }, "phoneE164": { "type": "string" } }, "required": [ "label" ] }, "sourceLabel": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assistant" ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "username" ] } }, "required": [ "id", "clientId", "startsAt", "startsLocal", "endsAt", "timezone", "localDate", "durationMinutes", "city", "region", "country", "price", "tip", "commission", "commissionKind", "commissionPercentBp", "commissionFixedMinor", "commissionOnTip", "sourceId", "status", "reminderMinutes", "notes", "createdAt", "updatedAt" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/appointments/{id}": { "get": { "operationId": "getAppointmentsId", "summary": "GET /appointments/{id}", "description": "Scope: `agenda:read` — Read the schedule (appointments).", "tags": [ "agenda" ], "security": [ { "bearer": [] }, { "oauth2": [ "agenda:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "startsAt": { "type": "string", "format": "date-time" }, "startsLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "localDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "durationMinutes": { "type": "integer" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "price": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "tip": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commission": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "commissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "commissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "commissionOnTip": { "type": "boolean" }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "reminderMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "bookedBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] }, "version": { "type": "integer", "minimum": 1 }, "missingPrice": { "type": "boolean" }, "partnerClient": { "type": "object", "properties": { "label": { "type": "string" }, "phoneE164": { "type": "string" } }, "required": [ "label" ] }, "sourceLabel": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assistant" ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "username" ] } }, "required": [ "id", "clientId", "startsAt", "startsLocal", "endsAt", "timezone", "localDate", "durationMinutes", "city", "region", "country", "price", "tip", "commission", "commissionKind", "commissionPercentBp", "commissionFixedMinor", "commissionOnTip", "sourceId", "status", "reminderMinutes", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "patchAppointmentsId", "summary": "PATCH /appointments/{id}", "description": "Scope: `appointments:write` — Book and reschedule appointments (date, time, price, status). Never delete.", "tags": [ "appointments" ], "security": [ { "bearer": [] }, { "oauth2": [ "appointments:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" }, "startsLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "tipMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "commissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "commissionPercentBp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "commissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,14}$" }, { "type": "null" } ] }, "commissionOnTip": { "type": "boolean" }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "reminderMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "allowConflict": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "startsAt": { "type": "string", "format": "date-time" }, "startsLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "endsAt": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "localDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "durationMinutes": { "type": "integer" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "price": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "tip": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commission": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "commissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "commissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "commissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "commissionOnTip": { "type": "boolean" }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "reminderMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "bookedBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] }, "version": { "type": "integer", "minimum": 1 }, "missingPrice": { "type": "boolean" }, "partnerClient": { "type": "object", "properties": { "label": { "type": "string" }, "phoneE164": { "type": "string" } }, "required": [ "label" ] }, "sourceLabel": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "assistant" ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "username" ] } }, "required": [ "id", "clientId", "startsAt", "startsLocal", "endsAt", "timezone", "localDate", "durationMinutes", "city", "region", "country", "price", "tip", "commission", "commissionKind", "commissionPercentBp", "commissionFixedMinor", "commissionOnTip", "sourceId", "status", "reminderMinutes", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putAppointmentsId", "summary": "PUT /appointments/{id}", "description": "Scope: `appointments:write` — Book and reschedule appointments (date, time, price, status). Never delete.", "tags": [ "appointments" ], "security": [ { "bearer": [] }, { "oauth2": [ "appointments:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" }, "startsLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 1440 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "priceMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "tipMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "commissionKind": { "type": "string", "enum": [ "percent", "fixed" ] }, "commissionPercentBp": { "type": "integer", "minimum": 0, "maximum": 10000 }, "commissionFixedMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "commissionOnTip": { "type": "boolean" }, "sourceId": { "type": "string", "format": "uuid" }, "tripId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "reminderMinutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "notes": { "type": "string", "minLength": 1, "maxLength": 2000 }, "allowConflict": { "type": "boolean" } }, "required": [ "clientId", "startsLocal", "timezone", "durationMinutes", "currency", "priceMinor" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients": { "get": { "operationId": "getClients", "summary": "GET /clients", "description": "Scope: `clients:read` — Read clients (name, phone, notes) and sources.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:read" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "blocked" ] } }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phoneE164": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "firstContactOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "name", "phoneE164", "city", "region", "country", "sourceId", "firstContactOn", "status", "notes", "createdAt", "updatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients/{id}": { "get": { "operationId": "getClientsId", "summary": "GET /clients/{id}", "description": "Scope: `clients:read` — Read clients (name, phone, notes) and sources.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phoneE164": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "firstContactOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "name", "phoneE164", "city", "region", "country", "sourceId", "firstContactOn", "status", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "patchClientsId", "summary": "PATCH /clients/{id}", "description": "Scope: `clients:write` — Add and change clients. Never delete.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "phoneE164": { "anyOf": [ { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "firstContactOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phoneE164": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "firstContactOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "name", "phoneE164", "city", "region", "country", "sourceId", "firstContactOn", "status", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putClientsId", "summary": "PUT /clients/{id}", "description": "Scope: `clients:write` — Add and change clients. Never delete.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "phoneE164": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "sourceId": { "type": "string", "format": "uuid" }, "firstContactOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "status": { "type": "string", "enum": [ "active", "blocked" ] }, "notes": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients/{id}/stats": { "get": { "operationId": "getClientsIdStats", "summary": "GET /clients/{id}/stats", "description": "Scope: `clients:read` — Read clients (name, phone, notes) and sources.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" }, "lastContactOn": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, { "type": "null" } ] }, "countsByStatus": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "count" ] } }, "revenue": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceMinor": { "type": "string", "pattern": "^\\d+$" }, "tipsMinor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "currency", "serviceMinor", "tipsMinor" ] } } }, "required": [ "clientId", "lastContactOn", "countsByStatus", "revenue" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients/history": { "get": { "operationId": "getClientsHistory", "summary": "GET /clients/history", "description": "Scope: `clients:read` — Read clients (name, phone, notes) and sources.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:read" ] } ], "parameters": [ { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientsCount": { "type": "integer", "minimum": 0 }, "appointmentsCount": { "type": "integer", "minimum": 0 }, "countsByStatus": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "count" ] } }, "revenue": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceMinor": { "type": "string", "pattern": "^\\d+$" }, "tipsMinor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "currency", "serviceMinor", "tipsMinor" ] } }, "clients": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" }, "appointmentsCount": { "type": "integer", "minimum": 0 }, "lastOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, "required": [ "clientId", "appointmentsCount", "lastOn" ] } } }, "required": [ "clientsCount", "appointmentsCount", "countsByStatus", "revenue", "clients" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/expense-categories": { "get": { "operationId": "getExpenseCategories", "summary": "GET /expense-categories", "description": "Scope: `finance:read` — Read expenses, other income and reports.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:read" ] } ], "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "hotel", "flight", "transportation", "fuel", "food", "advertising", "commission", "other", "custom" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "name", "archived", "createdAt" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/expenses": { "get": { "operationId": "getExpenses", "summary": "GET /expenses", "description": "Scope: `finance:read` — Read expenses, other income and reports.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:read" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "tripId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "categoryId": { "type": "string", "format": "uuid" }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "spentOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "categoryId", "amount", "spentOn", "tripId", "sourceId", "notes", "createdAt", "updatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/expenses/{id}": { "patch": { "operationId": "patchExpensesId", "summary": "PATCH /expenses/{id}", "description": "Scope: `finance:write` — Log and change expenses and other income. Never delete.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categoryId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "spentOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "categoryId": { "type": "string", "format": "uuid" }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "spentOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "categoryId", "amount", "spentOn", "tripId", "sourceId", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putExpensesId", "summary": "PUT /expenses/{id}", "description": "Scope: `finance:write` — Log and change expenses and other income. Never delete.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categoryId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "spentOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "type": "string", "format": "uuid" }, "sourceId": { "type": "string", "format": "uuid" }, "notes": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "categoryId", "currency", "amountMinor", "spentOn" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hotels": { "get": { "operationId": "getHotels", "summary": "GET /hotels", "description": "Scope: `trips:read` — Read trips and hotels.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:read" ] } ], "parameters": [ { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sameCity": { "type": "boolean" } }, "required": [ "id", "name", "address", "city", "region", "country", "notes", "createdAt", "updatedAt", "sameCity" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/hotels/{id}": { "patch": { "operationId": "patchHotelsId", "summary": "PATCH /hotels/{id}", "description": "Scope: `trips:write` — Add and change trips and hotels. Never delete.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "address": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "address", "city", "region", "country", "notes", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putHotelsId", "summary": "PUT /hotels/{id}", "description": "Scope: `trips:write` — Add and change trips and hotels. Never delete.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "address": { "type": "string", "minLength": 1, "maxLength": 300 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "notes": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/report-drafts": { "post": { "operationId": "postReportDrafts", "summary": "POST /report-drafts", "description": "Scope: `reports:draft` — Leave a community report draft for the user to confirm in the app.", "tags": [ "reports" ], "security": [ { "bearer": [] }, { "oauth2": [ "reports:draft" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneE164": { "type": "string", "minLength": 1, "maxLength": 40 }, "defaultCountry": { "type": "string", "pattern": "^[A-Z]{2}$" }, "category": { "type": "string", "enum": [ "scam", "suspicious_behavior", "identity_mismatch", "no_show", "false_information", "other" ] }, "comment": { "type": "string", "minLength": 10, "maxLength": 300 } }, "required": [ "phoneE164", "category", "comment" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "expiresAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/sources": { "get": { "operationId": "getReportsSources", "summary": "GET /reports/sources", "description": "Scope: `finance:read` — Read expenses, other income and reports.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "website", "instagram", "secretary", "referral", "recurring", "other", "custom" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "investment": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false } }, "clientsGenerated": { "type": "integer", "minimum": 0 }, "revenue": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false } } }, "required": [ "sourceId", "kind", "name", "archived", "investment", "clientsGenerated", "revenue" ] } }, "assistants": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false } } }, "required": [ "userId", "displayName", "username", "revenue" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/summary": { "get": { "operationId": "getReportsSummary", "summary": "GET /reports/summary", "description": "Scope: `finance:read` — Read expenses, other income and reports.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "tripId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceMinor": { "type": "string", "pattern": "^\\d+$" }, "tipsMinor": { "type": "string", "pattern": "^\\d+$" }, "otherRevenueMinor": { "type": "string", "pattern": "^\\d+$" }, "commissionsMinor": { "type": "string", "pattern": "^\\d+$" }, "expensesMinor": { "type": "string", "pattern": "^\\d+$" }, "profitMinor": { "type": "string", "pattern": "^-?\\d+$" }, "forecastMinor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "currency", "serviceMinor", "tipsMinor", "otherRevenueMinor", "commissionsMinor", "expensesMinor", "profitMinor", "forecastMinor" ] } }, "countsByStatus": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "count" ] } } }, "required": [ "totals", "countsByStatus" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/revenues": { "get": { "operationId": "getRevenues", "summary": "GET /revenues", "description": "Scope: `finance:read` — Read expenses, other income and reports.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:read" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "tripId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "receivedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "amount", "receivedOn", "tripId", "description", "createdAt", "updatedAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/revenues/{id}": { "patch": { "operationId": "patchRevenuesId", "summary": "PATCH /revenues/{id}", "description": "Scope: `finance:write` — Log and change expenses and other income. Never delete.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "receivedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "string", "pattern": "^-?\\d+$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ], "additionalProperties": false }, "receivedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "displayName": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "displayName", "username" ] } }, "required": [ "id", "amount", "receivedOn", "tripId", "description", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putRevenuesId", "summary": "PUT /revenues/{id}", "description": "Scope: `finance:write` — Log and change expenses and other income. Never delete.", "tags": [ "finance" ], "security": [ { "bearer": [] }, { "oauth2": [ "finance:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amountMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "receivedOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "tripId": { "type": "string", "format": "uuid" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "currency", "amountMinor", "receivedOn" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/security/lookup": { "post": { "operationId": "postSecurityLookup", "summary": "POST /security/lookup", "description": "Scope: `lookup:read` — Look up a phone number in community reports (same limits as the app).", "tags": [ "lookup" ], "security": [ { "bearer": [] }, { "oauth2": [ "lookup:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneE164": { "type": "string", "minLength": 1, "maxLength": 40 }, "defaultCountry": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "phoneE164" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "comment": { "type": "string" }, "createdOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "isMine": { "type": "boolean" } }, "required": [ "id", "comment", "createdOn", "isMine" ], "additionalProperties": false } }, "lookupsLeftToday": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "count", "reports" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/security/reports": { "post": { "operationId": "postSecurityReports", "summary": "POST /security/reports", "description": "Scope: `reports:write` — Publish community reports on the user's behalf (requires the user's one-time acceptance).", "tags": [ "reports" ], "security": [ { "bearer": [] }, { "oauth2": [ "reports:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneE164": { "type": "string", "minLength": 1, "maxLength": 40 }, "defaultCountry": { "type": "string", "pattern": "^[A-Z]{2}$" }, "category": { "type": "string", "enum": [ "scam", "suspicious_behavior", "identity_mismatch", "no_show", "false_information", "other" ] }, "comment": { "type": "string", "minLength": 10, "maxLength": 300 } }, "required": [ "phoneE164", "category", "comment" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, "required": [ "id", "createdOn" ], "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sources": { "get": { "operationId": "getSources", "summary": "GET /sources", "description": "Scope: `clients:read` — Read clients (name, phone, notes) and sources.", "tags": [ "clients" ], "security": [ { "bearer": [] }, { "oauth2": [ "clients:read" ] } ], "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "website", "instagram", "secretary", "referral", "recurring", "other", "custom" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "name", "archived", "createdAt" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trips": { "get": { "operationId": "getTrips", "summary": "GET /trips", "description": "Scope: `trips:read` — Read trips and hotels.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string" }, "hotelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "checkInLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkOutLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCommissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "defaultCommissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "defaultCommissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "defaultCommissionCurrency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "city", "region", "country", "startsOn", "endsOn", "timezone", "hotelId", "checkInLocal", "checkInAt", "checkOutLocal", "checkOutAt", "transport", "defaultCommissionKind", "defaultCommissionPercentBp", "defaultCommissionFixedMinor", "defaultCommissionCurrency", "defaultCommissionOnTip", "notes", "completedAt", "createdAt", "updatedAt" ] } } }, "required": [ "items" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trips/{id}": { "get": { "operationId": "getTripsId", "summary": "GET /trips/{id}", "description": "Scope: `trips:read` — Read trips and hotels.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string" }, "hotelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "checkInLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkOutLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCommissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "defaultCommissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "defaultCommissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "defaultCommissionCurrency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "city", "region", "country", "startsOn", "endsOn", "timezone", "hotelId", "checkInLocal", "checkInAt", "checkOutLocal", "checkOutAt", "transport", "defaultCommissionKind", "defaultCommissionPercentBp", "defaultCommissionFixedMinor", "defaultCommissionCurrency", "defaultCommissionOnTip", "notes", "completedAt", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "patchTripsId", "summary": "PATCH /trips/{id}", "description": "Scope: `trips:write` — Add and change trips and hotels. Never delete.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{2}$" }, { "type": "null" } ] }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "hotelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "checkInLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkOutLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "defaultCommissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "defaultCommissionPercentBp": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "defaultCommissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,14}$" }, { "type": "null" } ] }, "defaultCommissionCurrency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "completed": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string" }, "hotelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "checkInLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkOutLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCommissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "defaultCommissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "defaultCommissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "defaultCommissionCurrency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "city", "region", "country", "startsOn", "endsOn", "timezone", "hotelId", "checkInLocal", "checkInAt", "checkOutLocal", "checkOutAt", "transport", "defaultCommissionKind", "defaultCommissionPercentBp", "defaultCommissionFixedMinor", "defaultCommissionCurrency", "defaultCommissionOnTip", "notes", "completedAt", "createdAt", "updatedAt" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "putTripsId", "summary": "PUT /trips/{id}", "description": "Scope: `trips:write` — Add and change trips and hotels. Never delete.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "hotelId": { "type": "string", "format": "uuid" }, "checkInLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "checkOutLocal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, "transport": { "type": "string", "minLength": 1, "maxLength": 200 }, "defaultCommissionKind": { "type": "string", "enum": [ "percent", "fixed" ] }, "defaultCommissionPercentBp": { "type": "integer", "minimum": 0, "maximum": 10000 }, "defaultCommissionFixedMinor": { "type": "string", "pattern": "^\\d{1,14}$" }, "defaultCommissionCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "startsOn", "endsOn", "timezone" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Already existed (same id): returned as is" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trips/{id}/summary": { "get": { "operationId": "getTripsIdSummary", "summary": "GET /trips/{id}/summary", "description": "Scope: `trips:read` — Read trips and hotels.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "serviceMinor": { "type": "string", "pattern": "^\\d+$" }, "tipsMinor": { "type": "string", "pattern": "^\\d+$" }, "otherRevenueMinor": { "type": "string", "pattern": "^\\d+$" }, "commissionsMinor": { "type": "string", "pattern": "^\\d+$" }, "expensesMinor": { "type": "string", "pattern": "^\\d+$" }, "profitMinor": { "type": "string", "pattern": "^-?\\d+$" }, "forecastMinor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "currency", "serviceMinor", "tipsMinor", "otherRevenueMinor", "commissionsMinor", "expensesMinor", "profitMinor", "forecastMinor" ] } }, "countsByStatus": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "cancelled", "no_show" ] }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "status", "count" ] } } }, "required": [ "totals", "countsByStatus" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trips/active": { "get": { "operationId": "getTripsActive", "summary": "GET /trips/active", "description": "Scope: `trips:read` — Read trips and hotels.", "tags": [ "trips" ], "security": [ { "bearer": [] }, { "oauth2": [ "trips:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trip": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ] }, "startsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "endsOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "timezone": { "type": "string" }, "hotelId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "checkInLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkInAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "checkOutLocal": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "checkOutAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultCommissionKind": { "anyOf": [ { "type": "string", "enum": [ "percent", "fixed" ] }, { "type": "null" } ] }, "defaultCommissionPercentBp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "defaultCommissionFixedMinor": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ] }, "defaultCommissionCurrency": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 3 }, { "type": "null" } ] }, "defaultCommissionOnTip": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "city", "region", "country", "startsOn", "endsOn", "timezone", "hotelId", "checkInLocal", "checkInAt", "checkOutLocal", "checkOutAt", "transport", "defaultCommissionKind", "defaultCommissionPercentBp", "defaultCommissionFixedMinor", "defaultCommissionCurrency", "defaultCommissionOnTip", "notes", "completedAt", "createdAt", "updatedAt" ] }, { "type": "null" } ] } }, "required": [ "trip" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Personal access key mova_pat_..." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.movapro.app/oauth/authorize", "tokenUrl": "https://api.movapro.app/oauth/token", "scopes": { "agenda:read": "Read the schedule (appointments).", "appointments:write": "Book and reschedule appointments (date, time, price, status). Never delete.", "clients:read": "Read clients (name, phone, notes) and sources.", "clients:write": "Add and change clients. Never delete.", "trips:read": "Read trips and hotels.", "trips:write": "Add and change trips and hotels. Never delete.", "finance:read": "Read expenses, other income and reports.", "finance:write": "Log and change expenses and other income. Never delete.", "lookup:read": "Look up a phone number in community reports (same limits as the app).", "reports:draft": "Leave a community report draft for the user to confirm in the app.", "reports:write": "Publish community reports on the user's behalf (requires the user's one-time acceptance)." } } }, "description": "OAuth tokens are issued for the MCP connector (/mcp) only." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid, revoked or expired key" }, "InsufficientScope": { "description": "The key's scopes don't include this route (code insufficient_scope)" }, "RateLimited": { "description": "Too many requests; see Retry-After" } } } }