> 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/quickstart.md).

# Quick start: you already have a URL

## Who this is for

Providers who already have a subscription URL: the link returns raw `vless://...`, a base64 subscription, JSON `links`/`nodes`, Xray JSON, or sing-box JSON.

## What you can do

* Check that your existing link is compatible with Tumbler.
* Build an add link or QR code for the user.
* Understand when you need `crypt3`, metadata, and advanced features.

## Examples

* Raw subscription URL: `https://provider.example.com/sub/u_123`.
* Add link for Tumbler: `tumbler://add?link=https%3A%2F%2Fprovider.example.com%2Fsub%2Fu_123`.
* If the URL must stay hidden: `tumbler://add?link=<url-encoded schema://crypt3/...>`.

## See also

* [getting-started/add-link.md](/getting-started/add-link.md)
* [subscription/response-formats.md](/subscription-contract/response-formats.md)
* [subscription/metadata.md](/subscription-contract/metadata.md)
* [security/url-protection-and-crypt3.md](/getting-started/url-protection-and-crypt3.md)
* [troubleshooting/common-issues.md](/getting-started/common-issues.md)

## 15-minute flow

### 1. Check the existing subscription URL

If you already have a link, start with it:

```bash
curl -i 'https://provider.example.com/sub/u_123'
```

A minimal compatible response is `200 OK` with `text/plain; charset=utf-8` and VLESS lines:

```
vless://11111111-1111-1111-1111-111111111111@edge.example.com:443?security=reality&pbk=pk1&sid=s1&sni=edge.example.com#Edge-1
vless://22222222-2222-2222-2222-222222222222@backup.example.com:443?type=grpc#Backup
```

Base64 subscriptions, JSON `links`/`nodes`, Xray JSON, and sing-box JSON are also supported. See [response-formats.md](/subscription-contract/response-formats.md) for details.

### 2. Build a link that opens Tumbler

URL-encode the original subscription URL and put it into the `link` query parameter:

```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
```

You can place this URL in a button, email, account dashboard, or QR code.

### 3. What happens when the link opens

1. iOS opens Tumbler through the `tumbler://` scheme.
2. Tumbler extracts `link` and sends it to `POST /v1/subscriptions/add`.
3. The backend fetches your subscription URL through the fetcher.
4. The backend normalizes configs, applies metadata, and returns an encrypted runtime payload to the app.
5. The client shows the subscription and then syncs it through the backend.

The user app must not directly call the provider URL in the `crypt3` scenario.

### 4. Add metadata after the basic import works

Metadata is not required for the first launch. After validation, add:

* `profile-title` - profile name in the app.
* `support-url` and `manage-url` - Support and account management buttons.
* `subscription-userinfo` - traffic usage and expiry.
* `mirrors`, `new-url`, `new-domain` - migration and fallback.
* `balancer-method` - dynamic node ordering.

## When to use crypt3

Use `crypt3` if the raw HTTPS subscription URL must not be shown to the user, stored on the device, or shared directly.

In this case the provider or partner generates a source link:

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

The user receives this add link:

```
tumbler://add?link=<url-encoded schema://crypt3/<token>>
```

Read more in [URL protection and crypt3](/getting-started/url-protection-and-crypt3.md).

## What not to do at the start

* Do not rewrite your endpoint into a new format if it already returns supported VLESS/Xray/sing-box data.
* Do not add all metadata at once. Validate import and sync first.
* Do not use `tumbler://add/<url>`: the current contract is `tumbler://add?link=...`.
* Do not write `cryp3`: the correct mechanism name is `crypt3`.

## Minimal readiness checklist

* The subscription URL can be opened by the backend fetcher over HTTP/HTTPS on standard ports 80/443.
* The response is UTF-8, with no HTML page instead of configs and no junk at the beginning.
* The response contains at least one valid VLESS node or a JSON/Xray/sing-box object from which a VLESS outbound can be extracted.
* The add link uses `tumbler://add?link=<url-encoded source>`.
* If the link is sensitive, the raw URL is replaced with `crypt3`.


---

# 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/quickstart.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.