openapi: 3.2.0 info: title: RentalReady Incidents API version: 1.0.0 (api) description: 'This API enables you to access and update resources from RentalReady (GuestReady PMS) ### Throttling Our API supports up to 400 requests per minute ' servers: - url: https://pms.rentalready.io/api/v3/ description: Base URL declared by the provider in apis.yml (roadmap#122). tags: - name: incidents paths: /api/v3/incidents/: get: operationId: incidents_list description: Retrieve a list of mission incidents. summary: List Incidents parameters: - in: query name: category schema: type: array items: type: string enum: - CHECK_IN - CLEANING - MAINTENANCE - QUALITY description: '* `CLEANING` - Cleaning * `MAINTENANCE` - Maintenance * `CHECK_IN` - Check-in * `QUALITY` - Quality' explode: true style: form - in: query name: created_at_after schema: type: string format: date-time - in: query name: created_at_before schema: type: string format: date-time - name: limit required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: mission_id schema: type: array items: type: integer explode: true style: form - name: offset required: false in: query description: The initial index from which to return the results. schema: type: integer - name: ordering required: false in: query description: Which field to use when ordering the results. schema: type: string - in: query name: status schema: type: array items: type: string enum: - CLOSED - IGNORED - ISSUE_CREATED - NEW description: '* `NEW` - New * `ISSUE_CREATED` - Ticket * `IGNORED` - Archived * `CLOSED` - Closed' explode: true style: form tags: - incidents security: - oauth2: - incidents:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedIncidentList' description: '' /api/v3/incidents/{id}/: get: operationId: incidents_retrieve description: Retrieve a specific mission incident by ID. summary: Retrieve Incident parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this mission incident. required: true tags: - incidents security: - oauth2: - incidents:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/Incident' description: '' /api/v3/incidents/{id}/archive/: patch: operationId: incidents_archive_partial_update description: Archive a mission incident, optionally recording why. Archiving never records a closing user. Only a non-empty comment overwrites the existing status comment. Archived is terminal, so an already archived incident cannot be archived again (400). summary: Archive Incident parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this mission incident. required: true tags: - incidents requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedArchiveIncident' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedArchiveIncident' multipart/form-data: schema: $ref: '#/components/schemas/PatchedArchiveIncident' security: - oauth2: - incidents:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Incident' description: '' '400': content: application/json: schema: example: non_field_errors: - An archived incident cannot change status. description: '' '403': content: application/json: schema: example: detail: Permission to manage the incident dashboard is required. description: '' /api/v3/incidents/{id}/close/: patch: operationId: incidents_close_partial_update description: Close a mission incident, optionally recording why. The calling user is saved as the closing user. Archived is terminal, so an archived incident cannot be closed (400). Re-closing an already closed incident is allowed and only overwrites the status comment when a non-empty comment is given. summary: Close Incident parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this mission incident. required: true tags: - incidents requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedCloseIncident' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedCloseIncident' multipart/form-data: schema: $ref: '#/components/schemas/PatchedCloseIncident' security: - oauth2: - incidents:write responses: '200': content: application/json: schema: $ref: '#/components/schemas/Incident' description: '' '400': content: application/json: schema: example: non_field_errors: - An archived incident cannot change status. description: '' '403': content: application/json: schema: example: detail: Permission to manage the incident dashboard is required. description: '' components: schemas: PaginatedIncidentList: type: object required: - count - results properties: count: type: integer example: 123 next: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=400&limit=100 previous: type: - string - 'null' format: uri example: http://api.example.org/accounts/?offset=200&limit=100 results: type: array items: $ref: '#/components/schemas/Incident' limit: type: integer example: 100 IncidentStatusEnum: enum: - NEW - ISSUE_CREATED - IGNORED - CLOSED type: string description: '* `NEW` - New * `ISSUE_CREATED` - Ticket * `IGNORED` - Archived * `CLOSED` - Closed' PatchedCloseIncident: type: object description: "Base write serializer for the incident ``close`` / ``archive`` actions.\n\nBound to the incident instance (like\n``MarkPayoutAdjustmentAsPaidSerializer``): transition rules are checked in\n``validate`` against ``self.instance`` and the mutation happens in\n``update``.\n\nModelled on the incident dashboard's Close / Archive buttons, but it does\nNOT reproduce ``authentification.views.MarkIncidentAsClosed`` /\n``MarkIncidentAsIgnored`` line for line. Three deliberate divergences:\n\n1. **Only a non-empty comment overwrites** ``status_change_comment``. The\n views assign ``request.POST.get(\"comment\", None)`` UNCONDITIONALLY, so a\n no-comment post wipes the existing reason -- including the note\n ``issue_manager.signals.close_incident_when_all_tickets_closed`` writes\n (\"All tickets are closed.\"). An API caller re-closing without a comment\n must not silently destroy that provenance.\n2. **Transitions out of IGNORED are rejected.** The views themselves accept\n any transition; it is the dashboard TEMPLATES that make IGNORED terminal\n (``staffing/templates/staffing/mission_incidents.html`` and\n ``authentification/templates/authentification/table_actions.html`` both\n disable the whole action menu on an archived incident). The API mirrors\n what the interface can actually produce, not what the views would let\n through -- otherwise the API could re-archive an incident, overwriting a\n human's archive note and bumping ``status_updated_at`` in a way no user\n can.\n3. **Idempotent re-close is allowed** even though the template hides Close\n on a CLOSED incident: re-closing changes nothing a caller cares about\n (same target status, ``status_updated_at`` keeps the original transition\n time), and an agent retrying a call it cannot tell succeeded must not\n get a spurious 400. CLOSED -> IGNORED stays allowed too, because the\n templates do offer Archive on a closed incident." properties: comment: type: - string - 'null' description: Optional free-text reason recorded on the incident for this status change. Left out, blank, or null, the previous status comment is kept -- notably the automatic 'All tickets are closed.' note. Incident: type: object properties: id: type: integer readOnly: true created_at: type: string format: date-time readOnly: true description: When the incident was reported. category: allOf: - $ref: '#/components/schemas/IncidentCategoryEnum' description: 'The kind of mission the incident was reported on (cleaning, maintenance, check-in, or quality). * `CLEANING` - Cleaning * `MAINTENANCE` - Maintenance * `CHECK_IN` - Check-in * `QUALITY` - Quality' status: allOf: - $ref: '#/components/schemas/IncidentStatusEnum' description: 'Lifecycle status of the incident (new, ticket created, archived, or closed). * `NEW` - New * `ISSUE_CREATED` - Ticket * `IGNORED` - Archived * `CLOSED` - Closed' mission: type: integer description: Id of the mission the incident was reported on. property: type: - string - 'null' title: Property description: Id of the property (Appartement) the mission for this incident belongs to. readOnly: true comment: type: string description: Free-text description of the incident. status_change_comment: type: - string - 'null' description: Comment recorded the last time the status changed. status_updated_at: type: - string - 'null' format: date-time description: When the status was last changed, if ever. closed_by: type: integer readOnly: true description: Id of the user who closed the incident. Null on an incident that is not closed AND on one closed automatically (the system closes an incident once all the tickets created from it are closed), so a CLOSED incident with no closed_by was closed automatically, never by a person. Archiving never sets it. issues: type: array items: type: integer readOnly: true description: Ids of the tickets (issues) created from this incident. required: - category - closed_by - comment - created_at - id - issues - mission - property PatchedArchiveIncident: type: object description: "Base write serializer for the incident ``close`` / ``archive`` actions.\n\nBound to the incident instance (like\n``MarkPayoutAdjustmentAsPaidSerializer``): transition rules are checked in\n``validate`` against ``self.instance`` and the mutation happens in\n``update``.\n\nModelled on the incident dashboard's Close / Archive buttons, but it does\nNOT reproduce ``authentification.views.MarkIncidentAsClosed`` /\n``MarkIncidentAsIgnored`` line for line. Three deliberate divergences:\n\n1. **Only a non-empty comment overwrites** ``status_change_comment``. The\n views assign ``request.POST.get(\"comment\", None)`` UNCONDITIONALLY, so a\n no-comment post wipes the existing reason -- including the note\n ``issue_manager.signals.close_incident_when_all_tickets_closed`` writes\n (\"All tickets are closed.\"). An API caller re-closing without a comment\n must not silently destroy that provenance.\n2. **Transitions out of IGNORED are rejected.** The views themselves accept\n any transition; it is the dashboard TEMPLATES that make IGNORED terminal\n (``staffing/templates/staffing/mission_incidents.html`` and\n ``authentification/templates/authentification/table_actions.html`` both\n disable the whole action menu on an archived incident). The API mirrors\n what the interface can actually produce, not what the views would let\n through -- otherwise the API could re-archive an incident, overwriting a\n human's archive note and bumping ``status_updated_at`` in a way no user\n can.\n3. **Idempotent re-close is allowed** even though the template hides Close\n on a CLOSED incident: re-closing changes nothing a caller cares about\n (same target status, ``status_updated_at`` keeps the original transition\n time), and an agent retrying a call it cannot tell succeeded must not\n get a spurious 400. CLOSED -> IGNORED stays allowed too, because the\n templates do offer Archive on a closed incident." properties: comment: type: - string - 'null' description: Optional free-text reason recorded on the incident for this status change. Left out, blank, or null, the previous status comment is kept -- notably the automatic 'All tickets are closed.' note. IncidentCategoryEnum: enum: - CLEANING - MAINTENANCE - CHECK_IN - QUALITY type: string description: '* `CLEANING` - Cleaning * `MAINTENANCE` - Maintenance * `CHECK_IN` - Check-in * `QUALITY` - Quality' securitySchemes: basicAuth: type: http scheme: basic cookieAuth: type: apiKey in: cookie name: sessionid oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: /o/authorize/ tokenUrl: /o/token/ refreshUrl: /o/token/ scopes: read: Read scope write: Write scope amenities:read: Read amenities amenities:write: Create, update and delete amenities photos:write: Create, update and delete photos reservations:read: Read reservations reservations:write: Create, update and cancel reservations reservation_platform:read: Read reservation platform reviews:read: Read reviews reviews:write: Write reviews owners:read: Read owners owners:write: Write owners hosts:read: Read hosts (deprecated) hosts:write: Write hosts (deprecated) offices:read: Read offices property_managers:read: Read property managers onboarding_requests:read: Read onboarding requests listing_requests:read: Read listing requests pricing:read: Read pricing pricing:write: Create, update and delete pricing users:read: Read user data calendar:read: Read calendar calendar:write: Write calendar rentals:read: Read rentals rentals:write: Create, update and delete rentals issues:read: Read issues issues:write: Write issues incidents:read: Read incidents incidents:write: Write incidents missions:read: Read missions missions:write: Write missions agents:read: Read agents smart_schedulers:read: Read smart schedulers smart_schedulers:write: Write smart schedulers neighbourhoods:read: Read neighbourhoods payment_links:read: Read payment links swikly_deposits:read: Read swikly deposits payout_adjustments:read: Read payout adjustments payout_adjustments:write: Write payout adjustments payment_acceptance_transactions:read: Read payment acceptance transactions payment_acceptance_transactions:write: Write payment acceptance transactions accounting_invoice:read: Read accounting invoices accounting_invoice:write: Write accounting invoices guest_registration:read: Read guest registration data conversations:read: Read conversations conversations:write: Write conversations messages:read: Read messages messages:write: Write messages inquiries:read: Read inquiries city_tax_rules:read: Read city tax rules custom_fields:read: Read custom fields custom_fields:write: Write custom fields tokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token"