{
  "openapi": "3.1.0",
  "info": {
    "title": "Bare company directory",
    "version": "1.0.0",
    "description": "Free read-only company source reviews, separate from website attribution. Shared public directory budgets: 60 reads per IP per minute, 10000 service reads per UTC day."
  },
  "servers": [
    {
      "url": "https://bare.io"
    }
  ],
  "paths": {
    "/api/provider-companies": {
      "get": {
        "summary": "Read verified brand and service profiles",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 80
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hosting",
                "cloud",
                "platform",
                "cdn",
                "specialist"
              ]
            }
          },
          {
            "name": "confidence",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "high",
                "medium"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9999,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of at most 24 dated source reviews. sourceStatusAvailable=false explicitly marks unavailable monitoring; no upstream checks occur.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version",
                    "total",
                    "page",
                    "pages",
                    "pageSize",
                    "entries",
                    "sourceStatusAvailable"
                  ],
                  "properties": {
                    "version": {
                      "const": 1
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "pages": {
                      "type": "integer"
                    },
                    "pageSize": {
                      "const": 24
                    },
                    "sourceStatusAvailable": {
                      "type": "boolean"
                    },
                    "entries": {
                      "type": "array",
                      "maxItems": 24,
                      "items": {
                        "$ref": "#/components/schemas/Company"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid, unknown or duplicate filter"
          },
          "429": {
            "description": "Read quota exhausted; honor Retry-After"
          },
          "503": {
            "description": "Directory storage or service unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Company": {
        "type": "object",
        "required": [
          "id",
          "name",
          "website",
          "kind",
          "description",
          "aliases",
          "reviewedAt",
          "confidence",
          "sources",
          "path",
          "sourceCheck"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "website": {
            "type": "string",
            "format": "uri"
          },
          "kind": {
            "enum": [
              "hosting",
              "cloud",
              "platform",
              "cdn",
              "specialist"
            ]
          },
          "description": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time"
          },
          "confidence": {
            "enum": [
              "high",
              "medium"
            ],
            "description": "Confidence in the official brand/service evidence at manual review time, not hosting attribution or service quality."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "title": {
                  "type": "string"
                },
                "evidence": {
                  "type": "string"
                }
              }
            }
          },
          "path": {
            "type": "string"
          },
          "sourceCheck": {
            "type": "object",
            "properties": {
              "state": {
                "enum": [
                  "matched",
                  "changed",
                  "unreachable",
                  "redirect-review",
                  "blocked",
                  "not-checked",
                  "stale",
                  "limited",
                  "not-monitored"
                ]
              },
              "attemptedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "matchedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "nextCheckAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "httpStatus": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "contentHash": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sourceUrl": {
                "type": "string",
                "format": "uri"
              }
            },
            "description": "Automatic source signals only; matched is not a full identity re-verification."
          },
          "reviewBasis": {
            "type": "string",
            "enum": [
              "official-source",
              "saved-evidence"
            ],
            "description": "Whether the catalog review uses a direct official-source review or retained reviewed evidence. Neither is a fresh availability check."
          }
        }
      }
    }
  }
}