{
  "openapi": "3.1.0",
  "info": {
    "title": "Aether Public API",
    "version": "1.0.0",
    "description": "Discoverability and trust verification for installable AI web apps and agents. Catalog search requires a partner API key; trust-report verification is open so anyone can independently validate a signed report."
  },
  "servers": [
    {
      "url": "/",
      "description": "Same origin"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Listing": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "web_app",
              "agent"
            ]
          },
          "category": {
            "type": "string"
          },
          "autonomy": {
            "type": "string",
            "enum": [
              "assistive",
              "supervised",
              "autonomous"
            ]
          },
          "pricing": {
            "type": "string"
          },
          "installable": {
            "type": "boolean"
          },
          "offlineCapable": {
            "type": "boolean"
          },
          "trustTier": {
            "type": "string",
            "enum": [
              "unlisted",
              "listed",
              "verified",
              "audited"
            ]
          },
          "domain": {
            "type": "string"
          },
          "complianceTags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "trustCenterUrl": {
            "type": "string"
          },
          "latestScan": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "scanId": {
                "type": "string",
                "format": "uuid"
              },
              "score": {
                "type": "integer"
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "pass",
                  "warn",
                  "fail"
                ]
              },
              "signature": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "signatureKeyId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "scannedAt": {
                "type": "string",
                "format": "date-time"
              },
              "ageDays": {
                "type": "number"
              }
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            }
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "reason": {
            "type": "string"
          },
          "keyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "activeKeyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "rotatedKey": {
            "type": "boolean"
          },
          "score": {
            "type": "integer"
          },
          "verdict": {
            "type": "string"
          },
          "scannedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/api/public/catalog": {
      "get": {
        "summary": "Search the public catalog",
        "description": "Filterable search across every published listing. Rate limited per API key; responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "Free-text query."
          },
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated trust tiers, e.g. listed,verified."
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated kinds: web_app, agent."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated categories."
          },
          {
            "name": "tags",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated compliance tags; all must match."
          },
          {
            "name": "scannedWithinDays",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Only listings scanned within N days."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching listings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/verify-report": {
      "get": {
        "summary": "Verify a signed trust report by scan id",
        "parameters": [
          {
            "name": "scanId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed scanId."
          }
        }
      },
      "post": {
        "summary": "Verify a raw report and signature pair",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scanId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "report": {
                    "type": "object"
                  },
                  "signature": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}