{
  "openapi": "3.1.0",
  "info": {
    "title": "100ToolCrate Public API",
    "version": "2.1.0",
    "description": "Public service metadata, anonymous counters and 18 deterministic execution tools. REST and MCP require no token; execution inputs are transient."
  },
  "servers": [
    {
      "url": "https://100toolcrate.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "liveness",
        "summary": "Process liveness",
        "responses": {
          "200": {
            "description": "Process is running"
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "operationId": "readiness",
        "summary": "Database and generated-site readiness",
        "responses": {
          "200": {
            "description": "Ready"
          },
          "503": {
            "description": "Not ready"
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Service and database status",
        "responses": {
          "200": {
            "description": "Current service status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "version",
                    "tools_count",
                    "database",
                    "mcp_enabled",
                    "authentication_required"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "degraded"
                      ]
                    },
                    "version": {
                      "type": "string"
                    },
                    "tools_count": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "database": {
                      "type": "string"
                    },
                    "mcp_enabled": {
                      "const": true
                    },
                    "authentication_required": {
                      "const": false
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "execution_tools_count": {
                      "type": "integer",
                      "const": 18
                    },
                    "mcp_endpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/top-tools": {
      "get": {
        "operationId": "getTopTools",
        "summary": "Get tool IDs ordered by aggregate usage",
        "responses": {
          "200": {
            "description": "Tool ID array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "maxItems": 20,
                  "items": {
                    "type": "string",
                    "pattern": "^[a-z0-9-]+$"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/track": {
      "post": {
        "operationId": "trackTool",
        "summary": "Increment an aggregate tool counter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[a-z0-9-]{1,100}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Counter incremented",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "count"
                  ],
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "count": {
                      "type": "integer",
                      "minimum": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid tool ID"
          },
          "404": {
            "description": "Unknown tool"
          },
          "413": {
            "description": "Request body too large"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "modelContextProtocol",
        "summary": "MCP Streamable HTTP JSON-RPC endpoint",
        "description": "Supports initialize, ping, tools/list and tools/call for protocol 2025-03-26 and 2025-06-18. Accept header must include application/json and text/event-stream.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "number"
                    ]
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "initialize",
                      "ping",
                      "tools/list",
                      "tools/call",
                      "notifications/initialized"
                    ]
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or error"
          },
          "202": {
            "description": "Notification accepted"
          },
          "400": {
            "description": "Invalid request or protocol version"
          },
          "403": {
            "description": "Origin rejected"
          },
          "406": {
            "description": "Required Accept media types missing"
          }
        }
      },
      "get": {
        "operationId": "mcpListeningUnavailable",
        "summary": "SSE listening is not provided",
        "responses": {
          "405": {
            "description": "Stateless server does not offer GET SSE listening"
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listExecutionTools",
        "summary": "Discover executable tools, schemas and browser-only exclusions",
        "responses": {
          "200": {
            "description": "18 executable tools and the remaining browser-only catalog"
          }
        }
      }
    },
    "/api/v1/tools/{toolId}": {
      "get": {
        "operationId": "getExecutionTool",
        "summary": "Get one tool input/output schema",
        "parameters": [
          {
            "name": "toolId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "word-counter",
                "character-counter",
                "case-converter",
                "slug-generator",
                "url-encoder",
                "base64-encoder",
                "json-formatter",
                "json-validator",
                "json-minifier",
                "json-to-csv",
                "hash-generator",
                "uuid-generator",
                "unix-timestamp-converter",
                "date-diff",
                "percentage-calculator",
                "discount-calculator",
                "profit-margin",
                "read-time-calculator"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool metadata and execution contract"
          },
          "404": {
            "description": "Unknown or browser-only tool"
          }
        }
      }
    },
    "/api/v1/tools/{toolId}/execute": {
      "post": {
        "operationId": "executePublicTool",
        "summary": "Execute a deterministic public tool with transient input",
        "description": "Use the inputSchema returned by GET /api/v1/tools/{toolId}. Maximum request 16 KB; maximum result 256 KB; rate limited.",
        "parameters": [
          {
            "name": "toolId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "word-counter",
                "character-counter",
                "case-converter",
                "slug-generator",
                "url-encoder",
                "base64-encoder",
                "json-formatter",
                "json-validator",
                "json-minifier",
                "json-to-csv",
                "hash-generator",
                "uuid-generator",
                "unix-timestamp-converter",
                "date-diff",
                "percentage-calculator",
                "discount-calculator",
                "profit-margin",
                "read-time-calculator"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Tool-specific arguments from its published inputSchema"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Real execution result with dataHandling=not_persisted"
          },
          "400": {
            "description": "Input failed the tool schema or execution rules"
          },
          "404": {
            "description": "Unknown or browser-only tool"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit reached"
          }
        }
      }
    },
    "/api/og-preview": {
      "get": {
        "operationId": "previewOpenGraph",
        "summary": "Fetch public Open Graph metadata with SSRF protections",
        "description": "Only public IPs, three redirects, seven-second timeout and 512 KB HTML. URL is sent to the server; HTML is transient.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Extracted metadata"
          },
          "400": {
            "description": "Invalid URL or private target"
          },
          "422": {
            "description": "Target could not be parsed"
          },
          "429": {
            "description": "Rate limit reached"
          },
          "504": {
            "description": "Target timed out"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded; honor Retry-After",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}
