{
  "openapi": "3.0.3",
  "info": {
    "title": "t.link API",
    "version": "1.0.0",
    "description": "Short links, deep links and click analytics for a Tapstack workspace. t.link is part of Tapstack. Authenticate with a t.link API key from https://app.t.link/developers. Agents can use the MCP server at https://api.t.link/mcp/tlink with the same key. See https://t.link/llms.txt."
  },
  "servers": [
    {
      "url": "https://api.t.link/v1/tlink"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "Workspace, limits and usage",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/links": {
      "get": {
        "summary": "List links",
        "operationId": "listLinks",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Matches the code, destination and title."
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A domain id, or `shared` for t.link."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "recent",
                "clicks"
              ],
              "default": "recent"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Link"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a link",
        "operationId": "createLink",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Destination. https:// is added when missing."
                  },
                  "slug": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
                    "description": "Custom code. At least 3 characters on t.link. Omit for a generated code."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "tags": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "type": "string"
                    }
                  },
                  "domain_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "A connected custom domain from GET /domains. Omit to use t.link."
                  },
                  "deep_link": {
                    "type": "boolean",
                    "default": true,
                    "description": "Open the destination in its native app on phones when one is known."
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "$ref": "#/components/schemas/Link"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "hash_taken: the code is in use",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "links_limit or rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/links/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get a link",
        "operationId": "getLink",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "$ref": "#/components/schemas/Link"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a link",
        "operationId": "updateLink",
        "description": "Only the fields sent change.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Destination. https:// is added when missing."
                  },
                  "slug": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
                    "description": "Custom code. At least 3 characters on t.link. Omit for a generated code."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "tags": {
                    "type": "array",
                    "maxItems": 10,
                    "items": {
                      "type": "string"
                    }
                  },
                  "deep_link": {
                    "type": "boolean",
                    "default": true,
                    "description": "Open the destination in its native app on phones when one is known."
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "is_active": {
                    "type": "boolean",
                    "description": "false pauses the link."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "$ref": "#/components/schemas/Link"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a link",
        "operationId": "deleteLink",
        "description": "The short URL stops working and the code becomes available again. Click history is kept.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/links/{id}/stats": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "name": "days",
          "in": "query",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "default": 30
          }
        }
      ],
      "get": {
        "summary": "Analytics for one link",
        "operationId": "getLinkStats",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "$ref": "#/components/schemas/Link"
                    },
                    "days": {
                      "type": "integer"
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "clicks": {
                      "type": "integer"
                    },
                    "visitors": {
                      "type": "integer",
                      "description": "Unique per day."
                    },
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "day": {
                            "type": "string",
                            "format": "date"
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "visitors": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "referrers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "devices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "browsers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "os": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      },
                      "description": "link or qr"
                    },
                    "apps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      },
                      "description": "Native apps the visitor was sent into."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/analytics": {
      "parameters": [
        {
          "name": "days",
          "in": "query",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365,
            "default": 30
          }
        }
      ],
      "get": {
        "summary": "Analytics for the workspace",
        "operationId": "getAnalytics",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "days": {
                      "type": "integer"
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "clicks": {
                      "type": "integer"
                    },
                    "visitors": {
                      "type": "integer",
                      "description": "Unique per day."
                    },
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "day": {
                            "type": "string",
                            "format": "date"
                          },
                          "clicks": {
                            "type": "integer"
                          },
                          "visitors": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "countries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "referrers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "devices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "browsers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "os": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      },
                      "description": "link or qr"
                    },
                    "apps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "clicks": {
                            "type": "integer"
                          }
                        }
                      },
                      "description": "Native apps the visitor was sent into."
                    },
                    "total_links": {
                      "type": "integer"
                    },
                    "top_links": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Link"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/domains": {
      "get": {
        "summary": "List custom domains",
        "operationId": "listDomains",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shared_domain": {
                      "type": "string"
                    },
                    "domains": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Domain"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/deep-link": {
      "get": {
        "summary": "Which native app a URL opens",
        "operationId": "previewDeepLink",
        "security": [],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "supported": {
                      "type": "boolean"
                    },
                    "app": {
                      "type": "string",
                      "nullable": true
                    },
                    "app_name": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/public/links": {
      "post": {
        "summary": "Shorten without an account",
        "operationId": "createPublicLink",
        "security": [],
        "description": "The link works immediately and expires after 24 hours unless the person signs in and claims it. Stricter destination rules apply, and a per-IP limit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "link": {
                      "type": "object",
                      "properties": {
                        "short_url": {
                          "type": "string"
                        },
                        "hash": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        },
                        "deep_link_app": {
                          "type": "string",
                          "nullable": true
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "claim_token": {
                      "type": "string",
                      "description": "Shown once."
                    },
                    "expires_in_seconds": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A t.link API key, `tlk_...`. Also accepted in the `x-api-key` header."
      }
    },
    "schemas": {
      "Link": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "short_url": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "hash": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "deep_link": {
            "type": "boolean"
          },
          "deep_link_app": {
            "type": "string",
            "nullable": true,
            "description": "youtube, instagram, tiktok, spotify, amazon, x, ..."
          },
          "deep_link_app_name": {
            "type": "string",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expired": {
            "type": "boolean"
          },
          "is_active": {
            "type": "boolean"
          },
          "clicks": {
            "type": "integer"
          },
          "last_clicked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "source": {
            "type": "string",
            "enum": [
              "app",
              "api",
              "mcp",
              "public"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "verified": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "source": {
            "type": "string",
            "enum": [
              "tlink",
              "tapni"
            ]
          },
          "dns": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "description": "Stable code, e.g. hash_taken, url_invalid, links_limit."
          },
          "message": {
            "type": "string",
            "description": "Text for people."
          }
        }
      }
    }
  }
}