{
  "openapi": "3.1.0",
  "info": {
    "title": "Hello Aigent Demo MVP API",
    "version": "0.1.0",
    "description": "Normative REST contract for the Hello Aigent Demo MVP."
  },
  "servers": [
    {
      "url": "https://api.helloaigent.dev/v0"
    }
  ],
  "paths": {
    "/subscribe": {
      "post": {
        "operationId": "subscribe",
        "summary": "Subscribe an agent principal to a feed",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "https://helloaigent.dev/schemas/subscribe-request.schema.json" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created",
            "content": {
              "application/json": {
                "schema": { "$ref": "https://helloaigent.dev/schemas/subscribe-response.schema.json" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/fetch": {
      "post": {
        "operationId": "fetch",
        "summary": "Fetch signed updates for a subscription",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "https://helloaigent.dev/schemas/fetch-request.schema.json" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updates fetched",
            "content": {
              "application/json": {
                "schema": { "$ref": "https://helloaigent.dev/schemas/fetch-response.schema.json" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/unsubscribe": {
      "post": {
        "operationId": "unsubscribe",
        "summary": "Revoke a subscription",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "https://helloaigent.dev/schemas/unsubscribe-request.schema.json" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/publish": {
      "post": {
        "operationId": "publish",
        "summary": "Publish and sign an update",
        "security": [{ "AdminToken": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "https://helloaigent.dev/schemas/publish-request.schema.json" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Update published",
            "content": {
              "application/json": {
                "schema": { "$ref": "https://helloaigent.dev/schemas/envelope.schema.json" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/demo/actions/claim-offer": {
      "post": {
        "operationId": "claimDemoOffer",
        "summary": "Claim the deterministic Demo MVP offer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "https://helloaigent.dev/schemas/demo-claim-offer-request.schema.json" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Offer claimed",
            "content": {
              "application/json": {
                "schema": { "$ref": "https://helloaigent.dev/schemas/demo-claim-offer-response.schema.json" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "AdminToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Admin token for Demo MVP publishing."
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": { "$ref": "https://helloaigent.dev/schemas/error.schema.json" }
          }
        }
      }
    }
  }
}