One URL in.
One short link out.

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.

Request parameters

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.

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.

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.

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.