{
  "openapi": "3.1.0",
  "info": {
    "title": "StartupDatabase.ph Public API",
    "version": "1.0.0",
    "description": "Read-only access to approved Philippine startups, products, and ecosystem organizations, including investors. No API key required. Results are cached for up to five minutes. Cite profile_url; missing fields are unknown. Unknown or repeated search parameters return 400. Results sort by name, then ID.",
    "termsOfService": "https://startupdatabase.ph/terms"
  },
  "servers": [
    {
      "url": "https://startupdatabase.ph/api/v1"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "REST and MCP integration guide",
    "url": "https://startupdatabase.ph/developers"
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiInfo",
        "summary": "Get API information and discovery links",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiInfo"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint or approved listing not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported HTTP method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Directory temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/startups": {
      "get": {
        "operationId": "searchStartups",
        "summary": "Search or browse approved directory listings",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartupList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint or approved listing not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported HTTP method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Directory temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Case-insensitive search across name, descriptions, tags, category name, and location. All whitespace-separated words must match."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Exact category slug or ID from listCategories."
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Exact tag, case-insensitive."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Maximum number of results per page."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            },
            "description": "Number of matching records to skip."
          }
        ]
      }
    },
    "/startups/{slug}": {
      "get": {
        "operationId": "getStartup",
        "summary": "Get one approved listing by slug",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartupDetail"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint or approved listing not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported HTTP method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Directory temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[^/?#\\s]+$"
            },
            "description": "Exact slug returned by searchStartups."
          }
        ]
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List categories and approved listing counts",
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Endpoint or approved listing not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported HTTP method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Directory temporarily unavailable. Retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiInfo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "version",
          "description",
          "startups",
          "categories",
          "documentation",
          "openapi",
          "mcp"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "startups": {
            "type": "string"
          },
          "categories": {
            "type": "string"
          },
          "documentation": {
            "type": "string"
          },
          "openapi": {
            "type": "string"
          },
          "mcp": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "CategoryWithCount": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "slug",
          "count"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Startup": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "slug",
          "name",
          "website_url",
          "profile_url",
          "description",
          "summary",
          "tagline",
          "category",
          "tags",
          "location",
          "date_added",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "profile_url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical source profile. Cite this URL."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Category"
              },
              {
                "type": "null"
              }
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "required": [
              "city",
              "region",
              "country"
            ],
            "properties": {
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "region": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "date_added": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "total",
          "limit",
          "offset",
          "next_offset",
          "next"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        }
      },
      "StartupList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "pagination",
          "refreshed_at"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Startup"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "refreshed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StartupDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "refreshed_at"
        ],
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Startup"
          },
          "refreshed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CategoryList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "data",
          "refreshed_at"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CategoryWithCount"
            }
          },
          "refreshed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}