{
  "openapi": "3.1.0",
  "info": {
    "title": "ITHub Directory public dataset",
    "version": "1.0.0",
    "description": "Read-only public metadata for IT tools and services listed by ITHub Directory."
  },
  "servers": [
    {
      "url": "https://www.ithub.directory"
    }
  ],
  "paths": {
    "/developers/tools-v1.json": {
      "get": {
        "summary": "Get the version 1 tool dataset",
        "operationId": "getToolsV1",
        "responses": {
          "200": {
            "description": "Current public dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                },
                "example": {
                  "schema_version": "1.0",
                  "source": "https://www.ithub.directory/developers",
                  "count": 1,
                  "updated": "2026-10-09T00:00:00.000Z",
                  "statistics": {
                    "open_source": 1,
                    "self_hostable": 1,
                    "api_available": 1
                  },
                  "tools": [
                    {
                      "name": "Example tool",
                      "slug": "example-tool",
                      "url": "https://www.ithub.directory/category/example-tool",
                      "is_open_source": true,
                      "is_self_hostable": true,
                      "has_api": true
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dataset temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/developers/tools.json": {
      "get": {
        "summary": "Get the current tool dataset alias",
        "operationId": "getToolsCurrent",
        "responses": {
          "200": {
            "description": "Current public dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Dataset temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Dataset": {
        "type": "object",
        "required": [
          "schema_version",
          "source",
          "count",
          "updated",
          "statistics",
          "tools"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "1.0"
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "updated": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "statistics": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tool"
            }
          }
        }
      },
      "Tool": {
        "type": "object",
        "required": [
          "name",
          "slug",
          "url",
          "is_open_source",
          "is_self_hostable",
          "has_api"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "is_open_source": {
            "type": "boolean"
          },
          "is_self_hostable": {
            "type": "boolean"
          },
          "has_api": {
            "type": "boolean"
          },
          "pricing_model": {
            "type": [
              "string",
              "null"
            ]
          },
          "founded_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "hq_location": {
            "type": [
              "string",
              "null"
            ]
          },
          "github_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "docs_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "source_checked_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}