> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/getting-started/add-link.md).

# Add link or QR code

## Who this is for

Providers who want to give a user a button, QR code, or link that connects an existing subscription.

## What you can do

* Build a valid `tumbler://add?link=...`.
* Understand the difference between a raw HTTPS subscription URL and `crypt3`.
* Avoid path-like deep link formats that do not work for import.

## Examples

* Raw source: `https://provider.example.com/sub/u_123`.
* Protected source: `schema://crypt3/<token>`.
* Add link: `tumbler://add?link=<url-encoded source>`.

## See also

* [quickstart.md](/getting-started/quickstart.md)
* [subscription/fetch-url.md](/getting-started/fetch-url.md)
* [security/url-protection-and-crypt3.md](/getting-started/url-protection-and-crypt3.md)

## Current public contract

Tumbler supports these entrypoints:

| Deep link                                 | Behavior                                                |
| ----------------------------------------- | ------------------------------------------------------- |
| `tumbler://add`                           | Open the subscription add screen.                       |
| `tumbler://add?link=<url-encoded source>` | Start importing the specified subscription immediately. |
| `tumbler://qradd`                         | Open QR-based add flow.                                 |
| `tumbler://cpadd`                         | Open add from clipboard.                                |
| `tumbler://manualadd`                     | Open manual add flow.                                   |

For provider onboarding, the main option is:

```
tumbler://add?link=<url-encoded source>
```

`source` is one of:

* a regular `https://...` subscription URL;
* `schema://crypt3/<token>` if the original URL is encrypted.

## Raw HTTPS subscription URL

If the link may be exposed to the user:

```
https://provider.example.com/sub/u_123
```

Encode it as the query parameter value:

```bash
python3 - <<'PY'
from urllib.parse import quote

source = "https://provider.example.com/sub/u_123"
print("tumbler://add?link=" + quote(source, safe=""))
PY
```

Result:

```
tumbler://add?link=https%3A%2F%2Fprovider.example.com%2Fsub%2Fu_123
```

## crypt3 source link

If the original URL must stay hidden:

1. Fetch the backend public `crypt3` key from `/.well-known/crypt3`.
2. Encrypt the original subscription URL for the active key.
3. Build the source link:

```
schema://crypt3/<token>
```

4. URL-encode the whole source link and put it into `tumbler://add?link=...`.

Example final form:

```
tumbler://add?link=schema%3A%2F%2Fcrypt3%2FeyJraWQiOiJrMSJ9...
```

The word `schema` in the example means an external wrapper scheme for the `crypt3` source link. The important part is that the string contains `://crypt3/`, because the backend recognizes a crypt3 source by this marker.

## Why URL encoding is required

The source URL often contains `?`, `&`, `#`, `=`, and `/`. Without encoding, iOS or an intermediate website may truncate the link, change the query, or lose the fragment.

Encode the whole source, not only the query:

```
source:     https://provider.example.com/sub/u_123?format=vless#main
add link:   tumbler://add?link=https%3A%2F%2Fprovider.example.com%2Fsub%2Fu_123%3Fformat%3Dvless%23main
```

## What not to publish

* Do not use `tumbler://add/<source>` as a contract. The current app parser reads the source from the `link` query parameter.
* Do not use `cryp3`. The correct name is `crypt3`.
* Do not put an unprotected raw URL into a QR code if it must be one-time-use or hidden from the user. Use `crypt3` for that.

## Pre-publish QR check

1. Open the raw source with `curl -i` and verify that it returns configs.
2. Open the add link on a device with Tumbler installed.
3. Check that the app starts import immediately, not just an empty add screen.
4. If `crypt3` is used, verify that the backend decrypts the token successfully and does not return `invalid crypt3 token`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/getting-started/add-link.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.