{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentSpot data",
    "version": "2",
    "summary": "A curated, automatically refreshed directory where you can discover which AI agents, reusable skills, and agent tools are popular — ranked by transparent public metrics.",
    "description": "Static, read-only JSON. No key, no rate limit, CORS enabled for every origin. There are no query parameters — these are files, not a query service; fetch /data/index.json and filter it locally. Licensed CC-BY-4.0: reuse freely with attribution to AgentSpot (https://agentspot.dev).",
    "license": {
      "name": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://agentspot.dev"
    }
  ],
  "paths": {
    "/data/index.json": {
      "get": {
        "summary": "Compact index of every listing",
        "description": "Every active listing (81) with only the fields needed to search and shortlist. Fetch this first; fetch a single listing for the rest.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Compact index of every listing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_license": {
                      "type": "string",
                      "description": "SPDX identifier of the dataset license."
                    },
                    "_license_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "_attribution": {
                      "type": "string",
                      "description": "The attribution string to reproduce when reusing this data."
                    },
                    "api_version": {
                      "type": "integer",
                      "description": "Incremented only for breaking changes to the record shape."
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When this file was built."
                    },
                    "category": {
                      "type": "string",
                      "description": "\"all\", or the category slug this file covers."
                    },
                    "count": {
                      "type": "integer"
                    },
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/IndexListing"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/data/all.json": {
      "get": {
        "summary": "Every listing, in full",
        "description": "All active listings with every published field. Large; prefer /data/index.json for search.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Every listing, in full",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_license": {
                      "type": "string",
                      "description": "SPDX identifier of the dataset license."
                    },
                    "_license_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "_attribution": {
                      "type": "string",
                      "description": "The attribution string to reproduce when reusing this data."
                    },
                    "api_version": {
                      "type": "integer",
                      "description": "Incremented only for breaking changes to the record shape."
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When this file was built."
                    },
                    "category": {
                      "type": "string",
                      "description": "\"all\", or the category slug this file covers."
                    },
                    "count": {
                      "type": "integer"
                    },
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Listing"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/data/{category}.json": {
      "get": {
        "summary": "One category, in full",
        "description": "All active listings in a single category.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "agents",
                "skills",
                "tools",
                "coding",
                "learn"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One category, in full",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_license": {
                      "type": "string",
                      "description": "SPDX identifier of the dataset license."
                    },
                    "_license_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "_attribution": {
                      "type": "string",
                      "description": "The attribution string to reproduce when reusing this data."
                    },
                    "api_version": {
                      "type": "integer",
                      "description": "Incremented only for breaking changes to the record shape."
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When this file was built."
                    },
                    "category": {
                      "type": "string",
                      "description": "\"all\", or the category slug this file covers."
                    },
                    "count": {
                      "type": "integer"
                    },
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Listing"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/data/listings/{id}.json": {
      "get": {
        "summary": "A single listing",
        "description": "One listing by id, in a payload of the same shape. `id` is the listing id verbatim, e.g. `agent/openclaw`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "agent/openclaw"
          }
        ],
        "responses": {
          "200": {
            "description": "A single listing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_license": {
                      "type": "string",
                      "description": "SPDX identifier of the dataset license."
                    },
                    "_license_url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "_attribution": {
                      "type": "string",
                      "description": "The attribution string to reproduce when reusing this data."
                    },
                    "api_version": {
                      "type": "integer",
                      "description": "Incremented only for breaking changes to the record shape."
                    },
                    "generated": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When this file was built."
                    },
                    "category": {
                      "type": "string",
                      "description": "\"all\", or the category slug this file covers."
                    },
                    "count": {
                      "type": "integer"
                    },
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Listing"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Listing": {
        "type": "object",
        "title": "Listing",
        "required": [
          "id",
          "name",
          "category",
          "description",
          "url",
          "repo_url",
          "website_url",
          "license",
          "package",
          "install",
          "can_run_locally",
          "is_mcp_server",
          "open_source",
          "first_party",
          "derivative_of",
          "github_stars",
          "downloads",
          "popularity_score",
          "unranked",
          "growth",
          "tags",
          "first_listed",
          "last_verified",
          "editorial_note",
          "sponsored",
          "tier",
          "curation"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable identifier, `<category>/<slug>`. Never reused."
          },
          "name": {
            "type": "string",
            "description": "The project's own name."
          },
          "category": {
            "type": "string",
            "enum": [
              "agent",
              "skill",
              "tool",
              "coding",
              "education"
            ],
            "description": "One of: agent, skill, tool, coding, education."
          },
          "description": {
            "type": "string",
            "description": "A one- or two-sentence summary written by us — never copied from the README."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical AgentSpot page for this listing."
          },
          "repo_url": {
            "type": "string",
            "format": "uri",
            "description": "Source repository. Read this before running anything."
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "The project's own site or docs, when it has one."
          },
          "license": {
            "type": "string",
            "description": "SPDX identifier where GitHub could classify it, otherwise \"Other (see repo)\"."
          },
          "package": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "registry": {
                "type": "string",
                "enum": [
                  "npm",
                  "pypi",
                  "docker"
                ]
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "description": "Registry coordinates for the published package, when one exists. `null` means the project is installed from source."
          },
          "install": {
            "type": [
              "string",
              "null"
            ],
            "description": "One-line install command derived from `package`. A starting point, not a substitute for the project's own instructions — check the repo for required flags, runtimes, and configuration."
          },
          "can_run_locally": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the project can run entirely on your own machine, with no required hosted service. `null` where the question does not apply (a book, a prompt pack) or has not been assessed."
          },
          "is_mcp_server": {
            "type": "boolean",
            "description": "Heuristic: the project describes itself with MCP (Model Context Protocol) topics. A shortlisting hint, not a verified capability — we do not currently publish per-listing MCP endpoint URLs or config snippets."
          },
          "open_source": {
            "type": "boolean",
            "description": "False for listings whose source is not publicly available."
          },
          "first_party": {
            "type": "boolean",
            "description": "True for tools published by the lab or vendor whose model they serve."
          },
          "derivative_of": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "repo_url": {
                "type": "string",
                "format": "uri"
              }
            },
            "description": "Set when this listing is a fork that has overtaken the project it came from; points back at the original."
          },
          "github_stars": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Stars at `last_verified`."
          },
          "downloads": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "npm",
                  "pypi",
                  "docker"
                ]
              },
              "count": {
                "type": "integer"
              }
            },
            "description": "Downloads over the trailing 7 days, from the registry named in `source`. Container pulls count restarts as well as installs, so they are discounted in the score."
          },
          "popularity_score": {
            "type": [
              "number",
              "null"
            ],
            "description": "Composite 0–100 score. `null` when the listing is `unranked`. The formula is published at /methodology/."
          },
          "unranked": {
            "type": "boolean",
            "description": "Listed and shown, but deliberately excluded from popularity ordering. `editorial_note` says why."
          },
          "growth": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "stars_delta": {
                "type": "integer"
              },
              "stars_pct": {
                "type": "number"
              },
              "downloads_pct": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "window_days": {
                "type": "integer"
              },
              "as_of": {
                "type": "string",
                "format": "date"
              }
            },
            "description": "Change over the trailing week, held steady between weekly updates. `null` until a listing has enough history."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The project's own repository topics, lightly cleaned."
          },
          "first_listed": {
            "type": "string",
            "format": "date",
            "description": "The date this listing first appeared here."
          },
          "last_verified": {
            "type": "string",
            "format": "date",
            "description": "The date the metrics above were last refreshed from public APIs."
          },
          "editorial_note": {
            "type": [
              "string",
              "null"
            ],
            "description": "A public note from us, where a listing needs one."
          },
          "sponsored": {
            "type": "object",
            "properties": {
              "active": {
                "type": "boolean"
              },
              "label": {
                "type": "string"
              },
              "start_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              },
              "end_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              }
            },
            "description": "Sponsorship never affects inclusion, ordering, or `popularity_score`. `active` is false on every listing today."
          },
          "tier": {
            "type": "string",
            "description": "\"standard\" for every listing today; reserved for a future curated tier."
          },
          "curation": {
            "type": [
              "object",
              "null"
            ],
            "description": "Reserved for future independent evaluation results. `null` today."
          }
        }
      },
      "IndexListing": {
        "type": "object",
        "title": "Listing (compact)",
        "required": [
          "id",
          "name",
          "category",
          "description",
          "url",
          "repo_url",
          "package",
          "install",
          "can_run_locally",
          "is_mcp_server",
          "github_stars",
          "popularity_score",
          "tags"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable identifier, `<category>/<slug>`. Never reused."
          },
          "name": {
            "type": "string",
            "description": "The project's own name."
          },
          "category": {
            "type": "string",
            "enum": [
              "agent",
              "skill",
              "tool",
              "coding",
              "education"
            ],
            "description": "One of: agent, skill, tool, coding, education."
          },
          "description": {
            "type": "string",
            "description": "A one- or two-sentence summary written by us — never copied from the README."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical AgentSpot page for this listing."
          },
          "repo_url": {
            "type": "string",
            "format": "uri",
            "description": "Source repository. Read this before running anything."
          },
          "package": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "registry": {
                "type": "string",
                "enum": [
                  "npm",
                  "pypi",
                  "docker"
                ]
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "description": "Registry coordinates for the published package, when one exists. `null` means the project is installed from source."
          },
          "install": {
            "type": [
              "string",
              "null"
            ],
            "description": "One-line install command derived from `package`. A starting point, not a substitute for the project's own instructions — check the repo for required flags, runtimes, and configuration."
          },
          "can_run_locally": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the project can run entirely on your own machine, with no required hosted service. `null` where the question does not apply (a book, a prompt pack) or has not been assessed."
          },
          "is_mcp_server": {
            "type": "boolean",
            "description": "Heuristic: the project describes itself with MCP (Model Context Protocol) topics. A shortlisting hint, not a verified capability — we do not currently publish per-listing MCP endpoint URLs or config snippets."
          },
          "github_stars": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Stars at `last_verified`."
          },
          "popularity_score": {
            "type": [
              "number",
              "null"
            ],
            "description": "Composite 0–100 score. `null` when the listing is `unranked`. The formula is published at /methodology/."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The project's own repository topics, lightly cleaned."
          }
        }
      }
    }
  }
}