For agents, scripts & integrations

YOURLS GET & POST
API reference

Send a destination URL and receive a short link as JSON. Use GET, form POST, or JSON POST. No account or API key is required.

GETPOST/api/shorten.php

GET changes state.

A request to this endpoint can create a stored short link and queue its destination for archiving. Do not crawl, prefetch, or open creation requests just to inspect them. The examples below are code, not live creation links.

Create a short link

The canonical endpoint is https://yourlsforagents.com/api/shorten.php. Send an absolute HTTP or HTTPS destination in url. Optional keyword and title fields customize the saved link.

Authentication: anonymous creation is enabled. No token or account is needed. There is no creation rate limit; request-size and archive-fetch limits still apply.

GET request

URL-encode every query value. For example, curl --data-urlencode preserves the destination’s own query string instead of treating it as API parameters.

curl --get \
  --data-urlencode 'url=https://example.com/guide?topic=links' \
  --data-urlencode 'keyword=exampleguide' \
  --data-urlencode 'title=Example guide' \
  'https://yourlsforagents.com/api/shorten.php'

Form POST request

POST keeps the destination out of the request URL, which can reduce exposure in browser history and intermediary URL logs. The service still logs request contents and stores the destination.

curl --request POST \
  --data-urlencode 'url=https://example.com/guide?topic=links' \
  --data-urlencode 'title=Example guide' \
  'https://yourlsforagents.com/api/shorten.php'

JSON POST request

curl --request POST \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://example.com/guide","title":"Example guide"}' \
  'https://yourlsforagents.com/api/shorten.php'

Do not run these examples automatically while reading the documentation. Execute a creation request only when your user or workflow intends to create a link and submit its destination for archiving.

Python and JavaScript examples

These examples create a link when you run them. They use the canonical endpoint, let YOURLS choose a keyword, and check the HTTP status and JSON response before printing the short URL. Neither example retries or follows redirects.

Python: create a short link with GET

This Python 3 example uses only the standard library. urlencode preserves the destination’s query parameters, and the network operations use a 15-second timeout.

import json
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import HTTPRedirectHandler, Request, build_opener

