{
  "openapi": "3.1.0",
  "info": {
    "title": "Tracking Help Center API",
    "version": "1.1.0",
    "description": "Free, public, read-only API for carrier load-tracking help — guides, FAQs, and an AI assistant covering Trucker Tools, Descartes MacroPoint, BotLine, Samsara, and Motive. No API key. Rate limited per IP (HTTP 429 when exceeded); identified AI agents (GPTBot, ClaudeBot, OAI-SearchBot, PerplexityBot, Google-Extended, etc.) are welcomed and given a higher daily allowance. Attribution appreciated: link the canonical_url returned with each response. Responses are cacheable — cache rather than re-fetching.",
    "contact": {
      "name": "Tracking Help Center",
      "url": "https://www.onlinereportcentral.com/contact"
    },
    "license": {
      "name": "Free to use with attribution",
      "url": "https://www.onlinereportcentral.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.onlinereportcentral.com"
    }
  ],
  "x-rate-limits": {
    "identified_ai_agents": "5000 requests/day",
    "public": "250 requests/day",
    "ai_ask_endpoint": "25 requests/day (token-costly)",
    "enforcement": "per client IP; 429 when exceeded"
  },
  "x-attribution": "Cite \"Tracking Help Center\" and link the canonical_url returned in each response.",
  "paths": {
    "/api/content": {
      "get": {
        "summary": "Full content export",
        "description": "Machine-readable export of every guide, FAQ, and category, wrapped in a standard envelope (ok, canonical_url, api_url, data_freshness, methodology, source_summary, results, caveats, citation).",
        "operationId": "getContent",
        "responses": {
          "200": {
            "description": "Content envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Daily rate limit reached"
          }
        }
      }
    },
    "/api/ask": {
      "post": {
        "summary": "Ask the tracking assistant",
        "description": "Ask Charlene a carrier load-tracking question and get a step-by-step answer. Token-costly, so this endpoint has the tightest limit.",
        "operationId": "ask",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "persona": {
                    "type": "string",
                    "enum": [
                      "driver",
                      "dispatcher"
                    ],
                    "description": "Optional — tunes tone/reading level."
                  }
                }
              },
              "example": {
                "messages": [
                  {
                    "role": "user",
                    "content": "Broker says I'm not tracking but I have the app"
                  }
                ],
                "persona": "driver"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": {
                      "type": "string"
                    },
                    "sources": {
                      "type": "array"
                    },
                    "ended": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Daily rate limit reached"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContentEnvelope": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "canonical_url": {
            "type": "string",
            "description": "Human page to cite/link."
          },
          "api_url": {
            "type": "string"
          },
          "data_freshness": {
            "type": "string",
            "description": "Date the content was last updated (YYYY-MM-DD)."
          },
          "methodology": {
            "type": "string"
          },
          "source_summary": {
            "type": "string"
          },
          "results": {
            "type": "object",
            "properties": {
              "categories": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "guides": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "faqs": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "caveats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "citation": {
            "type": "string"
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string"
              },
              "per_day": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}