{"openapi":"3.1.0","info":{"title":"Superset API","version":"1.0.0","summary":"Programmatic access to Superset's agent-orchestration platform.","description":"Superset (https://superset.sh) runs parallel AI coding agents in isolated Git worktrees.\n\nThe primary programmatic surface is the **MCP server** (Model Context Protocol, JSON-RPC 2.0 over Streamable HTTP) at `/mcp` (legacy alias: `/api/v2/agent/mcp`). It exposes tools for tasks, workspaces, coding-agent sessions, terminals, automations, hosts, projects, and organization members. The tool catalog with input schemas is published at `https://api.superset.sh/.well-known/mcp/server-card.json` and served live via the MCP `tools/list` method.\n\nAuthentication is OAuth 2.1 authorization code + PKCE with RFC 7591 dynamic client registration, or a user-issued Superset API key sent as a Bearer token. Agent walkthrough: https://superset.sh/auth.md\n\nVersioning and deprecation: the current surface is v2, versioned in the URL path (/api/v2/...). Deprecations are announced in the changelog (https://superset.sh/changelog). The legacy v1 MCP server at /api/agent/mcp has been removed and returns 410 Gone.","contact":{"name":"Superset support","email":"support@superset.sh","url":"https://superset.sh/contact"},"termsOfService":"https://superset.sh/terms","x-versioning":{"strategy":"url-path","current":"v2","paths":["/mcp","/api/v2/agent/mcp"],"deprecationPolicy":"Breaking changes ship under a new path version. Deprecated surfaces keep serving for at least 90 days, return a Deprecation header, and are announced in the changelog (https://superset.sh/changelog) before removal; removed surfaces return 410 Gone with a hint pointing at the replacement."}},"externalDocs":{"description":"Superset MCP documentation","url":"https://docs.superset.sh/mcp-server"},"servers":[{"url":"https://api.superset.sh","description":"Production"}],"tags":[{"name":"mcp","description":"Model Context Protocol server"},{"name":"oauth","description":"OAuth 2.1 / OpenID Connect endpoints"},{"name":"discovery","description":"Machine-readable metadata"}],"security":[{"bearerAuth":[]}],"paths":{"/mcp":{"post":{"operationId":"mcpRequest","tags":["mcp"],"summary":"Send an MCP JSON-RPC request","description":"Streamable HTTP transport endpoint for the Superset MCP server (also served at the legacy alias /api/v2/agent/mcp). Send `initialize`, then `tools/list` to enumerate the available tools, then `tools/call` to act on the authenticated user's tasks, workspaces, agents, automations, terminals, hosts, and projects. Responses are `application/json` or `text/event-stream` depending on the request's Accept header. Rate limit: 600 requests per 60 seconds per credential, reported in RateLimit-* headers; over the limit returns 429 with Retry-After. A plain GET without `Accept: text/event-stream` returns a JSON description of the server instead of opening a stream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response (or SSE stream of responses).","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window for this credential (600)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota policy, e.g. 600;w=60 (draft-ietf-httpapi-ratelimit-headers)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Server-sent events, each carrying a JSON-RPC response."}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"mcpOpenStream","tags":["mcp"],"summary":"Open an MCP server-to-client event stream","description":"Opens the optional Streamable HTTP GET channel for server-initiated MCP messages on an existing session.","parameters":[{"name":"Mcp-Session-Id","in":"header","required":false,"schema":{"type":"string"},"description":"MCP session id returned by the initialize request."}],"responses":{"200":{"description":"Server-sent event stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v2/agent/mcp":{"post":{"operationId":"mcpRequestV2Alias","tags":["mcp"],"summary":"Versioned alias of /mcp","description":"Identical to POST /mcp. The path carries the API version explicitly for clients that pin versions in the URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response (or SSE stream of responses).","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window for this credential (600)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota policy, e.g. 600;w=60 (draft-ietf-httpapi-ratelimit-headers)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/agent/mcp":{"post":{"operationId":"mcpRequestV1Removed","tags":["mcp"],"deprecated":true,"summary":"Removed v1 MCP endpoint","description":"The v1 MCP server was removed after its deprecation window. Requests return 410 Gone with a hint pointing at /mcp.","security":[],"responses":{"410":{"description":"Gone. The body's hint names the replacement endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/oauth2/register":{"post":{"operationId":"oauthRegisterClient","tags":["oauth"],"summary":"Dynamically register an OAuth client (RFC 7591)","description":"Anonymous dynamic client registration. Public clients using PKCE should set token_endpoint_auth_method to none.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationRequest"}}}},"responses":{"201":{"description":"Registered client metadata including client_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationResponse"}}}},"400":{"description":"Invalid client metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/oauth2/authorize":{"get":{"operationId":"oauthAuthorize","tags":["oauth"],"summary":"Authorization endpoint (user consent)","description":"Browser endpoint where the user approves an agent's access. Use the authorization code + PKCE flow.","security":[],"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","examples":["openid profile email offline_access"]}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","enum":["S256"]}}],"responses":{"302":{"description":"Redirect to the consent UI, then to redirect_uri with ?code=...&state=...","headers":{"Location":{"description":"Consent UI, or redirect_uri with code and state query parameters appended.","schema":{"type":"string","format":"uri"}}}}}}},"/api/auth/oauth2/token":{"post":{"operationId":"oauthToken","tags":["oauth"],"summary":"Token endpoint","description":"Exchange an authorization code (with PKCE code_verifier) or a refresh token for an access token.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Standard OAuth token envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"OAuth error envelope (invalid_grant, invalid_client, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}},"/api/auth/oauth2/userinfo":{"get":{"operationId":"oauthUserinfo","tags":["oauth"],"summary":"OpenID Connect userinfo","responses":{"200":{"description":"Claims about the authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInfo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/auth/oauth2/revoke":{"post":{"operationId":"oauthRevoke","tags":["oauth"],"summary":"Revoke a token (RFC 7009)","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRevocationRequest"}}}},"responses":{"200":{"description":"Token revoked (idempotent)."}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getProtectedResourceMetadata","tags":["discovery"],"summary":"Protected resource metadata (RFC 9728)","security":[],"responses":{"200":{"description":"Resource metadata naming the authorization server and supported scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"getAuthorizationServerMetadata","tags":["discovery"],"summary":"Authorization server metadata (RFC 8414)","description":"Includes an agent_auth block (per the auth.md convention) with the registration and revocation URIs agents should use.","security":[],"responses":{"200":{"description":"Authorization server metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationServerMetadata"}}}}}}},"/.well-known/mcp/server-card.json":{"get":{"operationId":"getMcpServerCard","tags":["discovery"],"summary":"MCP server card","description":"Name, description, version, serverUrl, transport, authentication, and the full tool catalog of the Superset MCP server.","security":[],"responses":{"200":{"description":"MCP server card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerCard"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["discovery"],"summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 specification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Superset API key or OAuth 2.1 access token. Unauthenticated requests receive 401 with a WWW-Authenticate header pointing at the protected resource metadata."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization code + PKCE with RFC 7591 dynamic client registration.","flows":{"authorizationCode":{"authorizationUrl":"https://api.superset.sh/api/auth/oauth2/authorize","tokenUrl":"https://api.superset.sh/api/auth/oauth2/token","refreshUrl":"https://api.superset.sh/api/auth/oauth2/token","scopes":{"openid":"OpenID Connect identity","profile":"User profile","email":"User email","offline_access":"Refresh tokens"}}}}},"schemas":{"Error":{"type":"object","description":"Structured JSON error envelope returned by all API errors.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code.","examples":["UNAUTHORIZED","NOT_FOUND"]},"message":{"type":"string","description":"Human-readable description of the failure."},"hint":{"type":"string","description":"How to resolve the error, when known."}},"required":["code","message"]}},"required":["error"]},"JsonRpcRequest":{"type":"object","description":"A JSON-RPC 2.0 request as defined by the Model Context Protocol.","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"Request id. Omitted for notifications."},"method":{"type":"string","description":"MCP method, e.g. initialize, tools/list, tools/call.","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object","description":"Method parameters. For tools/call: { name, arguments }.","additionalProperties":true}},"required":["jsonrpc","method"]},"JsonRpcResponse":{"type":"object","description":"A JSON-RPC 2.0 response from the MCP server.","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc"]},"OAuthError":{"type":"object","properties":{"error":{"type":"string","examples":["invalid_grant","invalid_client","invalid_request"]},"error_description":{"type":"string"}},"required":["error"]},"ClientRegistrationRequest":{"type":"object","properties":{"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"}},"grant_types":{"type":"array","items":{"type":"string","enum":["authorization_code","refresh_token"]}},"token_endpoint_auth_method":{"type":"string","enum":["none","client_secret_basic","client_secret_post"]},"scope":{"type":"string"}},"required":["redirect_uris"]},"ClientRegistrationResponse":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"}},"grant_types":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string"}},"required":["client_id"]},"UserInfo":{"description":"OpenID Connect claims about the authenticated user.","type":"object","properties":{"sub":{"type":"string"},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"name":{"type":"string"},"picture":{"type":"string","format":"uri"}},"required":["sub"]},"TokenRevocationRequest":{"description":"RFC 7009 revocation request body.","type":"object","properties":{"token":{"type":"string"},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"]},"client_id":{"type":"string"}},"required":["token"]},"ProtectedResourceMetadata":{"description":"RFC 9728 protected resource metadata.","type":"object","properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"resource_name":{"type":"string"},"resource_documentation":{"type":"string","format":"uri"}},"required":["resource","authorization_servers"]},"AuthorizationServerMetadata":{"description":"RFC 8414 authorization server metadata with the agent_auth extension.","type":"object","properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"registration_endpoint":{"type":"string","format":"uri"},"revocation_endpoint":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"type":"string"}},"agent_auth":{"type":"object","properties":{"skill":{"type":"string","format":"uri"},"register_uri":{"type":"string","format":"uri"},"revocation_uri":{"type":"string","format":"uri"},"identity_types_supported":{"type":"array","items":{"type":"string","enum":["anonymous"]}}}}},"required":["issuer"],"additionalProperties":true},"McpServerCard":{"description":"MCP server card: identity, transport, authentication, and tool catalog.","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"serverUrl":{"type":"string","format":"uri"},"transport":{"type":"string","enum":["streamable-http"]},"documentationUrl":{"type":"string","format":"uri"},"authentication":{"type":"object","properties":{"type":{"type":"string"},"resourceMetadataUrl":{"type":"string","format":"uri"}}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","additionalProperties":true}},"required":["name"]}}},"required":["name","version","serverUrl","tools"]},"OpenApiDocument":{"description":"An OpenAPI 3.1 document.","type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object","additionalProperties":true},"paths":{"type":"object","additionalProperties":true},"components":{"type":"object","additionalProperties":true}},"required":["openapi","info","paths"]},"TokenRequest":{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","client_credentials"]},"code":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"client_id":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"}},"required":["grant_type"]},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","examples":["Bearer"]},"expires_in":{"type":"integer","description":"Access token lifetime in seconds (3600)."},"refresh_token":{"type":"string"},"scope":{"type":"string"},"id_token":{"type":"string"}},"required":["access_token","token_type"]}},"responses":{"Unauthorized":{"description":"Missing, expired, or revoked credential. The WWW-Authenticate header points at the RFC 9728 protected resource metadata to bootstrap OAuth discovery.","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"superset\", resource_metadata=\"https://api.superset.sh/.well-known/oauth-protected-resource\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this credential in the current window. Wait Retry-After seconds and retry.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window for this credential (600)."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Quota policy, e.g. 600;w=60 (draft-ietf-httpapi-ratelimit-headers)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}