{
  "openapi": "3.1.0",
  "info": {
    "title": "openin.app",
    "version": "1.0.0",
    "summary": "Make a link that opens in the app, not the browser.",
    "description": "Turn a YouTube, Spotify, Instagram, TikTok, LinkedIn, X or website link into an openin.app link. When the openin.app link is tapped inside Instagram, Facebook, WhatsApp or TikTok it opens the real app (logged in); elsewhere it opens the normal web page. Free, no account or key needed. The same destination always returns the same link.",
    "contact": { "url": "https://www.openin.app" }
  },
  "servers": [{ "url": "https://www.openin.app" }],
  "paths": {
    "/api/open": {
      "get": {
        "operationId": "createOpenInLink",
        "summary": "Create (or fetch) the app-opening link for a destination URL",
        "description": "Pass the destination as the `url` query parameter. Returns the openin.app link to share. Idempotent: calling it again with the same destination returns the same link.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The destination: a YouTube video/channel/playlist, Spotify track/album/playlist/artist, Instagram profile/post/reel, TikTok video/profile, LinkedIn post/profile, X post/profile, or any https website.",
            "schema": { "type": "string", "format": "uri", "maxLength": 2048 },
            "example": "https://youtu.be/dQw4w9WgXcQ"
          }
        ],
        "responses": {
          "200": { "description": "An existing link for this destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } },
          "201": { "description": "A new link was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } },
          "400": { "description": "Missing or unsupported URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Too many links from one network; try again in a few minutes." }
        }
      },
      "post": {
        "operationId": "createOpenInLinkPost",
        "summary": "Same as GET, with the destination in a JSON body",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } } } }
        },
        "responses": {
          "200": { "description": "An existing link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } },
          "201": { "description": "A new link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } },
          "400": { "description": "Missing or unsupported URL." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Link": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "The link to share, e.g. https://openin.app/go/abc123" },
          "display": { "type": "string", "description": "The link without the scheme, for showing to a person, e.g. openin.app/go/abc123" },
          "slug": { "type": "string" },
          "platform": { "type": "string", "enum": ["youtube", "spotify", "instagram", "tiktok", "linkedin", "twitter", "web"] },
          "destination": { "type": "string", "description": "The original URL the link opens." },
          "created": { "type": "boolean", "description": "true when this call created the link, false when it already existed." },
          "note": { "type": "string", "description": "A one-sentence explanation suitable for showing to the person." }
        },
        "required": ["url", "display", "slug", "platform", "destination", "created"]
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] }
    }
  }
}