URLR API Reference (2.0.0)

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

All requests must include an API key generated in your workspace. The key should be provided in the X-API-KEY HTTP header.

Links

Get a link

Authorizations:

ApiKeyAuth

path Parameters

link_id

required

string <uuid>

Link API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"user": "string",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"password": "**********",
"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",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"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"
}
]
}

Delete a link

Authorizations:

ApiKeyAuth

path Parameters

link_id

required

string <uuid>

Link API ID

Responses

Response samples

204
401
404
422
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"user": "string",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"password": "**********",
"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",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"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"
}
]
}

Edit a link

Authorizations:

ApiKeyAuth

path Parameters

link_id

required

string <uuid>

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 [ 2 .. 50 ] characters ^[\p{L}0-9_\-/]{2,50}$ Custom short code
label	string <= 255 characters Label
password	string <= 255 characters Password
delete_at	string <date-time> Scheduled deletion date
expired_at	string <date-time> Scheduled expiration date
expired_url	string <url> The URL to which users will be redirected after the link has expired
expired_title	string The title displayed on the expiration page
expired_text	string The text displayed on the expiration page
delete_after_expiration	boolean Default: false Whether the link should be deleted once it has expired
tags	Array of strings <uuid> <= 3 items [ items <uuid > ] Tags
	object QR Code
	object UTM parameters
	object Custom metadata for social previews
	Array of objects Dynamic routing conditions

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "mybrand.com",
"code": "xxxxx",
"label": "string",
"password": "string",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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"
}
]
}

Response samples

200
401
404
422
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"user": "string",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"password": "**********",
"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",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"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"
}
]
}

List links

Authorizations:

ApiKeyAuth

query Parameters

workspace_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 [ 1 .. 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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"user": "string",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"password": "**********",
"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",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"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"
}
]
}
],
"total": 0,
"limit": 0,
"pages": 0,
"page": 0
}

Create a link

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Info of the link to create

workspace_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 [ 2 .. 50 ] characters ^[\p{L}0-9_\-/]{2,50}$ Custom short code
label	string <= 255 characters Label
password	string <= 255 characters Password
delete_at	string <date-time> Scheduled deletion date
expired_at	string <date-time> Scheduled expiration date
expired_url	string <url> The URL to which users will be redirected after the link has expired
expired_title	string The title displayed on the expiration page
expired_text	string The text displayed on the expiration page
delete_after_expiration	boolean Default: false Whether the link should be deleted once it has expired
tags	Array of strings <uuid> <= 3 items [ items <uuid > ] Tags
	object QR Code
	object UTM parameters
	object Custom metadata for social previews
	Array of objects Dynamic routing conditions

Responses

Request samples

Payload

Content type

application/json

{"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"url": "string",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"domain": "mybrand.com",
"code": "xxxxx",
"label": "string",
"password": "string",
"delete_at": "2019-08-24T14:15:22Z",
"expired_at": "2019-08-24T14:15:22Z",
"expired_url": "string",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"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"
}
]
}

Response samples

201
401
422
429
500

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"folder_id": "7695bac3-9397-4ec2-9335-45a2a16f1901",
"user": "string",
"domain": "urlr.me",
"code": "xxxxx",
"label": "string",
"password": "**********",
"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",
"expired_title": "string",
"expired_text": "string",
"delete_after_expiration": false,
"tags": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string"
}
],
"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"
}
]
}

QR Codes

Create a QR Code

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Info of the QR Code to create

One of

url required	string <url> URL of the QR Code
workspace_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
404
422
429
500

Content type

application/problem+json

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

Statistics

Get statistics

Authorizations:

ApiKeyAuth

query Parameters

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

Response samples

200
401
404
422

Content type

application/json

{"link_id": "02a2c2f0-9521-47cc-9615-2e177adeebac",
"visits": 51,
"unique_visits": 32,
"clicks": 42,
"scans": 9
}

Workspaces

Get a workspace

Authorizations:

ApiKeyAuth

path Parameters

workspace_id

required

string <uuid>

Workspace API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "the best team",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

List workspaces of user

Authorizations:

ApiKeyAuth

Responses

Response samples

200
401

Content type

application/json

{"workspaces": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "the best team",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Folders

Get a folder

Authorizations:

ApiKeyAuth

path Parameters

folder_id

required

string <uuid>

Folder API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"parent_name": "string",
"color": "blue",
"domain": "example.com",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

List folders

Authorizations:

ApiKeyAuth

query Parameters

workspace_id

required

string <uuid>

Workspace API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"folders": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"parent_name": "string",
"color": "blue",
"domain": "example.com",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Create a folder

Authorizations:

ApiKeyAuth

Request Body schema: application/json

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

workspace_id required	string <uuid> Workspace API ID
name required	string <= 255 characters Name
parent_id	string <uuid> Folder API ID
color	string Enum: "blue" "green" "orange" "purple" "red" "rose" "yellow" "black" Color of folder

Responses

Request samples

Payload

Content type

application/json

{"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"name": "string",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"color": "blue"
}

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
"parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
"parent_name": "string",
"color": "blue",
"domain": "example.com",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Domains

Get a domain

Authorizations:

ApiKeyAuth

path Parameters

domain_id

required

string <uuid>

Domain API ID

Responses

Response samples

200
401
404
422

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"domain": "mybrand.com",
"root_url": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

List domains

Authorizations:

ApiKeyAuth

Responses

Response samples

200
401
404
422

Content type

application/json

{"domains": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"domain": "mybrand.com",
"root_url": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

Create a domain

Authorizations:

ApiKeyAuth

Request Body schema: application/json

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

domain required	string <hostname> <= 255 characters Domain
root_url	string <url> Redirect URL for the root of the domain

Responses

Request samples

Payload

Content type

application/json

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

Response samples

201
401
409
422
429

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"domain": "mybrand.com",
"root_url": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}