{
  "openapi": "3.1.0",
  "info": {
    "title": "Alem Agent Gateway",
    "version": "0.6.0",
    "description": "Self-serve sandbox for AI-agent economic controls: workspaces, API keys, policies, approvals, audit, ROI and MCP. Payment execution remains sandbox."
  },
  "servers": [
    {
      "url": "https://askalem.com"
    }
  ],
  "paths": {
    "/v1/capabilities": {
      "get": {
        "summary": "Discover Alem capabilities",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/workspaces": {
      "post": {
        "summary": "Create company workspace",
        "responses": {
          "201": {
            "description": "Workspace created; one-time workspace API key returned"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}": {
      "get": {
        "summary": "Get public workspace profile",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}/agents": {
      "get": {
        "summary": "List workspace agents",
        "responses": {
          "200": {
            "description": "Requires x-alem-workspace-key"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}/roi": {
      "get": {
        "summary": "Get AI workforce portfolio ROI",
        "responses": {
          "200": {
            "description": "Requires x-alem-workspace-key"
          }
        }
      }
    },
    "/v1/agents": {
      "post": {
        "summary": "Register an AI agent",
        "responses": {
          "200": {
            "description": "workspace_id + workspace_key binds it to a company"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/policy": {
      "put": {
        "summary": "Update agent financial policy",
        "responses": {
          "200": {
            "description": "Requires workspace or owner key"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/spend/request": {
      "post": {
        "summary": "Request spend authorization",
        "responses": {
          "200": {
            "description": "Requires agent key"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/ledger": {
      "get": {
        "summary": "Get agent audit ledger",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/roi/costs": {
      "post": {
        "summary": "Record an agent cost",
        "responses": {
          "200": {
            "description": "Agent, owner or workspace credential"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/roi/outcomes": {
      "post": {
        "summary": "Record an attributable business outcome",
        "responses": {
          "200": {
            "description": "Owner or workspace credential"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/roi": {
      "get": {
        "summary": "Calculate directional agent ROI",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/approvals/{token}/decision": {
      "post": {
        "summary": "Approve or reject spend request",
        "responses": {
          "200": {
            "description": "Requires owner or workspace key"
          }
        }
      }
    },
    "/v1/passport": {
      "post": {
        "summary": "Create sandbox Financial Passport",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/policy/check": {
      "post": {
        "summary": "Evaluate a proposed transaction",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/route/plan": {
      "post": {
        "summary": "Plan sandbox payment route",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/apply": {
      "post": {
        "summary": "Request design-partner access",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP endpoint",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/developer/signup": {
      "post": {
        "summary": "Self-serve developer signup",
        "description": "Creates a sandbox workspace and optionally a first agent. Returns one-time workspace and agent API keys.",
        "responses": {
          "201": {
            "description": "Sandbox ready; save returned API keys once"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/auth/signup": {
      "post": {
        "summary": "Create a human account + workspace session",
        "description": "Creates a company workspace and authenticated Control Tower account. Returns one-time API credentials and sets a secure session cookie.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "company",
                  "email",
                  "password"
                ],
                "properties": {
                  "company": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 8
                  },
                  "agent_name": {
                    "type": "string"
                  },
                  "monthly_limit": {
                    "type": "number"
                  },
                  "approval_threshold": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created"
          }
        }
      }
    },
    "/v1/auth/login": {
      "post": {
        "summary": "Log in to Control Tower",
        "responses": {
          "200": {
            "description": "Session created"
          }
        }
      }
    },
    "/v1/auth/me": {
      "get": {
        "summary": "Current human account",
        "responses": {
          "200": {
            "description": "Current user/workspace"
          }
        }
      }
    },
    "/v1/app/dashboard": {
      "get": {
        "summary": "Authenticated Control Tower snapshot",
        "responses": {
          "200": {
            "description": "Workspace metrics, agents, approvals and ledger"
          }
        }
      }
    }
  }
}
