Links
Paths are on the API origin. A link object has id, destination_url, alias, short_url, tags, status, archived, created_at, and updated_at. title is omitted when empty. reused is present when a create reused an existing link. short_url is on url-to.site.
| Method | Path | Scope | What it does |
|---|---|---|---|
| GET | /api/v1/easyshare/links | read | Page of links for this client. Archived links stay out unless archived=true. |
| POST | /api/v1/easyshare/links | write | Create a link. 201, or 200 when if_exists=return reuses one. |
| GET | /api/v1/easyshare/links/{alias} | read | One link. The alias is the code, matched without regard to case. |
| PATCH | /api/v1/easyshare/links/{alias} | write | Change destination, title, tags, status, or archived. The alias stays. |
| DELETE | /api/v1/easyshare/links/{alias} | write | 204. The code stays reserved and the public URL returns 410. |
| GET | /api/v1/easyshare/links/{alias}/history | read | Destination changes, oldest first, with the actor. |
| GET | /api/v1/easyshare/links/{alias}/stats | analytics | Click report for one link. JSON, or CSV when format=csv. |
| GET | /api/v1/easyshare/stats | analytics | Click report for the workspace. Optional tag filter. |
| POST | /api/v1/easyshare/links/bulk | write | Create up to 500 links. 200 with one result per row. |
Create
destination_url is required. It must be https, at most 2048 characters, with no user or password in the URL. Localhost, private addresses, and the short-link hosts are rejected. An empty alias gets a 6-letter code. A provided alias is stored in lowercase, 1–50 characters, using letters, digits, and hyphens. A hyphen cannot start or end it. feed and a code shaped like an AffiLink path (eight letters, optionally followed by s, d, or m) are reserved. A taken alias returns 409 conflict.
Optional title is at most 200 characters. Optional tags is up to 20 names, each at most 40 characters, stored in lowercase. Optional utm_source, utm_medium, utm_campaign, utm_content, and utm_term are merged into the destination and stored in lowercase. An empty UTM value is rejected.
if_exists is create by default. return reuses the oldest active, unarchived link with the same destination and responds 200 with reused. An alias on that request must match the reused link, or the response is 409. A new link is 201. See workflows for the request.
List
qmatches code, destination, or title.statusisactiveordisabled.tagis one tag name.archived=truelists archived links. Omit it to list the others.min_clicksandmax_clicksboundclick_count.sortiscreated_at(default),title,alias, orclicks.orderisdescunless you sendasc.
Deleted links are left out of list and get. Pages are described in authentication.
Update and delete
Patch sends only the fields that change. alias cannot be changed. destination_url follows the same https rules and is recorded in history. status is active or disabled. archived hides the link from the default list and leaves the redirect in place. An empty title clears it. Sending tags replaces the set.
Delete is a soft delete. The code stays reserved. A second delete of the same alias is still 204. The public short URL then returns HTTP 410.
History
The body is { "items": [] }. Each item has old_destination_url, new_destination_url, created_at, and actor. An API change has actor.type api_key plus id, name, and prefix. A dashboard change has actor.type user.
Stats
from and to are RFC3339 timestamps in UTC. from is inclusive and to is exclusive. When they are omitted, the window is the last 30 days ending now. Bot clicks are omitted unless include_bots=true. group_by is day (default), referrer, country, or device. Workspace stats also accept tag.
JSON includes total_clicks, estimated_unique_clicks (distinct visitor hashes in the window), series by UTC day, and the top referrer hosts, countries, and devices. format=csv returns key,clicks for the group_by rows.
Bulk
The body is { "items": [] }, at most 500 rows. Each row uses the create fields. The response is 200 and { "results": [] }. A result has index and outcome of created, reused, or error. A success also has alias and short_url. An error has error.code and error.message. One bad row does not roll back the others. A repeated alias in the same request is an error on the later row.