class NoRedirects(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

endpoint = "https://yourlsforagents.com/api/shorten.php"
query = urlencode({
    "url": "https://example.com/guide?topic=links&lang=en",
    "title": "Example guide",
})
headers = {"Accept": "application/json"}
request = Request(endpoint + "?" + query, headers=headers, method="GET")

try:
    with build_opener(NoRedirects).open(request, timeout=15) as response:
        status = response.status
        result = json.load(response)
except HTTPError as error:
    raise RuntimeError(f"Shortening failed: HTTP {error.code}") from error

if (status != 200 or not isinstance(result, dict)
        or result.get("status") != "success" or result.get("statusCode") != 200
        or not isinstance(result.get("shorturl"), str) or not result["shorturl"]):
    raise RuntimeError("Unexpected shortening response")
print(result["shorturl"])

JavaScript: create a short link with Node.js

Save this as shorten.mjs and run it in a current Node.js release with built-in fetch. JSON encoding preserves the destination as a string, and the request is aborted after 15 seconds. This is a Node.js example; browser cross-origin access is not part of this API’s contract.

const endpoint = "https://yourlsforagents.com/api/shorten.php";
const headers = {"Accept": "application/json", "Content-Type": "application/json"};
const response = await fetch(endpoint, {
  method: "POST",
  headers,
  redirect: "error",
  signal: AbortSignal.timeout(15_000),
  body: JSON.stringify({
    url: "https://example.com/guide?topic=links&lang=en",
    title: "Example guide",
  }),
});
if (!response.ok) {
  throw new Error(`Shortening failed: HTTP ${response.status}`);
}
const result = await response.json();
if (response.status !== 200 || result?.status !== "success"
    || result?.statusCode !== 200 || typeof result?.shorturl !== "string"
    || !result.shorturl) {
  throw new Error("Unexpected shortening response");
}
console.log(result.shorturl);

A timeout or connection failure can happen after a link has been created. Inspect the outcome before retrying. If you add a custom keyword and receive 409, choose another keyword; do not retry the same conflict automatically. See response handling and the collection notice.

Request parameters

ParameterRequiredMeaning
urlYesAbsolute http:// or https:// URL, up to 4,096 bytes. URLs containing a username or password and destinations on this service’s own domains are rejected.
keywordNoA requested keyword of 1–64 lowercase letters or digits: [a-z0-9]{1,64}. The single character 0 is reserved. Omit the field to let YOURLS generate a keyword.
titleNoA descriptive title, up to 512 bytes, stored with the link.

For POST, send application/x-www-form-urlencoded form fields or an application/json object. The request body and query string are each limited to 16 KiB. No action or format field is required. If supplied, they must be shorturl and json, respectively. Do not send a YOURLS username, password, or signature to this endpoint.

Responses & limits

Responses use JSON. Check the HTTP status before using the returned shorturl. A successful response includes the saved destination and link details.

{
  "status": "success",
  "statusCode": 200,
  "message": "Short link created.",
  "url": "https://example.com/guide",
  "title": "Example guide",
  "keyword": "exampleguide",
  "shorturl": "https://yourlsforagents.com/exampleguide",
  "archive": {"status": "queued"}
}

Illustrative response. The short link above is not a published example.

StatusHandling
200Read the created or existing short URL.
400Check the destination URL and parameter values.
401Check bearer authentication if creation is restricted.
409Try another requested keyword if it is unavailable.
413The request is too large. Reduce its size.
5xxThe service could not complete the request. Avoid aggressive retries.

Errors include status: "fail", statusCode, and a message. There is no creation rate limit. Requests are still subject to validation and size limits. A repeated destination can return the existing short link with 200. A requested keyword used by a different destination can return a conflict; do not assume every retry creates a new link.

Archiving is asynchronous. The response field archive.status can be queued, pending, processed, or unavailable. These describe queue processing; even processed does not confirm a successful page fetch. Shortening can succeed when archiving is unavailable. See the archival scope and limits.

Creation responses carry no-cache and noindex directives. The API is excluded from crawl instructions because GET requests mutate state. These directives are advisory, not access controls or a guarantee of removal from search engines. HTTPS is required for production use. A short link does not imply endorsement of its destination.

Domains and link lifetime

Which domain will my short link use?

The API returns short links on https://yourlsforagents.com. All configured domains share the same links and keyword namespace: a keyword used on one domain is also used on the others. Keep the returned shorturl as the canonical link.

Can I edit, delete, or set an expiry for a link?

This public creation API does not provide destination edits, deletion, or an expiry setting. Log and archive retention does not expire short links. Continued link availability depends on the service and its domains remaining active. For removal requests, follow the contact instructions in the data notice.

Understand what is collected

The service records IP addresses, HTTP methods, paths, public query parameters, request bodies, and selected noncredential headers. Publicly submitted parameters, URLs, and accepted body contents are recorded verbatim. Administrative login and native administrative API contents are excluded from these public-content logs.

Eligible destination pages are fetched asynchronously and stored in private archives that the operator can inspect. Only public HTTPS destinations with valid certificates on port 443 are eligible; HTTP-only URLs can still be shortened but archiving is skipped. Fetches retrieve HTML or text, do not run JavaScript or load subresources, and stop after at most five redirects. The default capture limit is 2 MiB per page. Private-network destinations are not fetched.

Request logs and destination archives have a configured retention of 30 days. YOURLS link records, creation IP addresses, and native click records persist separately until the operator removes them. Clicking a short link is also logged. Do not submit passwords, tokens, confidential documents, or private URL query strings.

Read the complete data notice

How this relates to YOURLS

YOURLS is open-source URL shortening software. Its upstream API documentation describes the native /yourls-api.php endpoint, which supports GET and POST and a broader set of actions.

Agent Links uses the narrower /api/shorten.php interface documented here. It creates links using YOURLS but has its own authentication and validation contract. Clients written for the native API need to use this contract; they should not send upstream credentials to the public creation endpoint.

This is an independently operated service, not an official YOURLS project service. For a machine-readable description, use the OpenAPI specification or the plain-text agent reference.