Endpoints

All endpoints are relative to the base URL: https://api.linkshark.xyz/link/external/v1

Create / Update a Short URL

Creates a new shortened URL or updates an existing one (matched by shortCode).


POST /link/external/v1/save

Request Headers

Header	Value	Required
`X-API-KEY`	Your API key	Yes
`Content-Type`	`application/json`	Yes

Request Body

Field	Type	Required	Description
`url`	string	Yes	Destination URL. Must be a valid URL (max 2048 chars).
`shortCode`	string	No	Custom alias for the short link. 3–30 alphanumeric/hyphen/underscore chars. Auto-generated if omitted. If an existing `shortCode` is provided, the record is updated.
`title`	string	No	Descriptive title (max 255 chars).
`iosDeeplinkUrl`	string	No	iOS deep link URL. Must be a valid URL (max 2048 chars).
`iosFallbackUrl`	string	No	iOS web fallback URL. Must be a valid URL (max 2048 chars).
`androidDeeplinkUrl`	string	No	Android deep link URL. Must be a valid URL (max 2048 chars).
`androidFallbackUrl`	string	No	Android web fallback URL. Must be a valid URL (max 2048 chars).
`expirationDate`	string	No	ISO 8601 timestamp (e.g., `2025-12-31T23:59:59`). Link expires after this date.
`isActive`	boolean	No	Whether the link is active. Defaults to `true`.
`tags`	string[]	No	Array of label strings for organizing links.
`password`	string	No	Password to protect the link. Visitors must enter this password before being redirected.

Example Request


curl -X POST https://api.linkshark.xyz/link/external/v1/save \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-article-url",
    "shortCode": "my-link",
    "title": "Example Article",
    "tags": ["article", "marketing"]
  }'

Success Response


HTTP/1.1 200 OK
Content-Type: application/json


{
  "response": {
    "id": "abc12345-6789-...",
    "url": "https://example.com/my-long-article-url",
    "shortCode": "my-link",
    "smartLink": "https://lnk.shark/my-link",
    "title": "Example Article",
    "tags": ["article", "marketing"],
    "isActive": true,
    "totalClicks": 0,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-15T10:30:00"
  },
  "error": null
}

Validation Errors


HTTP/1.1 400 Bad Request
Content-Type: application/json


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "url: must not be blank"
  }
}

Bulk Create / Update Short URLs

Creates or updates multiple short URLs in a single request. Maximum 30 records per request.


POST /link/external/v1/bulkSave

Request Headers

Header	Value	Required
`X-API-KEY`	Your API key	Yes
`Content-Type`	`application/json`	Yes

Request Body

Field	Type	Required	Description
`shortUrls`	array	Yes	Array of short URL objects (same fields as the single save endpoint). Max 30 items.

Example Request


curl -X POST https://api.linkshark.xyz/link/external/v1/bulkSave \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "shortUrls": [
      {
        "url": "https://example.com/page-one",
        "shortCode": "page1",
        "title": "Page One"
      },
      {
        "url": "https://example.com/page-two",
        "title": "Page Two"
      }
    ]
  }'

Success Response

Returns an array of results — one for each input record. Each element is a standard response envelope.


HTTP/1.1 200 OK
Content-Type: application/json


[
  {
    "response": {
      "id": "abc12345-...",
      "url": "https://example.com/page-one",
      "shortCode": "page1",
      "smartLink": "https://lnk.shark/page1",
      "title": "Page One",
      "isActive": true,
      "totalClicks": 0,
      "createdAt": "2025-01-15T10:30:00",
      "updatedAt": "2025-01-15T10:30:00"
    },
    "error": null
  },
  {
    "response": {
      "id": "def67890-...",
      "url": "https://example.com/page-two",
      "shortCode": "xK9mP2",
      "smartLink": "https://lnk.shark/xK9mP2",
      "title": "Page Two",
      "isActive": true,
      "totalClicks": 0,
      "createdAt": "2025-01-15T10:30:00",
      "updatedAt": "2025-01-15T10:30:00"
    },
    "error": null
  }
]

Partial Failures

Individual records that fail validation are returned with an error in their envelope while the remaining records process successfully:


[
  {
    "response": null,
    "error": {
      "code": "VE001",
      "message": "url: must not be blank"
    }
  },
  {
    "response": {
      "id": "def67890-...",
      "url": "https://example.com/page-two",
      "shortCode": "xK9mP2",
      "smartLink": "https://lnk.shark/xK9mP2",
      "title": "Page Two",
      "isActive": true,
      "totalClicks": 0
    },
    "error": null
  }
]

💡 Tip: If the array contains more than 30 items, you will receive error code SML004 — split your payload into batches of 30 or fewer.

List Shortened URLs

Retrieves a paginated list of your shortened URLs with optional filtering.


GET /link/external/v1/?page={page}&size={size}&isActive={isActive}&query={query}

Request Headers

Header	Value	Required
`X-API-KEY`	Your API key	Yes

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`0`	Page number (zero-based).
`size`	integer	`10`	Number of results per page.
`isActive`	boolean	—	Filter by active status. Omit to return all.
`query`	string	—	Search filter using LinkShark Query DSL (see below).

Example Request


curl -X GET "https://api.linkshark.xyz/link/external/v1/?page=0&size=10&isActive=true" \
  -H "X-API-KEY: your_api_key_here"

Success Response


HTTP/1.1 200 OK
Content-Type: application/json


{
  "response": {
    "content": [
      {
        "id": "abc12345-...",
        "url": "https://example.com/my-long-article-url",
        "shortCode": "my-link",
        "smartLink": "https://lnk.shark/my-link",
        "title": "Example Article",
        "tags": ["article", "marketing"],
        "isActive": true,
        "totalClicks": 42,
        "createdAt": "2025-01-15T10:30:00",
        "updatedAt": "2025-01-18T14:22:00"
      }
    ],
    "totalPages": 5,
    "totalElements": 42,
    "currentPage": 0,
    "pageSize": 10
  },
  "error": null
}

Query DSL — Filtering Syntax

The query parameter accepts a structured filter string to refine results. Use the format:


fieldName operator value

Supported fields and operators:

Field	Operators	Example
`url`	`:` (contains)	`url:example.com`
`shortCode`	`:` (contains)	`shortCode:my-link`
`title`	`:` (contains)	`title:Article`
`tags`	`:` (contains)	`tags:marketing`
`totalClicks`	`>`, `<`	`totalClicks>100`
`createdAt`	`>`, `<`	`createdAt>2025-01-01`
`updatedAt`	`>`, `<`	`updatedAt<2025-06-01`
`expirationDate`	`>`, `<`	`expirationDate>2025-12-31`

Example with query filter:


curl -X GET "https://api.linkshark.xyz/link/external/v1/?page=0&size=10&query=title:Article" \
  -H "X-API-KEY: your_api_key_here"

Note: Only one filter expression is supported per request. Combine with isActive for additional refinement.