URLR API Reference (1.12)

Download OpenAPI specification:Download

API powering the features of URLR.

Note that in order to facilitate integration, we provide SDKs for various languages at https://github.com/URLR.

Key API principles:

All dates follow ISO-8601 format
Most errors follow RFC 9457 standard
All responses are delivered in English

Access Tokens

Get an access token

Request Body schema: application/json

You can use this endpoint to get an access token to access the API.

username required	string Email
password required	string Password

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string"
}

Response samples

200
401

Content type

application/json

{"token": "string",
"refresh_token": "string"
}

Refresh an access token

Request Body schema: application/json

You can use this endpoint to refresh your access token without credentials.

refresh_token

required

string

Refresh token

Responses

Request samples

Payload

Content type

application/json

{"refresh_token": "string"
}

Response samples

200
401

Content type

application/json

{"token": "string",
"refresh_token": "string"
}

Links

Get a link

Authorizations:

bearerAuth

path Parameters

link_id

required

string <uuid>

Example: ffefc6c4-d970-4373-a867-2a69c8be2c89

Link API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"id": "436b5d20-e174-4363-94e5-2b3dd4e74b5f",
"url": "string",
"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"password": "**********",
"qrcode": {"data": "string"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}

Edit a link

Authorizations:

bearerAuth

path Parameters

link_id

required

string <uuid>

Example: ffefc6c4-d970-4373-a867-2a69c8be2c89

Link API ID

Request Body schema: application/json

Info of the link to edit

url	string <= 4096 characters URL to shorten
folder_id	string <uuid> Folder API ID
domain	string <hostname> Domain
code	string^[a-zA-Z0-9!-]{2,50}$ Custom short code
label	string Label
tags	Array of strings <uuid> <= 3 items [ items <uuid > ] Tags
password	string Password
	object QR Code
	object UTM parameters
	object Custom metadata for social previews
	Array of objects Dynamic routing conditions
delete_at	string <date-time> Scheduled deletion date
expired_at	string <date-time> Scheduled expiration date
expired_url	string <url> Expiration URL
delete_after_expiration	boolean Default: false Whether or not to remove the link after the expiry date

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "mybrand.com",
"code": "xxxxx",
"label": "string",
"tags": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"password": "string",
"qrcode": {"size": 600,
"format": "png",
"margin": 0,
"background_color": "#ffffff",
"foreground_color": "#000000"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}

Response samples

200
401
422
500

Content type

application/json

