{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/eater2/ai_agents_api_library/main/data/schema.json",
  "title": "AI Agents Accessible APIs — catalog entry",
  "type": "object",
  "required": [
    "id",
    "name",
    "category",
    "docs",
    "auth",
    "mcp",
    "desc_en",
    "desc_pl"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$",
      "description": "Stable slug, used as HTML anchor."
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "string",
      "description": "One of the ids in data/categories.json."
    },
    "homepage": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "docs": {
      "type": "string",
      "format": "uri",
      "description": "Official API reference an agent should read."
    },
    "auth": {
      "enum": [
        "api_key",
        "oauth2",
        "api_key+oauth2",
        "none",
        "cloud_iam"
      ]
    },
    "auth_hint": {
      "type": "string",
      "description": "How the credential is sent, e.g. 'Authorization: Bearer <key>'."
    },
    "mcp": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "enum": [
            "official",
            "community",
            "none"
          ]
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Remote MCP endpoint, or repository/docs of the server."
        },
        "maintainer": {
          "enum": [
            "vendor",
            "community",
            "none"
          ]
        },
        "remote_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Hosted MCP endpoint."
        },
        "repo": {
          "type": [
            "string",
            "null"
          ],
          "description": "Source or package of a local (stdio) server."
        },
        "tools": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "covers_full_api": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "config": {
          "type": ["object", "null"],
          "description": "Agent-facing JSON only (source: data/usage.json, else derived from remote_url with derived: true). How to connect the server.",
          "properties": {
            "transport": {"enum": ["streamable-http", "sse", "stdio"]},
            "url": {"type": "string"},
            "headers": {"type": ["object", "null"], "description": "Header name -> value with $ENV_VAR placeholders"},
            "oauth": {"type": "boolean"},
            "command": {"type": "string"},
            "args": {"type": "array", "items": {"type": "string"}},
            "env": {"type": "array", "items": {"type": "string"}, "description": "Environment variable names the server needs"},
            "docs_only": {"type": "boolean", "description": "The server only searches documentation and cannot call the API"},
            "derived": {"type": "boolean"},
            "source_url": {"type": "string", "format": "uri"},
            "checked_at": {"type": "string", "format": "date"}
          }
        },
        "issue": {"type": "string", "description": "Agent-facing JSON only: why the listed server cannot be used (archived, dead link)"},
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        },
        "kind": {
          "enum": [
            "vendor-hosted",
            "official",
            "community",
            "none"
          ],
          "description": "Derived in catalog/*.json: vendor-hosted = vendor's endpoint on the vendor's own domain."
        },
        "domain_verified": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Derived in catalog/*.json: remote_url is on the homepage or docs domain."
        }
      }
    },
    "free_tier": {
      "type": "string"
    },
    "sdk": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "openapi": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "llms_txt": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "desc_en": {
      "type": "string"
    },
    "desc_pl": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "verified": {
      "type": "string",
      "format": "date",
      "description": "Date the entry was last checked (links and researched fields). Shown to agents as last checked; it is not a test that the service performs a given task."
    },
    "call": {
      "type": "object",
      "description": "Agent-facing JSON only (source: data/usage.json). Minimal working request for the service's most common operation.",
      "properties": {
        "operation": {"type": "string"},
        "method": {"type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"]},
        "url": {"type": "string", "description": "Full URL with {placeholders}"},
        "example": {"type": "string", "description": "One curl command; secrets as $ENV_VAR placeholders"},
        "response_fields": {"type": "array", "items": {"type": "string"}},
        "async": {"type": ["string", "null"], "description": "How to get the result when it is not in the response"},
        "source_url": {"type": "string", "format": "uri"},
        "checked_at": {"type": "string", "format": "date"}
      },
      "required": ["method", "url", "example", "source_url"]
    },
    "unit_price": {
      "type": "object",
      "description": "Agent-facing JSON only (source: data/usage.json). Price of one operation as the vendor publishes it.",
      "properties": {
        "summary": {"type": "string"},
        "source_url": {"type": "string", "format": "uri"},
        "checked_at": {"type": "string", "format": "date"}
      },
      "required": ["summary", "source_url"]
    },
    "free_plan": {
      "type": "object",
      "description": "Structured free plan, researched on the vendor's pricing page.",
      "properties": {
        "kind": {
          "enum": [
            "free_tier",
            "trial",
            "no_key",
            "none"
          ]
        },
        "requires_card": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "quota": {
          "type": [
            "string",
            "null"
          ]
        },
        "period": {
          "enum": [
            "day",
            "month",
            "year",
            "one_time",
            null
          ]
        },
        "watermark": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "auth_scheme": {
      "type": "object",
      "description": "Credential format as an OpenAPI securityScheme.",
      "properties": {
        "type": {
          "enum": [
            "apiKey",
            "http",
            "oauth2",
            "none",
            "cloud_iam"
          ]
        },
        "in": {
          "enum": [
            "header",
            "query",
            "cookie",
            null
          ]
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheme": {
          "enum": [
            "bearer",
            "basic",
            null
          ]
        },
        "format": {
          "type": "string",
          "description": "Literal example of what goes on the wire."
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "base_url": {
      "type": "string",
      "format": "uri"
    },
    "rate_limits": {
      "type": "object",
      "description": "Rate limits as the vendor states them.",
      "properties": {
        "summary": {
          "type": "string"
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "data_policy": {
      "type": "object",
      "description": "Training use and retention of API inputs.",
      "properties": {
        "summary": {
          "type": "string"
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "oauth_scopes": {
      "type": "object",
      "properties": {
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        },
        "checked_at": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "async_jobs": {
      "type": "object",
      "description": "Long-running work returns a job id instead of the result.",
      "properties": {
        "value": {
          "type": "boolean"
        },
        "how": {
          "type": "string"
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Vendor page the value was read from."
        }
      }
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9-]+$"
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "Concrete actions an agent can perform with the service, most important first. Ids from data/operations.json (e.g. text-to-video, sms, street-geocoding)."
    }
  }
}