{
  "openapi" : "3.1.0",
  "components" : {
    "schemas" : {
      "EntityRef" : {
        "type" : "object",
        "required" : [ "id" ],
        "description" : "Reference to a related entity by stable identifier.",
        "properties" : {
          "id" : {
            "type" : "string",
            "description" : "Stable identifier of the referenced entity."
          },
          "displayName" : {
            "type" : [ "string", "null" ],
            "description" : "Human-readable display name. May be absent if the underlying record wasn't found in cache or has no usable name fields."
          }
        }
      },
      "PaginationInfo" : {
        "type" : "object",
        "description" : "Offset-based pagination metadata for a list response.",
        "properties" : {
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "examples" : [ 1 ],
            "description" : "1-based index of the page returned."
          },
          "pageSize" : {
            "type" : "integer",
            "format" : "int32",
            "examples" : [ 25 ],
            "description" : "Number of items requested per page."
          },
          "totalItems" : {
            "type" : "integer",
            "format" : "int64",
            "examples" : [ 137 ],
            "description" : "Total number of items matching the query across all pages."
          },
          "totalPages" : {
            "type" : "integer",
            "format" : "int32",
            "examples" : [ 6 ],
            "description" : "Total number of pages available at the current pageSize."
          },
          "hasMore" : {
            "type" : "boolean",
            "examples" : [ true ],
            "description" : "True when more pages remain after the current one (page < totalPages). Clients can stop paging when this is false rather than computing it themselves."
          }
        }
      },
      "WorkOrderListResponse" : {
        "type" : "object",
        "description" : "A paginated page of Work Order summaries (v1).",
        "properties" : {
          "items" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/WorkOrderResponse"
            },
            "description" : "Work Orders on the current page, ordered per the request's sort."
          },
          "pagination" : {
            "$ref" : "#/components/schemas/PaginationInfo",
            "type" : "object",
            "description" : "Pagination metadata describing the current page."
          },
          "enrichmentPartial" : {
            "type" : [ "boolean", "null" ],
            "description" : "Present and true when wor-cache-svc experienced a transient failure during this request. One or more displayName fields in the items list may be null. A subsequent request should return full display names once the cache service recovers."
          }
        }
      },
      "WorkOrderResponse" : {
        "type" : "object",
        "description" : "Public Work Order summary (v1).",
        "properties" : {
          "workOrderId" : {
            "type" : "string",
            "description" : "Stable unique identifier for the Work Order."
          },
          "workOrderNumber" : {
            "type" : "string",
            "description" : "Human-readable Work Order number."
          },
          "workOrderCustomer" : {
            "type" : [ "object", "null" ],
            "description" : "Reference to the customer for this Work Order.",
            "anyOf" : [ {
              "$ref" : "#/components/schemas/EntityRef"
            }, {
              "type" : "null"
            } ]
          },
          "workOrderUnit" : {
            "type" : [ "object", "null" ],
            "description" : "Reference to the unit (vehicle/asset) for this Work Order.",
            "anyOf" : [ {
              "$ref" : "#/components/schemas/EntityRef"
            }, {
              "type" : "null"
            } ]
          },
          "workOrderCreatedDate" : {
            "type" : "string",
            "description" : "Timestamp the Work Order was created, ISO 8601 UTC (e.g., \"2026-05-22T17:42:18Z\")."
          },
          "workOrderUpdatedDate" : {
            "type" : "string",
            "description" : "Timestamp the Work Order was last updated, ISO 8601 UTC. Use with the list endpoint's updatedSince filter for incremental sync."
          },
          "workOrderClosedDate" : {
            "type" : [ "string", "null" ],
            "description" : "Timestamp the Work Order was closed without invoicing, ISO 8601 UTC (e.g., \"2026-05-22T17:42:18Z\"). Present only when workOrderStage is CLOSED; omitted otherwise. Taken from the Work Order's last update, so in rare cases (a preview session released after closing) it can be slightly later than the moment of closing."
          },
          "workOrderStage" : {
            "type" : "string",
            "examples" : [ "IN_PROGRESS" ],
            "description" : "Current workflow stage. Free-form string, not a closed enum — the value is passed through from per-customer Kanban configuration and may be any value. Common values today are TO_DO, IN_PROGRESS, INVOICED, and CLOSED (closed without invoicing); clients must ignore any value not in that set without erroring, as the set may expand in future releases."
          },
          "stageAction" : {
            "type" : "string",
            "examples" : [ "DO_WORK" ],
            "description" : "Action expected next at the current stage. Free-form string, not a closed enum — the value is passed through from per-customer Kanban configuration and may be any value. Common values today are GET_AUTH, WAIT_FOR_AUTH, DO_WORK, INVOICE, COLLECT, and COMPLETE; clients must ignore any value not in that set without erroring, as the set may expand in future releases. Not meaningful when workOrderStage is CLOSED: it keeps the value it had when the Work Order was closed."
          },
          "workOrderRequest" : {
            "type" : "string",
            "description" : "Customer's stated request for the Work Order (sourced from the internal description field)."
          },
          "isArchived" : {
            "type" : "boolean",
            "description" : "True when the Work Order has been archived."
          },
          "enrichmentPartial" : {
            "type" : [ "boolean", "null" ],
            "description" : "Present and true when wor-cache-svc experienced a transient failure during this request. workOrderCustomer.displayName and/or workOrderUnit.displayName may be null as a result. A subsequent request should return full display names once the cache service recovers."
          }
        }
      },
      "WorkOrderSearchParams" : {
        "type" : "object",
        "description" : "Filter, sort, and pagination parameters for the list Work Orders endpoint. All fields are optional query parameters; omit any to accept its default.",
        "properties" : {
          "status" : {
            "type" : "array",
            "items" : {
              "type" : "string"
            }
          },
          "createdFrom" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          },
          "createdTo" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          },
          "updatedSince" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          },
          "includeArchived" : {
            "type" : "boolean"
          },
          "sortBy" : {
            "type" : "string",
            "enum" : [ "createdAt" ],
            "pattern" : "createdAt",
            "default" : "createdAt"
          },
          "sortOrder" : {
            "type" : "string",
            "enum" : [ "asc", "desc" ],
            "pattern" : "asc|desc",
            "default" : "desc"
          },
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "minimum" : 1
          },
          "pageSize" : {
            "type" : "integer",
            "format" : "int32",
            "maximum" : 100,
            "minimum" : 1
          }
        }
      }
    },
    "securitySchemes" : {
      "SecurityScheme" : {
        "description" : "Authenticated requests carry a Descope-issued JWT in the Authorization header.",
        "type" : "http",
        "scheme" : "bearer",
        "bearerFormat" : "JWT"
      }
    }
  },
  "tags" : [ {
    "name" : "Work Orders",
    "description" : "Read-only access to Work Orders for the public API (v1)."
  } ],
  "paths" : {
    "/v1/accounts/{accountId}/work-orders" : {
      "get" : {
        "summary" : "List Work Orders (paginated).",
        "description" : "Returns a paginated page of Work Order summaries for the account. The default sort is deterministic: workOrderCreatedDate descending (newest first) with workOrderId ascending as a stable tie-breaker, so paging never skips or duplicates rows. Walk pages with page/pageSize and stop when pagination.hasMore is false. Narrow results with status, a created-date range (createdFrom/createdTo), and updatedSince for incremental sync. Invalid filter or paging params return 400 with the standard error envelope.",
        "tags" : [ "Work Orders" ],
        "parameters" : [ {
          "description" : "Account whose Work Orders are listed (path-scoped).",
          "name" : "accountId",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string",
            "minLength" : 1
          }
        }, {
          "description" : "Inclusive lower bound on Work Order created date (ISO 8601 UTC, e.g. 2026-05-01T00:00:00Z).",
          "name" : "createdFrom",
          "in" : "query",
          "schema" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          }
        }, {
          "description" : "Inclusive upper bound on Work Order created date (ISO 8601 UTC, e.g. 2026-05-22T23:59:59Z).",
          "name" : "createdTo",
          "in" : "query",
          "schema" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          }
        }, {
          "description" : "When true, also include archived (deleted) Work Orders. Defaults to false (live Work Orders only).",
          "name" : "includeArchived",
          "in" : "query",
          "schema" : {
            "type" : "boolean",
            "default" : "false"
          }
        }, {
          "description" : "1-based page index. Defaults to 1.",
          "name" : "page",
          "in" : "query",
          "schema" : {
            "type" : "integer",
            "format" : "int32",
            "default" : "1",
            "minimum" : 1
          }
        }, {
          "description" : "Items per page. Defaults to 25, minimum 1, maximum 100.",
          "name" : "pageSize",
          "in" : "query",
          "schema" : {
            "type" : "integer",
            "format" : "int32",
            "default" : "25",
            "maximum" : 100,
            "minimum" : 1
          }
        }, {
          "description" : "Field to sort by. Only 'createdAt' is supported in v1.",
          "name" : "sortBy",
          "in" : "query",
          "schema" : {
            "type" : "string",
            "enum" : [ "createdAt" ],
            "pattern" : "createdAt",
            "default" : "createdAt"
          }
        }, {
          "description" : "Sort direction: 'asc' or 'desc'. Defaults to 'desc' (newest first).",
          "name" : "sortOrder",
          "in" : "query",
          "schema" : {
            "type" : "string",
            "enum" : [ "asc", "desc" ],
            "pattern" : "asc|desc",
            "default" : "desc"
          }
        }, {
          "description" : "Filter to a single workflow stage. Allowed values: TO_DO, IN_PROGRESS, INVOICED, CLOSED. CLOSED returns Work Orders closed without invoicing; the other values exclude them. v1 accepts at most one value; submitting multiple returns 400. Omit to return all stages.",
          "schema" : {
            "type" : "string",
            "enum" : [ "TO_DO", "IN_PROGRESS", "INVOICED", "CLOSED" ]
          },
          "name" : "status",
          "in" : "query"
        }, {
          "description" : "Return only Work Orders updated at or after this instant (ISO 8601 UTC). Use for incremental sync.",
          "name" : "updatedSince",
          "in" : "query",
          "schema" : {
            "type" : "string",
            "pattern" : "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "A page of Work Order summaries plus pagination metadata.",
            "content" : {
              "application/json" : {
                "examples" : {
                  "page" : {
                    "summary" : "First page of results",
                    "value" : {
                      "data" : {
                        "items" : [ {
                          "workOrderId" : "wor_8f3c2a1e9b7d4c5f",
                          "workOrderNumber" : "WO-10472",
                          "workOrderCustomer" : {
                            "id" : "cus_4a2b9d",
                            "displayName" : "Acme Freight Co."
                          },
                          "workOrderUnit" : {
                            "id" : "unt_77c1e0",
                            "displayName" : "Unit 204 - 2021 Freightliner Cascadia"
                          },
                          "workOrderCreatedDate" : "2026-05-22T17:42:18Z",
                          "workOrderUpdatedDate" : "2026-05-23T09:15:04Z",
                          "workOrderStage" : "IN_PROGRESS",
                          "stageAction" : "DO_WORK",
                          "workOrderRequest" : "Replace front brake pads and inspect rotors.",
                          "isArchived" : false
                        }, {
                          "workOrderId" : "wor_1b6e90a3c2f74d8e",
                          "workOrderNumber" : "WO-10471",
                          "workOrderCustomer" : {
                            "id" : "cus_91f0aa",
                            "displayName" : "Sunrise Logistics"
                          },
                          "workOrderUnit" : {
                            "id" : "unt_2db430",
                            "displayName" : null
                          },
                          "workOrderCreatedDate" : "2026-05-22T14:08:55Z",
                          "workOrderUpdatedDate" : "2026-05-22T14:08:55Z",
                          "workOrderStage" : "TO_DO",
                          "stageAction" : "GET_AUTH",
                          "workOrderRequest" : "Annual DOT inspection.",
                          "isArchived" : false
                        } ],
                        "pagination" : {
                          "page" : 1,
                          "pageSize" : 25,
                          "totalItems" : 137,
                          "totalPages" : 6,
                          "hasMore" : true
                        }
                      },
                      "error" : null
                    }
                  }
                }
              }
            }
          },
          "400" : {
            "description" : "A filter, sort, or paging parameter failed validation (e.g. pageSize > 100 or a malformed date).",
            "content" : {
              "application/json" : {
                "examples" : {
                  "validationError" : {
                    "summary" : "Standard error envelope",
                    "value" : {
                      "data" : null,
                      "error" : {
                        "id" : "err_9c1d4b8a2f",
                        "details" : [ {
                          "messageId" : "pageSize must be <= 100"
                        }, {
                          "messageId" : "REQUEST_ID",
                          "value" : "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
                        } ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security" : [ {
          "SecurityScheme" : [ ]
        } ]
      }
    },
    "/v1/accounts/{accountId}/work-orders/{workOrderId}" : {
      "get" : {
        "summary" : "Get a single Work Order by ID.",
        "description" : "Returns the Work Order summary payload for the supplied identifier. Intended for deep linking or validation of an ID already obtained from the list endpoint.",
        "tags" : [ "Work Orders" ],
        "parameters" : [ {
          "description" : "Account that owns the Work Order (path-scoped).",
          "name" : "accountId",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string",
            "minLength" : 1
          }
        }, {
          "description" : "Stable identifier of the Work Order to retrieve.",
          "name" : "workOrderId",
          "in" : "path",
          "required" : true,
          "schema" : {
            "type" : "string",
            "minLength" : 1
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "The Work Order summary for the supplied identifier.",
            "content" : {
              "application/json" : {
                "examples" : {
                  "workOrder" : {
                    "summary" : "A single Work Order",
                    "value" : {
                      "data" : {
                        "workOrderId" : "wor_8f3c2a1e9b7d4c5f",
                        "workOrderNumber" : "WO-10472",
                        "workOrderCustomer" : {
                          "id" : "cus_4a2b9d",
                          "displayName" : "Acme Freight Co."
                        },
                        "workOrderUnit" : {
                          "id" : "unt_77c1e0",
                          "displayName" : "Unit 204 - 2021 Freightliner Cascadia"
                        },
                        "workOrderCreatedDate" : "2026-05-22T17:42:18Z",
                        "workOrderUpdatedDate" : "2026-05-23T09:15:04Z",
                        "workOrderStage" : "IN_PROGRESS",
                        "stageAction" : "DO_WORK",
                        "workOrderRequest" : "Replace front brake pads and inspect rotors.",
                        "isArchived" : false
                      },
                      "error" : null
                    }
                  }
                }
              }
            }
          },
          "403" : {
            "description" : "The Work Order exists but is not accessible to the caller, or the caller is not authorized for the requested account."
          },
          "404" : {
            "description" : "No Work Order with the supplied identifier exists for the account.",
            "content" : {
              "application/json" : {
                "examples" : {
                  "notFound" : {
                    "summary" : "Standard error envelope",
                    "value" : {
                      "data" : null,
                      "error" : {
                        "id" : "err_3f9a1c7e2d",
                        "details" : [ {
                          "messageId" : "WORK_ORDER_NOT_FOUND"
                        }, {
                          "messageId" : "REQUEST_ID",
                          "value" : "a1b2c3d4-e5f6-7890-abcd-1234567890ab"
                        } ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security" : [ {
          "SecurityScheme" : [ ]
        } ]
      }
    }
  },
  "info" : {
    "title" : "Repair Center Public API",
    "version" : "1.0.0-SNAPSHOT",
    "description" : "Repair Center Public API (v1).\n\n## Versioning\n\nBreaking changes ship under a new major version (e.g. /v2). Additive fields may be added within v1 — clients MUST ignore unknown fields. Deprecated endpoints and fields are marked in OpenAPI (deprecated: true) and kept live for a 6-month notice window before removal in the next major version.\n\n## Rate limiting\n\nRate limiting is enforced upstream at the API Gateway / WAF layer (IP-based, coarse) — this API does not emit 429s itself. Clients should still handle 429 Too Many Requests with exponential backoff and honor the Retry-After header when present.\n\n## Errors\n\nAll errors return the standard envelope: a stable error id, a details list (carrying a messageId and a REQUEST_ID entry), and an X-Request-Id response header. Quote the request id when contacting support."
  }
}