{
  "openapi": "3.1.0",
  "info": {
    "title": "Honest Load Board API",
    "version": "1.0.0",
    "description": "API for brokers to post loads and receive webhook booking notifications on Honest Load Board."
  },
  "servers": [
    {
      "url": "https://honestloadboard.com",
      "description": "Honest Load Board Production Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/honest-load-board/v1/loads": {
      "post": {
        "summary": "Post a load",
        "description": "Posts a load to Honest Load Board. Uses posting credit after the initial 25 free posts.",
        "operationId": "createLoad",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLoadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Load posted successfully, or existing load returned if externalId matched.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["load"],
                  "properties": {
                    "load": { "$ref": "#/components/schemas/Load" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "402": {
            "description": "Payment required - insufficient posting credit",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "403": {
            "description": "Forbidden - broker vetting required",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List loads",
        "description": "Returns all loads posted by this broker account.",
        "operationId": "listLoads",
        "responses": {
          "200": {
            "description": "List of loads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["loads"],
                  "properties": {
                    "loads": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Load" }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/honest-load-board/v1/loads/{id}": {
      "get": {
        "summary": "Get a load",
        "description": "Returns a single load by ID.",
        "operationId": "getLoad",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Load ID (UUID)",
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Load details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["load"],
                  "properties": {
                    "load": { "$ref": "#/components/schemas/Load" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Load not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/honest-load-board/v1/loads/{id}/cancel": {
      "post": {
        "summary": "Cancel a load",
        "description": "Cancels an open load before pickup cutoff.",
        "operationId": "cancelLoad",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Load ID (UUID)",
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Load cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["load"],
                  "properties": {
                    "load": { "$ref": "#/components/schemas/Load" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "404": {
            "description": "Load not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "loadEvents": {
      "post": {
        "summary": "Load event webhook",
        "description": "Sent to your configured webhook URL when events occur.",
        "parameters": [
          {
            "name": "HLB-Signature",
            "in": "header",
            "required": true,
            "description": "Timestamp and HMAC-SHA256 signature, formatted as t=<timestamp>,v1=<signature>.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id", "type", "createdAt", "load"],
                "properties": {
                  "id": { "type": "string", "format": "uuid" },
                  "type": {
                    "type": "string",
                    "enum": ["load.booked", "load.cancelled", "load.closed", "load.test"]
                  },
                  "createdAt": { "type": "string", "format": "date-time" },
                  "load": { "$ref": "#/components/schemas/Load" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Webhook received successfully" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API key created in Settings. Pass as Authorization: Bearer <key>."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" }
        }
      },
      "Stop": {
        "type": "object",
        "required": ["street", "city", "state", "zip", "start", "end"],
        "properties": {
          "street": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" },
          "zip": { "type": "string", "pattern": "^\\d{5}$" },
          "start": { "type": "string", "format": "date-time" },
          "end": { "type": "string", "format": "date-time" }
        }
      },
      "Lumper": {
        "type": "object",
        "required": ["needed"],
        "properties": {
          "needed": { "type": "boolean" },
          "paidBy": { "type": "string", "enum": ["broker", "reimbursed"] }
        }
      },
      "CreateLoadRequest": {
        "type": "object",
        "required": [
          "terms",
          "pickup",
          "delivery",
          "equipment",
          "loadType",
          "weightLbs",
          "startPrice",
          "topPrice",
          "risePerStep",
          "stepMinutes",
          "fuelSurchargeIncluded",
          "rush",
          "lumper"
        ],
        "properties": {
          "terms": { "type": "string", "enum": ["2026-10-31", "2026-11-01"] },
          "externalId": { "type": "string", "maxLength": 120 },
          "pickup": { "$ref": "#/components/schemas/Stop" },
          "delivery": { "$ref": "#/components/schemas/Stop" },
          "equipment": {
            "type": "string",
            "enum": ["dry_van", "reefer", "flatbed", "step_deck"]
          },
          "loadType": {
            "type": "string",
            "enum": [
              "drop_hook",
              "empty_live_drop",
              "load_out",
              "live_load",
              "live_unload",
              "live_both"
            ]
          },
          "weightLbs": { "type": "integer", "minimum": 1, "maximum": 120000 },
          "startPrice": { "type": "number", "minimum": 1 },
          "topPrice": { "type": "number", "minimum": 1 },
          "risePerStep": { "type": "number", "minimum": 1 },
          "stepMinutes": { "type": "integer", "minimum": 1 },
          "fuelSurchargeIncluded": { "type": "boolean", "enum": [true] },
          "rush": { "type": "boolean" },
          "minAuthorityDays": { "type": "integer", "enum": [0, 90] },
          "lumper": { "$ref": "#/components/schemas/Lumper" },
          "temperatureF": { "type": "number", "minimum": -40, "maximum": 90 },
          "minus10Capable": { "type": "boolean" },
          "tarpDropFt": { "type": "integer", "enum": [4, 6, 8] },
          "chainsRequired": { "type": "boolean" },
          "returnBy": { "type": "string", "format": "date-time" }
        }
      },
      "Load": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "externalId": { "type": ["string", "null"] },
          "status": { "type": "string" },
          "origin": { "type": "object" },
          "destination": { "type": "object" },
          "equipment": { "type": "string" },
          "loadType": { "type": "string" },
          "weightLbs": { "type": "integer" },
          "currentPrice": { "type": "number" },
          "bookedCarrier": { "type": "object" }
        }
      }
    }
  }
}