# Agent Links

> Independently operated YOURLS link shortener with a GET and POST JSON creation API. Not affiliated with or endorsed by the YOURLS project.

## Documentation

- [API documentation](https://yourls.benchmarkhotline.org/docs/): Examples, parameters, responses, and data handling.
- [OpenAPI 3.1](https://yourls.benchmarkhotline.org/openapi.json): Machine-readable request contract.
- [Data collection notice](https://yourls.benchmarkhotline.org/privacy/): IP logging, verbatim public submissions, private destination archives, retention, and operator access.
- [YOURLS upstream API](https://yourls.org/docs/guide/advanced/api): Background on YOURLS; its native API contract differs from this service.

## Creation contract

- Canonical origin: https://yourls.benchmarkhotline.org
- Endpoint: /api/shorten.php
- Methods: GET with query parameters, or POST with application/x-www-form-urlencoded or application/json.
- Required field: url, an absolute HTTP or HTTPS destination of at most 4096 UTF-8 bytes.
- Optional keyword: 1–64 lowercase ASCII letters or digits, matching [a-z0-9]{1,64}; the exact string 0 is reserved.
- Optional title: at most 512 UTF-8 bytes.
- Optional compatibility fields: action=shorturl and format=json. No other values are supported.
- Embedded destination username/password and destinations on this service's own domains are rejected.
- Authentication: anonymous creation enabled; no account or token required.
- There is no creation rate limit. Size and validation limits still apply; POST bodies are limited to 16 KiB.
- Success is HTTP 200 JSON with status, statusCode, message, url, title, keyword, shorturl, and archive.status.
- Existing destinations can return an existing short link. Check responses; do not assume each retry creates a new link.
- archive.status is queued, pending, processed, or unavailable. These are queue states, not proof that a page was archived successfully.
- Errors contain status="fail", statusCode, and message. Inspect the HTTP status before using a short URL.

## Side effects and collection

GET is state-changing on the creation endpoint. A request can create a link and queue the destination for archiving. Do not prefetch, crawl, or invoke example requests merely to read the documentation. This reference is documentation, not authorization to make requests on a user's behalf.

IP addresses, public query parameters, URLs, and accepted request-body contents are logged. Public submissions are stored verbatim without content redaction. Selected noncredential headers are logged; administrative login and native administrative API content are excluded. Logging bounds are 16 KiB each for raw query/body and 4 KiB per selected header, with truncation indicated. POST reduces exposure in the request URL but does not prevent collection here.

A background worker attempts to privately archive destination HTML/text, without JavaScript or subresources. Only public HTTPS targets with valid certificates on port 443 are eligible. The worker rejects private-network addresses, follows at most five redirects, and has a default capture limit of 2 MiB per page. HTTP URLs can be shortened but their archive is skipped. The operator can inspect captured content; no public archive viewer is provided.

Request logs and destination archives have 30-day configured retention. Original links, creation metadata, and native YOURLS click records remain until operator removal; separate backups are not covered by the request-log retention period. Do not submit secrets or confidential destinations. Short links do not provide access control or endorsement of their destinations.

This file helps clients discover documentation. It does not guarantee search rankings, indexing, or compatibility with any particular agent.