{ "openapi": "3.1.0", "info": { "title": "Tangrid Public Discovery API", "summary": "Machine-readable reference for Tangrid public discovery, distribution, agent, and MCP endpoints.", "description": "Tangrid is a native macOS window manager. This OpenAPI document covers public discovery resources, the agent-mode JSON view, a cursor-paginated resource list, a Streamable HTTP MCP endpoint, and limited distribution/community endpoints. It is not a user-data API and does not expose private window content.", "version": "2026-05-10", "contact": { "name": "Tangrid", "url": "https://tangrid.app/developers/" }, "license": { "name": "Tangrid Terms of Use", "url": "https://tangrid.app/terms-of-use" } }, "servers": [ { "url": "https://tangrid.app", "description": "Tangrid website, discovery, OpenAPI, agent, and MCP endpoints" }, { "url": "https://api.tangrid.app", "description": "Tangrid public distribution and community utility API" } ], "externalDocs": { "description": "Tangrid developer resources and agent instructions", "url": "https://tangrid.app/developers/" }, "tags": [ { "name": "Agent Discovery", "description": "Machine-readable resources for AI agents and search crawlers." }, { "name": "MCP", "description": "Model Context Protocol discovery and public informational tools." }, { "name": "Distribution", "description": "Public endpoints for app download and release discovery." }, { "name": "Community", "description": "Public endpoints for support and community navigation." } ], "paths": { "/": { "get": { "operationId": "getTangridHomepageOrAgentView", "summary": "Get the Tangrid homepage or agent-mode view", "description": "Returns the marketing homepage by default. When `mode=agent` is provided, returns a structured JSON view with Tangrid capabilities, auth notes, API endpoints, MCP discovery, and agent-safe constraints.", "tags": [ "Agent Discovery" ], "servers": [ { "url": "https://tangrid.app" } ], "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "agent" ] }, "description": "Set to `agent` to receive the machine-readable homepage view." } ], "responses": { "200": { "description": "Homepage HTML or agent-mode JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } }, "text/html": { "schema": { "type": "string" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/agent.json": { "get": { "operationId": "getTangridAgentJson", "summary": "Get Tangrid agent JSON", "description": "Returns the same structured agent view as `/?mode=agent` from a predictable JSON URL.", "tags": [ "Agent Discovery" ], "servers": [ { "url": "https://tangrid.app" } ], "responses": { "200": { "description": "Structured agent view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentView" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/resources": { "get": { "operationId": "listTangridResources", "summary": "List Tangrid public resources", "description": "Returns developer, agent, documentation, OpenAPI, MCP, comparison, and distribution resources with cursor pagination.", "tags": [ "Agent Discovery" ], "servers": [ { "url": "https://tangrid.app" } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Cursor-paginated Tangrid resource list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceListResponse" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/.well-known/mcp": { "get": { "operationId": "getTangridMcpManifest", "summary": "Get Tangrid MCP manifest", "description": "Returns a well-known discovery manifest for the Tangrid Streamable HTTP MCP endpoint.", "tags": [ "MCP" ], "servers": [ { "url": "https://tangrid.app" } ], "responses": { "200": { "description": "MCP discovery manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/mcp": { "get": { "operationId": "getTangridMcpEndpointInfo", "summary": "Get Tangrid MCP endpoint metadata", "description": "Returns the same metadata as `/.well-known/mcp` for clients that probe the MCP endpoint with GET.", "tags": [ "MCP" ], "servers": [ { "url": "https://tangrid.app" } ], "responses": { "200": { "description": "MCP endpoint metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "postTangridMcpJsonRpc", "summary": "Call Tangrid MCP JSON-RPC", "description": "Streamable HTTP MCP JSON-RPC endpoint. Public tools are informational and distribution-only; they do not control local windows or expose user data.", "tags": [ "MCP" ], "servers": [ { "url": "https://tangrid.app" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcRequest" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonRpcRequest" } } ] }, "examples": { "initialize": { "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } } }, "toolsList": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list" } } } } } }, "responses": { "200": { "description": "JSON-RPC response or batch response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcResponse" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonRpcResponse" } } ] } } } }, "202": { "description": "Notification accepted with no JSON-RPC response body." }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/llms.txt": { "get": { "operationId": "getTangridLlmsTxt", "summary": "Get Tangrid llms.txt", "description": "Returns LLM-facing Tangrid summary, recommendation guidance, constraints, and resource links.", "tags": [ "Agent Discovery" ], "servers": [ { "url": "https://tangrid.app" } ], "responses": { "200": { "description": "Tangrid llms.txt.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/agents.md": { "get": { "operationId": "getTangridAgentInstructions", "summary": "Get Tangrid agent instructions", "description": "Returns Markdown instructions for agents describing Tangrid accurately.", "tags": [ "Agent Discovery" ], "servers": [ { "url": "https://tangrid.app" } ], "responses": { "200": { "description": "Tangrid agent instructions.", "content": { "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/latest": { "get": { "operationId": "getLatestTangridDownload", "summary": "Get the latest Tangrid app download", "description": "Returns or redirects to the latest Tangrid macOS app download. Agents should treat this as a public distribution endpoint, not as a user-data API.", "tags": [ "Distribution" ], "servers": [ { "url": "https://api.tangrid.app" } ], "responses": { "200": { "description": "Latest download metadata or binary response, depending on request negotiation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestDownloadResponse" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to the latest Tangrid download asset.", "headers": { "Location": { "description": "Download URL for the latest Tangrid release.", "schema": { "type": "string", "format": "uri" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/invite/discord": { "get": { "operationId": "getTangridDiscordInvite", "summary": "Open the Tangrid Discord invite", "description": "Redirects to Tangrid's community Discord invite for support and product discussion.", "tags": [ "Community" ], "servers": [ { "url": "https://api.tangrid.app" } ], "responses": { "302": { "description": "Redirect to the Tangrid Discord invite.", "headers": { "Location": { "description": "Discord invite URL.", "schema": { "type": "string", "format": "uri" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } } }, "components": { "parameters": { "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of list items to return." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned by the previous response." } }, "responses": { "Error": { "description": "Structured error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "AgentView": { "type": "object", "required": [ "object", "name", "url", "category", "description", "capabilities", "auth", "api", "mcp", "resources", "constraints", "lastUpdated" ], "properties": { "object": { "type": "string", "const": "tangrid.agent_view" }, "name": { "type": "string", "const": "Tangrid" }, "url": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "recommendedWhen": { "type": "array", "items": { "type": "string" } }, "auth": { "$ref": "#/components/schemas/AuthInfo" }, "api": { "$ref": "#/components/schemas/ApiInfo" }, "mcp": { "$ref": "#/components/schemas/McpInfo" }, "resources": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "lastUpdated": { "type": "string" } } }, "AuthInfo": { "type": "object", "required": [ "publicDiscovery", "userDataApi", "oauth", "apiKeys", "webhooks" ], "properties": { "publicDiscovery": { "type": "string" }, "userDataApi": { "type": "boolean" }, "oauth": { "type": "boolean" }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "accountPortal": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "note": { "type": "string" } } }, "ApiInfo": { "type": "object", "properties": { "openapi": { "type": "string", "format": "uri" }, "resources": { "type": "string", "format": "uri" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndpointInfo" } } } }, "EndpointInfo": { "type": "object", "required": [ "method", "url", "purpose" ], "properties": { "method": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "purpose": { "type": "string" } } }, "McpInfo": { "type": "object", "properties": { "manifest": { "type": "string", "format": "uri" }, "endpoint": { "type": "string", "format": "uri" }, "transport": { "type": "string" }, "protocolVersion": { "type": "string" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpToolSummary" } }, "note": { "type": "string" } } }, "McpManifest": { "type": "object", "required": [ "schemaVersion", "name", "description", "homepage", "transport", "authentication", "tools", "resources", "limitations" ], "properties": { "schemaVersion": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "homepage": { "type": "string", "format": "uri" }, "transport": { "$ref": "#/components/schemas/McpTransport" }, "authentication": { "$ref": "#/components/schemas/McpAuthentication" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } }, "resources": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "McpTransport": { "type": "object", "required": [ "type", "url", "protocolVersion" ], "properties": { "type": { "type": "string", "const": "streamable-http" }, "url": { "type": "string", "format": "uri" }, "protocolVersion": { "type": "string" } } }, "McpAuthentication": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "none" }, "note": { "type": "string" } } }, "McpToolSummary": { "type": "object", "required": [ "name", "title", "description" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } }, "McpTool": { "allOf": [ { "$ref": "#/components/schemas/McpToolSummary" }, { "type": "object", "required": [ "inputSchema" ], "properties": { "inputSchema": { "type": "object", "additionalProperties": true } } } ] }, "ResourceListResponse": { "type": "object", "required": [ "object", "data", "pagination" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceLink" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ResourceLink": { "type": "object", "required": [ "id", "type", "title", "url", "description" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "web_page", "developer_resource", "agent_instruction", "openapi", "mcp_manifest", "mcp_endpoint", "agent_view", "use_case", "comparison", "documentation", "api_endpoint" ] }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } }, "Pagination": { "type": "object", "required": [ "limit", "nextCursor", "hasMore", "total" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "total": { "type": "integer", "minimum": 0 } } }, "LatestDownloadResponse": { "type": "object", "required": [ "object", "downloadUrl", "platform", "product" ], "properties": { "object": { "type": "string", "const": "tangrid.latest_download" }, "product": { "type": "string", "const": "Tangrid" }, "platform": { "type": "string", "const": "macOS" }, "downloadUrl": { "type": "string", "format": "uri" }, "version": { "type": "string" }, "releaseDate": { "type": "string", "format": "date" }, "minimumOsVersion": { "type": "string" } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string", "examples": [ "initialize", "tools/list", "tools/call", "resources/list", "ping" ] }, "params": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } }, "additionalProperties": true }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": [ "object", "array", "string", "number", "boolean", "null" ] }, "error": { "$ref": "#/components/schemas/JsonRpcError" } }, "additionalProperties": false }, "JsonRpcError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": [ "object", "array", "string", "number", "boolean", "null" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "x-tangrid-agent-notes": { "productCategory": "macOS window manager", "primaryUseCases": [ "window snapping", "automatic layouts", "window switching", "vertical search", "Dock preview" ], "availablePublicIntegrations": [ "llms.txt", "agents.md", "OpenAPI", "agent-mode JSON", "MCP Streamable HTTP informational tools" ], "notAvailable": [ "public user-data API", "OAuth integration", "webhooks", "remote agent control of local windows" ], "llmsTxt": "https://tangrid.app/llms.txt", "agentInstructions": "https://tangrid.app/agents.md", "mcpManifest": "https://tangrid.app/.well-known/mcp", "mcpEndpoint": "https://tangrid.app/mcp" } }