Piq.ru API

Table of Contents

1. General information

   1.1. URL

   1.2. Requests

   1.3. Responses

2. Links

   2.1 Create short link

   2.2 List of links

   2.3 Delete short link

3. Groups

   3.1 Create group

   3.2 List of groups

   3.3 Delete group

General information

Piq.ru API allows you to create short links, create link groups, manage links and link groups, get statistical information.

URL

Our main API service is available here:

https://piq.ru/api

Requests

You need to use in HTTP requests only HTTPS protocol and UTF-8 encoding. All requests require a header X-Piq-Api-Token.

Responses

All responses are returned in JSON format and UTF-8 encoding.

Possible response HTTP status codes:

1. 200 OK. The request was processed successfully.
2. 400 Bad Request. The request contains invalid parameters.
3. 401 Unauthorized. Token is required for this request.
4. 403 Forbidden. Not enough token rights for this request.
5. 405 Method Not Allowed. status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource.
6. 404 Not Found. Unknown API Method.
7. 500 Internal Server Error. The error is related to technical problems on the server.

Links

Create short link

POST /links/create

Service alows to create short link with any parameters

Required parameters:

• url String URL to be shortened

Optional parameters:

• alias String This value will be displayed as an identifier. For example for "cool" alias, the short link will look like this - https://piq.ru/cool. Max length 10 characters. By default, the alias will be randomly generated.
• is_public Boolean By choosing the PUBLIC type, the link may be available to other Internet users. If you want the link to be private, set the value to Personal. By default value is TRUE
• password STRING Set a password to protect your links from unauthorized access. By default this value is NULL.
• group_id INTEGER The id of one of your groups. By setting the identifier, the created link will be available among other links within the group. By default this value is NULL.
• active_before DATE Format 'Y-m-d'. The date until which the link will be available. After the expiration of the period, referrals to the link will be unavailable. If this parameter is not set, then the link will always be available. By default this value is NULL.

Request example:

curl --request POST \
  --url https://piq.ru/api/links/create \
  --header 'content-type: application/json' \
  --header 'X-Piq-Api-Token: XXXXXX' \
  --data '{
	"url":"https://www.api.com",
	"alias":"cool",
	"is_public": true,
	"group_id":2
}'

Response example:

{
    "successful": true,
    "message": "Link successfully created",
    "link": {
        "long_url": "https://www.api.com",
        "short": "cool",
        "hits": 0,
        "group": {
            "id": 2,
            "name": "Test Group",
            "short": "wow",
            "description": "Description of the group",
            "url": "https://piq.ru/g/wow"
        }
    },
    "short_url": "https://piq.ru/cool",
    "qr": {
        "base64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QAAd2KE6QAAAGPSURBVGje7ZpdroQgDIV5Y9m4ZHbQ64iUU/7u43TIIcag8+nE1LanxRB0RLnHvb+nqU4mg9hPYe+mh8NN3vs8m+R21fsTMTeYMSjaNFqgu7bOiXnG0D0TseOwnZ/mz03Knphz7GPxHFY2bc5eMEjQ84BP7FsYaiSc/CuluvxLzCc2FcDPEBwZYng054l5wMbKJYFr69ZhqQTzEs+J+cbUrCOWalJuyVexOiHmBHt9E3UR2vdhmqdrRs7EXGO91h0x24kq+qo5clVcxLxgM6WUsjk0TSfQUULMHzZvNYzaWKtUeCX69yQT84Whb2JAbidrtdvqX8zIp2DXEU/6GtE2jlaYpuYErwf+BTEXWJdJMcOCodXuqr7ENhILQMwVtlx+tR0M49GqvoSYF2xUQTulFALWubt+IzFP2NymNjuLzKukA7DriCc1a22y7fDHxTcw4/rdz2LXcU+6D7lGMolZyyPmF9OSZ4Nh5avrO6t0TMwHNmkPxl5uaZRO2awCEPs+NkTjDpuvsIfWmBJivrA/OACaB5gWD2cAAAAASUVORK5CYII="
    }
}

Response fields:

• successful Boolean Successful request
• message String Text message. By default is NULL
• link.long_url String Source url
• link.short String Alias of the short link
• link.hits Integer Number of clicks on the link
• link.group.id Integer Id of the link group
• link.group.name String Name of the link group
• link.group.description String Description of the link group
• link.group.url String Url of the link group
• short_url String Short link
• qr.base64 String Image of the QR code of the link in base64 format

List of links

GET /links

Piq.ru Api alows to get list of your links.

Optional parameters:

• limit Integer The number of links contained in the result. Max value is 25. By default is 25.
• offset Integer The number of items to skip. By default is 0.
• group_id Integer Id of one of your groups. The result will include links for this group. By default NULL.

Request example:

curl --header 'X-Piq-Api-Token: XXXXXXX' 'https://piq.ru/api/links?limit=2&offset=3&group_id=2'

Response example:

