{
  "openapi": "3.1.0",
  "info": {
    "title": "ytimesy Public API",
    "summary": "Public discovery and integration API for y.",
    "description": "y is a Mac coding agent app for Claude Code and Codex. This public API exposes safe product metadata, developer resources, feedback submission, product analytics ingestion, and missing-brick request ingestion. It does not expose private user chats or local project data.",
    "version": "1.0.0",
    "contact": {
      "name": "y",
      "email": "contact@ytimesy.com",
      "url": "https://ytimesy.com/developers"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/y-times-y/y/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://ytimesy.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Public product and API discovery endpoints."
    },
    {
      "name": "Desktop ingest",
      "description": "Public ingestion endpoints used by the y desktop app."
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol discovery and tools."
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "tags": ["Discovery"],
        "summary": "List public y API resources",
        "operationId": "getApiIndex",
        "responses": {
          "200": {
            "description": "Public API index.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/product": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Get public y product metadata",
        "operationId": "getProduct",
        "responses": {
          "200": {
            "description": "Public product metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Check public API health",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Health status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok"],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/feedback": {
      "post": {
        "tags": ["Desktop ingest"],
        "summary": "Submit y product feedback",
        "description": "Used by the desktop app feedback dialog. Do not include secrets, source code, full prompts, or private project data.",
        "operationId": "submitFeedback",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Feedback accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/events": {
      "post": {
        "tags": ["Desktop ingest"],
        "summary": "Submit sanitized product analytics event",
        "description": "Used by the desktop app for allowlisted, privacy-scoped product analytics. User chats and local project contents are not accepted.",
        "operationId": "submitEvent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/brick-requests": {
      "post": {
        "tags": ["Desktop ingest"],
        "summary": "Report a missing y brick",
        "description": "Used by y agents to report a missing integration capability using a restricted enum payload.",
        "operationId": "submitBrickRequest",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrickRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brick request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/.well-known/mcp.json": {
      "get": {
        "tags": ["MCP"],
        "summary": "Get y MCP manifest",
        "operationId": "getMcpManifest",
        "responses": {
          "200": {
            "description": "MCP manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpManifest"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "tags": ["MCP"],
        "summary": "Get y MCP manifest",
        "operationId": "getMcpManifestFromEndpoint",
        "responses": {
          "200": {
            "description": "MCP manifest.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpManifest"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["MCP"],
        "summary": "Call the y MCP Streamable HTTP endpoint",
        "description": "Supports initialize, tools/list, and tools/call for read-only public y metadata tools.",
        "operationId": "postMcp",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiIndex": {
        "type": "object",
        "required": ["name", "product", "resources", "endpoints"],
        "properties": {
          "name": { "type": "string" },
          "product": { "type": "string" },
          "description": { "type": "string" },
          "resources": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } },
          "endpoints": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
        }
      },
      "ProductInfo": {
        "type": "object",
        "required": ["name", "description", "website", "developers", "openapi", "llms", "mcp", "download", "repository"],
        "properties": {
          "name": { "type": "string", "example": "y" },
          "alternateName": { "type": "string", "example": "ytimesy" },
          "description": { "type": "string" },
          "website": { "type": "string", "format": "uri" },
          "developers": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" },
          "llms": { "type": "string", "format": "uri" },
          "mcp": { "type": "string", "format": "uri" },
          "download": { "type": "string", "format": "uri" },
          "repository": { "type": "string", "format": "uri" },
          "contact": { "type": "string", "format": "email" },
          "platform": { "type": "array", "items": { "type": "string" } },
          "integrations": { "type": "array", "items": { "type": "string" } }
        }
      },
      "FeedbackRequest": {
        "type": "object",
        "required": ["message"],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string" },
          "message": { "type": "string", "maxLength": 6000 },
          "category": { "type": "string", "maxLength": 80 },
          "timestamp": { "type": "string", "format": "date-time" },
          "appVersion": { "type": "string", "maxLength": 80 },
          "platform": { "type": "string", "maxLength": 80 },
          "userId": { "type": "string", "maxLength": 160 },
          "context": { "type": "object", "additionalProperties": true }
        }
      },
      "EventRequest": {
        "type": "object",
        "required": ["event"],
        "additionalProperties": true,
        "properties": {
          "id": { "type": "string" },
          "event": { "type": "string", "maxLength": 160 },
          "name": { "type": "string", "maxLength": 160 },
          "anonymousId": { "type": "string", "maxLength": 120 },
          "userId": { "type": "string", "maxLength": 160 },
          "timestamp": { "type": "string", "format": "date-time" },
          "appVersion": { "type": "string", "maxLength": 80 },
          "platform": { "type": "string", "maxLength": 80 },
          "props": { "type": "object", "additionalProperties": true }
        }
      },
      "BrickRequest": {
        "type": "object",
        "required": ["brick", "reason", "surface", "confidence"],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string" },
          "userId": { "type": "string" },
          "brick": {
            "type": "string",
            "enum": ["browser", "file_editor", "terminal", "database", "github", "figma", "web_search", "auth", "analytics", "deployment", "unknown"]
          },
          "reason": {
            "type": "string",
            "enum": ["needs_external_page_interaction", "needs_project_file_access", "needs_shell_execution", "needs_remote_repo_context", "needs_design_asset_access", "needs_live_web_lookup", "needs_user_identity", "needs_product_event_tracking", "needs_hosting_or_release", "other"]
          },
          "surface": {
            "type": "string",
            "enum": ["main", "modify"]
          },
          "confidence": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          },
          "engineId": {
            "type": "string",
            "enum": ["claude-code", "codex"]
          }
        }
      },
      "AcceptedResponse": {
        "type": "object",
        "required": ["ok", "id"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "id": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      },
      "McpManifest": {
        "type": "object",
        "required": ["name", "description", "transport", "capabilities"],
        "properties": {
          "name": { "type": "string" },
          "display_name": { "type": "string" },
          "description": { "type": "string" },
          "protocol_version": { "type": "string" },
          "transport": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "example": "streamable-http" },
              "url": { "type": "string", "format": "uri" }
            }
          },
          "capabilities": { "type": "object", "additionalProperties": true },
          "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] },
          "method": { "type": "string", "examples": ["initialize", "tools/list", "tools/call"] },
          "params": { "type": "object", "additionalProperties": true }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] },
          "result": { "type": "object", "additionalProperties": true },
          "error": { "type": "object", "additionalProperties": true }
        }
      }
    }
  }
}