> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt > Use this file to discover all available pages before exploring further. # List planned maintenance schedules > Lists planned maintenance schedules for the caller's buyer company. Filtering: every query parameter other than the pagination parameters is passed to the entity's filter layer and matched against its indexed columns (multi-value filters are comma-separated strings); the per-entity column names are not exhaustively documented here. Filters are combined with the tenant-security filters derived from the API key. ## OpenAPI ````yaml /openapi/buyer.json get /v1/buyer/pm/planned_maintenance_schedules openapi: 3.1.0 info: title: OpenWrench Buyer API version: 1.0.0 description: >- External REST API for OpenWrench buyers (facilities-management side). Generated from the application source (Play routes, controllers and models). ## Authentication Every request must carry a buyer API key in the `X-API-KEY` header. The key resolves to a buyer contact, and all reads/writes are tenant-scoped to that contact's buyer company (plus, on several endpoints, role-based location/brand restrictions). Endpoints under `/v1/buyer/super_admin/...` (and a few others noted per-operation) additionally require the key's contact to be a buyer super admin. ## Rate limiting 10 requests per 20-second window per API key; requests beyond that receive **429**. A handful of operations noted per-operation bypass the rate limiter. ## Response envelope Single-entity responses: `{ "type": "", "data": { ... }, "status": "ok" }`. List responses: `{ "type": "", "data": [ ... ], "count": , "status": "ok" }`. count_by responses: `{ "type": "CountBy", "data": , "status": "ok" }`. Errors: `{ "message": "...", "type": "", "status": "error", "traceId": "..." }` — 401 missing/invalid key, 400 bad input, 404 not found, 429 rate limit. ## Pagination & filtering List endpoints accept `offset`, `limit` (default 10, max 25 — the locations list clamps to 10), `sort_by` and `order` (asc|desc). Every other query parameter is treated as a filter and matched against the entity's indexed columns (multi-value filters are comma-separated strings); these are combined with the tenant-security filters derived from the API key. Timestamps are ISO 8601 strings unless noted otherwise. ## Date formats Date-time fields serialize as strings in one of two shapes depending on the underlying type: ISO 8601 with offset (e.g. `2026-08-14T13:05:22.000-07:00`) for most timestamps, or `yyyy-MM-dd HH:mm:ss.S` (space-separated, no offset) for database timestamp fields. Plain dates are `yyyy-MM-dd`. When sending date-times, ISO 8601 is accepted. ## Required headers Every request must carry BOTH `X-API-KEY` (your API key) and `OW-KEY` (the OpenWrench shared secret issued with it). Requests missing either return 401. servers: - url: https://api.useopenwrench.com/api/external security: - ApiKeyAuth: [] OwKeyAuth: [] tags: - name: Ping - name: Me - name: Locations - name: Regions - name: Asset Types - name: Asset Meters - name: Assets - name: Asset Labels description: Read the asset label catalog and replace the labels applied to an asset. - name: Asset Models - name: Work Orders - name: Work Order Notes - name: Work Order Labels description: >- Read your work order label catalog and replace the labels applied to a work order. - name: Service Calls - name: Site Survey Walkthroughs - name: Invoices - name: Proposals - name: Files - name: Planned Maintenance - name: Currency Exchange - name: Supplier Network - name: User Provisioning paths: /v1/buyer/pm/planned_maintenance_schedules: get: tags: - Planned Maintenance summary: List planned maintenance schedules description: >- Lists planned maintenance schedules for the caller's buyer company. Filtering: every query parameter other than the pagination parameters is passed to the entity's filter layer and matched against its indexed columns (multi-value filters are comma-separated strings); the per-entity column names are not exhaustively documented here. Filters are combined with the tenant-security filters derived from the API key. operationId: listPlannedMaintenanceSchedules parameters: - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sort_by' - $ref: '#/components/parameters/order' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/PlannedMaintenanceScheduleListResponse' '400': description: >- Bad input, parse failure, or the API key's contact could not be resolved. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid X-API-KEY. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded (10 requests per 20-second window per key). content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: offset: name: offset in: query required: false description: Number of records to skip. schema: type: integer minimum: 0 limit: name: limit in: query required: false description: Page size. Default 10, maximum 25. schema: type: integer minimum: 1 maximum: 25 default: 10 sort_by: name: sort_by in: query required: false description: Field/column to sort by. schema: type: string order: name: order in: query required: false description: Sort direction. schema: type: string enum: - asc - desc schemas: PlannedMaintenanceScheduleListResponse: type: object properties: type: type: string description: Entity type marker, e.g. "PlannedMaintenanceSchedule". data: type: array items: $ref: '#/components/schemas/PlannedMaintenanceSchedule' count: type: integer description: Total number of matching records (not just this page). status: type: string enum: - ok required: - type - data - count - status Error: type: object properties: message: type: string type: type: string description: >- Exception type, e.g. unauthorizedException, NotFoundException, BadRequestException, ParseException, InvalidInputDataException, ConflictException, UnexpectedException. status: type: string enum: - error traceId: type: string description: >- Trace id (a random 11-char alphanumeric string when no explicit trace applies). required: - message - type - status - traceId description: >- Standard error envelope. 401 = missing/invalid API key, 400 = bad input, 404 = not found, 429 = rate limit exceeded. PlannedMaintenanceSchedule: type: object properties: id: type: - integer - 'null' scheduleId: type: - string - 'null' title: type: string status: type: string description: >- PM status (e.g. Active, Paused, Expired); serialized via a custom format. basedOn: type: - string - 'null' description: >- What the schedule is based on: location, asset, assetType, meter or meterType. frequency: type: string description: >- Frequency expression (e.g. every-N-weeks / every-N-months forms); serialized via a custom format. frequencyDays: type: integer createConfig: type: - string - 'null' plannedMaintenanceTemplateId: type: integer startDate: type: string format: date-time endDate: type: - string - 'null' format: date-time monthConfig: type: - object - 'null' properties: {} additionalProperties: true weekDays: type: - array - 'null' items: type: string idealVisitTime: type: - string - 'null' description: Time of day, HH:mm:ss. nextScheduled: type: - string - 'null' format: date-time nextToNextScheduled: type: - string - 'null' format: date-time nte: type: - number - 'null' supplierFacilityId: type: - integer - 'null' supplierContractId: type: - string - 'null' supplierContractDocuments: type: - array - 'null' items: $ref: '#/components/schemas/FileDetails' triggerConditionId: type: - integer - 'null' meterTypeId: type: - integer - 'null' meterId: type: - integer - 'null' assetTypeId: type: - integer - 'null' assetId: type: - integer - 'null' additionalInfo: type: - string - 'null' locationId: type: integer location: anyOf: - $ref: '#/components/schemas/Location' - type: 'null' buyerFacilityId: type: integer buyerCompanyId: type: integer createdAt: type: - string - 'null' format: date-time createdBy: type: - string - 'null' updatedAt: type: - string - 'null' format: date-time updatedBy: type: - string - 'null' isDeleted: type: boolean deletedAt: type: - string - 'null' format: date-time required: - title - status - frequency - frequencyDays - plannedMaintenanceTemplateId - startDate - locationId - buyerFacilityId - buyerCompanyId - isDeleted additionalProperties: true description: >- Planned maintenance schedule. Abridged: hydrated template, trigger condition, meter, asset and run-log objects may also appear; status/frequency use custom serializations. FileDetails: type: object properties: fileName: type: string description: Original file name (non-ASCII characters stripped on upload). fileId: type: string description: Opaque file identifier used for later download. required: - fileName - fileId description: 'File reference: name plus storage identifier.' Location: type: object properties: id: type: - integer - 'null' storeId: type: - string - 'null' name: type: string brandId: type: - integer - 'null' brandAssetGroupId: type: - integer - 'null' allAssetCount: type: - integer - 'null' description: type: - string - 'null' isActive: type: boolean openDate: type: - string - 'null' format: date-time closeDate: type: - string - 'null' format: date-time operatingHours: anyOf: - $ref: '#/components/schemas/OperatingHours' - type: 'null' phoneNumber: type: - string - 'null' locationTypeId: type: integer locationTypeDetails: type: array items: $ref: '#/components/schemas/FieldTypeDetails' notes: type: - string - 'null' notesNonFormatted: type: - string - 'null' internalNotes: type: - string - 'null' images: type: array items: type: string internalAttachments: type: array items: $ref: '#/components/schemas/FileDetails' primaryContactsEmails: type: array items: type: string facilityInChargeEmails: type: array items: type: string sendApprovedInvoicesToEmails: type: array items: type: string sendApprovedQuotesToEmails: type: array items: type: string storeAssociateEmails: type: array items: type: string fieldTechEmails: type: array items: type: string timeZoneId: type: - string - 'null' hasPresetAssetUUID: type: - boolean - 'null' regionId: type: - integer - 'null' region: anyOf: - $ref: '#/components/schemas/Region' - type: 'null' purchaseOrderPrefix: type: - string - 'null' isLeased: type: - boolean - 'null' leaseStartDate: type: - string - 'null' format: date-time leaseEndDate: type: - string - 'null' format: date-time taxRate: type: - string - 'null' customFieldDetails: type: - array - 'null' items: $ref: '#/components/schemas/FieldTypeDetails' buildingWarrantyStartDate: type: - string - 'null' format: date-time buildingWarrantyExpirationDate: type: - string - 'null' format: date-time buildingWarrantyProblemTypeIds: type: - array - 'null' items: type: integer buildingWarrantyServiceProviderId: type: - integer - 'null' invoicesBillTo: anyOf: - $ref: '#/components/schemas/InvoicesBillTo' - type: 'null' countryCode: type: - string - 'null' buyerFacilityId: type: integer buyerCompanyId: type: integer totalWOCount: type: - integer - 'null' totalNotClosedWOCount: type: - integer - 'null' createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time isDeleted: type: boolean deletedAt: type: - string - 'null' format: date-time required: - name - isActive - locationTypeId - buyerFacilityId - buyerCompanyId - isDeleted additionalProperties: true description: >- Location. Abridged: hydrated contact/settings arrays and brand/facility/company objects may also appear in responses. OperatingHours: type: object properties: timeZoneId: type: - string - 'null' timeZoneName: type: - string - 'null' Monday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Tuesday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Wednesday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Thursday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Friday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Saturday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' Sunday: anyOf: - $ref: '#/components/schemas/Timings' - type: 'null' FieldTypeDetails: type: object properties: key: type: string valueAsString: type: string valueType: type: string required: - key - valueAsString - valueType Region: type: object properties: id: type: - integer - 'null' name: type: string buyerCompanyId: type: integer hierarchyName: type: - string - 'null' parentId: type: - integer - 'null' hasChildren: type: boolean createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time isDeleted: type: boolean deletedAt: type: - string - 'null' format: date-time required: - name - buyerCompanyId - hasChildren - isDeleted InvoicesBillTo: type: object properties: billTo: type: string serviceAddress: type: object properties: {} additionalProperties: true required: - billTo - serviceAddress Timings: type: object properties: {} additionalProperties: true description: Opening/closing timings for one weekday. Shape abridged. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY OwKeyAuth: type: apiKey in: header name: OW-KEY description: >- OpenWrench shared secret. Required on every request alongside X-API-KEY; issued together with your API key. ````