{
  "openapi": "3.0.3",
  "info": {
    "title": "HaulMatch organization integrations",
    "version": "1.0.0",
    "description": "Organization-scoped load, quote and fleet operations. Writes require stable Idempotency-Key headers. Machine credentials cannot move money."
  },
  "servers": [
    {
      "url": "https://YOUR_GATEWAY/api/integrations/v1"
    }
  ],
  "security": [
    {
      "organizationKey": []
    }
  ],
  "paths": {
    "/loads": {
      "get": {
        "summary": "Organization loads for a shipper; public available loads for a fleet",
        "x-required-scope": "loads:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    {
                      "type": "object",
                      "additionalProperties": true
                    }
                  ],
                  "description": "Shippers receive their organization loads as an array. Fleets receive a paginated marketplace result."
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a shipper organization load",
        "x-required-scope": "loads:write",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLoad"
              }
            }
          }
        }
      }
    },
    "/quotes": {
      "get": {
        "summary": "List shipper load quotes or this fleet\u2019s quotes",
        "x-required-scope": "quotes:read",
        "parameters": [
          {
            "name": "jobId",
            "in": "query",
            "description": "Required for shippers; optional for fleets",
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit a fleet quote with explicit payout ownership",
        "x-required-scope": "quotes:write",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateQuote"
              }
            }
          }
        }
      }
    },
    "/quotes/{quoteId}/update": {
      "post": {
        "summary": "Update a pending fleet quote",
        "x-required-scope": "quotes:write",
        "parameters": [
          {
            "name": "quoteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateQuote"
              }
            }
          }
        }
      }
    },
    "/quotes/{quoteId}/withdraw": {
      "post": {
        "summary": "Withdraw a pending fleet quote",
        "x-required-scope": "quotes:write",
        "parameters": [
          {
            "name": "quoteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{quoteId}/accept": {
      "post": {
        "summary": "Award a shipper organization load",
        "x-required-scope": "quotes:accept",
        "parameters": [
          {
            "name": "quoteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "acknowledgeUnverifiedRisk": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs": {
      "get": {
        "summary": "List organization jobs; fleet keys see their assigned team",
        "x-required-scope": "jobs:read",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "summary": "Get an organization job and authorized quotes",
        "x-required-scope": "jobs:read",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/release-booking": {
      "post": {
        "summary": "Release an unfunded booking and relist its load",
        "x-required-scope": "jobs:write",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/status": {
      "post": {
        "summary": "Update an authorized job\u2019s delivery state",
        "x-required-scope": "jobs:write",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "IN_TRANSIT",
                      "COMPLETED",
                      "CANCELLED"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/driver": {
      "post": {
        "summary": "Allocate a verified operating driver to a COMPANY-pay job before transit",
        "x-required-scope": "drivers:assign",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "driverId"
                ],
                "properties": {
                  "driverId": {
                    "type": "string",
                    "description": ""
                  },
                  "teamId": {
                    "type": "string",
                    "description": ""
                  }
                }
              }
            }
          }
        }
      }
    },
    "/drivers": {
      "get": {
        "summary": "List fleet member drivers within the key\u2019s team restriction",
        "x-required-scope": "drivers:read",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/tracking": {
      "get": {
        "summary": "Get tracking for an organization job",
        "x-required-scope": "tracking:read",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/payment": {
      "get": {
        "summary": "Read the job\u2019s milestone payment and ledger",
        "x-required-scope": "payments:read",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}/documents/{type}": {
      "get": {
        "summary": "Generate an authorized PDF; response contains filename, contentType and base64",
        "x-required-scope": "documents:read",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/references/{kind}/{externalRef}": {
      "get": {
        "summary": "Look up a tenant-authorized partner reference (LOAD or QUOTE)",
        "x-required-scope": "jobs:read",
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          },
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{quoteId}/preview": {
      "get": {
        "summary": "Preview shipper freight, GST, fees and total before awarding a quote",
        "x-required-scope": "quotes:read",
        "parameters": [
          {
            "name": "quoteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": ""
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; list responses are bounded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Payload validation failed"
          },
          "401": {
            "description": "Missing organization key"
          },
          "403": {
            "description": "Scope, organization, team or current membership denied"
          },
          "404": {
            "description": "Resource not found"
          },
          "409": {
            "description": "Idempotency, external-reference or lifecycle conflict"
          },
          "503": {
            "description": "Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "429": {
            "description": "A shared organisation, key or endpoint quota was reached. Respect Retry-After.",
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying with the original request identifier.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "organizationKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Owner-issued hm_org_... key; server enforces its scopes and team assignment."
      }
    },
    "schemas": {
      "LoadData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "pickupLocation",
          "dropoffLocation",
          "loadType",
          "itemName",
          "readiness"
        ],
        "properties": {
          "pickupLocation": {
            "type": "string",
            "description": "Pickup address, minimum 3 characters",
            "minLength": 3
          },
          "pickupLat": {
            "type": "number",
            "description": "",
            "minimum": -90,
            "maximum": 90
          },
          "pickupLng": {
            "type": "number",
            "description": "",
            "minimum": -180,
            "maximum": 180
          },
          "pickupOsmLat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "pickupOsmLng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "pickupGeoProvider": {
            "type": "string",
            "enum": [
              "GOOGLE",
              "OSM",
              "MANUAL",
              "INTERNAL"
            ]
          },
          "pickupPlaceId": {
            "type": "string"
          },
          "dropoffLocation": {
            "type": "string",
            "description": "Delivery address, minimum 3 characters",
            "minLength": 3
          },
          "dropoffLat": {
            "type": "number",
            "description": "",
            "minimum": -90,
            "maximum": 90
          },
          "dropoffLng": {
            "type": "number",
            "description": "",
            "minimum": -180,
            "maximum": 180
          },
          "dropoffOsmLat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "dropoffOsmLng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "dropoffGeoProvider": {
            "type": "string",
            "enum": [
              "GOOGLE",
              "OSM",
              "MANUAL",
              "INTERNAL"
            ]
          },
          "dropoffPlaceId": {
            "type": "string"
          },
          "loadType": {
            "type": "string",
            "description": "Freight category"
          },
          "itemName": {
            "type": "string",
            "description": "Load title",
            "minLength": 2
          },
          "readiness": {
            "type": "string",
            "enum": [
              "READY_NOW",
              "URGENT",
              "AVAILABLE_FROM",
              "ESTIMATE_ONLY"
            ]
          },
          "availableFromDate": {
            "type": "string",
            "description": "ISO 8601 date or date-time"
          },
          "loadWeight": {
            "type": "number",
            "description": "Total weight in kg",
            "minimum": 0
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "itemLength": {
            "type": "number",
            "description": "Metres",
            "minimum": 0
          },
          "itemWidth": {
            "type": "number",
            "description": "Metres",
            "minimum": 0
          },
          "itemHeight": {
            "type": "number",
            "description": "Metres",
            "minimum": 0
          },
          "weightEach": {
            "type": "number",
            "description": "Weight per item in kg",
            "minimum": 0
          },
          "hasDelicateItems": {
            "type": "boolean"
          },
          "needsBlanketWrap": {
            "type": "boolean"
          },
          "needsAssemblyAssist": {
            "type": "boolean"
          },
          "isDriveable": {
            "type": "boolean"
          },
          "isNew": {
            "type": "boolean"
          },
          "needsCovered": {
            "type": "boolean"
          },
          "isEmpty": {
            "type": "boolean"
          },
          "atInternationalPort": {
            "type": "boolean"
          },
          "requiresContainerHire": {
            "type": "boolean"
          },
          "isRegistered": {
            "type": "boolean"
          },
          "hasDangerousGoods": {
            "type": "boolean"
          },
          "contentsSecured": {
            "type": "boolean"
          },
          "pipeMaterial": {
            "type": "string"
          },
          "needsBolsters": {
            "type": "boolean"
          },
          "pipePackaging": {
            "type": "string"
          },
          "isPalletised": {
            "type": "boolean"
          },
          "temperatureC": {
            "type": "number"
          },
          "hayPackaging": {
            "type": "string"
          },
          "needsMoistureProtection": {
            "type": "boolean"
          },
          "hayType": {
            "type": "string"
          },
          "needsTippingTrailer": {
            "type": "boolean"
          },
          "pickupSiteType": {
            "type": "string"
          },
          "pickupFacilities": {
            "type": "string"
          },
          "pickupNotes": {
            "type": "string"
          },
          "pickupContactName": {
            "type": "string"
          },
          "pickupContactPhone": {
            "type": "string"
          },
          "dropoffSiteType": {
            "type": "string"
          },
          "dropoffFacilities": {
            "type": "string"
          },
          "dropoffNotes": {
            "type": "string"
          },
          "dropoffContactName": {
            "type": "string"
          },
          "dropoffContactPhone": {
            "type": "string"
          },
          "budget": {
            "type": "number",
            "description": "Optional AUD target price",
            "minimum": 0
          },
          "budgetPublished": {
            "type": "boolean"
          },
          "requiredDate": {
            "type": "string",
            "description": "ISO 8601 date or date-time"
          },
          "details": {
            "type": "string",
            "description": "Equipment, time windows and freight instructions"
          },
          "imageUrls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "QuoteData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "jobId",
          "amount"
        ],
        "properties": {
          "jobId": {
            "type": "string",
            "description": ""
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "AUD, excluding GST, at most two decimal places"
          },
          "baseRate": {
            "type": "number",
            "description": "",
            "minimum": 0
          },
          "distanceFee": {
            "type": "number",
            "description": "",
            "minimum": 0
          },
          "laborFee": {
            "type": "number",
            "description": "",
            "minimum": 0
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expectedDriverReceivesCents": {
            "type": "integer"
          },
          "message": {
            "type": "string",
            "description": ""
          },
          "pickupPlan": {
            "type": "string",
            "description": "",
            "minLength": 2,
            "maxLength": 160
          },
          "deliveryPlan": {
            "type": "string",
            "description": "",
            "minLength": 2,
            "maxLength": 160
          },
          "vehicleEquipment": {
            "type": "string",
            "description": "",
            "minLength": 2,
            "maxLength": 160
          },
          "bundleId": {
            "type": "string"
          }
        }
      },
      "CreateLoad": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/LoadData"
          },
          "externalRef": {
            "type": "string",
            "maxLength": 160
          }
        }
      },
      "CreateQuote": {
        "type": "object",
        "required": [
          "data",
          "payoutMode"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/QuoteData"
          },
          "payoutMode": {
            "type": "string",
            "enum": [
              "DRIVER",
              "COMPANY"
            ]
          },
          "driverId": {
            "type": "string",
            "description": "Required for DRIVER mode; current fleet member"
          },
          "teamId": {
            "type": "string",
            "description": "Ignored in favour of a key\u2019s fixed team restriction"
          },
          "externalRef": {
            "type": "string",
            "maxLength": 160
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer"
          },
          "message": {
            "type": "string",
            "description": ""
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt",
          "organizationId",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": ""
          },
          "type": {
            "type": "string",
            "description": ""
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "organizationId": {
            "type": "string",
            "description": ""
          },
          "teamId": {
            "type": "string",
            "nullable": true
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "UpdateQuote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "minimum": 0.01
          },
          "baseRate": {
            "type": "number",
            "minimum": 0
          },
          "distanceFee": {
            "type": "number",
            "minimum": 0
          },
          "laborFee": {
            "type": "number",
            "minimum": 0
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expectedDriverReceivesCents": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "pickupPlan": {
            "type": "string",
            "minLength": 2,
            "maxLength": 160
          },
          "deliveryPlan": {
            "type": "string",
            "minLength": 2,
            "maxLength": 160
          },
          "vehicleEquipment": {
            "type": "string",
            "minLength": 2,
            "maxLength": 160
          },
          "bundleId": {
            "type": "string"
          }
        }
      }
    }
  }
}