{
  "openapi": "3.1.0",
  "info": {
    "title": "SourcingTools.org Directory API",
    "version": "1.0.0",
    "description": "Free, read-only JSON API for the SourcingTools.org directory of candidate sourcing tools. No authentication required. Data is reusable with attribution under the SourcingTools.org data license.",
    "contact": {
      "name": "SourcingTools.org Editorial Team",
      "email": "hello@sourcingtools.org",
      "url": "https://sourcingtools.org/contact/"
    },
    "license": {
      "name": "SourcingTools.org Data License (free with attribution)",
      "url": "https://sourcingtools.org/data-license/"
    }
  },
  "servers": [
    { "url": "https://sourcingtools.org", "description": "Production" }
  ],
  "paths": {
    "/api/v1/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "List all sourcing tools",
        "description": "Returns summary records for all 40 candidate sourcing tools in the directory, optionally filtered by category substring.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring filter on the tool category, e.g. `AI` or `search database`.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of tools",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolList" }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/{slug}": {
      "get": {
        "operationId": "getTool",
        "summary": "Get one sourcing tool by slug",
        "description": "Returns the full directory record for a single tool, including pros, cons, integrations, pricing, and review URL.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Tool slug, e.g. `hireez`, `noon`, `seekout`. List valid slugs with `listTools`.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full tool record",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Tool" }
              }
            }
          },
          "404": {
            "description": "Unknown slug",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "description": "Summary record for one sourcing tool.",
        "required": ["slug", "name", "category"],
        "properties": {
          "slug": { "type": "string", "description": "Stable identifier, e.g. `hireez`." },
          "name": { "type": "string", "description": "Product name." },
          "category": { "type": "string", "description": "Editorial category, e.g. `AI-powered talent search database`." },
          "tagline": { "type": "string", "description": "One-line description." },
          "best_for": { "type": "string", "description": "Who the tool suits best." },
          "pricing": { "type": "string", "description": "Pricing summary." },
          "website": { "type": "string", "format": "uri", "description": "Vendor website." },
          "updated": { "type": "string", "format": "date", "description": "Date the record was last updated." },
          "review_url": { "type": "string", "format": "uri", "description": "Full editorial review on sourcingtools.org." },
          "api_url": { "type": "string", "format": "uri", "description": "API URL for the full record." }
        }
      },
      "ToolList": {
        "type": "object",
        "description": "Response for listTools.",
        "required": ["count", "tools"],
        "properties": {
          "count": { "type": "integer", "description": "Number of tools returned." },
          "license": { "type": "string", "format": "uri", "description": "Data license URL." },
          "tools": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ToolSummary" }
          }
        }
      },
      "Tool": {
        "type": "object",
        "description": "Full directory record for one sourcing tool.",
        "required": ["slug", "name", "category"],
        "properties": {
          "slug": { "type": "string", "description": "Stable identifier." },
          "name": { "type": "string", "description": "Product name." },
          "category": { "type": "string", "description": "Editorial category." },
          "tagline": { "type": "string", "description": "One-line description." },
          "bestFor": { "type": "string", "description": "Who the tool suits best." },
          "pricing": { "type": "string", "description": "Pricing summary." },
          "website": { "type": "string", "format": "uri", "description": "Vendor website." },
          "overview": { "type": "string", "description": "Editorial overview paragraph." },
          "pros": { "type": "array", "items": { "type": "string" }, "description": "Strengths." },
          "cons": { "type": "array", "items": { "type": "string" }, "description": "Weaknesses." },
          "integrations": { "type": "array", "items": { "type": "string" }, "description": "Known integrations." },
          "published": { "type": "string", "format": "date", "description": "First published date." },
          "updated": { "type": "string", "format": "date", "description": "Last updated date." },
          "review_url": { "type": "string", "format": "uri", "description": "Full editorial review URL." },
          "license": { "type": "string", "format": "uri", "description": "Data license URL." }
        }
      },
      "Error": {
        "type": "object",
        "description": "Structured JSON error response.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "description": "Machine-readable error code, e.g. `tool_not_found`." },
              "message": { "type": "string", "description": "Human-readable explanation." },
              "resolution": { "type": "string", "description": "Hint for how to resolve the error." }
            }
          }
        }
      }
    }
  }
}