{
  "openapi": "3.1.0",
  "info": {
    "title": "aitobot Public Service API",
    "version": "0.1.0",
    "description": "Public-safe service API for aitobot portal agents."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:18880"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "summary": "Liveness check",
        "security": [],
        "responses": {
          "200": {
            "description": "Portal process is alive"
          }
        }
      },
      "head": {
        "summary": "Liveness check without body",
        "security": [],
        "responses": {
          "200": {
            "description": "Portal process is alive"
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "summary": "Readiness check",
        "security": [],
        "responses": {
          "200": {
            "description": "Portal dependencies are ready"
          },
          "503": {
            "description": "One or more dependencies are not ready"
          }
        }
      },
      "head": {
        "summary": "Readiness check without body",
        "security": [],
        "responses": {
          "200": {
            "description": "Portal dependencies are ready"
          },
          "503": {
            "description": "One or more dependencies are not ready"
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "summary": "Operational metrics snapshot",
        "security": [],
        "responses": {
          "200": {
            "description": "Aggregated operational metrics without secrets"
          }
        }
      }
    },
    "/api/v1/agents": {
      "get": {
        "summary": "List available services",
        "security": [],
        "responses": {
          "200": {
            "description": "Service list"
          }
        }
      }
    },
    "/api/v1/account": {
      "get": {
        "summary": "Get current account and plan",
        "responses": {
          "200": {
            "description": "Current account"
          }
        }
      }
    },
    "/api/v1/accounts": {
      "get": {
        "summary": "List local accounts",
        "responses": {
          "200": {
            "description": "Account list"
          }
        }
      },
      "post": {
        "summary": "Create a local account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "developer",
                      "team"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created"
          },
          "409": {
            "description": "Account already exists"
          }
        }
      }
    },
    "/api/v1/api-keys": {
      "get": {
        "summary": "List registered API keys",
        "responses": {
          "200": {
            "description": "API key list without secrets"
          }
        }
      },
      "post": {
        "summary": "Create a developer API key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "account_id": {
                    "type": "string"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created; token returned once"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "Missing key management scope"
          }
        }
      }
    },
    "/api/v1/api-keys/{key_id}/revoke": {
      "post": {
        "summary": "Revoke a developer API key",
        "parameters": [
          {
            "name": "key_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key revoked"
          },
          "404": {
            "description": "API key not found"
          },
          "409": {
            "description": "API key already revoked"
          }
        }
      }
    },
    "/api/v1/agent-runs": {
      "post": {
        "summary": "Create a traceable service run",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "agent_id",
                  "input"
                ],
                "properties": {
                  "agent_id": {
                    "type": "string",
                    "enum": [
                      "student-schedule-planner",
                      "tech-explainer-public"
                    ]
                  },
                  "input": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing run reused by idempotency key"
          },
          "201": {
            "description": "Run created"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/v1/agent-runs/{run_id}": {
      "get": {
        "summary": "Get a service run",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run"
          },
          "404": {
            "description": "Run not found"
          }
        }
      }
    },
    "/api/v1/agent-runs/{run_id}/cancel": {
      "post": {
        "summary": "Cancel a queued or running service run",
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run canceled"
          },
          "409": {
            "description": "Run already final"
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "Get local usage summary",
        "responses": {
          "200": {
            "description": "Usage summary"
          }
        }
      }
    },
    "/api/v1/wiki/search": {
      "get": {
        "summary": "Search public wiki documents",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wiki search results"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}