API Reference

Endpoints Overview

The Lynkd API provides RESTful endpoints for managing links, retrieving analytics, and managing your account. All requests and responses use JSON.

Links

The Links endpoints let you create, read, update, and delete short links:

1. 1POST /v1/links - Create a new short link. Required field: url. Optional: alias, tags, utm_source, utm_medium, utm_campaign, expires_at, click_limit.
2. 2GET /v1/links - List all links. Supports pagination with limit and offset parameters. Filter by tag or date range.
3. 3GET /v1/links/:id - Get details for a specific link, including its short URL, destination, tags, and creation date.
4. 4PATCH /v1/links/:id - Update a link's destination URL, tags, or expiration rules.
5. 5DELETE /v1/links/:id - Delete a link. This action is permanent and cannot be undone.

Analytics

The Analytics endpoints let you retrieve click data for your links:

1. 1GET /v1/analytics/:link_id - Get click analytics for a specific link. Returns click counts, geographic data, device breakdowns, and referrer information.
2. 2GET /v1/analytics/:link_id/clicks - Get raw click events with full detail (timestamp, location, device, referrer). Supports date range filtering and pagination.
3. 3GET /v1/analytics/summary - Get aggregate analytics across all your links for a given date range.

Error Handling

The API returns standard HTTP status codes. Successful requests return 200 (OK) or 201 (Created). Client errors return 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), or 429 (Rate Limited). Server errors return 500 (Internal Server Error).

Error responses include a JSON body with an error field containing a human-readable message and a code field for programmatic handling.