{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentScore API",
    "version": "1.0.0",
    "description": "The API benchmark, scored from an agent's point of view.\n\nCurrent rubric: v0.2.0 — 11 criteria.\n\nA score is only comparable within the same category and the same rubric version. A missing criterion means NOT MEASURED or NOT APPLICABLE, never zero.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://agentsco.re"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getDiscovery",
        "summary": "Discovery document: routes, conventions, score semantics.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "List the scored tools.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category. See /api/v1/categories.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Identifier of the last item on the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Fields to return, comma-separated. Shrinks the response. Values: id, name, category, vendor, tagline, description, homepage, pricing_model, surfaces.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "vendor": {
                            "type": "string"
                          },
                          "tagline": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "description": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "homepage": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "pricing_model": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "surfaces": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "Identifiant stable, ex. `stripe-rest-v1`."
                                },
                                "kind": {
                                  "type": "string",
                                  "enum": [
                                    "rest",
                                    "graphql",
                                    "grpc",
                                    "mcp",
                                    "sdk",
                                    "webhook"
                                  ]
                                },
                                "name": {
                                  "type": "string"
                                },
                                "version": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "base_url": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "docs_url": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "openapi_url": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "llms_txt_url": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "auth_type": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "is_primary": {
                                  "type": "boolean"
                                },
                                "score": {
                                  "type": "object",
                                  "properties": {
                                    "status": {
                                      "type": "string",
                                      "enum": [
                                        "not_yet_scored",
                                        "partial",
                                        "scored"
                                      ],
                                      "description": "not_yet_scored: Surface catalogued, benchmark not run. `overall` is null: this is an ABSENCE OF MEASUREMENT, never a score of zero. Do not rank this surface last. | partial: Partial benchmark: coverage is below the publication threshold, so no overall score is computed. The criteria present in `criteria` are valid and usable individually. | scored: Complete benchmark. `overall` is a weighted average of the applicable criteria, comparable to other surfaces in the same category and the same rubric version."
                                    },
                                    "meaning": {
                                      "type": "string",
                                      "description": "What the status means, in plain words, to prevent misreading."
                                    },
                                    "overall": {
                                      "anyOf": [
                                        {
                                          "type": "number"
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "Weighted average out of 100. null means ABSENCE OF MEASUREMENT or insufficient coverage — never a score of zero."
                                    },
                                    "coverage": {
                                      "type": "number",
                                      "description": "Share of the applicable weight actually measured, from 0 to 1."
                                    },
                                    "rubric_version": {
                                      "type": "string"
                                    },
                                    "measured_at": {
                                      "anyOf": [
                                        {
                                          "type": "string"
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "ISO 8601 date of the OLDEST measurement still counted in this score: every criterion is at least this recent. Measurements are refreshed weekly; the costly agent runs are redone when the documentation changes, and at least every 30 days."
                                    },
                                    "criteria": {
                                      "type": "object",
                                      "propertyNames": {
                                        "type": "string"
                                      },
                                      "additionalProperties": {
                                        "type": "number"
                                      },
                                      "description": "Score per criterion. A missing criterion is not measured or not applicable."
                                    }
                                  },
                                  "required": [
                                    "status",
                                    "meaning",
                                    "overall",
                                    "coverage",
                                    "rubric_version",
                                    "measured_at",
                                    "criteria"
                                  ],
                                  "additionalProperties": false
                                },
                                "category_rank": {
                                  "anyOf": [
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ],
                                  "description": "Rank within the category. null if fewer than 3 competitors."
                                }
                              },
                              "required": [
                                "id",
                                "kind",
                                "name",
                                "version",
                                "base_url",
                                "docs_url",
                                "openapi_url",
                                "llms_txt_url",
                                "auth_type",
                                "is_primary",
                                "score",
                                "category_rank"
                              ],
                              "additionalProperties": false
                            }
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "category",
                          "vendor",
                          "tagline",
                          "description",
                          "homepage",
                          "pricing_model",
                          "surfaces"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "next_cursor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "data",
                    "next_cursor",
                    "has_more"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter. `field` names the offending parameter.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "number"
                    },
                    "detail": {
                      "type": "string",
                      "description": "Written as an instruction, with the value received and the correction expected."
                    },
                    "field": {
                      "description": "Path of the offending parameter.",
                      "type": "string"
                    },
                    "allowed_values": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          }
                        ]
                      }
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "docs"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/{id}": {
      "get": {
        "operationId": "getTool",
        "summary": "Detail of a tool and its surfaces.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Fields to return, comma-separated. Shrinks the response. Values: id, name, category, vendor, tagline, description, homepage, pricing_model, surfaces.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "category": {
                      "type": "string"
                    },
                    "vendor": {
                      "type": "string"
                    },
                    "tagline": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "homepage": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pricing_model": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "surfaces": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Identifiant stable, ex. `stripe-rest-v1`."
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "rest",
                              "graphql",
                              "grpc",
                              "mcp",
                              "sdk",
                              "webhook"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "version": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "base_url": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "docs_url": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "openapi_url": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "llms_txt_url": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "auth_type": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "is_primary": {
                            "type": "boolean"
                          },
                          "score": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "not_yet_scored",
                                  "partial",
                                  "scored"
                                ],
                                "description": "not_yet_scored: Surface catalogued, benchmark not run. `overall` is null: this is an ABSENCE OF MEASUREMENT, never a score of zero. Do not rank this surface last. | partial: Partial benchmark: coverage is below the publication threshold, so no overall score is computed. The criteria present in `criteria` are valid and usable individually. | scored: Complete benchmark. `overall` is a weighted average of the applicable criteria, comparable to other surfaces in the same category and the same rubric version."
                              },
                              "meaning": {
                                "type": "string",
                                "description": "What the status means, in plain words, to prevent misreading."
                              },
                              "overall": {
                                "anyOf": [
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Weighted average out of 100. null means ABSENCE OF MEASUREMENT or insufficient coverage — never a score of zero."
                              },
                              "coverage": {
                                "type": "number",
                                "description": "Share of the applicable weight actually measured, from 0 to 1."
                              },
                              "rubric_version": {
                                "type": "string"
                              },
                              "measured_at": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "ISO 8601 date of the OLDEST measurement still counted in this score: every criterion is at least this recent. Measurements are refreshed weekly; the costly agent runs are redone when the documentation changes, and at least every 30 days."
                              },
                              "criteria": {
                                "type": "object",
                                "propertyNames": {
                                  "type": "string"
                                },
                                "additionalProperties": {
                                  "type": "number"
                                },
                                "description": "Score per criterion. A missing criterion is not measured or not applicable."
                              }
                            },
                            "required": [
                              "status",
                              "meaning",
                              "overall",
                              "coverage",
                              "rubric_version",
                              "measured_at",
                              "criteria"
                            ],
                            "additionalProperties": false
                          },
                          "category_rank": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Rank within the category. null if fewer than 3 competitors."
                          }
                        },
                        "required": [
                          "id",
                          "kind",
                          "name",
                          "version",
                          "base_url",
                          "docs_url",
                          "openapi_url",
                          "llms_txt_url",
                          "auth_type",
                          "is_primary",
                          "score",
                          "category_rank"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "category",
                    "vendor",
                    "tagline",
                    "description",
                    "homepage",
                    "pricing_model",
                    "surfaces"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "404": {
            "description": "Outil introuvable. `allowed_values` propose des identifiants voisins.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "number"
                    },
                    "detail": {
                      "type": "string",
                      "description": "Written as an instruction, with the value received and the correction expected."
                    },
                    "field": {
                      "description": "Path of the offending parameter.",
                      "type": "string"
                    },
                    "allowed_values": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "number"
                          }
                        ]
                      }
                    },
                    "docs": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "title",
                    "status",
                    "detail",
                    "docs"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "Categories and whether they are comparable.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/rubric": {
      "get": {
        "operationId": "getRubric",
        "summary": "Criteria, weights and methods of the current rubric.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/tools/{id}.md": {
      "get": {
        "operationId": "getToolMarkdown",
        "summary": "Entry as markdown. Also served on /tools/{id} with Accept: text/markdown.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Not required today, already accepted. Wire it in now: it will be required beyond the free tier without anything else in the contract changing."
      }
    }
  }
}