Skip to documentation
Link 2 Link / Docs
Documentation home
Browse documentation

Developer reference

Links API reference

The implemented endpoints, accepted fields, response shapes and error behavior.

Current product guide · Reviewed October 28, 2026

Endpoints and abilities

Method & pathAbilityResult
GET /api/linkslinks:read200; data array and next_page.
GET /api/links/{id}links:read200; data object.
POST /api/linkslinks:write201; data object.
PATCH /api/links/{id}links:write200; data object.
DELETE /api/links/{id}links:write200; {"deleted":true}.
POST /api/conversionsconversions:write200; link_id and recorded; see A/B tests & conversions.

Create a link

Bash example

curl -X POST https://li2.li/api/links \
  -H "Authorization: Bearer $LI2LI_TOKEN" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  --data '{"destination":"https://example.com/guide","title":"Campaign guide"}'

Python example

from li2li_api import request
status, result = request("POST", "/api/links", {
    "destination": "https://example.com/guide", "title": "Campaign guide"})
if status != 201:
    raise RuntimeError(f"Create failed: HTTP {status}")
link_id = result["data"]["id"]  # Use this ID in later examples.

Java example

// Inside your method, after compiling Li2liApi.java:
var response = Li2liApi.request("POST", "/api/links",
    "{\"destination\":\"https://example.com/guide\",\"title\":\"Campaign guide\"}");
if (response.statusCode() != 201) throw new IllegalStateException("Create failed");
// Read data.id with your JSON library. Do not assume the example ID 42 exists.

POST accepts destination (required, public HTTP/HTTPS URL, at most 2,048 characters) and title (optional, nullable, at most 120 characters). The server generates the slug and returns short_url as the canonical sharing address. Existing clients can continue using /s/ plus the exact slug. Dashboard options such as custom alias, tags, expiry, passwords and domain selection are not part of this API create contract. Do not assume an extra JSON property was applied.

Update or pause

Bash example

curl -X PATCH https://li2.li/api/links/42 \
  -H "Authorization: Bearer $LI2LI_TOKEN" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  --data '{"is_active":false}'

Python example

from li2li_api import request
link_id = 42  # Replace with the ID returned by your create request.
status, result = request("PATCH", f"/api/links/{link_id}", {"is_active": False})
if status != 200:
    raise RuntimeError(f"Pause failed: HTTP {status}")

Java example

long linkId = 42; // Replace with your returned data.id.
var response = Li2liApi.request("PATCH", "/api/links/" + linkId, "{\"is_active\":false}");
if (response.statusCode() != 200) throw new IllegalStateException("Pause failed");

PATCH accepts any combination of destination, title and is_active. A supplied destination is required/nonempty and validated; title can be null. It does not rename the slug. DELETE is permanent and preserves the alias reservation. There is no API restore endpoint.

Read a link and delete deliberately

GET returns one accessible link. DELETE is permanent: it removes the link and reserves its alias. Replace 42 with your own returned ID and run deletion only when you intend to remove that link. These snippets are separate actions, not an automatic onboarding script.

Bash example

curl https://li2.li/api/links/42 -H "Authorization: Bearer $LI2LI_TOKEN" -H "Accept: application/json"
# Only when intentionally deleting:
curl -X DELETE https://li2.li/api/links/42 -H "Authorization: Bearer $LI2LI_TOKEN" -H "Accept: application/json"

Python example

from li2li_api import request
status, result = request("GET", "/api/links/42")
# Separate, intentional deletion:
status, result = request("DELETE", "/api/links/42")
if status != 200:
    raise RuntimeError(f"Delete failed: HTTP {status}")

Java example

var read = Li2liApi.request("GET", "/api/links/42", null);
// Separate, intentional deletion:
var deleted = Li2liApi.request("DELETE", "/api/links/42", null);
if (deleted.statusCode() != 200) throw new IllegalStateException("Delete failed");

Errors and throttling

StatusMeaning / response
401Missing, malformed, unknown or expired token. Check the bearer token rather than repeatedly retrying.
403Missing ability, ineligible account or insufficient workspace permission.
404Unknown or inaccessible link. Do not infer that another account’s link exists.
422Validation or capacity failure. JSON validation responses include message and errors where applicable; other failures may have only message.
429Rate limited. Back off; honor Retry-After when provided.
5xxServer failure. Use bounded retries appropriate to the operation; creation may have an uncertain result.

Read routes share a 60-per-minute throttle; write routes share a 30-per-minute throttle. POST creation also uses the per-account 10-per-minute and 50-per-hour limits. These are not separate allowances per token; do not multiply tokens to evade limits. Conversion submission has its own 60-per-minute route throttle.

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.