{
  "openapi": "3.1.0",
  "info": {
    "title": "Try That UI public API",
    "version": "2026-11-09",
    "summary": "Anonymous endpoints behind trythatui.com: the free 3-version try, share links and votes, and the read-only MCP server.",
    "description": "Every endpoint here works without an account. Anything that writes to a repository or opens a pull request is not in this API: that is an owner action inside the signed-in app. Errors always carry a plain `error` message you can show a person.",
    "contact": {
      "name": "Mike Yerke",
      "url": "https://mikeyerke.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://trythatui.com/terms.html"
    }
  },
  "servers": [
    {
      "url": "https://app.trythatui.com"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Developers page",
    "url": "https://app.trythatui.com/developers"
  },
  "tags": [
    {
      "name": "Guest try",
      "description": "The free 3-version try on trythatui.com/try."
    },
    {
      "name": "Shares",
      "description": "30-day share links and no-signup votes."
    },
    {
      "name": "MCP",
      "description": "The read-only MCP server for coding agents."
    }
  ],
  "paths": {
    "/api/guest/versions": {
      "post": {
        "tags": [
          "Guest try"
        ],
        "operationId": "createGuestVersions",
        "summary": "Get a public page as Current plus 3 proposed versions",
        "description": "No human check by default. If the operator turns the check on, the call answers 403 with code `turnstile` and then needs a Cloudflare Turnstile token minted on trythatui.com (action `guest-try`); scripts and agents are better served by the MCP server. The page is fetched server-side over https on port 443 only, pinned to a public IPv4 address, with every redirect re-checked; scripts are stripped. 3 successful tries a day per visitor (signed cookie); failures and JavaScript-only pages are free. Per-IP limits apply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 500,
                    "examples": [
                      "example.com/pricing"
                    ]
                  },
                  "html": {
                    "type": "string",
                    "maxLength": 400000,
                    "description": "Pasted HTML instead of a fetch. Never fetched against."
                  },
                  "turnstileToken": {
                    "type": "string",
                    "description": "Only needed when the operator has turned the human check on."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Versions, or a JavaScript-only page (`ok: false, code: blank`) with a paste-HTML fallback.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "ok",
                        "document",
                        "slot",
                        "versions",
                        "remaining"
                      ],
                      "properties": {
                        "ok": {
                          "const": true
                        },
                        "url": {
                          "type": "string"
                        },
                        "remaining": {
                          "type": "integer"
                        },
                        "ticket": {
                          "type": "string",
                          "description": "Lets this visitor create a share link for 1 hour."
                        },
                        "document": {
                          "type": "string",
                          "description": "Sanitised HTML. Render only in a sandbox=\"\" frame."
                        },
                        "slot": {
                          "type": "string"
                        },
                        "versions": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Version"
                          }
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/guest/shares": {
      "post": {
        "tags": [
          "Shares"
        ],
        "operationId": "createShare",
        "summary": "Make a 30-day share link for a try",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "ticket"
                ],
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "ticket": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "id": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9]{10}$"
                    },
                    "path": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresInDays": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/guest/shares/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ShareId"
        }
      ],
      "get": {
        "tags": [
          "Shares"
        ],
        "operationId": "viewShare",
        "summary": "Read a share: the page as it is now, plus the same 3 versions",
        "description": "CDN-cached for 15 minutes. Page bytes are never stored; the page is fetched again with the same guards.",
        "responses": {
          "200": {
            "description": "Share",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "document": {
                      "type": "string"
                    },
                    "slot": {
                      "type": "string"
                    },
                    "versions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Version"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/guest/shares/{id}/votes": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ShareId"
        }
      ],
      "get": {
        "tags": [
          "Shares"
        ],
        "operationId": "readVotes",
        "summary": "Vote counts",
        "responses": {
          "200": {
            "description": "Counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "counts": {
                      "$ref": "#/components/schemas/Counts"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": [
          "Shares"
        ],
        "operationId": "castVote",
        "summary": "Vote, no account needed",
        "description": "One vote per visitor (signed cookie); voting again moves it. Capped per network per share per day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "choice"
                ],
                "properties": {
                  "choice": {
                    "type": "string",
                    "enum": [
                      "current",
                      "bolder-action",
                      "clearer-hierarchy",
                      "calmer-reading"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Counted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "choice": {
                      "type": "string"
                    },
                    "counts": {
                      "$ref": "#/components/schemas/Counts"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "operationId": "mcp",
        "summary": "Read-only MCP server (JSON-RPC 2.0 over HTTPS)",
        "description": "Tools: check_service, describe_connection, validate_public_url, build_coding_prompt. No key. 60 calls a minute per IP. It never opens pull requests.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "integer",
                      "string"
                    ]
                  },
                  "method": {
                    "type": "string",
                    "examples": [
                      "initialize",
                      "tools/list",
                      "tools/call"
                    ]
                  },
                  "params": {
                    "type": "object"
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                  "name": "check_service",
                  "arguments": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result or error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/waitlist/config": {
      "get": {
        "tags": [
          "Guest try"
        ],
        "operationId": "turnstileConfig",
        "summary": "Public Turnstile site key for trythatui.com forms",
        "responses": {
          "200": {
            "description": "Config",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "available": {
                      "type": "boolean"
                    },
                    "siteKey": {
                      "type": "string"
                    },
                    "action": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ShareId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9]{10}$"
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "code": {
            "type": "string"
          },
          "error": {
            "type": "string",
            "description": "Plain-language message safe to show a person."
          },
          "remaining": {
            "type": "integer"
          },
          "fallback": {
            "type": "string",
            "enum": [
              "paste-html"
            ]
          },
          "retryAfterSeconds": {
            "type": "integer"
          }
        }
      },
      "Version": {
        "type": "object",
        "required": [
          "id",
          "label",
          "changes",
          "css",
          "prompt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "bolder-action",
              "clearer-hierarchy",
              "calmer-reading"
            ]
          },
          "label": {
            "type": "string"
          },
          "changes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "css": {
            "type": "string",
            "description": "CSS to place in the document's treatment slot."
          },
          "prompt": {
            "type": "string",
            "description": "A prompt a coding agent can follow to make this version real."
          }
        }
      },
      "Counts": {
        "type": "object",
        "properties": {
          "current": {
            "type": "integer"
          },
          "bolder-action": {
            "type": "integer"
          },
          "clearer-hierarchy": {
            "type": "integer"
          },
          "calmer-reading": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error with a plain-language message",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