{"id": "436b5d20-e174-4363-94e5-2b3dd4e74b5f",
"url": "string",
"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"password": "**********",
"qrcode": {"data": "string"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}

List links

Authorizations:

bearerAuth

query Parameters

team_id	string <uuid> Filter by Workspace API ID
folder_id	string <uuid> Filter by Folder API ID
tag_id	string <uuid> Filter by Tag API ID
limit	integer [ 10 .. 50 ] Default: 10 Number of items per page
page	integer >= 1 Default: 1 Page number

Responses

Response samples

200
401
404
422

Content type

application/json

{"links": [{"id": "436b5d20-e174-4363-94e5-2b3dd4e74b5f",
"url": "string",
"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"password": "**********",
"qrcode": {"data": "string"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}
],
"total": 0,
"limit": 0,
"pages": 0,
"page": 0
}

Create a link

Authorizations:

bearerAuth

Request Body schema: application/json

Info of the link to create

team_id required	string <uuid> Workspace API ID
url required	string <= 4096 characters URL to shorten
folder_id	string <uuid> Folder API ID
domain	string <hostname> Domain
code	string^[a-zA-Z0-9!-]{2,50}$ Custom short code
label	string Label
tags	Array of strings <uuid> <= 3 items [ items <uuid > ] Tags
password	string Password
	object QR Code
	object UTM parameters
	object Custom metadata for social previews
	Array of objects Dynamic routing conditions
delete_at	string <date-time> Scheduled deletion date
expired_at	string <date-time> Scheduled expiration date
expired_url	string <url> Expiration URL
delete_after_expiration	boolean Default: false Whether or not to remove the link after the expiry date

Responses

Request samples

Payload

Content type

application/json

{"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"url": "string",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "mybrand.com",
"code": "xxxxx",
"label": "string",
"tags": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"password": "string",
"qrcode": {"size": 600,
"format": "png",
"margin": 0,
"background_color": "#ffffff",
"foreground_color": "#000000"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}

Response samples

201
401
422
429
500

Content type

application/json

{"id": "436b5d20-e174-4363-94e5-2b3dd4e74b5f",
"url": "string",
"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"password": "**********",
"qrcode": {"data": "string"
},
"utm": {"campaign": "string",
"medium": "string",
"source": "string",
"content": "string"
},
"metatag": {"title": "string",
"description": "string",
"image": "string"
},
"geolinks": [{"conditions": [{"type": "country",
"value": "string",
"operator": "AND"
}
],
"url": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"delete_after_expiration": false
}

QR Codes

Create a QR Code

Authorizations:

bearerAuth

Request Body schema: application/json

Info of the QR Code to create

One of

url required	string <url> URL of the QR Code
team_id required	string <uuid> Workspace API ID
size	integer [ 100 .. 1000 ] Default: 600 The size of the QR code (px)
format	string Default: "png" Enum: "png" "webp" "svg" The format of the QR code
margin	integer Default: 0 The margin around the QR code (px)
background_color	string Default: "#ffffff" The background color of the QR code (hexadecimal)
foreground_color	string Default: "#000000" The foreground color of the QR code (hexadecimal)

Responses

Request samples

Payload

Content type

application/json

{"link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
"size": 600,
"format": "png",
"margin": 0,
"background_color": "#ffffff",
"foreground_color": "#000000"
}

Response samples

401
422
429
500

Content type

application/problem+json

{"type": "string",
"title": "string",
"status": 401,
"detail": "string"
}

Statistics

Get statistics of a link

Authorizations:

bearerAuth

Request Body schema: application/json

Infos to provide to get statistics of a link

link_id required	string <uuid> Link API ID
from	string <date-time> Get statistics from this date
to	string <date-time> Get statistics until this date

Responses

Request samples

Payload

Content type

application/json

{"link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
"from": "2019-08-24T14:15:22Z",
"to": "2019-08-24T14:15:22Z"
}

Response samples

200
401
404
422

Content type

application/json

{"link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
"clicks": 51,
"unique_clicks": 32
}

Workspaces

Get workspaces of user

Authorizations:

bearerAuth

Responses

Response samples

200
401

Content type

application/json

{"teams": [{"id": "ffefc6c4-d970-4373-a867-2a69c8be2c89",
"name": "the best team"
}
]
}

Folders

Get folders of workspace

Authorizations:

bearerAuth

path Parameters

team_id

required

string <uuid>

Example: ffefc6c4-d970-4373-a867-2a69c8be2c89

Workspace API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"folders": [{"id": "436b5d20-e174-4363-94e5-2b3dd4e74b5f",
"name": "folder-campaign-google-ads"
}
]
}

Create a folder

Request Body schema: application/json

You can use this endpoint to add a folder to URLR.

team_id required	string <uuid> Team API ID
name required	string Name
parent_id	string <uuid> Folder API ID (if any)
color	string Enum: "blue" "green" "orange" "purple" "red" "rose" "yellow" "black" Color of folder

Responses

Request samples

Payload

Content type

application/json

{"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"name": "string",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"color": "blue"
}

Response samples

200
401
409
429

Content type

application/json

{"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"name": "string",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"parent_name": "string",
"color": "48aefa"
}

Domains

Create a domain

Request Body schema: application/json

You can use this endpoint to add a custom domain to URLR.

team_id required	string <uuid> Team API ID
domain required	string <hostname> Domain
root_url	string <url> Redirect URL for the root of the domain

Responses

Request samples

Payload

Content type

application/json

{"team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
"domain": "mybrand.com",
"root_url": "string"
}

Response samples

200
401
409
429

Content type

application/json

{"domain": "mybrand.com",
"root_url": "string"
}