{ "openapi": "3.1.0", "info": { "title": "Alpha Governance API", "version": "2.0.0", "description": "The Alpha Governance API provides programmatic access to AI governance intelligence for board directors, institutional investors, and AI agents. Alpha is the independent verification organization (IVO) for AI governance, rating public companies on The Alpha Standard (12 dimensions, D1-D12).\n\nTwo integration paths:\n- **MCP Server** (recommended for agents): Full Model Context Protocol integration with 18 tools, 8 resource templates, 3 UI resources (`ui://` MCP Apps), and 5 prompts\n- **REST API**: Lightweight endpoints for governance scores and credential verification\n\n## Authentication\n\nAlpha supports two authentication methods:\n\n1. **API Key** (direct): Pass `x-api-key: YOUR_KEY` header or `Authorization: Bearer YOUR_KEY`\n2. **OAuth 2.0** (for agents): Authorization Code flow with PKCE (S256). See `/auth/authorize`\n\nGet an API key at https://alpha.ac/radar. Selected public-access endpoints require no key, while authenticated endpoints require API credentials.\n\n## OAuth 2.0 Scopes\n\n| Scope | Access |\n|-------|--------|\n| `read:governance` | Company AGR ratings, GEH, AART, trajectory |\n| `read:ratings` | Full D1-D12 dimension scores, D2R Map, DPD |\n| `read:directors` | Director AGIQ scores, board seats, committee roles |\n| `read:regulatory` | EU AI Act, NIST, ISO 42001 regulatory intelligence |\n\n## Rate Limits\n\n100 requests/minute per IP. Every response includes:\n- `X-RateLimit-Limit: 100`\n- `X-RateLimit-Remaining: N`\n- `X-RateLimit-Reset: `\n- On 429: `Retry-After: 60`", "contact": { "name": "Alpha Developer Support", "email": "info@alpha.ac", "url": "https://alpha.ac/developers" }, "license": { "name": "Proprietary", "url": "https://alpha.ac/terms" }, "x-logo": { "url": "https://alpha.ac/logo-cowork.png", "altText": "Alpha" }, "x-access": { "public": { "tools": [ "search_companies", "get_platform_stats", "get_epoch_model_context", "get_compute_tier", "get_frontier_models_timeline" ], "description": "Public access \u2014 no API key required", "url": "https://www.alpha.ac/radar" }, "authenticated": { "description": "Authenticated access \u2014 API key required (x-api-key header)", "url": "https://www.alpha.ac/radar" } }, "x-mcp-server": "https://api.alpha.ac/functions/v1/mcp-server" }, "servers": [ { "url": "https://api.alpha.ac/functions/v1", "description": "Production API" } ], "tags": [ { "name": "MCP", "description": "Model Context Protocol server for AI agent integration \u2014 18 tools, MCP Apps (ui:// resources)" }, { "name": "Governance", "description": "Company AI governance ratings and scores" }, { "name": "Credentials", "description": "ACD.AI / ACE.AI certification verification (public access, no auth required)" } ], "paths": { "/mcp-server": { "post": { "operationId": "mcpServer", "summary": "MCP JSON-RPC endpoint", "description": "Model Context Protocol (MCP) server implementing Streamable HTTP transport (JSON-RPC 2.0). Protocol version: 2025-03-26.\n\n**Capabilities:** `tools`, `resources`, `prompts`, `apps` (MCP Apps \u2014 ui:// interactive resources).\n\n**MCP Apps:** 3 interactive UI resources accessible via `resources/list` and `resources/read`. Tool results include `_meta.ui.resourceUri` linking to these resources.\n\n**Public-access tools** (no auth): `search_companies`, `get_platform_stats`, `get_epoch_model_context`, `get_compute_tier`, `get_frontier_models_timeline`.\n\n**Authenticated tools** (API key or OAuth2 required): `score_ai_governance_risk`, `get_board_profile`, `compare_companies`, `get_director_profile`, `get_governance_signals`, `get_regulatory_intelligence`, `benchmark_board_ai_readiness`, `find_ai_governance_signals`, `verify_credential`, `get_governance_rating`, `get_governance_debt`, `compare_capability_velocity`, `get_governance_scaling_index`.\n\nRate limit: 100 requests/minute per IP.", "tags": [ "MCP" ], "security": [ {}, { "ApiKeyHeader": [] }, { "BearerToken": [] }, { "OAuth2": [ "read:governance" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "initialize": { "summary": "Initialize MCP session", "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": { "apps": {} }, "clientInfo": { "name": "my-agent", "version": "1.0" } } } }, "listTools": { "summary": "List available tools", "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } }, "searchFree": { "summary": "Search companies (public access, no auth required)", "value": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_companies", "arguments": { "query": "Microsoft" } } } }, "listResources": { "summary": "List MCP Apps (ui://) and resource templates", "value": { "jsonrpc": "2.0", "id": 4, "method": "resources/list" } }, "readUiResource": { "summary": "Read interactive governance dashboard (MCP Apps)", "value": { "jsonrpc": "2.0", "id": 5, "method": "resources/read", "params": { "uri": "ui://alpha/governance-dashboard?ticker=MSFT" } } }, "scoreGovernance": { "summary": "Score AI governance risk (authenticated access)", "value": { "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "score_ai_governance_risk", "arguments": { "ticker": "MSFT" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC response. For MCP Apps, tool results include `_meta.ui.resourceUri` pointing to `ui://alpha/*` resources.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests per minute (100)" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the rate limit window resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" }, "example": { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-03-26", "capabilities": { "tools": { "listChanged": false }, "resources": { "subscribe": false, "listChanged": false }, "prompts": { "listChanged": false }, "apps": {} }, "serverInfo": { "name": "Alpha Radar", "version": "2.0.0" } } } } } }, "400": { "description": "Invalid JSON-RPC request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcErrorResponse" }, "example": { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } } } } }, "429": { "description": "Rate limit exceeded (100 req/min per IP)", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until next allowed request (60)" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcErrorResponse" }, "example": { "jsonrpc": "2.0", "id": 1, "error": { "code": -32029, "message": "Rate limit exceeded. Retry after 60 seconds.", "data": { "retryAfter": 60 } } } } } } } }, "get": { "operationId": "mcpServerInfo", "summary": "MCP server discovery (GET)", "description": "Returns MCP server metadata: capabilities, available tools, UI resources, protocol version. Used by agents for service discovery without initiating a full JSON-RPC session.", "tags": [ "MCP" ], "security": [ {} ], "responses": { "200": { "description": "Server capability summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "protocol": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "integer" }, "resources": { "type": "integer" }, "uiResources": { "type": "integer", "description": "Number of MCP Apps (ui://) resources" }, "prompts": { "type": "integer" } } } } } } } } }, "/credential-verify": { "get": { "operationId": "verifyCredential", "summary": "Verify ACD.AI or ACE.AI certification (public access, no auth required)", "description": "Publicly verifiable endpoint. No authentication required. Returns certification status, issue date, expiry, and AGIQ band for a director's ACD.AI (AI Director) or ACE.AI (AI Executive) credential.", "tags": [ "Credentials" ], "security": [ {} ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "example": "ACD-2026-00142" }, "description": "Credential ID (format: ACD-YYYY-NNNNN or ACE-YYYY-NNNNN)" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "example": "Jane Smith" }, "description": "Director or executive full name" } ], "responses": { "200": { "description": "Credential verification result", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialResponse" }, "examples": { "verified": { "summary": "Valid credential", "value": { "verified": true, "credential_type": "ACD.AI", "holder_name": "Jane Smith", "credential_id": "ACD-2026-00142", "issued_at": "2026-01-15", "expires_at": "2028-01-15", "agiq_band": "Proficient", "issuer": "Alpha Institute for AI Governance" } }, "not_found": { "summary": "Credential not found", "value": { "verified": false, "error": "Credential not found or not publicly listed" } } } } } }, "400": { "description": "Missing required parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing credential ID", "usage": "GET /credential-verify?id=ACD-2026-00142" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alpha API key. Obtain at https://alpha.ac/radar. Selected public-access endpoints work without a key, while authenticated endpoints require API credentials." }, "BearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "ApiKey", "description": "Bearer token authentication (same API key value as x-api-key header). Format: `Authorization: Bearer alpha_k_xxxxxxxx`" }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 Authorization Code flow with PKCE (S256). Suitable for agent-facing applications that need delegated access. Authorization server: https://www.alpha.ac", "flows": { "authorizationCode": { "authorizationUrl": "https://www.alpha.ac/auth/authorize", "tokenUrl": "https://api.alpha.ac/functions/v1/auth-token", "refreshUrl": "https://api.alpha.ac/functions/v1/auth-token", "scopes": { "read:governance": "Read company AGR ratings, GEH probability, AART tier, and trajectory", "read:ratings": "Read full D1-D12 dimension scores, D2R Map (regulatory citations), and Disclosure-Practice Divergence (DPD)", "read:directors": "Read director AGIQ scores (0-200), board seats, committee roles, and governance expertise", "read:regulatory": "Read EU AI Act compliance status, NIST AI RMF mapping, ISO 42001 gap analysis, and enforcement timelines" } }, "clientCredentials": { "tokenUrl": "https://api.alpha.ac/functions/v1/auth-token", "scopes": { "read:governance": "Read company AGR ratings, GEH probability, AART tier, and trajectory", "read:ratings": "Read full D1-D12 dimension scores, D2R Map (regulatory citations), and Disclosure-Practice Divergence (DPD)", "read:directors": "Read director AGIQ scores (0-200), board seats, committee roles, and governance expertise", "read:regulatory": "Read EU AI Act compliance status, NIST AI RMF mapping, ISO 42001 gap analysis, and enforcement timelines" } } } } }, "schemas": { "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "description": "MCP method: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get" }, "params": { "type": "object", "description": "Method-specific parameters" } } }, "JsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object", "description": "For tool calls: includes `content` array and optionally `_meta.ui.resourceUri` pointing to a `ui://alpha/*` MCP App resource" } } }, "JsonRpcErrorResponse": { "type": "object", "required": [ "jsonrpc", "error" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "Standard JSON-RPC error codes: -32700 (Parse error), -32600 (Invalid request), -32601 (Method not found), -32602 (Invalid params), -32603 (Internal error), -32029 (Rate limit exceeded)" }, "message": { "type": "string" }, "data": { "type": "object", "description": "Optional structured error data" } } } } }, "CredentialResponse": { "type": "object", "properties": { "verified": { "type": "boolean" }, "credential_type": { "type": "string", "enum": [ "ACD.AI", "ACE.AI" ] }, "holder_name": { "type": "string" }, "credential_id": { "type": "string" }, "issued_at": { "type": "string", "format": "date" }, "expires_at": { "type": "string", "format": "date" }, "agiq_band": { "type": "string", "enum": [ "Expert", "Proficient", "Developing", "Foundational" ] }, "issuer": { "type": "string" }, "error": { "type": "string", "description": "Present when verified=false" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "usage": { "type": "string", "description": "Example usage hint" } } } } }, "externalDocs": { "description": "Alpha Developer Documentation \u2014 API overview, OAuth2 setup, MCP integration guide", "url": "https://alpha.ac/developers" } }