{
    "successful": true,
    "message": "",
    "count": 6,
    "limit": 2,
    "offset": 3,
    "links": [
        {
            "long_url": "https://docs.google.com/",
            "short": "A",
            "hits": 0,
            "group": {
                "id": 2,
                "name": "Test Group",
                "short": "wow",
                "description": "Description of the group",
                "url": "https://piq.ru/g/wow"
            },
            "short_url": "https://piq.local/A",
            "qr": {
                "base64": "1TcdDYAfMJNqAAvxewusLbDh+eIg1OXqjeFtvb00cj5APCyGNHrBqVp7+xfCz6RQ65cyevtaKqzVMErWArWF9N0CDgAXOznjb22eh+xl38dHJ53tnhbcmLZX3vEvflXe62YxtW+TZ7ftVXsVD4UALrcFGwA7ttu786rAIBmckqMLgKAw4OZi6blE1tyadXIuzEuBQDGnTRkDwHee5DzEu0eAQAfkOlQ8QoA4EHKzNYwiXVpYxlDaKPQze7IPubIuYbCUNZbA6P4FIY9BYYsnCc9WcmK2A+AN4PMEBsbfMCVT8/890/wQcvtzWzzD1chFDtDsaIiFJfqLFXwCpaCNWBMh52xZfCe5Twzwh57GZGSPnwDZE+zOSjvzujc6Rk0QAcO5OZesoE1JjZWy3lXe9pv/kJbepEa104O4aKxqzt15C0hCfPFLk2ShDzqsk4WT60ne+5l3xixy7l9a5TmzyOw4osovB0AzPwIOoUGzXI2wR3R84l8u0J1lip4BUvBUrC+APT/l5ygYhinPbUAAAAASUVORK5CYII="
            },
            "active_before":"2020-12-15"
        },
        {
            "long_url": "http://test.ru",
            "short": "p",
            "hits": 0,
            "group": {
                "id": 2,
                "name": "Test Group",
                "short": "wow",
                "description": "Description of the group",
                "url": "https://piq.ru/g/wow"
            },
            "short_url": "https://piq.local/p",
            "qr": {
                "base64": "1rc1av1mtOveAmEWABxawgAUsBCxgAQtYwFpR1WxuuHieo/JZlKquPv5qh9Ud25/bDQLrbzVFrOxOP0pVMY73+3ZY272afQfiNg+1Zo6crHfNKx3ELAI8sIAFLGAhYAELWMAC1orq2tyw9ESnFXiU+ktYt5t2WLul99XLjiLypf4eJjvKDZnZ9FgbsrjMoz2s4MfTcrJKyXyp3gkcNTuK1DQ7s+pcbTgmJysBHljAAhawELCABSxgAQtYSNG/sv+mdR376s4AAAAASUVORK5CYII="
            },
            "active_before": null
        }
    ]
}

Response fields:

• successful Boolean Successful request
• message String Text message. By default is NULL
• count Integer Total number of links on request
• limit Integer The number of links contained in the result.
• offset Integer The number of items to skip.
• links Array of Link List of links.
• links[].long_url String Source url
• links[].short String Alias of the short link
• links[].hits Integer Number of clicks on the link
• links[].group.id Integer Id of the link group
• links[].group.name String Name of the link group
• links[].group.description String Description of the link group
• links[].group.url String Url of the link group
• links[].short_url String Short link
• links[].qr.base64 String Image of the QR code of the link in base64 format
• links[].active_before Date|null The date until which the link will be available. After the expiration of the period, referrals to the link will be unavailable. If this parameter is not set, then the link will always be available.

Delete short link

POST|DELETE /links/delete/<alias>

You can remove your short link using the link alias.

Request example:

curl --request POST \
  --url https://piq.local/api/links/delete/cool \
  --header 'content-type: application/json' \
  --header 'X-Piq-Api-Token: XXXXXX'

Response example:

{
    "successful": true,
    "message": "Link removed"
}

Groups

Create group

POST /groups/create

Service alows to create groups for your links.

Required parameters:

• name String Group name

Optional parameters:

• description String Group description. Default NULL
• alias String This value will be displayed as an identifier. For example for "super" alias, link to new group will look like this - https://piq.ru/g/super. Max length 10 characters. By default, the alias will be randomly generated.
• is_active Boolean Whether this link group is publicly viewable. By default value is TRUE
• is_rotation Boolean If set, the above URL will redirect to a random link from the group instead of displaying all links belonging to the group. By default value is FALSE

Request example:

curl --request POST \
  --url https://piq.ru/api/groups/create \
  --header 'content-type: application/json' \
  --header 'X-Piq-Api-Token: XXXXXX' \
  --data '{
	"name":"My links",
	"description":"Links to my social networks",
	"alias": "super",
	"is_active":true,
	"is_rotation":true
}'

Response example:

{
    "successful": true,
    "message": "Group created",
    "group": {
        "id": 3,
        "name": "My links",
        "short": "super",
        "description": "Links to my social networks",
        "url": "https://piq.local/g/super"
    }
}

Response fields:

• successful Boolean Successful request
• message String Text message.
• group.id Integer Group ID
• group.name String Group name
• group.short String Group alias
• group.description String Group description
• group.url String Group url

List of groups

GET /groups

You can receive list of your groups.

Optional parameters:

• limit Integer The number of groups contained in the result. Max value is 100. By default is 100.
• offset Integer The number of items to skip. By default is 0.

Request example:

curl --request GET \
  --url https://piq.ru/api/groups \
  --header 'token: XXXXX'

Response example:

{
    "successful": true,
    "message": "",
    "count": 1,
    "groups": [
        {
            "id": 3,
            "name": "My links",
            "short": "super",
            "description": "Links to my social networks",
            "url": "https://piq.local/g/super"
        }
    ]
}

Response fields:

• successful Boolean Successful request
• message String Text message.
• groups Array of Group List of your groups.
• group.id String Group id
• group.name String Group name
• group.short String Group alias
• group.description String Group description
• group.url String Group url

Delete group

POST|DELETE /groups/delete/<group_id>

You can remove your group using the group id.

Request example:

curl --request POST \
  --url https://piq.ru/api/groups/delete/3 \
  --header 'content-type: application/json' \
  --header 'X-Piq-Api-Token: XXXXX'

Response example:

{
    "successful": true,
    "message": "Group removed"
}