{
  "openapi": "3.1.0",
  "info": {
    "title": "Alem Agent Integration API",
    "version": "0.1.0",
    "description": "Public discovery and owner-authorized onboarding surface for Alem. The MCP endpoint is the primary agent tool interface; this OpenAPI document describes discovery and pairing entry points.",
    "contact": {
      "url": "https://askalem.com/"
    }
  },
  "servers": [
    {
      "url": "https://askalem.com",
      "description": "Alem production"
    }
  ],
  "tags": [
    {
      "name": "Discovery"
    },
    {
      "name": "Authentication"
    },
    {
      "name": "Pairing"
    },
    {
      "name": "MCP"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Service health",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Healthy service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    },
                    "storage": {
                      "type": "string"
                    },
                    "mcp": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/setup": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Machine-readable agent setup manifest",
        "operationId": "getSetupManifest",
        "description": "Returns service URLs, supported client ids, installer metadata and pairing guidance.",
        "responses": {
          "200": {
            "description": "Setup manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/register": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Create a workspace owner account",
        "operationId": "register",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Credentials"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created"
          },
          "400": {
            "description": "Invalid input"
          },
          "409": {
            "description": "Account could not be created"
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign in as workspace owner",
        "operationId": "login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Credentials"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created"
          },
          "401": {
            "description": "Invalid credentials"
          }
        }
      }
    },
    "/api/pairings": {
      "post": {
        "tags": [
          "Pairing"
        ],
        "summary": "Create a short-lived one-time agent pairing",
        "operationId": "createPairing",
        "description": "Requires an authenticated workspace-owner browser session and CSRF protection.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "client"
                ],
                "properties": {
                  "client": {
                    "type": "string",
                    "enum": [
                      "codex",
                      "claude-code",
                      "cursor",
                      "hermes",
                      "pi"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pairing instruction created"
          },
          "403": {
            "description": "Owner session required"
          }
        }
      }
    },
    "/api/pairings/exchange": {
      "post": {
        "tags": [
          "Pairing"
        ],
        "summary": "Exchange a one-time pairing code",
        "operationId": "exchangePairing",
        "description": "Used by the trusted local installer. Codes expire quickly and are single-use.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "client"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "client": {
                    "type": "string",
                    "enum": [
                      "codex",
                      "claude-code",
                      "cursor",
                      "hermes",
                      "pi"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paired bearer credential issued"
          },
          "401": {
            "description": "Invalid or expired pairing code"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "summary": "Model Context Protocol endpoint",
        "operationId": "mcp",
        "description": "Streamable HTTP MCP endpoint. Use the owner-authorized pairing flow to obtain a credential. MCP message schemas are defined by the Model Context Protocol rather than this OpenAPI document.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "MCP response"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Credentials": {
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "password": {
            "type": "string",
            "minLength": 15
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Alem developer discovery",
    "url": "https://askalem.com/developers.html"
  },
  "x-mcp": {
    "transport": "streamable-http",
    "url": "https://askalem.com/mcp",
    "setup": "https://askalem.com/api/setup"
  }
}