# API Portal and MCP Gateway method reference

Local source snapshot: 2026-11-08. API 1.3.0; MCP 0.3.0. Regenerate after building connect-api with `npm run docs:integrations -- ../connect-api`. No live deployment is verified. Source SHA-256 hashes are in src/content/generated/integration-index.json.

146 registered HTTP methods; 144 business methods below plus GET /v1/api/openapi.json and GET /v1/api/mcp-catalog.json. Full parameter, body, response and security schemas: [OpenAPI](./openapi.json). Full MCP input/output schemas: [catalogue](./mcp-catalog.json).

## External HTTP methods

Paths below include the /v1/api prefix. A group-level scope list is not permission for every method: use each operation's security requirements. Delegated routes reject organizational API keys.

| Method | Path | Purpose | Scopes | Authentication |
| --- | --- | --- | --- | --- |
| GET | `/v1/api/mcp/staff/inspections/{actId}` | mcpGetStaffInspection | inspections:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties` | mcpListResidentProperties | resident:properties:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties/{siteId}/requests` | mcpListResidentRequests | resident:requests:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties/{siteId}/requests/{id}` | mcpGetResidentRequest | resident:requests:read | Delegated MCP only |
| GET | `/v1/api/mcp/supplier/bids` | mcpListSupplierOpportunities | supplier:bids:read | Delegated MCP only |
| GET | `/v1/api/mcp/supplier/bids/{bidRequestId}/status` | mcpGetOwnSupplierBidStatus | supplier:bids:read | Delegated MCP only |
| GET | `/v1/api/mcp/staff/inspections` | List currently authorized staff inspections | inspections:read | Delegated MCP only |
| GET | `/v1/api/building-finance/imports` | List normalized financial imports | building-finance:read | API key |
| POST | `/v1/api/building-finance/imports` | Stage a normalized building-finance document | building-finance:write | API key |
| POST | `/v1/api/building-finance/imports/{id}/document` | Upload invoice PDF bytes | building-finance:write | API key |
| POST | `/v1/api/building-finance/payments` | Import payment allocations | building-finance:write | API key |
| GET | `/v1/api/building-finance/provider-identities` | List provider identity mappings | building-finance:read | API key |
| PUT | `/v1/api/building-finance/provider-identities` | Bind a provider identity | building-finance:write | API key |
| GET | `/v1/api/employees` | List employees | employees:read | API key |
| POST | `/v1/api/employees` | Create employee and invitation user | employees:write | API key |
| GET | `/v1/api/employees/{employeeId}` | Get employee | employees:read | API key |
| PATCH | `/v1/api/employees/{employeeId}` | Update employee | employees:write | API key |
| POST | `/v1/api/employees/{employeeId}/discontinue` | End-date employee and user login | employees:write | API key |
| GET | `/v1/api/time/worked-shifts` | Get worked shifts and reported entries | time:read | API key |
| GET | `/v1/api/time/summary` | Get worked-time and pay summary by employee | time:read | API key |
| GET | `/v1/api/expenses` | List expense headers and lines | expenses:read | API key |
| GET | `/v1/api/absences` | List vacations and absences | absences:read | API key |
| POST | `/v1/api/absences` | Create vacation or absence | absences:write | API key |
| GET | `/v1/api/absences/{absenceId}` | Get absence | absences:read | API key |
| PATCH | `/v1/api/absences/{absenceId}` | Update absence | absences:write | API key |
| DELETE | `/v1/api/absences/{absenceId}` | Delete absence | absences:write | API key |
| GET | `/v1/api/clients` | List CRM clients | clients:read | API key |
| POST | `/v1/api/clients` | Create CRM client | clients:write | API key |
| GET | `/v1/api/clients/{clientId}` | Get CRM client details | clients:read | API key |
| PATCH | `/v1/api/clients/{clientId}` | Update CRM client | clients:write | API key |
| GET | `/v1/api/clients/{clientId}/sites` | List sites for CRM client | sites:read | API key |
| POST | `/v1/api/clients/{clientId}/sites` | Create site for CRM client | sites:write | API key |
| PATCH | `/v1/api/clients/{clientId}/sites/{siteId}` | Update site for CRM client | sites:write | API key |
| GET | `/v1/api/clients/{clientId}/contacts` | List contacts for CRM client | contacts:read | API key |
| POST | `/v1/api/clients/{clientId}/contacts` | Create contact for CRM client | contacts:write | API key |
| GET | `/v1/api/contacts` | List CRM contacts | contacts:read | API key |
| PATCH | `/v1/api/contacts/{contactPointId}` | Update CRM contact | contacts:write | API key |
| GET | `/v1/api/locations` | List CRM site locations | locations:read | API key |
| GET | `/v1/api/sites` | List organization sites | sites:read | API key |
| POST | `/v1/api/sites` | Create organization site with location | sites:write | API key |
| GET | `/v1/api/sites/{siteId}` | Get organization site | sites:read | API key |
| PATCH | `/v1/api/sites/{siteId}` | Update organization site | sites:write | API key |
| GET | `/v1/api/sites/{siteId}/equipment` | List equipment | setup:read | API key |
| POST | `/v1/api/sites/{siteId}/equipment` | Create equipment | setup:write | API key |
| GET | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Get equipment | setup:read | API key |
| PATCH | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Update equipment | setup:write | API key |
| DELETE | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Delete equipment | setup:write | API key |
| GET | `/v1/api/compensations` | List compensation definitions | compensation:read | API key |
| POST | `/v1/api/compensations` | Create compensation definition | compensation:write | API key |
| POST | `/v1/api/employees/{employeeId}/compensations` | Assign compensation to employee | compensation:write | API key |
| GET | `/v1/api/materials` | List materials | materials:read | API key |
| POST | `/v1/api/materials` | Create material | materials:write | API key |
| GET | `/v1/api/materials/{materialId}` | Get material | materials:read | API key |
| PATCH | `/v1/api/materials/{materialId}` | Update material | materials:write | API key |
| GET | `/v1/api/suppliers` | List suppliers | suppliers:read | API key |
| POST | `/v1/api/suppliers` | Create supplier | suppliers:write | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}` | Get supplier details | suppliers:read | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}/employees` | List supplier employees | suppliers:read | API key |
| POST | `/v1/api/suppliers/{supplierPartyId}/employees` | Create supplier employee | suppliers:write | API key |
| PATCH | `/v1/api/suppliers/{supplierPartyId}/employees/{employeePartyId}` | Update supplier employee | suppliers:write | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}/agreements` | List agreements for supplier | agreements:read | API key |
| GET | `/v1/api/agreements` | List agreements | agreements:read | API key |
| POST | `/v1/api/agreements` | Create agreement | agreements:write | API key |
| GET | `/v1/api/agreements/stats` | Get agreement expiry statistics | agreements:read | API key |
| GET | `/v1/api/agreements/{agreementId}` | Get agreement | agreements:read | API key |
| PATCH | `/v1/api/agreements/{agreementId}` | Update agreement | agreements:write | API key |
| DELETE | `/v1/api/agreements/{agreementId}` | Terminate agreement | agreements:write | API key |
| GET | `/v1/api/work-orders` | List CRM work orders | work-orders:read | API key |
| POST | `/v1/api/work-orders` | Create CRM work order | work-orders:write | API key |
| GET | `/v1/api/work-orders/{workOrderId}` | Get CRM work order | work-orders:read | API key |
| PATCH | `/v1/api/work-orders/{workOrderId}` | Update CRM work order | work-orders:write | API key |
| GET | `/v1/api/clients/{clientId}/work-orders` | List CRM client work orders | work-orders:read | API key |
| GET | `/v1/api/sites/{siteId}/work-orders` | List CRM site work orders | work-orders:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/statistics` | Get work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/work-orders/statistics` | Get client work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/sites/{siteId}/work-orders/statistics` | Get site work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/sites/{siteId}/work-orders/statistics` | Get client-site work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/pdf` | Download work order PDF report | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/excel` | Download work order Excel report | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/csv` | Download work order CSV report | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/work-orders/statistics/report/pdf` | Download client work order statistics PDF report | work-order-reports:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings` | List apartment meter readings | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings` | Create apartment meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters` | List configured apartment meters | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters` | Create an apartment meter | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters/{meterId}` | Update an apartment meter | building-management:write | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings/{id}/corrections` | Correct an apartment meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/agreements` | List apartment ownership and tenancy agreements | building-ownership:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/agreements` | Create an apartment ownership or tenancy agreement | building-ownership:write | API key |
| PATCH | `/v1/api/building-management/apartment-agreements/{agreementId}` | Update an apartment agreement | building-ownership:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/financial-documents` | List canonical apartment bills | building-finance:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/payments` | List canonical apartment payments | building-finance:read | API key |
| GET | `/v1/api/building-management/financial-documents/{id}/details` | Get canonical bill details | building-finance:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/meters` | List communal building meters | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/meters` | Create communal building meter | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/meters/{meterId}` | Update communal building meter | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/meter-readings` | List communal building meter readings | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/meter-readings` | Create communal building meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons` | List apartment owners, tenants, payers, and contacts | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons` | Create apartment person relationship | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons/{relationshipId}` | Update apartment person relationship | building-management:write | API key |
| DELETE | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons/{relationshipId}` | End apartment person relationship | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors` | List house senior assignments for building | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors` | Assign house senior to building | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors/{relationshipId}` | Update house senior assignment | building-management:write | API key |
| DELETE | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors/{relationshipId}` | End house senior assignment | building-management:write | API key |
| PATCH | `/v1/api/building-management/meter-readings/{id}` | Update meter reading | building-management:write | API key |
| DELETE | `/v1/api/building-management/meter-readings/{id}` | Delete meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/financial-documents` | List building financial documents | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/financial-documents` | Create building financial document | building-management:write | API key |
| PATCH | `/v1/api/building-management/financial-documents/{id}` | Update financial document | building-management:write | API key |
| DELETE | `/v1/api/building-management/financial-documents/{id}` | Delete financial document | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/payments` | List building payments | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/payments` | Create building payment | building-management:write | API key |
| PATCH | `/v1/api/building-management/payments/{id}` | Update payment | building-management:write | API key |
| DELETE | `/v1/api/building-management/payments/{id}` | Delete payment | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/tasks` | List building CRM tasks | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/tasks` | Create building CRM task | building-management:write | API key |
| PATCH | `/v1/api/building-management/tasks/{id}` | Update building CRM task | building-management:write | API key |
| GET | `/v1/api/building-management/notifications` | List building notifications | building-management:read | API key |
| POST | `/v1/api/building-management/notifications` | Create or queue building notification | building-management:write | API key |
| PATCH | `/v1/api/building-management/notifications/{id}` | Update or send draft building notification | building-management:write | API key |
| DELETE | `/v1/api/building-management/notifications/{id}` | Delete draft building notification | building-management:write | API key |
| GET | `/v1/api/building-management/sync-attempts` | List building-management sync attempts | building-management:sync | API key |
| POST | `/v1/api/building-management/sync/{objectType}/{id}` | Synchronize one building-management object | building-management:sync | API key |
| GET | `/v1/api/inspections/buildings` | List inspection buildings | inspections:read | API key |
| GET | `/v1/api/inspections/buildings/{clientId}/history` | List building inspection history | inspections:read | API key |
| GET | `/v1/api/inspections/buildings/{clientId}/work-orders` | List inspection work orders for building | inspections:read | API key |
| GET | `/v1/api/inspections/work-orders/{workOrderId}/details` | Get section-scoped inspection details for a work order | inspections:read | API key |
| GET | `/v1/api/inspections/act-templates` | List inspection act templates | inspections:read | API key |
| GET | `/v1/api/inspections/acts` | List inspection acts | inspections:read | API key |
| POST | `/v1/api/inspections/acts` | Create inspection act | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}` | Get inspection act details | inspections:read | API key |
| PATCH | `/v1/api/inspections/acts/{actId}` | Update inspection act | inspections:write | API key |
| PUT | `/v1/api/inspections/acts/{actId}/values` | Replace inspection act values | inspections:write | API key |
| POST | `/v1/api/inspections/acts/{actId}/evidence` | Add inspection evidence metadata | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/defects` | List inspection defects | inspections:read | API key |
| POST | `/v1/api/inspections/acts/{actId}/defects` | Create inspection defect | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/work-orders` | List work orders linked to inspection act | inspections:read | API key |
| POST | `/v1/api/inspections/acts/{actId}/work-orders` | Create work order from inspection act | inspections:write, work-orders:write | API key |
| POST | `/v1/api/inspections/acts/{actId}/section-work-orders` | Create section work orders for one inspection act | inspections:write, work-orders:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/statistics` | Get inspection act rollup statistics | inspections:read | API key |
| GET | `/v1/api/inspections/acts/{actId}/versions` | List inspection act versions | inspections:read | API key |
| GET | `/v1/api/attachments` | List attachment metadata | attachments:read | API key |

## MCP tools

All ten tools are read-only. The public catalogue does not grant execution access; tools/list is filtered to the current grant.

| Tool | Audience | Scope | Backend mapping | Example arguments |
| --- | --- | --- | --- | --- |
| `get_property_inspection_details` | STAFF | inspections:read | GET `/v1/api/mcp/staff/inspections/:actId` | `{"act_id":"70"}` |
| `list_properties` | RESIDENT | resident:properties:read | GET `/v1/api/mcp/resident/properties` | `{"skip":0,"take":20}` |
| `list_maintenance_requests` | RESIDENT | resident:requests:read | GET `/v1/api/mcp/resident/properties/:siteId/requests` | `{"site_id":"50","skip":0,"take":20}` |
| `get_maintenance_request_details` | RESIDENT | resident:requests:read | GET `/v1/api/mcp/resident/properties/:siteId/requests/:id` | `{"site_id":"50","request_id":"9"}` |
| `list_supplier_opportunities` | SUPPLIER | supplier:bids:read | GET `/v1/api/mcp/supplier/bids` | `{"page":0,"take":20}` |
| `get_supplier_bid_status` | SUPPLIER | supplier:bids:read | GET `/v1/api/mcp/supplier/bids/:bidRequestId/status` | `{"bid_request_id":"9"}` |
| `list_work_orders` | STAFF | work-orders:read | GET `/v1/api/work-orders` | `{"page":0,"take":20}` |
| `get_work_order_details` | STAFF | work-orders:read | GET `/v1/api/work-orders/:workOrderId` | `{"work_order_id":"9"}` |
| `list_contractors` | STAFF | suppliers:read | GET `/v1/api/suppliers` | `{"skip":0,"take":20}` |
| `list_property_inspections` | STAFF | inspections:read | GET `/v1/api/mcp/staff/inspections` | `{"skip":0,"take":20}` |

## Pagination and results

MCP take: 1–50, default 20. skip: row offset 0–100000, default 0. page: zero-based 0–2000, default 0. IDs: positive decimal strings up to 16 digits. Work-order page forwards as the backend page-index skip; supplier page converts to an offset; other lists use row offsets. property_id is a building party ID; resident site_id is an apartment/site ID. Unknown arguments are rejected. Lists return success, data, metadata and pagination (skip, take, total, hasMore). Errors set isError with a bounded category and correlation ID. Private contacts, notes, compensation, attachments, precise locations and competitor responses are excluded. See catalogue for exact required, optional and nullable fields.

REST pagination and filters vary by operation: consult its parameters in the local OpenAPI. Do not assume skip is always a row offset or that every declared shared filter is implemented.

## Supporting protocol, OAuth and consent methods

See [setup and supporting methods](integration-setup.md) and [missing capabilities and release gates](integration-gaps.md).