EndpointCatalog

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/stophy-dev/json-schema/stophy-dev-endpoint-catalog-schema.json",
  "title": "EndpointCatalog",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stophy-dev-openapi.json#/components/schemas/EndpointCatalog",
  "type": "object",
  "required": [
    "endpoints",
    "sources"
  ],
  "properties": {
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "summary",
          "kind"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "description": "The source's name, such as YouTube or Google Maps."
          },
          "summary": {
            "type": "string",
            "description": "What you can get from this source."
          },
          "kind": {
            "type": "string",
            "enum": [
              "site",
              "aiAnswers"
            ],
            "description": "aiAnswers when the source returns another AI's answer, site otherwise."
          }
        }
      }
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "title",
          "summary",
          "bestWhen",
          "method",
          "path",
          "credits",
          "maxCredits",
          "keyless",
          "cacheTtlSeconds",
          "example"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "description": "A short name for the endpoint within its source, such as Comment replies."
          },
          "summary": {
            "type": "string",
            "description": "What this endpoint returns, in one line."
          },
          "bestWhen": {
            "type": [
              "string",
              "null"
            ],
            "description": "When this endpoint beats a similar one, such as another source with the same kind of data. Null when there is no overlap worth calling out."
          },
          "method": {
            "const": "POST"
          },
          "path": {
            "type": "string"
          },
          "credits": {
            "type": "integer",
            "description": "What one call costs, or the lowest it can cost when pricing is set."
          },
          "maxCredits": {
            "type": "integer",
            "description": "The most one call can cost. The same as credits when pricing is null."
          },
          "pricing": {
            "type": [
              "string",
              "null"
            ],
            "description": "How the price changes with the answer. Null when every call costs the same."
          },
          "keyless": {
            "type": "boolean"
          },
          "cacheTtlSeconds": {
            "type": "integer"
          },
          "input": {
            "type": "object",
            "description": "The endpoint's input as JSON Schema."
          }
        }
      }
    }
  }
}