Developer reference
API quickstart
Create a scoped token and make your first authenticated JSON request.
Current product guide · Reviewed October 28, 2026
Create a narrowly scoped token
- Open Domains & integrations and confirm your password if requested.
- Create a named token for Personal or one eligible workspace. Choose only links:read, links:write and/or conversions:write as needed.
- Choose an expiry between 1 and 90 days. Copy the secret when shown and store it in your backend’s secret storage. It is not shown again.
- Revoke a token when no longer needed. The current account limit is 10 token records; revoke unused records rather than assuming expired records disappear automatically.
A token is not a separate user. The owning account must remain verified and unsuspended, and workspace membership is checked on requests. Use HTTPS and an Authorization: Bearer header. Do not put tokens in query strings, source control, client-side bundles or support messages.
List your links
Bash example
curl https://li2.li/api/links \
-H "Authorization: Bearer $LI2LI_TOKEN" \
-H "Accept: application/json"
Python example
# Save as li2li_api.py. Python 3 standard library only.
import json
import os
import urllib.request
import urllib.error
BASE = "https://li2.li"
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def request(method, path, payload=None):
if not path.startswith("/api/") or "\\" in path:
raise ValueError("Use a relative /api/ path")
token = os.environ["LI2LI_TOKEN"]
body = None if payload is None else json.dumps(payload).encode("utf-8")
req = urllib.request.Request(BASE + path, data=body, method=method,
headers={"Authorization": "Bearer " + token,
"Accept": "application/json", "Content-Type": "application/json"})
try:
with urllib.request.build_opener(NoRedirect()).open(req, timeout=15) as response:
return response.status, json.loads(response.read())
except urllib.error.HTTPError as error:
# Return the status for explicit handling; never log tokens or response bodies.
return error.code, None
if __name__ == "__main__":
status, result = request("GET", "/api/links")
print("HTTP", status)
if status == 200:
print("Links on this page:", len(result["data"]))
print("Next page:", result["next_page"])
Java example
// Save as Li2liApi.java. Java 17 standard library only.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
public class Li2liApi {
static final String BASE = "https://li2.li";
static final HttpClient CLIENT = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(5))
.followRedirects(HttpClient.Redirect.NEVER).build();
public static HttpResponse<String> request(String method, String path, String json)
throws Exception {
if (!path.startsWith("/api/") || path.contains("\\"))
throw new IllegalArgumentException("Use a relative /api/ path");
String token = System.getenv("LI2LI_TOKEN");
if (token == null || token.isBlank()) throw new IllegalStateException("Set LI2LI_TOKEN");
var body = json == null ? HttpRequest.BodyPublishers.noBody()
: HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8);
var req = HttpRequest.newBuilder(URI.create(BASE + path))
.timeout(Duration.ofSeconds(15))
.header("Authorization", "Bearer " + token)
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.method(method, body).build();
return CLIENT.send(req, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
}
public static void main(String[] args) throws Exception {
var response = request("GET", "/api/links", null);
System.out.println("HTTP " + response.statusCode());
// response.body() is raw JSON. Parse with your application's JSON library.
// Do not log bodies: they can contain private destinations.
}
}
json · example
{"data":[{"id":42,"slug":"Guide2026","title":"Guide","destination":"https://example.com/guide","is_active":true,"visits":0,"workspace_id":null,"created_at":"2026-10-27T12:00:00.000000Z"}],"next_page":null}Examples use illustrative IDs and data. The list returns up to 50 links with next_page for continuation. Follow that URL only against the expected Li2.li origin and keep your Authorization header private. No total-count or filter/sort API is documented.
Python and Java: these small standard-library helpers are examples, not official SDKs. Tested with Python 3.12.5 and OpenJDK 17.0.8. Set LI2LI_TOKEN in your process environment using your normal secret manager; never commit it. Save the Python helper as li2li_api.py and run python3 li2li_api.py; save the Java helper as Li2liApi.java and run javac Li2liApi.java && java Li2liApi. Both refuse redirects, use timeouts and make one request without automatic retries.
Scope cannot be overridden in a request
The token determines personal/workspace scope. Do not send workspace_id to switch access. GET and write authorization applies to each numeric link ID; a link outside the scope is not made accessible by knowing its slug. A links:write token does not implicitly include links:read.
Retry carefully
GET is suitable for a bounded retry after a transient failure. POST /api/links has no idempotency-key contract: after a timeout, inspect the list before repeating it or you may create a second link. Honor Retry-After when supplied on 429 responses. Keep bounded backoff and do not loop indefinitely on 401, 403 or 422.
Still need a hand?
Use Help & support in your dashboard or support@li2.li. Share the action and a sanitized error, never a password, token or private reset link.