{
  "openapi": "3.0.3",
  "info": {
    "title": "RunAgencyOS API",
    "version": "0.1.0",
    "description": "Filtered public overview of the RunAgencyOS HTTP API. Documentation is public; every authenticated endpoint still requires credentials. REST uses JWT access tokens from login. Workspace API keys (af_...) authenticate the MCP transport at /mcp/. Internal admin, provider webhook, and founder-only routes are omitted from this document.",
    "contact": {
      "name": "RunAgencyOS Support",
      "email": "support@runagencyos.com",
      "url": "https://runagencyos.com/support"
    }
  },
  "servers": [
    {
      "url": "https://runagencyos.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "health",
      "description": "Liveness and dependency status"
    },
    {
      "name": "auth",
      "description": "Login, refresh, and identity"
    },
    {
      "name": "workspaces",
      "description": "Workspaces and API key management"
    },
    {
      "name": "crm",
      "description": "Contacts and companies"
    },
    {
      "name": "mcp",
      "description": "MCP discovery for signed-in workspace users"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Access JWT from login/refresh for REST routes."
      },
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "af_...",
        "description": "Workspace API key for MCP (/mcp/). Create in Settings \u2192 API Keys & MCP."
      }
    },
    "parameters": {
      "WorkspaceId": {
        "name": "X-Workspace-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Active workspace tenant id for tenant-scoped REST routes."
      }
    }
  },
  "paths": {
    "/healthz": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "Per-component status payload"
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Email/password login",
        "security": [],
        "responses": {
          "200": {
            "description": "Access token issued; refresh cookie set"
          },
          "401": {
            "description": "Invalid credentials"
          }
        }
      }
    },
    "/api/v1/auth/refresh": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Refresh access token",
        "security": [],
        "responses": {
          "200": {
            "description": "New access token"
          },
          "401": {
            "description": "Refresh rejected"
          }
        }
      }
    },
    "/api/v1/workspaces/api-keys": {
      "get": {
        "tags": [
          "workspaces"
        ],
        "summary": "List workspace API keys",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "API key metadata (no plaintext)"
          },
          "401": {
            "description": "Not authenticated"
          }
        }
      },
      "post": {
        "tags": [
          "workspaces"
        ],
        "summary": "Create a scoped workspace API key",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "201": {
            "description": "Key created; plaintext returned once"
          },
          "401": {
            "description": "Not authenticated"
          }
        }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "tags": [
          "crm"
        ],
        "summary": "List contacts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact page"
          },
          "401": {
            "description": "Not authenticated"
          }
        }
      }
    },
    "/api/v1/mcp/info": {
      "get": {
        "tags": [
          "mcp"
        ],
        "summary": "MCP connection details and tool catalog for the current workspace",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint URL, scopes, and tool list"
          },
          "401": {
            "description": "Not authenticated"
          }
        }
      }
    },
    "/mcp/": {
      "post": {
        "tags": [
          "mcp"
        ],
        "summary": "MCP streamable HTTP transport",
        "description": "Requires a workspace API key. Not a public anonymous endpoint.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "MCP response"
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    }
  }
}
