{
  "openapi": "3.1.0",
  "info": {
    "title": "Snowline Real Business Intelligence API",
    "description": "Public REST API for Snowline — Real Business Tracker. Access verified enterprise company data, real-time market updates, sector reports, and search endpoints. Supports RFC 9457 Problem Details error formats and acceptmarkdown.com content negotiation.",
    "version": "1.0.0",
    "contact": {
      "name": "Snowline App",
      "url": "https://snowlineapp.xyz",
      "email": "support@snowlineapp.xyz"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://snowlineapp.xyz",
      "description": "Production (Apex Domain)"
    },
    {
      "url": "https://snowlinehq.vercel.app",
      "description": "Vercel Edge Deployment"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development"
    }
  ],
  "paths": {
    "/api/businesses": {
      "get": {
        "summary": "List all tracked businesses",
        "description": "Returns the complete catalog of verified technology enterprises and AI labs tracked on Snowline.",
        "operationId": "listBusinesses",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by business category (e.g. 'Artificial Intelligence', 'Search & Cloud', 'Semiconductor & Silicon')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of tracked businesses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "integer" },
                    "businesses": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Business" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request or invalid query parameters.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/businesses/{slug}": {
      "get": {
        "summary": "Get business by slug",
        "description": "Retrieve deep company intelligence, metrics, and milestones by business slug (e.g., 'anthropic', 'nvidia', 'alphabet').",
        "operationId": "getBusinessBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The unique identifier or slug of the business",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Business profile details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Business" }
              }
            }
          },
          "404": {
            "description": "Business not found.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/updates": {
      "get": {
        "summary": "List verified updates",
        "description": "Retrieve recent corporate milestones, product launches, earnings reports, and regulatory filings.",
        "operationId": "listUpdates",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of updates to return",
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of recent market updates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "integer" },
                    "updates": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Update" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/updates/{slug}": {
      "get": {
        "summary": "Get update by slug",
        "description": "Retrieve detailed information on a single corporate milestone or market update.",
        "operationId": "getUpdateBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The unique headline slug or ID of the update",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Update details.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Update" }
              }
            }
          },
          "404": {
            "description": "Update milestone not found.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/reports": {
      "get": {
        "summary": "List sector reports",
        "description": "Retrieve structured intelligence summaries across key technology sectors.",
        "operationId": "listReports",
        "responses": {
          "200": {
            "description": "List of industry sector intelligence reports.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "integer" },
                    "reports": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Report" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Search businesses and updates",
        "description": "Perform full-text search across tracked enterprises, categories, summaries, and news headlines.",
        "operationId": "searchEntities",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query string",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching businesses and updates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "total": { "type": "integer" },
                    "businesses": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Business" }
                    },
                    "updates": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Update" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing search query parameter.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Service health check",
        "description": "Verify API service availability and version metadata.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string", "example": "snowline" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "version": { "type": "string", "example": "1.0.0" },
                    "agentReadiness": {
                      "type": "object",
                      "properties": {
                        "acceptMarkdown": { "type": "boolean" },
                        "llmsTxt": { "type": "string" },
                        "openapi": { "type": "string" },
                        "sitemap": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "RFC 9457 compliant Problem Details error model providing machine-readable error codes and resolution guidance.",
        "required": ["type", "title", "status", "detail", "code", "resolution", "timestamp"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference identifying the problem type."
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code generated by the origin server for this occurrence."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem."
          },
          "code": {
            "type": "string",
            "description": "A unique machine-readable error code for AI agent triage (e.g., 'BUSINESS_NOT_FOUND', 'INVALID_QUERY_PARAMETER', 'ENDPOINT_NOT_FOUND')."
          },
          "resolution": {
            "type": "string",
            "description": "Specific actionable guidance explaining how the client or agent can remediate the error."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the error occurred."
          },
          "instance": {
            "type": "string",
            "description": "A URI reference that identifies the specific occurrence of the problem."
          }
        }
      },
      "Business": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "verified": { "type": "boolean" },
          "shortDescription": { "type": "string" },
          "description": { "type": "string" },
          "logoUrl": { "type": "string" },
          "stats": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": { "type": "string" },
                "value": { "type": "string" }
              }
            }
          },
          "latestUpdate": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "date": { "type": "string" },
              "platform": { "type": "string" },
              "sourceUrl": { "type": "string" }
            }
          }
        }
      },
      "Update": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "businessName": { "type": "string" },
          "businessSlug": { "type": "string" },
          "newsTitle": { "type": "string" },
          "publishedAt": { "type": "string" },
          "platform": { "type": "string" },
          "category": { "type": "string" },
          "summary": { "type": "string" },
          "content": {
            "type": "array",
            "items": { "type": "string" }
          },
          "sourceUrl": { "type": "string" }
        }
      },
      "Report": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "sector": { "type": "string" },
          "summary": { "type": "string" },
          "companiesCovered": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    }
  }
}