{"_id":"58f6088e914540250034e97f","sync_unique":"","title":"API limits","__v":0,"body":"The number of links, domains and teammates you are allowed to create depends on the plan you subscribed.\n\nYou can check your limits at any time by logging into your account and accessing [our pricing page](https://www.rebrandly.com/pricing). To programmatically access your limits and features availability, see [Account info](doc:account-model).\n\nMind that in Rebrandly premium accounts you can have up to:\n- 50 workspaces, if your plan includes workspaces\n- 50 tags, if your plan includes tags\n- 50 retargeting scripts, if your plan include retargeting feature\n- 10 API keys\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"How do we count resources\",\n \"body\": \"Counters are updated transactionally with your API operations.\\n- Trashed links count as active links: you need to permanently delete the link to reduce links usage in your account.\\n- Pending teammates count as active teammates.\\n- Deleted domains are not included in the domains counting, as well as deleted tags and deleted scripts.\"\n}\n[/block]\nIf you need more, please [contact us](mailto:support@rebrandly.com?subject=Increase my account limits) sharing your use case.\n\nYou are allowed to perform up to 10 API calls per second.","category":"577d1b8b74aea422007230c8","link_external":false,"order":3,"version":"577d1b8b74aea422007230c7","link_url":"","project":"577d1b8b74aea422007230c4","slug":"api-limits","updates":[],"createdAt":"2017-04-18T12:37:34.561Z","hidden":false,"isReference":false,"next":{"pages":[],"description":""},"parentDoc":null,"type":"basic","api":{"params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required"},"excerpt":"","githubsync":"","user":"577d1b6d87acf617003c421d","childrenPages":[]}

API limits

The number of links, domains and teammates you are allowed to create depends on the plan you subscribed.
You can check your limits at any time by logging into your account and accessing [our pricing page](https://www.rebrandly.com/pricing). To programmatically access your limits and features availability, see [Account info](doc:account-model).
Mind that in Rebrandly premium accounts you can have up to:
- 50 workspaces, if your plan includes workspaces
- 50 tags, if your plan includes tags
- 50 retargeting scripts, if your plan include retargeting feature
- 10 API keys
[block:callout]
{
"type": "warning",
"title": "How do we count resources",
"body": "Counters are updated transactionally with your API operations.\n- Trashed links count as active links: you need to permanently delete the link to reduce links usage in your account.\n- Pending teammates count as active teammates.\n- Deleted domains are not included in the domains counting, as well as deleted tags and deleted scripts."
}
[/block]
If you need more, please [contact us](mailto:support@rebrandly.com?subject=Increase my account limits) sharing your use case.
You are allowed to perform up to 10 API calls per second.

The number of links, domains and teammates you are allowed to create depends on the plan you subscribed.
You can check your limits at any time by logging into your account and accessing [our pricing page](https://www.rebrandly.com/pricing). To programmatically access your limits and features availability, see [Account info](doc:account-model).
Mind that in Rebrandly premium accounts you can have up to:
- 50 workspaces, if your plan includes workspaces
- 50 tags, if your plan includes tags
- 50 retargeting scripts, if your plan include retargeting feature
- 10 API keys
[block:callout]
{
"type": "warning",
"title": "How do we count resources",
"body": "Counters are updated transactionally with your API operations.\n- Trashed links count as active links: you need to permanently delete the link to reduce links usage in your account.\n- Pending teammates count as active teammates.\n- Deleted domains are not included in the domains counting, as well as deleted tags and deleted scripts."
}
[/block]
If you need more, please [contact us](mailto:support@rebrandly.com?subject=Increase my account limits) sharing your use case.
You are allowed to perform up to 10 API calls per second.

{"_id":"57a217455220910e002a1759","link_url":"","order":4,"sync_unique":"","title":"Live APPS","type":"basic","__v":3,"body":"Rebrandly Web API is currently consumed by the following applications:\n- [Rebrandly.com](https://www.rebrandly.com): the Rebrandly main website\n- [Rebrandly Chrome extension](https://app.rebrandly.com/apps/chrome-extension): a Google Chrome extension to easily rebrand links\n- [Rebrandly Firefox extension](https://app.rebrandly.com/apps/firefox-extension): a Mozilla Firefox extension to easily rebrand links\n- [Rebrandly Safari extension](https://app.rebrandly.com/apps/safari-extension): an Apple Safari extension to easily rebrand links\n- [ClickMeter connector](https://app.rebrandly.com/apps/clickmeter-connector): a feature to connect your Rebrandly and ClickMeter accounts together, to get ClickMeter statistics\n- [Rebrandly iOS app](https://app.rebrandly.com/apps/iphone): an iOS mobile application to manage your branded link\n- [Rebrandly Android app](https://app.rebrandly.com/apps/android): an Android mobile application to manage your branded link\n- [Google Sheet](https://support.rebrandly.com/hc/en-us/articles/115005896748-Google-Drive-bulk-links-creation-with-Google-Sheet): create branded short links from a Google Sheet\n- [Name.com](https://name.com): a registrar allowing you to easily integrate your domains with Rebrandly\n- [Iwantmyname.com](https://iwantmyname.com): a registrar allowing you to easily integrate your domains with Rebrandly\n- [Short Menu app](https://app.rebrandly.com/apps/short-menu): a mobile application to short links\n- [SocialPilot](https://support.rebrandly.com/hc/en-us/articles/115000278528-How-to-connect-Rebrandly-to-SocialPilot): a social media scheduling and marketing tool for agencies and social media professionals.\n- [SocialBee](https://app.rebrandly.com/apps/socialbee): a social media content, growth and engagement automation service.\n- [ViralTag](https://app.rebrandly.com/apps/viraltag): an easy to use Social Media Marketing tool built for sharing visual content.\n- [Easy Social Share Button](app://www.rebrandly.com/apps/essb): a social sharing plugin for WordPress.\n- [Tweetbot](https://support.rebrandly.com/hc/en-us/articles/229596467-Custom-URL-Shortening-for-Tweetbot-iOS-and-MAC-): a twitter client for Mac.\n- [Rebrandly Bookmarklet](https://app.rebrandly.com/apps/bookmarklet): a browser addon to short links from web pages\n- [Zapier - Google Sheets](https://app.rebrandly.com/apps/zapier): to import and export your Rebrandly links using Google Sheets\n- [Zapier - Gmail](https://app.rebrandly.com/apps/zapier): to connect your Gmail account with Rebrandly and get notifications on events (e.g. reached 100 clicks on a link, created a new link and so on)\n- [Zapier - RSS](https://app.rebrandly.com/apps/zapier): to create Rebrandly links based on RSS feeds\n- [Zapier - Buffer](https://zapier.com/zapbook/zaps/15529/buffer-your-rebrandly-links/): push your new Rebrandly Links to your Buffer queue\n- [Postpickr](https://www.postpickr.com/): a social media assistant which let you use your Rebrandly domains for your online posts\n\n\n\n\nA full list of applications is available in [Rebrandly Apps page](https://app.rebrandly.com/apps).\nAlso look at <a href=\"https://blog.rebrandly.com/reasons-build-integration-rebrandly-api/\" target=\"_blank\">5 Reasons to Build an Integration with the Rebrandly API</a> \nor <a href=\"http://www.programmableweb.com/news/api-godai-5-elements-amazing-api/analysis/2016/11/10\" target=\"_blank\">The philosophy of Rebrandly's API</a> (by ProgrammableWeb).\n\n\nWe love to hear about Rebrandly use cases.\nPlease [let us know](mailto:dev@rebrandly.com) what you're developing using our API!","createdAt":"2016-08-03T16:09:41.097Z","githubsync":"","isReference":false,"project":"577d1b8b74aea422007230c4","updates":["582ae5997a96051b0070b0e5","58ef82c2de2a332300c9d675"],"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"category":"577d1b8b74aea422007230c8","excerpt":"","hidden":false,"next":{"description":"","pages":[]},"parentDoc":null,"version":"577d1b8b74aea422007230c7","link_external":false,"slug":"live-apps","user":"56b22f582d96461700599230","childrenPages":[]}

Live APPS

Rebrandly Web API is currently consumed by the following applications:
- [Rebrandly.com](https://www.rebrandly.com): the Rebrandly main website
- [Rebrandly Chrome extension](https://app.rebrandly.com/apps/chrome-extension): a Google Chrome extension to easily rebrand links
- [Rebrandly Firefox extension](https://app.rebrandly.com/apps/firefox-extension): a Mozilla Firefox extension to easily rebrand links
- [Rebrandly Safari extension](https://app.rebrandly.com/apps/safari-extension): an Apple Safari extension to easily rebrand links
- [ClickMeter connector](https://app.rebrandly.com/apps/clickmeter-connector): a feature to connect your Rebrandly and ClickMeter accounts together, to get ClickMeter statistics
- [Rebrandly iOS app](https://app.rebrandly.com/apps/iphone): an iOS mobile application to manage your branded link
- [Rebrandly Android app](https://app.rebrandly.com/apps/android): an Android mobile application to manage your branded link
- [Google Sheet](https://support.rebrandly.com/hc/en-us/articles/115005896748-Google-Drive-bulk-links-creation-with-Google-Sheet): create branded short links from a Google Sheet
- [Name.com](https://name.com): a registrar allowing you to easily integrate your domains with Rebrandly
- [Iwantmyname.com](https://iwantmyname.com): a registrar allowing you to easily integrate your domains with Rebrandly
- [Short Menu app](https://app.rebrandly.com/apps/short-menu): a mobile application to short links
- [SocialPilot](https://support.rebrandly.com/hc/en-us/articles/115000278528-How-to-connect-Rebrandly-to-SocialPilot): a social media scheduling and marketing tool for agencies and social media professionals.
- [SocialBee](https://app.rebrandly.com/apps/socialbee): a social media content, growth and engagement automation service.
- [ViralTag](https://app.rebrandly.com/apps/viraltag): an easy to use Social Media Marketing tool built for sharing visual content.
- [Easy Social Share Button](app://www.rebrandly.com/apps/essb): a social sharing plugin for WordPress.
- [Tweetbot](https://support.rebrandly.com/hc/en-us/articles/229596467-Custom-URL-Shortening-for-Tweetbot-iOS-and-MAC-): a twitter client for Mac.
- [Rebrandly Bookmarklet](https://app.rebrandly.com/apps/bookmarklet): a browser addon to short links from web pages
- [Zapier - Google Sheets](https://app.rebrandly.com/apps/zapier): to import and export your Rebrandly links using Google Sheets
- [Zapier - Gmail](https://app.rebrandly.com/apps/zapier): to connect your Gmail account with Rebrandly and get notifications on events (e.g. reached 100 clicks on a link, created a new link and so on)
- [Zapier - RSS](https://app.rebrandly.com/apps/zapier): to create Rebrandly links based on RSS feeds
- [Zapier - Buffer](https://zapier.com/zapbook/zaps/15529/buffer-your-rebrandly-links/): push your new Rebrandly Links to your Buffer queue
- [Postpickr](https://www.postpickr.com/): a social media assistant which let you use your Rebrandly domains for your online posts
A full list of applications is available in [Rebrandly Apps page](https://app.rebrandly.com/apps).
Also look at <a href="https://blog.rebrandly.com/reasons-build-integration-rebrandly-api/" target="_blank">5 Reasons to Build an Integration with the Rebrandly API</a>
or <a href="http://www.programmableweb.com/news/api-godai-5-elements-amazing-api/analysis/2016/11/10" target="_blank">The philosophy of Rebrandly's API</a> (by ProgrammableWeb).
We love to hear about Rebrandly use cases.
Please [let us know](mailto:dev@rebrandly.com) what you're developing using our API!

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details at [Getting account details](doc:getting-account-details).

{"_id":"57cd7ce2873de50e00724a3b","body":"More details in [Listing your links](doc:list-links).","next":{"description":"","pages":[]},"parentDoc":null,"isReference":false,"link_url":"","title":"/v1/links","type":"get","api":{"params":[{"_id":"57cd7fb567e1be1700c28570","ref":"","in":"query","required":false,"desc":"Filter branded short links which refer to a specific branded domain id (or specify a comma-separated set of ids)","default":"","type":"string","name":"domain.id"},{"_id":"5aec3d7f489de2000318f506","ref":"","in":"query","required":false,"desc":"Filter branded short links which refer to a specific branded domain's name (FQDN)","default":"","type":"string","name":"domain.fullName"},{"_id":"5aec3d7f489de2000318f505","ref":"","in":"query","required":false,"desc":"Filter branded short links according to their slashtag value. Use in conjunction with domain.id or domain.fullName parameter to get a specific link. WARNING: this will not take effect if you don't specify also a domain.id or a domain.fullName along with the request","default":"","type":"string","name":"slashtag"},{"_id":"5ac38bdd77227b0012a393a0","ref":"","in":"query","required":false,"desc":"Filter branded short links which have been created by a specific teammate id (or specify a comma-separated set of ids)","default":"","type":"string","name":"creator.id"},{"_id":"57cd7f9e67e1be1700c2856f","ref":"","in":"query","required":false,"desc":"Filter branded short links according to their status among `active` and `trashed`.","default":"","type":"string","name":"status"},{"_id":"57cd7f7c33cbfb2200e6cd4e","ref":"","in":"query","required":false,"desc":"Filter branded short links depending on favourite (loved) property","default":"","type":"boolean","name":"favourite"},{"_id":"57cd7f134b5a7f1900899379","ref":"","in":"query","required":false,"desc":"Sorting criteria to apply to your branded short links collection among `createdAt`, `title` and `slashtag`.","default":"createdAt","type":"string","name":"orderBy"},{"_id":"57cd7f134b5a7f1900899378","ref":"","in":"query","required":false,"desc":"Sorting direction to apply to your branded short links collection","default":"desc","type":"string","name":"orderDir"},{"_id":"57cd7f68873de50e00724a3d","ref":"","in":"query","required":false,"desc":"How many branded short links to load, starting from offset on","default":"100","type":"int","name":"limit"},{"_id":"5926b02fc4ee340f001275dc","ref":"","in":"header","required":false,"desc":"Which workspace id to filter links by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"},{"_id":"5aec73e1489de2000318f9bf","ref":"","in":"query","required":false,"desc":"The id of the last link you fetched, see Infinite Scrolling section","default":"","type":"string","name":"last"}],"results":{"codes":[{"code":"[\n {\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"title\": \"What is Rebrandly?\",\n \"slashtag\": \"video\",\n \"destination\": \"https://www.youtube.com/watch?v=3VmtibKpmXI\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-15T10:05:22.000Z\",\n \"shortUrl\": \"rebrand.ly/video\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n }\n},\n ...\n]","name":"","status":200,"language":"json"},{"status":404,"language":"json","code":"{\n \"property\": \"domain.id\",\n \"message\": \"Not found\",\n \"code\": \"NotFound\"\n}"}]},"settings":"","url":"/v1/links","auth":"required","examples":{"codes":[]},"method":"get"},"githubsync":"","hidden":false,"link_external":false,"order":2,"updates":[],"sync_unique":"","user":"56b22f582d96461700599230","__v":19,"category":"57cd7c3267e1be1700c2856d","createdAt":"2016-09-05T14:10:42.560Z","excerpt":"Get a list of links","project":"577d1b8b74aea422007230c4","slug":"links-list-endpoint","version":"577d1b8b74aea422007230c7","childrenPages":[]}

get/v1/links

Get a list of links

Query Params

domain.id:

string

Filter branded short links which refer to a specific branded domain id (or specify a comma-separated set of ids)

domain.fullName:

string

Filter branded short links which refer to a specific branded domain's name (FQDN)

slashtag:

string

Filter branded short links according to their slashtag value. Use in conjunction with domain.id or domain.fullName parameter to get a specific link. WARNING: this will not take effect if you don't specify also a domain.id or a domain.fullName along with the request

creator.id:

string

Filter branded short links which have been created by a specific teammate id (or specify a comma-separated set of ids)

status:

string

Filter branded short links according to their status among `active` and `trashed`.

favourite:

boolean

Filter branded short links depending on favourite (loved) property

orderBy:

stringcreatedAt

Sorting criteria to apply to your branded short links collection among `createdAt`, `title` and `slashtag`.

orderDir:

stringdesc

Sorting direction to apply to your branded short links collection

limit:

integer100

How many branded short links to load, starting from offset on

last:

string

The id of the last link you fetched, see Infinite Scrolling section

Headers

workspace:

string

Which workspace id to filter links by. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details in [Getting link details](doc:get-link-details).

{"_id":"57cd85701e75f217006dce2b","category":"57cd7c3267e1be1700c2856d","createdAt":"2016-09-05T14:47:12.753Z","hidden":false,"parentDoc":null,"updates":[],"version":"577d1b8b74aea422007230c7","api":{"url":"/v1/links/count","auth":"required","examples":{"codes":[]},"method":"get","params":[{"_id":"57ce8ad9065d9a0e00d47c8a","ref":"","in":"query","required":false,"desc":"Filter branded short links depnding on the favourite (loved) property","default":"","type":"boolean","name":"favourite"},{"_id":"57ce8ad9065d9a0e00d47c89","ref":"","in":"query","required":false,"desc":"Filter branded short links depending on their status among `active` and `trashed`","default":"","type":"string","name":"status"},{"_id":"57ce8af75f5adc0e0075c683","ref":"","in":"query","required":false,"desc":"Filter branded short links which refer to a specific branded domain id","default":"","type":"string","name":"domain.id"},{"_id":"5926b06721e2930f001c189d","ref":"","in":"header","required":false,"desc":"Which workspace id to filter links by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"results":{"codes":[{"code":"{\n \"count\": 42\n}","language":"json","status":200,"name":""}]},"settings":""},"body":"More details at [Counting your links](doc:counting-your-links).","order":4,"project":"577d1b8b74aea422007230c4","excerpt":"Get how many links with given filtering conditions","githubsync":"","link_external":false,"link_url":"","title":"/v1/links/count","type":"get","user":"56b22f582d96461700599230","__v":5,"isReference":false,"next":{"description":"","pages":[]},"slug":"counting-links-endpoint","sync_unique":"","childrenPages":[]}

get/v1/links/count

Get how many links with given filtering conditions

Query Params

favourite:

boolean

Filter branded short links depnding on the favourite (loved) property

status:

string

Filter branded short links depending on their status among `active` and `trashed`

domain.id:

string

Filter branded short links which refer to a specific branded domain id

Headers

workspace:

string

Which workspace id to filter links by. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details at [Counting your links](doc:counting-your-links).

{"_id":"57ea648566130b1700056ec5","category":"57cd7c3267e1be1700c2856d","next":{"description":"","pages":[]},"parentDoc":null,"type":"get","api":{"auth":"required","examples":{"codes":[{"name":"Paste in your browser","language":"text","code":"https://api.rebrandly.com/v1/links/new?apikey=YOUR_API_KEY&destination=http://google.com&domain[fullName]=rebrand.ly"}]},"method":"get","params":[{"_id":"57ea650474088b17002237db","ref":"","in":"query","required":true,"desc":"The destination URL you want your branded short link to point to","default":"","type":"string","name":"destination"},{"_id":"57ea650474088b17002237da","ref":"","in":"query","required":false,"desc":"The keyword portion of your branded short link","default":"","type":"string","name":"slashtag"},{"_id":"57ea650474088b17002237d9","ref":"","in":"query","required":false,"desc":"A title you assign to the branded short link in order to remember what's behind it","default":"","type":"string","name":"title"},{"_id":"57ea65e174088b17002237dc","ref":"","in":"query","required":false,"desc":"The unique id of the branded domain. If not specified, rebrand.ly is used","default":"","type":"string","name":"domain[id]"},{"_id":"57ea662bb9f45420005724d0","ref":"","in":"query","required":false,"desc":"The unique name of the branded domain, to be used in place of domain[id] in special cases. Precedence will be given to domain[id] value.","default":"","type":"string","name":"domain[fullName]"},{"_id":"5926b0926c729e0f005959e7","ref":"","in":"header","required":false,"desc":"Which workspace id to be used to create new links. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"title\": \"What is Rebrandly\",\n \"slashtag\": \"video\",\n \"destination\": \"https://www.youtube.com/watch?v=3VmtibKpmXI\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-13T10:54:12.000Z\",\n \"shortUrl\": \"rebrand.ly/video\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n }\n}\n"},{"status":403,"language":"json","code":"{\n \"property\": \"slashtag\",\n \"message\": \"Already exists\",\n \"code\": \"AlreadyExists\"\n}\n","name":""},{"code":"{\n \"property\": \"domain.id\",\n \"message\": \"Not found\",\n \"code\": \"NotFound\"\n}","language":"json","status":404}]},"settings":"","url":"/v1/links/new"},"hidden":false,"link_external":false,"order":5,"project":"577d1b8b74aea422007230c4","sync_unique":"","title":"/v1/links/new","excerpt":"Create a new link","githubsync":"","version":"577d1b8b74aea422007230c7","link_url":"","slug":"create-link-url","updates":["592c1d2d9bc0980f00276247"],"body":"","isReference":false,"user":"56b22f582d96461700599230","__v":11,"createdAt":"2016-09-27T12:22:29.674Z","childrenPages":[]}

get/v1/links/new

Create a new link

Query Params

destination:

required

string

The destination URL you want your branded short link to point to

slashtag:

string

The keyword portion of your branded short link

title:

string

A title you assign to the branded short link in order to remember what's behind it

domain[id]:

string

The unique id of the branded domain. If not specified, rebrand.ly is used

domain[fullName]:

string

The unique name of the branded domain, to be used in place of domain[id] in special cases. Precedence will be given to domain[id] value.

Headers

workspace:

string

Which workspace id to be used to create new links. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details at [Deleting a link](doc:delete-a-link).

{"_id":"57cd83b7873de50e00724a42","api":{"settings":"","url":"/v1/domains","auth":"required","examples":{"codes":[]},"method":"get","params":[{"_id":"57cd84411e75f217006dce1f","ref":"","in":"query","required":false,"desc":"Filter branded domains depending on whether they can be used to brand short links or not","default":"","type":"boolean","name":"active"},{"_id":"57cd84511e75f217006dce20","ref":"","in":"query","required":false,"desc":"Filter branded domains depending on their type (owned by user, `user`, or service domains like rebrand.ly, `service`)","default":"","type":"string","name":"type"},{"_id":"57cd83e567e1be1700c28572","ref":"","in":"query","required":false,"desc":"Sorting criteria to apply to your branded domains collection among `createdAt`, `updatedAt` and `fullName`.","default":"createdAt","type":"string","name":"orderBy"},{"_id":"57cd84111e75f217006dce1d","ref":"","in":"query","required":false,"desc":"Sorting direction to apply to your branded short links collection among `desc` and `asc`.","default":"desc","type":"string","name":"orderDir"},{"_id":"57cd84345f5adc0e0075c5dd","ref":"","in":"query","required":false,"desc":"How many branded domains to load, starting from offset on","default":"100","type":"int","name":"limit"},{"_id":"57cd842967e1be1700c28573","ref":"","in":"query","required":false,"desc":"The id of the last domain you fetched, see Infinite Scrolling section","default":"","type":"string","name":"last"},{"_id":"5926b102c385770f00113416","ref":"","in":"header","required":false,"desc":"Which workspace id to filter domains by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"results":{"codes":[{"code":"[\n {\n \"id\": \"4d20ec31db1e48c5aded19e93f137a11\",\n \"fullName\": \"brand.cool\",\n \"topLevelDomain\": \"cool\",\n \"createdAt\": \"2016-07-01T13:12:22.000Z\",\n \"updatedAt\": \"2016-07-03T13:17:50.000Z\",\n \"type\": \"user\",\n \"active\": false\n },\n ...\n]","language":"json","status":200,"name":""}]}},"excerpt":"Get a list of domains","hidden":false,"link_external":false,"project":"577d1b8b74aea422007230c4","updates":[],"category":"57cd7c3267e1be1700c2856d","order":9,"parentDoc":null,"type":"get","user":"56b22f582d96461700599230","version":"577d1b8b74aea422007230c7","__v":11,"isReference":false,"next":{"description":"","pages":[]},"sync_unique":"","body":"More details at [Listing your domains](doc:listing-your-domains-collection).","createdAt":"2016-09-05T14:39:51.819Z","githubsync":"","link_url":"","slug":"domains-list-endpoint","title":"/v1/domains","childrenPages":[]}

get/v1/domains

Get a list of domains

Query Params

active:

boolean

Filter branded domains depending on whether they can be used to brand short links or not

type:

string

Filter branded domains depending on their type (owned by user, `user`, or service domains like rebrand.ly, `service`)

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details at [Getting domain details](doc:getting-single-domain-details).

{"_id":"57cd86495f5adc0e0075c5e5","body":"More details at [Counting your domains](doc:counting-your-domains).","excerpt":"Get how many domains with given filtering conditions","isReference":false,"next":{"description":"","pages":[]},"sync_unique":"","title":"/v1/domains/count","__v":3,"hidden":false,"link_url":"","version":"577d1b8b74aea422007230c7","githubsync":"","api":{"auth":"required","examples":{"codes":[]},"method":"get","params":[{"_id":"57ce8b2a07d7ea0e00e43884","ref":"","in":"query","required":false,"desc":"Filter branded domains depending on whether they can be used to branded short links or not","default":"","type":"boolean","name":"active"},{"_id":"57ce8b2a07d7ea0e00e43883","ref":"","in":"query","required":false,"desc":"Filter branded domains depending on their type (own by `user` or `service` domains like rebrand.ly)","default":"","type":"string","name":"type"},{"_id":"5926b118c4ee340f001275de","ref":"","in":"header","required":false,"desc":"Which workspace id to filter domains by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n \"count\": 42\n}","name":""}]},"settings":"","url":"/v1/domains/count"},"category":"57cd7c3267e1be1700c2856d","createdAt":"2016-09-05T14:50:49.333Z","link_external":false,"order":11,"parentDoc":null,"project":"577d1b8b74aea422007230c4","user":"56b22f582d96461700599230","type":"get","updates":[],"slug":"count-domains-endpoint","childrenPages":[]}

get/v1/domains/count

Get how many domains with given filtering conditions

Query Params

active:

boolean

Filter branded domains depending on whether they can be used to branded short links or not

type:

string

Filter branded domains depending on their type (own by `user` or `service` domains like rebrand.ly)

Headers

workspace:

string

Which workspace id to filter domains by. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details in [Getting tag details](doc:getting-tag-details).

{"_id":"59c10ab590de33001076c0a1","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T12:16:53.573Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"settings":"","results":{"codes":[{"name":"","code":"{\n\t\"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"name\": \"promo\",\n \"color\": \"FF0044\"\n}","language":"json","status":200}]},"method":"post","auth":"required","params":[{"_id":"57cd88c667e1be1700c2857e","ref":"","in":"body","required":true,"desc":"The name you want to associated to the tag","default":"","type":"string","name":"name"},{"_id":"57cd88c667e1be1700c2857d","ref":"","in":"body","required":true,"desc":"The hexadecimal code for a color you want to assign to the tag","default":"","type":"string","name":"color"},{"_id":"5926b0c26c729e0f005959e8","ref":"","in":"header","required":false,"desc":"Which workspace id to be used to create tags. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"url":"/v1/tags"},"isReference":false,"order":4,"body":"","excerpt":"Create a new tag","slug":"create-tag-endpoint","type":"post","title":"/v1/tags","__v":3,"parentDoc":null,"childrenPages":[]}

post/v1/tags

Create a new tag

Body Params

name:

required

string

The name you want to associated to the tag

color:

required

string

The hexadecimal code for a color you want to assign to the tag

Headers

workspace:

string

Which workspace id to be used to create tags. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{"_id":"59c3892d2262d50032e94c95","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:41:01.727Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"name":"","code":"{\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"name\": \"promo\",\n \"color\": \"FF0044\"\n}","language":"json","status":200}]},"settings":"","examples":{"codes":[]},"auth":"required","params":[{"_id":"57cd88c667e1be1700c2857e","ref":"","in":"body","required":true,"desc":"The new name you want to associated to the tag","default":"","type":"string","name":"name"},{"_id":"57cd88c667e1be1700c2857d","ref":"","in":"body","required":true,"desc":"The hexadecimal code for a new color you want to assign to the tag","default":"","type":"string","name":"color"},{"_id":"5926b0c26c729e0f005959e8","ref":"","in":"header","required":false,"desc":"The workspace unique identifier of the workspace where the tag has been created. If the tag is in the main workspace, no workspace header must be specified.","default":"","type":"string","name":"workspace"},{"_id":"59c3892d2262d50032e94c96","ref":"","in":"path","required":true,"desc":"Unique identifier of the Tag resource you want to update","default":"","type":"string","name":"id"}],"url":"/v1/tags/:id"},"isReference":false,"order":5,"body":"","excerpt":"Update a tag","slug":"update-tag-endpoint","type":"post","title":"/v1/tags/:id","__v":2,"parentDoc":null,"childrenPages":[]}

post/v1/tags/:id

Update a tag

Path Params

id:

required

string

Unique identifier of the Tag resource you want to update

Body Params

name:

required

string

The new name you want to associated to the tag

color:

required

string

The hexadecimal code for a new color you want to assign to the tag

Headers

workspace:

string

The workspace unique identifier of the workspace where the tag has been created. If the tag is in the main workspace, no workspace header must be specified.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{"_id":"59c10ae6d9801400265454eb","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T12:17:42.381Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"code":"{\n \"count\": 42\n}","language":"json","status":200,"name":""}]},"method":"get","examples":{"codes":[]},"auth":"required","params":[{"_id":"5926b06721e2930f001c189d","ref":"","in":"header","required":false,"desc":"Which workspace id to filter tags by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"url":"/v1/tags/count"},"isReference":false,"order":6,"body":"More details at [Counting your tags](doc:counting-your-tags).","excerpt":"Get how many tags with given filtering conditions","slug":"count-tags-endpoint","type":"get","title":"/v1/tags/count","__v":2,"parentDoc":null,"childrenPages":[]}

get/v1/tags/count

Get how many tags with given filtering conditions

Headers

workspace:

string

Which workspace id to filter tags by. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details in [Listing your scripts](doc:listing-your-scripts)

{"_id":"59c3895ec65b90001a662398","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:41:50.493Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"name\": \"Test alert\",\n \"value\": \"<script>alert('test');</script>\"\n}","name":""}]},"method":"post","auth":"required","params":[{"_id":"57cd88c667e1be1700c2857e","ref":"","in":"body","required":true,"desc":"The new name you want to associate to the script","default":"","type":"string","name":"name"},{"_id":"57cd88c667e1be1700c2857d","ref":"","in":"body","required":true,"desc":"The new javascript snippet (including <script> and </script>) for the script","default":"","type":"string","name":"value"},{"_id":"5926b0c26c729e0f005959e8","ref":"","in":"header","required":false,"desc":"The workspace unique identifier of the workspace where the script has been created. If the script is in the main workspace, no workspace header must be specified.","default":"","type":"string","name":"workspace"},{"_id":"59c3892d2262d50032e94c96","ref":"","in":"path","required":true,"desc":"Unique identifier of the Script resource you want to update","default":"","type":"string","name":"id"}],"url":"/v1/scripts/:id"},"isReference":false,"order":10,"body":"","excerpt":"Update a script","slug":"update-script-endpoint","type":"post","title":"/v1/scripts/:id","__v":4,"parentDoc":null,"childrenPages":[]}

post/v1/scripts/:id

Update a script

Path Params

id:

required

string

Unique identifier of the Script resource you want to update

Body Params

name:

required

string

The new name you want to associate to the script

value:

required

string

The new javascript snippet (including <script> and </script>) for the script

Headers

workspace:

string

The workspace unique identifier of the workspace where the script has been created. If the script is in the main workspace, no workspace header must be specified.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details in [Getting script details](doc:getting-script-details)

{"_id":"59c3873c185f99001034e2e9","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:32:44.887Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"name":"","code":"{\n \"name\": \"Test alert\",\n \"value\": \"<script>alert('test');</script>\"\n}","language":"json","status":200}]},"settings":"","examples":{"codes":[]},"auth":"required","params":[{"_id":"57cd88c667e1be1700c2857e","ref":"","in":"body","required":true,"desc":"The name you want to associated to the script","default":"","type":"string","name":"name"},{"_id":"57cd88c667e1be1700c2857d","ref":"","in":"body","required":true,"desc":"A javascript snippet (including <script> and </script> HTML tags)","default":"","type":"string","name":"value"},{"_id":"5926b0c26c729e0f005959e8","ref":"","in":"header","required":false,"desc":"Which workspace id to be used to create scripts. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"url":"/v1/scripts"},"isReference":false,"order":12,"body":"","excerpt":"Create a new script","slug":"create-script-endpoint","type":"post","title":"/v1/scripts","__v":2,"parentDoc":null,"childrenPages":[]}

post/v1/scripts

Create a new script

Body Params

name:

required

string

The name you want to associated to the script

value:

required

string

A javascript snippet (including <script> and </script> HTML tags)

Headers

workspace:

string

Which workspace id to be used to create scripts. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{"_id":"59c38756c65b90001a662383","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:33:10.316Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"code":"{\n \"count\": 42\n}","language":"json","status":200,"name":""}]},"settings":"","auth":"required","params":[{"_id":"5926b06721e2930f001c189d","ref":"","in":"header","required":false,"desc":"Which workspace id to filter scripts by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"url":"/v1/scripts/count"},"isReference":false,"order":13,"body":"More details at [Counting your scripts](doc:counting-your-scripts)","excerpt":"Get how many scripts with given filtering conditions","slug":"count-scripts-endpoint","type":"get","title":"/v1/scripts/count","__v":4,"parentDoc":null,"childrenPages":[]}

get/v1/scripts/count

Get how many scripts with given filtering conditions

Headers

workspace:

string

Which workspace id to filter scripts by. No workspace specified will select main workspace.

Definition

{{ api_url }}{{ page_api_url }}

Result Format

More details at [Deleting a script](doc:deleting-a-script)

{"_id":"59c385fab2b45c0010b7b68e","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c38cd5b2b45c0010b7b7f4","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:27:22.018Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"get","examples":{"codes":[]},"settings":"","results":{"codes":[{"language":"json","status":200,"name":"","code":"[\n {\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"name\": \"Test alert\",\n \"uri\": \"https://s3.amazonaws.com/rb-scripts/user/abcdecc5b6ee45d6g7897b06ac2d1xyz\"\n },\n ...\n]"},{"code":"{\n \"property\": \"domain.id\",\n \"message\": \"Not found\",\n \"code\": \"NotFound\"\n}","language":"json","status":404}]},"auth":"required","params":[{"_id":"59c3859d185f99001034e276","ref":"","in":"path","required":false,"desc":"Unique identifier of the Link resource","default":"","type":"string","name":"id"},{"_id":"57cd7f134b5a7f1900899378","ref":"","in":"query","required":false,"desc":"Sorting direction to apply to your scripts collection","default":"","type":"string","name":"orderDir"},{"_id":"59c3859d185f99001034e275","ref":"","in":"query","required":false,"desc":"Sorting criteria to apply to your scripts collection. The only available option is by `name` property.","default":"","type":"string","name":"orderBy"},{"_id":"57cd7f68873de50e00724a3d","ref":"","in":"query","required":false,"desc":"How many scripts to load, starting from offset on","default":"100","type":"int","name":"limit"},{"_id":"57cd7f5b67e1be1700c2856e","ref":"","in":"query","required":false,"desc":"The id of the last script you fetched, see Infinite Scrolling section","default":"","type":"string","name":"last"},{"_id":"5926b02fc4ee340f001275dc","ref":"","in":"header","required":false,"desc":"Which workspace id to filter links by. No workspace specified will select main workspace.","default":"","type":"string","name":"workspace"}],"url":"/v1/links/:id/scripts"},"isReference":false,"order":15,"body":"[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Beware the script value\",\n \"body\": \"When you list the scripts associated to a link, we only render scripts' name and id, along with an uri where you can retrieve the script content.\"\n}\n[/block]\nMore details in [Listing your scripts](doc:listing-your-scripts)","excerpt":"Get all scripts attached to a specific link","slug":"list-scripts-of-link","type":"get","title":"/v1/links/:id/scripts","__v":10,"parentDoc":null,"childrenPages":[]}

get/v1/links/:id/scripts

Get all scripts attached to a specific link

Path Params

id:

string

Unique identifier of the Link resource

Query Params

orderDir:

string

Sorting direction to apply to your scripts collection

orderBy:

string

Sorting criteria to apply to your scripts collection. The only available option is by `name` property.

limit:

integer100

How many scripts to load, starting from offset on

last:

string

The id of the last script you fetched, see Infinite Scrolling section

Headers

workspace:

string

Which workspace id to filter links by. No workspace specified will select main workspace.

[block:callout]
{
"type": "warning",
"title": "Beware the script value",
"body": "When you list the scripts associated to a link, we only render scripts' name and id, along with an uri where you can retrieve the script content."
}
[/block]
More details in [Listing your scripts](doc:listing-your-scripts)

Definition

{{ api_url }}{{ page_api_url }}

Result Format

[block:callout]
{
"type": "warning",
"title": "Beware the script value",
"body": "When you list the scripts associated to a link, we only render scripts' name and id, along with an uri where you can retrieve the script content."
}
[/block]
More details in [Listing your scripts](doc:listing-your-scripts)

{"_id":"5a86e81d5aec8c003716b7cc","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"5791e88c4973f50e00f07683","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-16T14:18:05.209Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Every Rebrandly account has a default workspace: the Main Workspace.\nMost API calls about Links, Tags, Scripts and Domains will default to the main workspace if you don't specify a different workspace.\nSee [Get started](doc:get-started) section for info about how to specify a different workspace for resources you are going to create, edit/delete or just list.\n\nYou can create workspaces in your Rebrandly dashboard and invite teammates to collaborate. \nEach workspace will allow you to define which subset of your domains your teammates will be able to use to shorten URLs.","excerpt":"Rebrandly links, together with tags and retargeting scripts attached to them, exist in a specific Workspace (ex Team). Workspaces allow you to organize your resources and share them with your teammates.","slug":"workspaces","type":"basic","title":"Workspaces","__v":0,"parentDoc":null,"childrenPages":[]}

Workspaces

Rebrandly links, together with tags and retargeting scripts attached to them, exist in a specific Workspace (ex Team). Workspaces allow you to organize your resources and share them with your teammates.

Every Rebrandly account has a default workspace: the Main Workspace.
Most API calls about Links, Tags, Scripts and Domains will default to the main workspace if you don't specify a different workspace.
See [Get started](doc:get-started) section for info about how to specify a different workspace for resources you are going to create, edit/delete or just list.
You can create workspaces in your Rebrandly dashboard and invite teammates to collaborate.
Each workspace will allow you to define which subset of your domains your teammates will be able to use to shorten URLs.

Every Rebrandly account has a default workspace: the Main Workspace.
Most API calls about Links, Tags, Scripts and Domains will default to the main workspace if you don't specify a different workspace.
See [Get started](doc:get-started) section for info about how to specify a different workspace for resources you are going to create, edit/delete or just list.
You can create workspaces in your Rebrandly dashboard and invite teammates to collaborate.
Each workspace will allow you to define which subset of your domains your teammates will be able to use to shorten URLs.

{"_id":"5796078ef7d5760e006ee5aa","link_url":"","title":"Branded short links","type":"basic","user":"577d1b6d87acf617003c421d","githubsync":"","isReference":false,"link_external":false,"parentDoc":null,"api":{"auth":"required","params":[],"url":"","results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"category":"5791f02edaa64a0e008bc261","createdAt":"2016-07-25T12:35:26.232Z","excerpt":"","project":"577d1b8b74aea422007230c4","slug":"links-overview","sync_unique":"","version":"577d1b8b74aea422007230c7","updates":[],"__v":0,"body":"Branded short links are the main Rebrandly resource.\nLinks can be viewed [individually](doc:get-link-details) or [as a collection](doc:list-links).\nYou can [create](doc:create-a-new-link) , [update](doc:update-a-link) and [delete](doc:delete-a-link) a branded link.","hidden":false,"order":0,"childrenPages":[]}

Branded short links

Branded short links are the main Rebrandly resource.
Links can be viewed [individually](doc:get-link-details) or [as a collection](doc:list-links).
You can [create](doc:create-a-new-link) , [update](doc:update-a-link) and [delete](doc:delete-a-link) a branded link.

Branded short links are the main Rebrandly resource.
Links can be viewed [individually](doc:get-link-details) or [as a collection](doc:list-links).
You can [create](doc:create-a-new-link) , [update](doc:update-a-link) and [delete](doc:delete-a-link) a branded link.

{"_id":"5791f7d24973f50e00f0768c","project":"577d1b8b74aea422007230c4","user":"577d1b6d87acf617003c421d","excerpt":"","link_external":false,"order":3,"parentDoc":null,"slug":"get-link-details","sync_unique":"","__v":2,"category":"5791f02edaa64a0e008bc261","createdAt":"2016-07-22T10:39:14.857Z","next":{"description":"","pages":[]},"version":"577d1b8b74aea422007230c7","githubsync":"","hidden":false,"link_url":"","isReference":false,"title":"Getting link details","type":"basic","updates":["57940b817d1e4a0e00346088"],"api":{"settings":"","auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"Each Link object has its own URL: `https://api.rebrandly.com/v1/links/{id}`, where ` {id}` is the unique identifier of the branded short link.\nTo get Link object details, you should HTTP GET on the specific links endpoint, and a JSON object representing the link will be returned.\n\nIf you don't know a link's id, but you still know in which workspace it was created (if you have one single workspace, don't worry about), you can fetch it by getting the [Listing of links](doc:list-links) filtered by `domain.fullName` (which is the FQDN of the domain) and by `slashtag` of the link.\n\nE.g. if you are searching for link `https://rebrand.ly/abc`, you can filter the list by `domain.fullName=rebrand.ly` and `slashtag=abc`.\n\nWhen you specify a domain fullName (if you have the domain id, you can use `domain.id` instead) and a slashtag, the resulting list will contain exactly one link as no two links can share the same domain name and slashtag.\n\nPlease mind that it is not allowed to filter the list of links by the slashtag only: the only case when `slashtag` input is considered is when you also specify a `domain.id` parameter or a `domain.fullName` in your request.\n\n## PATH PARAMETERS\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Path parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"id\",\n \"0-1\": \"Unique identifier of the branded short link you want to get details for\"\n },\n \"cols\": 2,\n \"rows\": 1\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"GETting link details\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af' \\\\\\n-H 'apikey: YOUR_API_KEY'\",\n \"language\": \"curl\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"JSON Response (link details)\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"id\\\": \\\"fffa4cc5b6ee45d6g7897b06ac2d16af\\\",\\n \\\"title\\\": \\\"What is Rebrandly\\\",\\n \\\"slashtag\\\": \\\"video\\\",\\n \\\"destination\\\": \\\"https://www.youtube.com/watch?v=3VmtibKpmXI\\\",\\n \\\"createdAt\\\": \\\"2016-07-13T10:54:12.000Z\\\",\\n \\\"updatedAt\\\": \\\"2016-07-13T10:54:12.000Z\\\",\\n \\\"shortUrl\\\": \\\"rebrand.ly/video\\\",\\n \\\"domain\\\": {\\n \\\"id\\\": \\\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\",\\n \\\"ref\\\": \\\"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\",\\n \\\"fullName\\\": \\\"rebrand.ly\\\"\\n },\\n \\\"status\\\": \\\"active\\\",\\n \\\"favourite\\\": false\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Handling errors\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"HTTP Status\",\n \"h-1\": \"Error type\",\n \"h-2\": \"Description\",\n \"0-0\": \"404\",\n \"0-1\": \"[404 - Not found](doc:404-not-found-errors)\",\n \"0-2\": \"Given `id` does not correspond to any existing link\"\n },\n \"cols\": 3,\n \"rows\": 1\n}\n[/block]","childrenPages":[]}

Getting link details

Each Link object has its own URL: `https://api.rebrandly.com/v1/links/{id}`, where ` {id}` is the unique identifier of the branded short link.
To get Link object details, you should HTTP GET on the specific links endpoint, and a JSON object representing the link will be returned.
If you don't know a link's id, but you still know in which workspace it was created (if you have one single workspace, don't worry about), you can fetch it by getting the [Listing of links](doc:list-links) filtered by `domain.fullName` (which is the FQDN of the domain) and by `slashtag` of the link.
E.g. if you are searching for link `https://rebrand.ly/abc`, you can filter the list by `domain.fullName=rebrand.ly` and `slashtag=abc`.
When you specify a domain fullName (if you have the domain id, you can use `domain.id` instead) and a slashtag, the resulting list will contain exactly one link as no two links can share the same domain name and slashtag.
Please mind that it is not allowed to filter the list of links by the slashtag only: the only case when `slashtag` input is considered is when you also specify a `domain.id` parameter or a `domain.fullName` in your request.
## PATH PARAMETERS
[block:parameters]
{
"data": {
"h-0": "Path parameter",
"h-1": "Description",
"0-0": "id",
"0-1": "Unique identifier of the branded short link you want to get details for"
},
"cols": 2,
"rows": 1
}
[/block]
[block:textarea]
{
"text": "GETting link details",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af' \\\n-H 'apikey: YOUR_API_KEY'",
"language": "curl"
}
],
"sidebar": true
}
[/block]
[block:textarea]
{
"text": "JSON Response (link details)",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"title\": \"What is Rebrandly\",\n \"slashtag\": \"video\",\n \"destination\": \"https://www.youtube.com/watch?v=3VmtibKpmXI\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-13T10:54:12.000Z\",\n \"shortUrl\": \"rebrand.ly/video\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"ref\": \"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n },\n \"status\": \"active\",\n \"favourite\": false\n}",
"language": "json"
}
],
"sidebar": true
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Handling errors"
}
[/block]
[block:parameters]
{
"data": {
"h-0": "HTTP Status",
"h-1": "Error type",
"h-2": "Description",
"0-0": "404",
"0-1": "[404 - Not found](doc:404-not-found-errors)",
"0-2": "Given `id` does not correspond to any existing link"
},
"cols": 3,
"rows": 1
}
[/block]

Each Link object has its own URL: `https://api.rebrandly.com/v1/links/{id}`, where ` {id}` is the unique identifier of the branded short link.
To get Link object details, you should HTTP GET on the specific links endpoint, and a JSON object representing the link will be returned.
If you don't know a link's id, but you still know in which workspace it was created (if you have one single workspace, don't worry about), you can fetch it by getting the [Listing of links](doc:list-links) filtered by `domain.fullName` (which is the FQDN of the domain) and by `slashtag` of the link.
E.g. if you are searching for link `https://rebrand.ly/abc`, you can filter the list by `domain.fullName=rebrand.ly` and `slashtag=abc`.
When you specify a domain fullName (if you have the domain id, you can use `domain.id` instead) and a slashtag, the resulting list will contain exactly one link as no two links can share the same domain name and slashtag.
Please mind that it is not allowed to filter the list of links by the slashtag only: the only case when `slashtag` input is considered is when you also specify a `domain.id` parameter or a `domain.fullName` in your request.
## PATH PARAMETERS
[block:parameters]
{
"data": {
"h-0": "Path parameter",
"h-1": "Description",
"0-0": "id",
"0-1": "Unique identifier of the branded short link you want to get details for"
},
"cols": 2,
"rows": 1
}
[/block]
[block:textarea]
{
"text": "GETting link details",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af' \\\n-H 'apikey: YOUR_API_KEY'",
"language": "curl"
}
],
"sidebar": true
}
[/block]
[block:textarea]
{
"text": "JSON Response (link details)",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "{\n \"id\": \"fffa4cc5b6ee45d6g7897b06ac2d16af\",\n \"title\": \"What is Rebrandly\",\n \"slashtag\": \"video\",\n \"destination\": \"https://www.youtube.com/watch?v=3VmtibKpmXI\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-13T10:54:12.000Z\",\n \"shortUrl\": \"rebrand.ly/video\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"ref\": \"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n },\n \"status\": \"active\",\n \"favourite\": false\n}",
"language": "json"
}
],
"sidebar": true
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Handling errors"
}
[/block]
[block:parameters]
{
"data": {
"h-0": "HTTP Status",
"h-1": "Error type",
"h-2": "Description",
"0-0": "404",
"0-1": "[404 - Not found](doc:404-not-found-errors)",
"0-2": "Given `id` does not correspond to any existing link"
},
"cols": 3,
"rows": 1
}
[/block]

{"_id":"579634e73fedf00e0067acdc","type":"basic","__v":0,"api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"category":"579242d1310cb22200f6e172","isReference":false,"slug":"account-identity","title":"Account identity","updates":[],"version":"577d1b8b74aea422007230c7","body":"Accounts are designed to provide your application with an identity.\nYou can [get](doc:getting-account-details) account details at any time.","createdAt":"2016-07-25T15:48:55.820Z","link_url":"","order":0,"excerpt":"","githubsync":"","parentDoc":null,"project":"577d1b8b74aea422007230c4","sync_unique":"","hidden":false,"link_external":false,"user":"577d1b6d87acf617003c421d","childrenPages":[]}

Account identity

Accounts are designed to provide your application with an identity.
You can [get](doc:getting-account-details) account details at any time.

{"_id":"59c0e7e875aab0002627ab74","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"5792557390ad641700d46b8d","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T09:48:24.876Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Tags are used to better organize your branded links collection.\nTags can be viewed [individually](doc:getting-tag-details) or [as a collection](doc:listing-your-tags).","excerpt":"","slug":"tags","type":"basic","title":"Tags","__v":0,"parentDoc":null,"childrenPages":[]}

Tags

Tags are used to better organize your branded links collection.
Tags can be viewed [individually](doc:getting-tag-details) or [as a collection](doc:listing-your-tags).

{"_id":"59c0f5bfd98014002654509c","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"5792557390ad641700d46b8d","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T10:47:27.920Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"You can attach a Tag object to a Link object.\n\nIn order to attach a Tag to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:\n\n`https://api.rebrandly.com/v1/links/:lid/tags/:tid`, where `lid` is the Link resource's `id` property and `tid` is the Tag resource's `id` property.\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Check compatibility first\",\n \"body\": \"Double check whether your API key or OAuth token is enabled to use the Tags feature.\\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model).\"\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"Attaching a Tag to a Link\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/tags/3aehje9d536s46d59ba5bcf49b582ear' \\\\\\n-X POST \\\\\\n-H 'apikey: YOUR_API_KEY' \\\\\\n-H 'Content-Type: application/json'\\n\\nHTTP/1.1 200 OK\",\n \"language\": \"text\",\n \"name\": \"cURL\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"attaching-a-tag","type":"basic","title":"Attaching a tag","__v":0,"parentDoc":null,"childrenPages":[]}

Attaching a tag

You can attach a Tag object to a Link object.
In order to attach a Tag to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:
`https://api.rebrandly.com/v1/links/:lid/tags/:tid`, where `lid` is the Link resource's `id` property and `tid` is the Tag resource's `id` property.
[block:callout]
{
"type": "warning",
"title": "Check compatibility first",
"body": "Double check whether your API key or OAuth token is enabled to use the Tags feature.\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model)."
}
[/block]
[block:textarea]
{
"text": "Attaching a Tag to a Link",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/tags/3aehje9d536s46d59ba5bcf49b582ear' \\\n-X POST \\\n-H 'apikey: YOUR_API_KEY' \\\n-H 'Content-Type: application/json'\n\nHTTP/1.1 200 OK",
"language": "text",
"name": "cURL"
}
],
"sidebar": true
}
[/block]

You can attach a Tag object to a Link object.
In order to attach a Tag to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:
`https://api.rebrandly.com/v1/links/:lid/tags/:tid`, where `lid` is the Link resource's `id` property and `tid` is the Tag resource's `id` property.
[block:callout]
{
"type": "warning",
"title": "Check compatibility first",
"body": "Double check whether your API key or OAuth token is enabled to use the Tags feature.\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model)."
}
[/block]
[block:textarea]
{
"text": "Attaching a Tag to a Link",
"sidebar": true
}
[/block]
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/tags/3aehje9d536s46d59ba5bcf49b582ear' \\\n-X POST \\\n-H 'apikey: YOUR_API_KEY' \\\n-H 'Content-Type: application/json'\n\nHTTP/1.1 200 OK",
"language": "text",
"name": "cURL"
}
],
"sidebar": true
}
[/block]

{"_id":"59c0f85755166d00301e5abe","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"5792557390ad641700d46b8d","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T10:58:31.362Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"You can detach a Tag object from a Link object.\nWhen you delete a Tag, it is detached from all the branded links it was attached to.\n\nIn order to detach a Tag from a Link, you must first get both unique identifiers for the Link and the Tag. Once you have them, you can perform a `DELETE` API call (without body) to the association endpoint, which is composed as follow:\n\n`https://api.rebrandly.com/v1/links/:lid/tags/:tid`, where `lid` is the Link resource's `id` property and `tid` is the Tag resource's `id` property.\n\n## Path parameters\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Path parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"lid\",\n \"0-1\": \"Unique identifier of the branded short link you want the tag to be attached to\",\n \"1-0\": \"tid\",\n \"1-1\": \"Unique identifier of the tag you want to attach to this link\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"Detaching a Tag to a Link\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/tags/3aehje9d536s46d59ba5bcf49b582ear' \\\\\\n-X DELETE \\\\\\n-H 'apikey: YOUR_API_KEY' \\\\\\n-H 'Content-Type: application/json'\\n\\nHTTP/1.1 200 OK\",\n \"language\": \"text\",\n \"name\": \"cURL\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Handling errors\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"HTTP status\",\n \"h-1\": \"Error type\",\n \"h-2\": \"Description\",\n \"0-1\": \"[404 - Not found](doc:404-not-found-errors) \\nwith `property` value \\\"link.id\\\"\",\n \"0-0\": \"404\",\n \"0-2\": \"Given path parameter `lid` does not correspond to any existing link\",\n \"1-0\": \"404\",\n \"1-1\": \"[404 - Not found](doc:404-not-found-errors) \\nwith `property` value \\\"tag.id\\\"\",\n \"1-2\": \"Given path parameter `tid` does not correspond to any existing tag\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]","excerpt":"","slug":"detaching-a-tag","type":"basic","title":"Detaching a tag","__v":0,"parentDoc":null,"childrenPages":[]}

{"_id":"59c13ee42d0b430010f6502d","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c13eceeafd5b0026571219","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-19T15:59:32.876Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"You can run custom scripts at redirection time on your short links: every time someone clicks on your links, your script will run on his browser.\nSuch scripts are generally referred to as Retargeting scripts (or just scripts).\n\nScripts can be viewed [individually](doc:getting-script-details) or [as a collection](doc:listing-your-scripts).","excerpt":"","slug":"retargeting-scripts","type":"basic","title":"Retargeting scripts","__v":0,"parentDoc":null,"childrenPages":[]}

Retargeting scripts

You can run custom scripts at redirection time on your short links: every time someone clicks on your links, your script will run on his browser.
Such scripts are generally referred to as Retargeting scripts (or just scripts).
Scripts can be viewed [individually](doc:getting-script-details) or [as a collection](doc:listing-your-scripts).

You can run custom scripts at redirection time on your short links: every time someone clicks on your links, your script will run on his browser.
Such scripts are generally referred to as Retargeting scripts (or just scripts).
Scripts can be viewed [individually](doc:getting-script-details) or [as a collection](doc:listing-your-scripts).

{"_id":"59c37447b2b45c0010b7b2bc","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c13eceeafd5b0026571219","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T08:11:51.463Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"You can attach a Script object to a Link object.\nWhen someone clicks on the link, during the redirection process the script will be executed on his/her browser.\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Check compatibility first\",\n \"body\": \"Double check whether your API key or OAuth token is enabled to use the Scripts feature.\\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model).\"\n}\n[/block]\nIn order to attach a Script to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:\n\n`https://api.rebrandly.com/v1/links/:lid/scripts/:sid`, where `sid` is the Link resource's `id` property and `sid` is the Script resource's `id` property.\n\n## Path parameters\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Path parameter\",\n \"h-1\": \"Description\",\n \"0-1\": \"Unique identifier of the branded short link you want the script to be attached to\",\n \"0-0\": \"lid\",\n \"1-0\": \"sid\",\n \"1-1\": \"Unique identifier of the script you want to attach to the link\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\nAttaching a Scripts to a Link\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/scripts/3aehje9d536s46d59ba5bcf49b582ear' \\\\\\n-X POST \\\\\\n-H 'apikey: YOUR_API_KEY' \\\\\\n-H 'Content-Type: application/json'\\n\\nHTTP/1.1 200 OK\",\n \"language\": \"text\",\n \"name\": \"cURL\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"attaching-a-script","type":"basic","title":"Attaching a script","__v":0,"parentDoc":null,"childrenPages":[]}

Attaching a script

You can attach a Script object to a Link object.
When someone clicks on the link, during the redirection process the script will be executed on his/her browser.
[block:callout]
{
"type": "warning",
"title": "Check compatibility first",
"body": "Double check whether your API key or OAuth token is enabled to use the Scripts feature.\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model)."
}
[/block]
In order to attach a Script to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:
`https://api.rebrandly.com/v1/links/:lid/scripts/:sid`, where `sid` is the Link resource's `id` property and `sid` is the Script resource's `id` property.
## Path parameters
[block:parameters]
{
"data": {
"h-0": "Path parameter",
"h-1": "Description",
"0-1": "Unique identifier of the branded short link you want the script to be attached to",
"0-0": "lid",
"1-0": "sid",
"1-1": "Unique identifier of the script you want to attach to the link"
},
"cols": 2,
"rows": 2
}
[/block]
Attaching a Scripts to a Link
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/scripts/3aehje9d536s46d59ba5bcf49b582ear' \\\n-X POST \\\n-H 'apikey: YOUR_API_KEY' \\\n-H 'Content-Type: application/json'\n\nHTTP/1.1 200 OK",
"language": "text",
"name": "cURL"
}
],
"sidebar": true
}
[/block]

You can attach a Script object to a Link object.
When someone clicks on the link, during the redirection process the script will be executed on his/her browser.
[block:callout]
{
"type": "warning",
"title": "Check compatibility first",
"body": "Double check whether your API key or OAuth token is enabled to use the Scripts feature.\nFor every account, you can check for features and limits with [a preliminary API call](doc:account-model)."
}
[/block]
In order to attach a Script to a Link, you must first create both the resources and get their unique identifiers. Once you have them, you can perform a `POST` API call (without body) to the association endpoint, which is composed as follow:
`https://api.rebrandly.com/v1/links/:lid/scripts/:sid`, where `sid` is the Link resource's `id` property and `sid` is the Script resource's `id` property.
## Path parameters
[block:parameters]
{
"data": {
"h-0": "Path parameter",
"h-1": "Description",
"0-1": "Unique identifier of the branded short link you want the script to be attached to",
"0-0": "lid",
"1-0": "sid",
"1-1": "Unique identifier of the script you want to attach to the link"
},
"cols": 2,
"rows": 2
}
[/block]
Attaching a Scripts to a Link
[block:code]
{
"codes": [
{
"code": "$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/scripts/3aehje9d536s46d59ba5bcf49b582ear' \\\n-X POST \\\n-H 'apikey: YOUR_API_KEY' \\\n-H 'Content-Type: application/json'\n\nHTTP/1.1 200 OK",
"language": "text",
"name": "cURL"
}
],
"sidebar": true
}
[/block]

{"_id":"59c376e5c99a7d0010b488b4","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"59c13eceeafd5b0026571219","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T08:23:01.606Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"You can detach a Script object from a Link object.\nWhen you delete a Script, it is detached from all the branded links it was attached to.\n\nIn order to detach a Script from a Link, you must first get both unique identifiers for the Link and the Script. Once you have them, you can perform a `DELETE` API call (without body) to the association endpoint, which is composed as follow:\n\n`https://api.rebrandly.com/v1/links/:lid/scripts/:sid`, where `lid` is the Link resource's `id` property and `sid` is the Script resource's `id` property.\n\n## Path parameters\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Path parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"lid\",\n \"0-1\": \"Unique identifier of the branded short link you want the script to be attached to\",\n \"1-0\": \"sid\",\n \"1-1\": \"Unique identifier of the script you want to attach to this link\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"Detaching a Script from a Link\",\n \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/scripts/3aehje9d536s46d59ba5bcf49b582ear' \\\\\\n-X DELETE \\\\\\n-H 'apikey: YOUR_API_KEY' \\\\\\n-H 'Content-Type: application/json'\\n\\nHTTP/1.1 200 OK\",\n \"language\": \"text\",\n \"name\": \"cURL\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"Handling errors\"\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"HTTP status\",\n \"h-1\": \"Error type\",\n \"h-2\": \"Description\",\n \"0-1\": \"[404 - Not found](doc:404-not-found-errors) \\nwith `property` value \\\"link.id\\\"\",\n \"0-0\": \"404\",\n \"0-2\": \"Given path parameter `lid` does not correspond to any existing link\",\n \"1-0\": \"404\",\n \"1-1\": \"[404 - Not found](doc:404-not-found-errors) \\nwith `property` value \\\"script.id\\\"\",\n \"1-2\": \"Given path parameter `sid` does not correspond to any existing script\"\n },\n \"cols\": 3,\n \"rows\": 2\n}\n[/block]","excerpt":"","slug":"detaching-a-script","type":"basic","title":"Detaching a script","__v":0,"parentDoc":null,"childrenPages":[]}

{"_id":"57971ad2acc0bb0e0033358b","githubsync":"","hidden":false,"slug":"resource-collections","version":"577d1b8b74aea422007230c7","category":"577d2b505fd4de0e00cc3e09","link_external":false,"link_url":"","sync_unique":"","type":"basic","api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[]},"order":0,"project":"577d1b8b74aea422007230c4","title":"Resource collections","updates":[],"__v":0,"body":"Your branded short links and branded domains are arranged by **collections**. \nA collection can contain as many elements as your Rebrandly plan allows, or can be empty.","createdAt":"2016-07-26T08:09:54.900Z","excerpt":"","isReference":false,"parentDoc":null,"user":"577d1b6d87acf617003c421d","childrenPages":[]}

Resource collections

Your branded short links and branded domains are arranged by **collections**.
A collection can contain as many elements as your Rebrandly plan allows, or can be empty.

Your branded short links and branded domains are arranged by **collections**.
A collection can contain as many elements as your Rebrandly plan allows, or can be empty.

{"_id":"5790ea9af7ff000e004ba3e6","hidden":false,"parentDoc":null,"slug":"understanding-pagination","updates":["5793e4e90b4ca20e00beaa2e","5793e590514c7b0e00e17c3e"],"version":"577d1b8b74aea422007230c7","category":"577d2b505fd4de0e00cc3e09","sync_unique":"","title":"Paginating collections","order":1,"createdAt":"2016-07-21T15:30:34.698Z","excerpt":"","isReference":false,"link_url":"","user":"577d1b6d87acf617003c421d","__v":3,"api":{"auth":"required","params":[],"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":""},"body":"You cannot list/download all of your collection's resources at once: there can be too many. \nSo we provided you with standard scrolling features: as soon as you finish fetching a set of resources, you can trigger a second API call to fetch next resources according to the ordering configuration you are using in the request, then a third API call and so on.\n\nThe largest possible set of resources returned at one contains up to 100 resources and it's the default choice we provide to you. This means that if you have less than 100 resources in a collection, you don't have to worry about resources scrolling at all. However, when you have more than 100 resources in a collection, you'll need to download first 100 and then ask for resources from 101 to 200, and so on with 201 to 300 up to the totality of your resources.\n\nResponses to listing endpoint are ordered lists of resources, according to sorting criteria and sorting direction. \nIf a request wasn't specifying any criteria and any direction (see [Sorting collections](doc:understanding-sorting)), default values apply for sorting, depending on the collection's nature.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Limiting resources per request\"\n}\n[/block]\nA `limit` parameter is provided in all endpoints returning a collection of resources.\nSuch parameter is valued 100 (maximum) as default, but you can change with smaller values if you want your collection to be returned in more batches.\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"Please mind we reserve the ability to change anytime the maximum number of resources returned in a single listing request.\",\n \"title\": \"Do not rely on max limit\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Getting other resources\"\n}\n[/block]\nA `last` parameter is provided in all endpoints returning a collection of resources.\nSuch parameter is not valued by default, but you can change it with the last id you fetched from the previous API listing request so that the current API request will return next set of resources according to the sorting criteria and direction you specified, starting from `last` (excluded) onward.","githubsync":"","link_external":false,"project":"577d1b8b74aea422007230c4","type":"basic","next":{"description":"","pages":[]},"childrenPages":[]}

Paginating collections

You cannot list/download all of your collection's resources at once: there can be too many.
So we provided you with standard scrolling features: as soon as you finish fetching a set of resources, you can trigger a second API call to fetch next resources according to the ordering configuration you are using in the request, then a third API call and so on.
The largest possible set of resources returned at one contains up to 100 resources and it's the default choice we provide to you. This means that if you have less than 100 resources in a collection, you don't have to worry about resources scrolling at all. However, when you have more than 100 resources in a collection, you'll need to download first 100 and then ask for resources from 101 to 200, and so on with 201 to 300 up to the totality of your resources.
Responses to listing endpoint are ordered lists of resources, according to sorting criteria and sorting direction.
If a request wasn't specifying any criteria and any direction (see [Sorting collections](doc:understanding-sorting)), default values apply for sorting, depending on the collection's nature.
[block:api-header]
{
"type": "basic",
"title": "Limiting resources per request"
}
[/block]
A `limit` parameter is provided in all endpoints returning a collection of resources.
Such parameter is valued 100 (maximum) as default, but you can change with smaller values if you want your collection to be returned in more batches.
[block:callout]
{
"type": "warning",
"body": "Please mind we reserve the ability to change anytime the maximum number of resources returned in a single listing request.",
"title": "Do not rely on max limit"
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Getting other resources"
}
[/block]
A `last` parameter is provided in all endpoints returning a collection of resources.
Such parameter is not valued by default, but you can change it with the last id you fetched from the previous API listing request so that the current API request will return next set of resources according to the sorting criteria and direction you specified, starting from `last` (excluded) onward.

You cannot list/download all of your collection's resources at once: there can be too many.
So we provided you with standard scrolling features: as soon as you finish fetching a set of resources, you can trigger a second API call to fetch next resources according to the ordering configuration you are using in the request, then a third API call and so on.
The largest possible set of resources returned at one contains up to 100 resources and it's the default choice we provide to you. This means that if you have less than 100 resources in a collection, you don't have to worry about resources scrolling at all. However, when you have more than 100 resources in a collection, you'll need to download first 100 and then ask for resources from 101 to 200, and so on with 201 to 300 up to the totality of your resources.
Responses to listing endpoint are ordered lists of resources, according to sorting criteria and sorting direction.
If a request wasn't specifying any criteria and any direction (see [Sorting collections](doc:understanding-sorting)), default values apply for sorting, depending on the collection's nature.
[block:api-header]
{
"type": "basic",
"title": "Limiting resources per request"
}
[/block]
A `limit` parameter is provided in all endpoints returning a collection of resources.
Such parameter is valued 100 (maximum) as default, but you can change with smaller values if you want your collection to be returned in more batches.
[block:callout]
{
"type": "warning",
"body": "Please mind we reserve the ability to change anytime the maximum number of resources returned in a single listing request.",
"title": "Do not rely on max limit"
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Getting other resources"
}
[/block]
A `last` parameter is provided in all endpoints returning a collection of resources.
Such parameter is not valued by default, but you can change it with the last id you fetched from the previous API listing request so that the current API request will return next set of resources according to the sorting criteria and direction you specified, starting from `last` (excluded) onward.

{"_id":"5790f0f2f7ff000e004ba3ec","title":"Sorting collections","updates":["5793eaf87d1e4a0e0034607f"],"__v":1,"api":{"url":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[]},"category":"577d2b505fd4de0e00cc3e09","createdAt":"2016-07-21T15:57:38.895Z","link_url":"","excerpt":"","project":"577d1b8b74aea422007230c4","slug":"understanding-sorting","user":"577d1b6d87acf617003c421d","githubsync":"","isReference":false,"order":2,"type":"basic","version":"577d1b8b74aea422007230c7","body":"A collection of resources can be sorted (either descending or ascending) according to a given criteria.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Sorting criteria\"\n}\n[/block]\nSorting criteria is the sorting mode to be applied on a collection *before* pagination (see [Understanding Pagination](doc:understanding-pagination)) applies.\n\nEvery resource collection management endpoint comes with an `orderBy` parameter used to define which sorting criteria has to be applied.\n\nExamples of an `orderBy` parameter's possible values are: `createdAt` (to sort by creation datetime), `updatedAt` (to sort by last update date/time) and so on.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Sorting direction\"\n}\n[/block]\nSorting direction is the direction, according to sorting criteria, to be applied on a collection *before* pagination applies. The only two possible directions are \"ascending\" (from first to last) and \"descending\" (from last to first).\n\nEvery resource collection management endpoint comes with an `orderDir` parameter used to define which sorting direction has to be applied.\nPossible values for `orderDir` are `asc` (ascending) and `desc` (descending).\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Combining sorting criteria\"\n}\n[/block]\nTo exploit the full power of sorting criteria, it is possible to combine two sorting criteria together:\n\n*First, sort by descending X, then sort by ascending Y if X subsequent X values are equal*,\ncan be obtained by assigning `orderBy` parameter value `X,Y` and by assigning `orderDir` parameter value `desc,asc`.","hidden":false,"link_external":false,"parentDoc":null,"sync_unique":"","childrenPages":[]}

Sorting collections

A collection of resources can be sorted (either descending or ascending) according to a given criteria.
[block:api-header]
{
"type": "basic",
"title": "Sorting criteria"
}
[/block]
Sorting criteria is the sorting mode to be applied on a collection *before* pagination (see [Understanding Pagination](doc:understanding-pagination)) applies.
Every resource collection management endpoint comes with an `orderBy` parameter used to define which sorting criteria has to be applied.
Examples of an `orderBy` parameter's possible values are: `createdAt` (to sort by creation datetime), `updatedAt` (to sort by last update date/time) and so on.
[block:api-header]
{
"type": "basic",
"title": "Sorting direction"
}
[/block]
Sorting direction is the direction, according to sorting criteria, to be applied on a collection *before* pagination applies. The only two possible directions are "ascending" (from first to last) and "descending" (from last to first).
Every resource collection management endpoint comes with an `orderDir` parameter used to define which sorting direction has to be applied.
Possible values for `orderDir` are `asc` (ascending) and `desc` (descending).
[block:api-header]
{
"type": "basic",
"title": "Combining sorting criteria"
}
[/block]
To exploit the full power of sorting criteria, it is possible to combine two sorting criteria together:
*First, sort by descending X, then sort by ascending Y if X subsequent X values are equal*,
can be obtained by assigning `orderBy` parameter value `X,Y` and by assigning `orderDir` parameter value `desc,asc`.

A collection of resources can be sorted (either descending or ascending) according to a given criteria.
[block:api-header]
{
"type": "basic",
"title": "Sorting criteria"
}
[/block]
Sorting criteria is the sorting mode to be applied on a collection *before* pagination (see [Understanding Pagination](doc:understanding-pagination)) applies.
Every resource collection management endpoint comes with an `orderBy` parameter used to define which sorting criteria has to be applied.
Examples of an `orderBy` parameter's possible values are: `createdAt` (to sort by creation datetime), `updatedAt` (to sort by last update date/time) and so on.
[block:api-header]
{
"type": "basic",
"title": "Sorting direction"
}
[/block]
Sorting direction is the direction, according to sorting criteria, to be applied on a collection *before* pagination applies. The only two possible directions are "ascending" (from first to last) and "descending" (from last to first).
Every resource collection management endpoint comes with an `orderDir` parameter used to define which sorting direction has to be applied.
Possible values for `orderDir` are `asc` (ascending) and `desc` (descending).
[block:api-header]
{
"type": "basic",
"title": "Combining sorting criteria"
}
[/block]
To exploit the full power of sorting criteria, it is possible to combine two sorting criteria together:
*First, sort by descending X, then sort by ascending Y if X subsequent X values are equal*,
can be obtained by assigning `orderBy` parameter value `X,Y` and by assigning `orderDir` parameter value `desc,asc`.

{"_id":"579228ea310cb22200f6e153","slug":"understanding-responses","version":"577d1b8b74aea422007230c7","body":"Each API endpoint has its own response model.","createdAt":"2016-07-22T14:08:42.111Z","link_url":"","parentDoc":null,"title":"Handling errors","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"githubsync":"","isReference":false,"project":"577d1b8b74aea422007230c4","type":"basic","user":"577d1b6d87acf617003c421d","excerpt":"","hidden":false,"order":0,"sync_unique":"","updates":["5793e112514c7b0e00e17c3c","579653a75fe9610e00d8a8bd"],"__v":2,"category":"579619c5cf84ae1700244f1c","link_external":false,"childrenPages":[]}

{"_id":"59c37f382262d50032e94c07","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"579619c5cf84ae1700244f1c","user":"577d1b6d87acf617003c421d","updates":["5b97569ef5247d00039f82ce"],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T08:58:32.980Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"A `400 - Bad Request` error occurs when you send to Rebrandly API a `POST` or `PUT` API call without a JSON body inside. All such requests must provide a JSON: if the endpoint does not require a specific body to be specified, you are supposed to forward an empty JSON body (`{}`) along with the request.\n\nExample generic error\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"\\\"Body required.\\\"\",\n \"language\": \"text\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"400-bad-request","type":"basic","title":"400 - Bad Request","__v":1,"parentDoc":null,"childrenPages":[]}

400 - Bad Request

A `400 - Bad Request` error occurs when you send to Rebrandly API a `POST` or `PUT` API call without a JSON body inside. All such requests must provide a JSON: if the endpoint does not require a specific body to be specified, you are supposed to forward an empty JSON body (`{}`) along with the request.
Example generic error
[block:code]
{
"codes": [
{
"code": "\"Body required.\"",
"language": "text"
}
],
"sidebar": true
}
[/block]

A `400 - Bad Request` error occurs when you send to Rebrandly API a `POST` or `PUT` API call without a JSON body inside. All such requests must provide a JSON: if the endpoint does not require a specific body to be specified, you are supposed to forward an empty JSON body (`{}`) along with the request.
Example generic error
[block:code]
{
"codes": [
{
"code": "\"Body required.\"",
"language": "text"
}
],
"sidebar": true
}
[/block]

{"_id":"59c37cf8b2b45c0010b7b4f1","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"579619c5cf84ae1700244f1c","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T08:48:56.598Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"A `429 - Too Many Requests` error indicates that you exceeded the allowed API rate your account is allowed to reach.\n\nWe have per-second rate checking, you are allowed to perform up to 10 API calls per second in a classic Rebrandly account.","excerpt":"","slug":"429-too-many-requests","type":"basic","title":"429 - Too Many Requests","__v":0,"parentDoc":null,"childrenPages":[]}

429 - Too Many Requests

A `429 - Too Many Requests` error indicates that you exceeded the allowed API rate your account is allowed to reach.
We have per-second rate checking, you are allowed to perform up to 10 API calls per second in a classic Rebrandly account.

A `429 - Too Many Requests` error indicates that you exceeded the allowed API rate your account is allowed to reach.
We have per-second rate checking, you are allowed to perform up to 10 API calls per second in a classic Rebrandly account.

{"_id":"59c3814fc65b90001a6622de","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"579619c5cf84ae1700244f1c","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:07:27.263Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"A `502 - Bad Gateway` occurs when one of the upstream providers Rebrandly relies on is under maintenance or is experiencing a downtime.","excerpt":"","slug":"502-bad-gateway","type":"basic","title":"502 - Bad Gateway","__v":0,"parentDoc":null,"childrenPages":[]}

502 - Bad Gateway

A `502 - Bad Gateway` occurs when one of the upstream providers Rebrandly relies on is under maintenance or is experiencing a downtime.

{"_id":"59c38350c65b90001a66232e","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"579619c5cf84ae1700244f1c","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-21T09:16:00.343Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"A `504 - Gateway Timeout` occurs when Rebrandly API is not reachable or when an API operation is taking more than expected to be completed.\nThis generally resembles a buggy behavior, please report to us.","excerpt":"","slug":"504-gateway-timeout","type":"basic","title":"504 - Gateway Timeout","__v":0,"parentDoc":null,"childrenPages":[]}

504 - Gateway Timeout

A `504 - Gateway Timeout` occurs when Rebrandly API is not reachable or when an API operation is taking more than expected to be completed.
This generally resembles a buggy behavior, please report to us.

A `504 - Gateway Timeout` occurs when Rebrandly API is not reachable or when an API operation is taking more than expected to be completed.
This generally resembles a buggy behavior, please report to us.

Authentication overview

All requests to Rebrandly API need to be authenticated.
We currently support:
- [API Key mode](doc:api-key-authentication)
- [OAuth mode](doc:request-api-access)

{"_id":"57bdd47add496f0e0004c006","sync_unique":"","type":"basic","__v":1,"category":"57bdd4aa0fe3a00e003e2d22","createdAt":"2016-08-24T17:08:10.057Z","excerpt":"","link_external":false,"project":"577d1b8b74aea422007230c4","githubsync":"","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"link_url":"","order":1,"updates":[],"version":"577d1b8b74aea422007230c7","user":"56b22f582d96461700599230","body":"Create a new API key for your application/script in <a href=\"https://app.rebrandly.com/account/api-keys\" target=\"_blank\">your Rebrandly dashboard</a>.\n\nYou have three ways to include API key in your HTTP requests:\n- Specifying an HTTP header\n- Specifying an HTTP query parameter\n- Specifying an HTTP body parameter\n\nIn all cases, parameter name must be `apikey` and parameter value is `YOUR_API_KEY`.\nAll examples in this documentation include API Key authentication via HTTP header.","hidden":false,"parentDoc":null,"slug":"api-key-authentication","title":"API Key","next":{"description":"","pages":[]},"childrenPages":[]}

API Key

Create a new API key for your application/script in <a href="https://app.rebrandly.com/account/api-keys" target="_blank">your Rebrandly dashboard</a>.
You have three ways to include API key in your HTTP requests:
- Specifying an HTTP header
- Specifying an HTTP query parameter
- Specifying an HTTP body parameter
In all cases, parameter name must be `apikey` and parameter value is `YOUR_API_KEY`.
All examples in this documentation include API Key authentication via HTTP header.

Create a new API key for your application/script in <a href="https://app.rebrandly.com/account/api-keys" target="_blank">your Rebrandly dashboard</a>.
You have three ways to include API key in your HTTP requests:
- Specifying an HTTP header
- Specifying an HTTP query parameter
- Specifying an HTTP body parameter
In all cases, parameter name must be `apikey` and parameter value is `YOUR_API_KEY`.
All examples in this documentation include API Key authentication via HTTP header.

{"_id":"577e6147c7b5c50e00a70a63","user":"577d1b6d87acf617003c421d","excerpt":"","isReference":false,"__v":96,"sync_unique":"","version":"577d1b8b74aea422007230c7","createdAt":"2016-07-07T14:03:51.224Z","hidden":false,"link_external":false,"order":2,"api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"**IMPORTANT**: you don't need to implement an OAuth flow if you know the API key of the Rebrandly account. If you are using Rebrandly API with your own Rebrandly account, it's lot easier to use an [API Key](doc:api-key-authentication) than to use an OAuth flow.\n\nIf you want to use the Rebrandly API in your app on behalf of a Rebrandly account, you need to authorize your application.\nYou can submit your authorization request at <a target=\"_blank\" href=\"http://rebrand.ly/AuthorizeMe\">Rebrand.ly/AuthorizeMe</a>. \n\nWhen you authorize a new app in Rebrandly, a `client_id` is assigned to it. \nThat's enough to let your app users connect with their Rebrandly accounts:\nif your users happen not to have a Rebrandly account, they will be able to register a new account from the same page and then get back to you. \n\nYou can either search for an OAuth client in your favorite programming language or you can configure your own HTTP calls.\n\nIf the following standard OAuth flow doesn't fit your needs, we can arrange together for another OAuth flow.\n\n## Using an OAuth client\n\nThere are <a href='http://oauth.net/2/' target='_blank'>plenty of OAuth clients</a> you can include in your application to get the authorization job done for you.\n\n## Configuring a basic OAuth flow\n\nIf you need to take control over the http flow, here's how to manually setup the authentication process.\nIn order to get a valid token, you have to redirect your users to `https://oauth.rebrandly.com/connect/authorize` with the following query parameters:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"client_id\",\n \"0-1\": \"The unique Client ID associated with your app.\",\n \"1-0\": \"redirect_uri\",\n \"1-1\": \"This is the callback to your app you asked to be authorized in your request. You can ask us to change it anytime.\",\n \"2-0\": \"response_type\",\n \"2-1\": \"This should be always `token`.\",\n \"3-0\": \"scope\",\n \"3-1\": \"This should be always `rbapi`.\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\nA full URL would be like: `https://oauth.rebrandly.com/connect/authorize` with parameters `?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=token&scope=rbapi`.\n\nYour users will compile the <a href='https://www.rebrandly.com/login' target='_blank'>Rebrandly Signin form</a> and we will send them back to you via GET HTTP method ([What if I need HTTP POST?](doc:authentication)) at the `redirect_uri` you provided in the request, with the token in URL:\n\n`http://yourapp.com/#access_token=YOUR_TOKEN&token_type=Bearer&expires_in=2592000&scope=rbapi`\n\n## Authenticate requests with OAuth\n\nNow that you have a valid token, you need to add this HTTP header **in all future API requests** to `https://api.rebrandly.com`: \n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Header name\",\n \"h-1\": \"Header value\",\n \"0-0\": \"Authorization\",\n \"0-1\": \"\\\"Bearer YOUR_TOKEN\\\"\\n(`Bearer` - or in general your token type -, then a white space, then the token)\"\n },\n \"cols\": 2,\n \"rows\": 1\n}\n[/block]\nYet another cURL example:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl \\\\\\n-H \\\"Authorization: Bearer YOUR_TOKEN\\\" \\\\\\n'https://api.rebrandly.com/v1/account'\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]","category":"57bdd4aa0fe3a00e003e2d22","parentDoc":null,"project":"577d1b8b74aea422007230c4","slug":"request-api-access","title":"OAuth flow","type":"basic","githubsync":"","link_url":"","next":{"pages":[],"description":""},"updates":["57925cbb4973f50e00f0770e","5792b6b390ad641700d46bd2","5a4e4f6ad9329a001e3245d9"],"childrenPages":[]}

OAuth flow

**IMPORTANT**: you don't need to implement an OAuth flow if you know the API key of the Rebrandly account. If you are using Rebrandly API with your own Rebrandly account, it's lot easier to use an [API Key](doc:api-key-authentication) than to use an OAuth flow.
If you want to use the Rebrandly API in your app on behalf of a Rebrandly account, you need to authorize your application.
You can submit your authorization request at <a target="_blank" href="http://rebrand.ly/AuthorizeMe">Rebrand.ly/AuthorizeMe</a>.
When you authorize a new app in Rebrandly, a `client_id` is assigned to it.
That's enough to let your app users connect with their Rebrandly accounts:
if your users happen not to have a Rebrandly account, they will be able to register a new account from the same page and then get back to you.
You can either search for an OAuth client in your favorite programming language or you can configure your own HTTP calls.
If the following standard OAuth flow doesn't fit your needs, we can arrange together for another OAuth flow.
## Using an OAuth client
There are <a href='http://oauth.net/2/' target='_blank'>plenty of OAuth clients</a> you can include in your application to get the authorization job done for you.
## Configuring a basic OAuth flow
If you need to take control over the http flow, here's how to manually setup the authentication process.
In order to get a valid token, you have to redirect your users to `https://oauth.rebrandly.com/connect/authorize` with the following query parameters:
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"0-0": "client_id",
"0-1": "The unique Client ID associated with your app.",
"1-0": "redirect_uri",
"1-1": "This is the callback to your app you asked to be authorized in your request. You can ask us to change it anytime.",
"2-0": "response_type",
"2-1": "This should be always `token`.",
"3-0": "scope",
"3-1": "This should be always `rbapi`."
},
"cols": 2,
"rows": 4
}
[/block]
A full URL would be like: `https://oauth.rebrandly.com/connect/authorize` with parameters `?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=token&scope=rbapi`.
Your users will compile the <a href='https://www.rebrandly.com/login' target='_blank'>Rebrandly Signin form</a> and we will send them back to you via GET HTTP method ([What if I need HTTP POST?](doc:authentication)) at the `redirect_uri` you provided in the request, with the token in URL:
`http://yourapp.com/#access_token=YOUR_TOKEN&token_type=Bearer&expires_in=2592000&scope=rbapi`
## Authenticate requests with OAuth
Now that you have a valid token, you need to add this HTTP header **in all future API requests** to `https://api.rebrandly.com`:
[block:parameters]
{
"data": {
"h-0": "Header name",
"h-1": "Header value",
"0-0": "Authorization",
"0-1": "\"Bearer YOUR_TOKEN\"\n(`Bearer` - or in general your token type -, then a white space, then the token)"
},
"cols": 2,
"rows": 1
}
[/block]
Yet another cURL example:
[block:code]
{
"codes": [
{
"code": "curl \\\n-H \"Authorization: Bearer YOUR_TOKEN\" \\\n'https://api.rebrandly.com/v1/account'",
"language": "curl"
}
]
}
[/block]

**IMPORTANT**: you don't need to implement an OAuth flow if you know the API key of the Rebrandly account. If you are using Rebrandly API with your own Rebrandly account, it's lot easier to use an [API Key](doc:api-key-authentication) than to use an OAuth flow.
If you want to use the Rebrandly API in your app on behalf of a Rebrandly account, you need to authorize your application.
You can submit your authorization request at <a target="_blank" href="http://rebrand.ly/AuthorizeMe">Rebrand.ly/AuthorizeMe</a>.
When you authorize a new app in Rebrandly, a `client_id` is assigned to it.
That's enough to let your app users connect with their Rebrandly accounts:
if your users happen not to have a Rebrandly account, they will be able to register a new account from the same page and then get back to you.
You can either search for an OAuth client in your favorite programming language or you can configure your own HTTP calls.
If the following standard OAuth flow doesn't fit your needs, we can arrange together for another OAuth flow.
## Using an OAuth client
There are <a href='http://oauth.net/2/' target='_blank'>plenty of OAuth clients</a> you can include in your application to get the authorization job done for you.
## Configuring a basic OAuth flow
If you need to take control over the http flow, here's how to manually setup the authentication process.
In order to get a valid token, you have to redirect your users to `https://oauth.rebrandly.com/connect/authorize` with the following query parameters:
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"0-0": "client_id",
"0-1": "The unique Client ID associated with your app.",
"1-0": "redirect_uri",
"1-1": "This is the callback to your app you asked to be authorized in your request. You can ask us to change it anytime.",
"2-0": "response_type",
"2-1": "This should be always `token`.",
"3-0": "scope",
"3-1": "This should be always `rbapi`."
},
"cols": 2,
"rows": 4
}
[/block]
A full URL would be like: `https://oauth.rebrandly.com/connect/authorize` with parameters `?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=token&scope=rbapi`.
Your users will compile the <a href='https://www.rebrandly.com/login' target='_blank'>Rebrandly Signin form</a> and we will send them back to you via GET HTTP method ([What if I need HTTP POST?](doc:authentication)) at the `redirect_uri` you provided in the request, with the token in URL:
`http://yourapp.com/#access_token=YOUR_TOKEN&token_type=Bearer&expires_in=2592000&scope=rbapi`
## Authenticate requests with OAuth
Now that you have a valid token, you need to add this HTTP header **in all future API requests** to `https://api.rebrandly.com`:
[block:parameters]
{
"data": {
"h-0": "Header name",
"h-1": "Header value",
"0-0": "Authorization",
"0-1": "\"Bearer YOUR_TOKEN\"\n(`Bearer` - or in general your token type -, then a white space, then the token)"
},
"cols": 2,
"rows": 1
}
[/block]
Yet another cURL example:
[block:code]
{
"codes": [
{
"code": "curl \\\n-H \"Authorization: Bearer YOUR_TOKEN\" \\\n'https://api.rebrandly.com/v1/account'",
"language": "curl"
}
]
}
[/block]

Examples

{"_id":"577d23925fd4de0e00cc3de5","slug":"create-your-first-link","title":"Rebrand your first link","user":"577d1b6d87acf617003c421d","createdAt":"2016-07-06T15:28:18.091Z","isReference":false,"next":{"pages":[],"description":""},"parentDoc":null,"type":"basic","version":"577d1b8b74aea422007230c7","__v":36,"api":{"auth":"required","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"link_url":"","updates":["579404ce514c7b0e00e17c4a"],"category":"577d22a35fd4de0e00cc3ddd","link_external":false,"order":1,"githubsync":"","hidden":false,"project":"577d1b8b74aea422007230c4","sync_unique":"","body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Prerequisites\"\n}\n[/block]\n * You have already created a Rebrandly account\n If you have not, please read the [Signup to Rebrandly guide](doc:getting-started).\n\n * You already have an API KEY to authenticate your API requests\n If you don't know how to authenticate your API requests, please read the [Authentication guide](doc:request-api-access) documentation\n\n * You understood what a branded short link is and how it is represented as an API\n If you have not, please read [Branded short link model](doc:link-entity)\n\n* You understood what a branded domain is and how it is related to a branded short link\nIf you have not, please read [Branded domain model](doc:branded-domain-model)\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Creating a new branded short link\"\n}\n[/block]\nIn order to create a new Link entity, you should first decide what content to rebrand and how you want the final branded short link to look like.\n\nQuick example of rebranding a link with the 'rebrand.ly' default domain: every account can use the 'rebrand.ly' default.\nLet's say we want to shorten [https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/](https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/) to become [http://rebrand.ly/burn10M](http://rebrand.ly/burn10M).\n\nWell, the domain id of rebrand.ly is `8f104cc5b6ee4a4ba7897b06ac2ddcfb`, but since rebrand.ly is the default domain for every Rebrandly account, we can choose to not specify the domain while creating a new link. This is up to the user.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Where do I get that branded domain \\\"id\\\"?\",\n \"body\": \"Every time you add a new branded domain in Rebrandly, it is associated with a unique identifier. If you want to create a link with your own custom branded domain, instead of the default rebrand.ly domain, you should [list your domains](doc:listing-your-domains-collection) in order to get each domain's id.\"\n}\n[/block]\nCorrespondent Link object is:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"title\\\": \\\"How to burn 10M\\\",\\n \\\"slashtag\\\": \\\"burn10M\\\",\\n\\t\\\"destination\\\": \\\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\\\",\\n \\\"domain\\\": {\\n \\\"id\\\": \\\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Test with a different slashtag!\",\n \"body\": \"**NOTE**: for your personal tests, you should choose another `slashtag`, because the one used for this demo is already used.\"\n}\n[/block]\nNow we have to send our Link entity to Rebrandly API.\nThe endpoint to do this is `/links` (see [how to create a new link](doc:create-a-new-link)).\nAn HTTP POST request to `https://api.rebrandly.com/v1/links` will create the link:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl \\\\\\n -H 'apikey: YOUR_API_KEY' \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -X POST -d '\\n {\\n \\t\\\"slashtag\\\":\\\"burn10M\\\",\\n \\\"title\\\":\\\"How to burn 10M\\\",\\n \\\"domain\\\": {\\t\\n \\t\\\"id\\\":\\\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\"\\n },\\n \\\"destination\\\":\\\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\\\"\\n }' \\\\\\n 'https://api.rebrandly.com/v1/links'\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nOr, without the domain part (because the domain is rebrand.ly, the default domain):\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl \\n -H 'apikey: YOUR_API_KEY' \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -X POST -d \\\\\\n '{\\n \\t\\\"slashtag\\\":\\\"burn10M\\\",\\n \\\"title\\\":\\\"How to burn 10M\\\",\\n \\\"destination\\\":\\\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\\\"\\n }' \\\\\\n 'https://api.rebrandly.com/v1/links'\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nIf everything works properly, you will get back the Link entity you just created:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \" {\\n \\\"id\\\": \\\"ffs24cc5b6ee4a5gh7897b06ac2d16d4\\\",\\n \\\"title\\\": \\\"The LaFerrari Supercar Convertible Is the New Best Way to Burn $1M | WIRED\\\",\\n \\\"slashtag\\\": \\\"burn10M\\\",\\n \\\"destination\\\": \\\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\\\",\\n \\\"createdAt\\\": \\\"2016-07-13T10:54:12.000Z\\\",\\n \\\"updatedAt\\\": \\\"2016-07-13T10:54:12.000Z\\\",\\n \\\"shortUrl\\\": \\\"rebrand.ly/burn10M\\\",\\n \\\"domain\\\": {\\n \\\"id\\\": \\\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\",\\n \\\"ref\\\": \\\"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\\\",\\n \\\"fullName\\\": \\\"rebrand.ly\\\"\\n },\\n ...\\n }\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Testing your branded short link\"\n}\n[/block]\nJust click on <a href=\"http://rebrand.ly/burn10M\" target=\"_blank\">http://rebrand.ly/burn10M</a> to test it: you should be redirected to the destination url within milliseconds.\nWeird, right?","excerpt":"How to rebrand your first link with API","childrenPages":[]}

Rebrand your first link

How to rebrand your first link with API

[block:api-header]
{
"type": "basic",
"title": "Prerequisites"
}
[/block]
* You have already created a Rebrandly account
If you have not, please read the [Signup to Rebrandly guide](doc:getting-started).
* You already have an API KEY to authenticate your API requests
If you don't know how to authenticate your API requests, please read the [Authentication guide](doc:request-api-access) documentation
* You understood what a branded short link is and how it is represented as an API
If you have not, please read [Branded short link model](doc:link-entity)
* You understood what a branded domain is and how it is related to a branded short link
If you have not, please read [Branded domain model](doc:branded-domain-model)
[block:api-header]
{
"type": "basic",
"title": "Creating a new branded short link"
}
[/block]
In order to create a new Link entity, you should first decide what content to rebrand and how you want the final branded short link to look like.
Quick example of rebranding a link with the 'rebrand.ly' default domain: every account can use the 'rebrand.ly' default.
Let's say we want to shorten [https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/](https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/) to become [http://rebrand.ly/burn10M](http://rebrand.ly/burn10M).
Well, the domain id of rebrand.ly is `8f104cc5b6ee4a4ba7897b06ac2ddcfb`, but since rebrand.ly is the default domain for every Rebrandly account, we can choose to not specify the domain while creating a new link. This is up to the user.
[block:callout]
{
"type": "info",
"title": "Where do I get that branded domain \"id\"?",
"body": "Every time you add a new branded domain in Rebrandly, it is associated with a unique identifier. If you want to create a link with your own custom branded domain, instead of the default rebrand.ly domain, you should [list your domains](doc:listing-your-domains-collection) in order to get each domain's id."
}
[/block]
Correspondent Link object is:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"How to burn 10M\",\n \"slashtag\": \"burn10M\",\n\t\"destination\": \"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\"\n }\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Test with a different slashtag!",
"body": "**NOTE**: for your personal tests, you should choose another `slashtag`, because the one used for this demo is already used."
}
[/block]
Now we have to send our Link entity to Rebrandly API.
The endpoint to do this is `/links` (see [how to create a new link](doc:create-a-new-link)).
An HTTP POST request to `https://api.rebrandly.com/v1/links` will create the link:
[block:code]
{
"codes": [
{
"code": "curl \\\n -H 'apikey: YOUR_API_KEY' \\\n -H \"Content-Type: application/json\" \\\n -X POST -d '\n {\n \t\"slashtag\":\"burn10M\",\n \"title\":\"How to burn 10M\",\n \"domain\": {\t\n \t\"id\":\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\"\n },\n \"destination\":\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\"\n }' \\\n 'https://api.rebrandly.com/v1/links'",
"language": "curl"
}
]
}
[/block]
Or, without the domain part (because the domain is rebrand.ly, the default domain):
[block:code]
{
"codes": [
{
"code": "curl \n -H 'apikey: YOUR_API_KEY' \\\n -H \"Content-Type: application/json\" \\\n -X POST -d \\\n '{\n \t\"slashtag\":\"burn10M\",\n \"title\":\"How to burn 10M\",\n \"destination\":\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\"\n }' \\\n 'https://api.rebrandly.com/v1/links'",
"language": "curl"
}
]
}
[/block]
If everything works properly, you will get back the Link entity you just created:
[block:code]
{
"codes": [
{
"code": " {\n \"id\": \"ffs24cc5b6ee4a5gh7897b06ac2d16d4\",\n \"title\": \"The LaFerrari Supercar Convertible Is the New Best Way to Burn $1M | WIRED\",\n \"slashtag\": \"burn10M\",\n \"destination\": \"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-13T10:54:12.000Z\",\n \"shortUrl\": \"rebrand.ly/burn10M\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"ref\": \"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n },\n ...\n }",
"language": "json"
}
]
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Testing your branded short link"
}
[/block]
Just click on <a href="http://rebrand.ly/burn10M" target="_blank">http://rebrand.ly/burn10M</a> to test it: you should be redirected to the destination url within milliseconds.
Weird, right?

[block:api-header]
{
"type": "basic",
"title": "Prerequisites"
}
[/block]
* You have already created a Rebrandly account
If you have not, please read the [Signup to Rebrandly guide](doc:getting-started).
* You already have an API KEY to authenticate your API requests
If you don't know how to authenticate your API requests, please read the [Authentication guide](doc:request-api-access) documentation
* You understood what a branded short link is and how it is represented as an API
If you have not, please read [Branded short link model](doc:link-entity)
* You understood what a branded domain is and how it is related to a branded short link
If you have not, please read [Branded domain model](doc:branded-domain-model)
[block:api-header]
{
"type": "basic",
"title": "Creating a new branded short link"
}
[/block]
In order to create a new Link entity, you should first decide what content to rebrand and how you want the final branded short link to look like.
Quick example of rebranding a link with the 'rebrand.ly' default domain: every account can use the 'rebrand.ly' default.
Let's say we want to shorten [https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/](https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/) to become [http://rebrand.ly/burn10M](http://rebrand.ly/burn10M).
Well, the domain id of rebrand.ly is `8f104cc5b6ee4a4ba7897b06ac2ddcfb`, but since rebrand.ly is the default domain for every Rebrandly account, we can choose to not specify the domain while creating a new link. This is up to the user.
[block:callout]
{
"type": "info",
"title": "Where do I get that branded domain \"id\"?",
"body": "Every time you add a new branded domain in Rebrandly, it is associated with a unique identifier. If you want to create a link with your own custom branded domain, instead of the default rebrand.ly domain, you should [list your domains](doc:listing-your-domains-collection) in order to get each domain's id."
}
[/block]
Correspondent Link object is:
[block:code]
{
"codes": [
{
"code": "{\n \"title\": \"How to burn 10M\",\n \"slashtag\": \"burn10M\",\n\t\"destination\": \"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\"\n }\n}",
"language": "json"
}
]
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Test with a different slashtag!",
"body": "**NOTE**: for your personal tests, you should choose another `slashtag`, because the one used for this demo is already used."
}
[/block]
Now we have to send our Link entity to Rebrandly API.
The endpoint to do this is `/links` (see [how to create a new link](doc:create-a-new-link)).
An HTTP POST request to `https://api.rebrandly.com/v1/links` will create the link:
[block:code]
{
"codes": [
{
"code": "curl \\\n -H 'apikey: YOUR_API_KEY' \\\n -H \"Content-Type: application/json\" \\\n -X POST -d '\n {\n \t\"slashtag\":\"burn10M\",\n \"title\":\"How to burn 10M\",\n \"domain\": {\t\n \t\"id\":\"8f104cc5b6ee4a4ba7897b06ac2ddcfb\"\n },\n \"destination\":\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\"\n }' \\\n 'https://api.rebrandly.com/v1/links'",
"language": "curl"
}
]
}
[/block]
Or, without the domain part (because the domain is rebrand.ly, the default domain):
[block:code]
{
"codes": [
{
"code": "curl \n -H 'apikey: YOUR_API_KEY' \\\n -H \"Content-Type: application/json\" \\\n -X POST -d \\\n '{\n \t\"slashtag\":\"burn10M\",\n \"title\":\"How to burn 10M\",\n \"destination\":\"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\"\n }' \\\n 'https://api.rebrandly.com/v1/links'",
"language": "curl"
}
]
}
[/block]
If everything works properly, you will get back the Link entity you just created:
[block:code]
{
"codes": [
{
"code": " {\n \"id\": \"ffs24cc5b6ee4a5gh7897b06ac2d16d4\",\n \"title\": \"The LaFerrari Supercar Convertible Is the New Best Way to Burn $1M | WIRED\",\n \"slashtag\": \"burn10M\",\n \"destination\": \"https://www.wired.com/2016/07/ferrari-laferrari-spider-convertible-photos-specs/\",\n \"createdAt\": \"2016-07-13T10:54:12.000Z\",\n \"updatedAt\": \"2016-07-13T10:54:12.000Z\",\n \"shortUrl\": \"rebrand.ly/burn10M\",\n \"domain\": {\n \"id\": \"8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"ref\": \"/domains/8f104cc5b6ee4a4ba7897b06ac2ddcfb\",\n \"fullName\": \"rebrand.ly\"\n },\n ...\n }",
"language": "json"
}
]
}
[/block]
[block:api-header]
{
"type": "basic",
"title": "Testing your branded short link"
}
[/block]
Just click on <a href="http://rebrand.ly/burn10M" target="_blank">http://rebrand.ly/burn10M</a> to test it: you should be redirected to the destination url within milliseconds.
Weird, right?

{"_id":"57ea5f1666130b1700056ec0","excerpt":"","title":"Use Rebrandly within Tweetbot","type":"basic","version":"577d1b8b74aea422007230c7","sync_unique":"","updates":[],"user":"56b22f582d96461700599230","api":{"auth":"required","params":[],"url":"","results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"createdAt":"2016-09-27T11:59:18.961Z","githubsync":"","slug":"use-rebrandly-within-tweetbot","__v":0,"body":"<a href=\"http://tapbots.com/tweetbot/\" target=\"_blank\">Tweetbot</a> iOS and Mac applications enable users to integrate with their own custom URL shortener: instead of using the Twitter's anonymous `t.co` domain, you can tweet using your own custom domain by integrating Tweetbot with <a href=\"https://www.rebrandly.com\" target=\"_blank\">Rebrandly</a>. \n\nIntegration is very straightforward, as Rebrandly allows to short URLs with a specially crafted URL ([see it in action in API explorer](https://developers.rebrandly.com/docs/create-link-url)) and Tweetbot's custom URL shortener configuration works great with URLs.\n\n## CRAFT YOUR URL\n\nTo get a special URL for Tweetbot, replace `YOUR_API_KEY` with your own API key ([How to get an API key?](doc:api-key-authentication)) in the following:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://api.rebrandly.com/v1/links/new?apikey=YOUR_API_KEY&domain[fullName]=rebrand.ly&destination=%@\",\n \"language\": \"text\",\n \"name\": \"Configuration URL for Tweetbot\"\n }\n ]\n}\n[/block]\nThis will shorten all URLs in your next tweets with `rebrand.ly` domain.\nWant to use your own custom domain you activated in Rebrandly? Just replace `rebrand.ly` with your domain name in the URL.\n\n## SAVE YOUR SETTINGS\n\nOnce you crafted your own configuration URL for Tweetbot, just write it down into your `URL shortening` section (within your account settings), choosing the `Custom...` option.\n\nMore info on <a href=\"https://support.rebrandly.com/hc/en-us/articles/229596467-Custom-URL-shortening-for-Tweetbot-iOS-and-MAC\" target=\"_blank\">Rebrandly knowledge base</a>.\n\n## TEST IT\n\nTweet something which includes an URL: it will be rebranded using your own custom domain from Rebrandly and you'll even get insights on your visitors from your Rebrandly dashboard.\n\n## TWEET IT\nDon't forget to tweet about how much cool Rebrandly+Tweetbot is.","hidden":false,"order":3,"project":"577d1b8b74aea422007230c4","category":"577d22a35fd4de0e00cc3ddd","isReference":false,"link_external":false,"link_url":"","parentDoc":null,"childrenPages":[]}

Use Rebrandly within Tweetbot

<a href="http://tapbots.com/tweetbot/" target="_blank">Tweetbot</a> iOS and Mac applications enable users to integrate with their own custom URL shortener: instead of using the Twitter's anonymous `t.co` domain, you can tweet using your own custom domain by integrating Tweetbot with <a href="https://www.rebrandly.com" target="_blank">Rebrandly</a>.
Integration is very straightforward, as Rebrandly allows to short URLs with a specially crafted URL ([see it in action in API explorer](https://developers.rebrandly.com/docs/create-link-url)) and Tweetbot's custom URL shortener configuration works great with URLs.
## CRAFT YOUR URL
To get a special URL for Tweetbot, replace `YOUR_API_KEY` with your own API key ([How to get an API key?](doc:api-key-authentication)) in the following:
[block:code]
{
"codes": [
{
"code": "https://api.rebrandly.com/v1/links/new?apikey=YOUR_API_KEY&domain[fullName]=rebrand.ly&destination=%@",
"language": "text",
"name": "Configuration URL for Tweetbot"
}
]
}
[/block]
This will shorten all URLs in your next tweets with `rebrand.ly` domain.
Want to use your own custom domain you activated in Rebrandly? Just replace `rebrand.ly` with your domain name in the URL.
## SAVE YOUR SETTINGS
Once you crafted your own configuration URL for Tweetbot, just write it down into your `URL shortening` section (within your account settings), choosing the `Custom...` option.
More info on <a href="https://support.rebrandly.com/hc/en-us/articles/229596467-Custom-URL-shortening-for-Tweetbot-iOS-and-MAC" target="_blank">Rebrandly knowledge base</a>.
## TEST IT
Tweet something which includes an URL: it will be rebranded using your own custom domain from Rebrandly and you'll even get insights on your visitors from your Rebrandly dashboard.
## TWEET IT
Don't forget to tweet about how much cool Rebrandly+Tweetbot is.

<a href="http://tapbots.com/tweetbot/" target="_blank">Tweetbot</a> iOS and Mac applications enable users to integrate with their own custom URL shortener: instead of using the Twitter's anonymous `t.co` domain, you can tweet using your own custom domain by integrating Tweetbot with <a href="https://www.rebrandly.com" target="_blank">Rebrandly</a>.
Integration is very straightforward, as Rebrandly allows to short URLs with a specially crafted URL ([see it in action in API explorer](https://developers.rebrandly.com/docs/create-link-url)) and Tweetbot's custom URL shortener configuration works great with URLs.
## CRAFT YOUR URL
To get a special URL for Tweetbot, replace `YOUR_API_KEY` with your own API key ([How to get an API key?](doc:api-key-authentication)) in the following:
[block:code]
{
"codes": [
{
"code": "https://api.rebrandly.com/v1/links/new?apikey=YOUR_API_KEY&domain[fullName]=rebrand.ly&destination=%@",
"language": "text",
"name": "Configuration URL for Tweetbot"
}
]
}
[/block]
This will shorten all URLs in your next tweets with `rebrand.ly` domain.
Want to use your own custom domain you activated in Rebrandly? Just replace `rebrand.ly` with your domain name in the URL.
## SAVE YOUR SETTINGS
Once you crafted your own configuration URL for Tweetbot, just write it down into your `URL shortening` section (within your account settings), choosing the `Custom...` option.
More info on <a href="https://support.rebrandly.com/hc/en-us/articles/229596467-Custom-URL-shortening-for-Tweetbot-iOS-and-MAC" target="_blank">Rebrandly knowledge base</a>.
## TEST IT
Tweet something which includes an URL: it will be rebranded using your own custom domain from Rebrandly and you'll even get insights on your visitors from your Rebrandly dashboard.
## TWEET IT
Don't forget to tweet about how much cool Rebrandly+Tweetbot is.

Frequently Asked Questions

{"_id":"579742eafa1ff60e006a1314","user":"577d1b6d87acf617003c421d","version":"577d1b8b74aea422007230c7","category":"579742da50804820005ec90a","githubsync":"","parentDoc":null,"title":"Authentication","__v":1,"body":"## How to receive the OAuth token via `POST`?\n\nIn default mode (see [Authentication](doc:request-api-access)), Rebrandly OAuth server reaches the user `redirect_url` using a `GET` request, passing the token as a query parameter.\nIn some cases, it would be the choice of preference to have the OAuth token returned within a `POST` body.\nIn order to get back the token wrapped into the body of a `POST` request, a further query parameter is required in the OAuth URL (`https://oauth.rebrandly.com/connect/oauth`):\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Parameter\",\n \"h-1\": \"Description\",\n \"0-0\": \"client_id\",\n \"0-1\": \"The unique Client ID associated with your app.\",\n \"1-0\": \"redirect_uri\",\n \"1-1\": \"This is the callback to your app you asked to be authorized in your request.\",\n \"4-0\": \"<span style='color:green'>**response_mode**</span>\",\n \"4-1\": \"Leave it empty if you want the OAuth server to use `GET` HTTP method when redirecting to your `redirect_uri`. Use \\\"form_post\\\" value if you want the OAuth server to use `POST` HTTP method, instead.\",\n \"2-0\": \"response_type\",\n \"2-1\": \"This should be always `token`.\",\n \"3-0\": \"scope\",\n \"3-1\": \"This should be always `rbapi`.\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]","excerpt":"","updates":["5797aa376b0a1b19006decae"],"api":{"params":[],"url":"","results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required"},"order":1,"sync_unique":"","type":"basic","project":"577d1b8b74aea422007230c4","slug":"authentication","createdAt":"2016-07-26T11:00:58.597Z","hidden":false,"isReference":false,"link_external":false,"link_url":"","childrenPages":[]}

Authentication

## How to receive the OAuth token via `POST`?
In default mode (see [Authentication](doc:request-api-access)), Rebrandly OAuth server reaches the user `redirect_url` using a `GET` request, passing the token as a query parameter.
In some cases, it would be the choice of preference to have the OAuth token returned within a `POST` body.
In order to get back the token wrapped into the body of a `POST` request, a further query parameter is required in the OAuth URL (`https://oauth.rebrandly.com/connect/oauth`):
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"0-0": "client_id",
"0-1": "The unique Client ID associated with your app.",
"1-0": "redirect_uri",
"1-1": "This is the callback to your app you asked to be authorized in your request.",
"4-0": "<span style='color:green'>**response_mode**</span>",
"4-1": "Leave it empty if you want the OAuth server to use `GET` HTTP method when redirecting to your `redirect_uri`. Use \"form_post\" value if you want the OAuth server to use `POST` HTTP method, instead.",
"2-0": "response_type",
"2-1": "This should be always `token`.",
"3-0": "scope",
"3-1": "This should be always `rbapi`."
},
"cols": 2,
"rows": 5
}
[/block]

## How to receive the OAuth token via `POST`?
In default mode (see [Authentication](doc:request-api-access)), Rebrandly OAuth server reaches the user `redirect_url` using a `GET` request, passing the token as a query parameter.
In some cases, it would be the choice of preference to have the OAuth token returned within a `POST` body.
In order to get back the token wrapped into the body of a `POST` request, a further query parameter is required in the OAuth URL (`https://oauth.rebrandly.com/connect/oauth`):
[block:parameters]
{
"data": {
"h-0": "Parameter",
"h-1": "Description",
"0-0": "client_id",
"0-1": "The unique Client ID associated with your app.",
"1-0": "redirect_uri",
"1-1": "This is the callback to your app you asked to be authorized in your request.",
"4-0": "<span style='color:green'>**response_mode**</span>",
"4-1": "Leave it empty if you want the OAuth server to use `GET` HTTP method when redirecting to your `redirect_uri`. Use \"form_post\" value if you want the OAuth server to use `POST` HTTP method, instead.",
"2-0": "response_type",
"2-1": "This should be always `token`.",
"3-0": "scope",
"3-1": "This should be always `rbapi`."
},
"cols": 2,
"rows": 5
}
[/block]

{"_id":"592c52729bc0980f0027719d","order":2,"project":"577d1b8b74aea422007230c4","title":"Migrate links over workspaces","updates":["592e99873f1cc5002f665ce3"],"user":"577d1b6d87acf617003c421d","createdAt":"2017-05-29T16:55:14.096Z","next":{"pages":[],"description":""},"link_external":false,"parentDoc":null,"sync_unique":"","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"category":"579742da50804820005ec90a","excerpt":"","version":"577d1b8b74aea422007230c7","__v":1,"slug":"migrate-links-over-teams","type":"basic","isReference":false,"link_url":"","body":"## How to migrate a link to or from a specific workspace?\n\nThere is no specific endpoint to migrate a link, whether it's to or from your personal account to a workspace or to or from different workspaces you own.\nA workaround is that it can be done programmatically by deleting and recreating the links.\n\n**IMPORTANT**: In this case, you will lose the click stats and all tags/information associated with the link.\n\nThis workaround is only possible if you are the workspace owner (this means you must have created the workspace from your personal Rebrandly dashboard). Here is a procedure to do that:\n\n1. Load from API a set of links you want to migrate.\nDepending on where the links have been created, you may need to include the workspace header (see [Get started](doc:get-started) for more info). \nDouble check how to filter your Rebrandly links in [Listing your links](doc:list-links). \n*E.g. you may want to select all links with a given domain.*\n\n2. For each of the links, perform the following:\n - DELETE the link from its current workspace (be sure to include the right workspace header if the link is visible only within that workspace context).\n - CREATE the link into your final context. If you are moving the link into a workspace, attach the workspace header (see [Creating a new link](doc:create-a-new-link) for more info).\nRemember that you need to specify the branded domain in the request, as no default domain is defined for a team.","githubsync":"","hidden":false,"childrenPages":[]}

Migrate links over workspaces

## How to migrate a link to or from a specific workspace?
There is no specific endpoint to migrate a link, whether it's to or from your personal account to a workspace or to or from different workspaces you own.
A workaround is that it can be done programmatically by deleting and recreating the links.
**IMPORTANT**: In this case, you will lose the click stats and all tags/information associated with the link.
This workaround is only possible if you are the workspace owner (this means you must have created the workspace from your personal Rebrandly dashboard). Here is a procedure to do that:
1. Load from API a set of links you want to migrate.
Depending on where the links have been created, you may need to include the workspace header (see [Get started](doc:get-started) for more info).
Double check how to filter your Rebrandly links in [Listing your links](doc:list-links).
*E.g. you may want to select all links with a given domain.*
2. For each of the links, perform the following:
- DELETE the link from its current workspace (be sure to include the right workspace header if the link is visible only within that workspace context).
- CREATE the link into your final context. If you are moving the link into a workspace, attach the workspace header (see [Creating a new link](doc:create-a-new-link) for more info).
Remember that you need to specify the branded domain in the request, as no default domain is defined for a team.

## How to migrate a link to or from a specific workspace?
There is no specific endpoint to migrate a link, whether it's to or from your personal account to a workspace or to or from different workspaces you own.
A workaround is that it can be done programmatically by deleting and recreating the links.
**IMPORTANT**: In this case, you will lose the click stats and all tags/information associated with the link.
This workaround is only possible if you are the workspace owner (this means you must have created the workspace from your personal Rebrandly dashboard). Here is a procedure to do that:
1. Load from API a set of links you want to migrate.
Depending on where the links have been created, you may need to include the workspace header (see [Get started](doc:get-started) for more info).
Double check how to filter your Rebrandly links in [Listing your links](doc:list-links).
*E.g. you may want to select all links with a given domain.*
2. For each of the links, perform the following:
- DELETE the link from its current workspace (be sure to include the right workspace header if the link is visible only within that workspace context).
- CREATE the link into your final context. If you are moving the link into a workspace, attach the workspace header (see [Creating a new link](doc:create-a-new-link) for more info).
Remember that you need to specify the branded domain in the request, as no default domain is defined for a team.

{"_id":"5a310668434301002850f0da","project":"577d1b8b74aea422007230c4","version":"577d1b8b74aea422007230c7","category":"579742da50804820005ec90a","user":"577d1b6d87acf617003c421d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-12-13T10:52:24.448Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"## Can I customize the slashtag on links I create?\nOf course, you can set a value for `slashtag` field when [creating a new link](doc:create-a-new-link).\nMind that you cannot edit a link's slashtag once the link is created.\n\n## Are client integrations supposed to save the link ID to be able to get/edit/delete the link afterward?\nNot necessarily. By properly using filters of [List of links](doc:list-links) endpoint, you can uniquely fetch a specific link when you know in advance in which workspace it was created, and when you know at least the short URL itself.\nDouble check example in [Getting link details](doc:get-link-details), you can exploit it to build a clean integration which does not need to store anything on your model about Rebrandly IDs.\n\n## Is it possible to fetch a link if you only know its destination URL?\nNo. In Rebrandly you can rebrand a given destination URL many times with many different branded domains and slashtags, this is the reason why you cannot fetch links by destination URL.\nIf your system is in need to fetch by destination URL (e.g. blog posts sharing), we recommend you to use *hashing* techniques to choose your slashtag when you create the link: if you can correspond every destination URL to a specific hash code, you can always easily fetch the right link by means of calculating the hash of the destination URL.\n\n## Does Rebrandly API support bulk link creation?\n\nNo. There is no possibility yet to create/edit or delete links in batch. \nThere are plans to support them in 2018.\n\n## How to configure different behaviors for slashtag autogeneration?\n\nUnfortunately, there is no API support to interact with slashtag generation.\nAPI clients are supposed to build their own slashtag generation systems to avoid URL collisions and to match their application needs.\nThere are plans to support destination-aware slashtag generation, like Rebrandly Dashboard use to propose, in 2018.","excerpt":"","slug":"integrations","type":"basic","title":"Integrations","__v":0,"parentDoc":null,"childrenPages":[]}

Integrations

## Can I customize the slashtag on links I create?
Of course, you can set a value for `slashtag` field when [creating a new link](doc:create-a-new-link).
Mind that you cannot edit a link's slashtag once the link is created.
## Are client integrations supposed to save the link ID to be able to get/edit/delete the link afterward?
Not necessarily. By properly using filters of [List of links](doc:list-links) endpoint, you can uniquely fetch a specific link when you know in advance in which workspace it was created, and when you know at least the short URL itself.
Double check example in [Getting link details](doc:get-link-details), you can exploit it to build a clean integration which does not need to store anything on your model about Rebrandly IDs.
## Is it possible to fetch a link if you only know its destination URL?
No. In Rebrandly you can rebrand a given destination URL many times with many different branded domains and slashtags, this is the reason why you cannot fetch links by destination URL.
If your system is in need to fetch by destination URL (e.g. blog posts sharing), we recommend you to use *hashing* techniques to choose your slashtag when you create the link: if you can correspond every destination URL to a specific hash code, you can always easily fetch the right link by means of calculating the hash of the destination URL.
## Does Rebrandly API support bulk link creation?
No. There is no possibility yet to create/edit or delete links in batch.
There are plans to support them in 2018.
## How to configure different behaviors for slashtag autogeneration?
Unfortunately, there is no API support to interact with slashtag generation.
API clients are supposed to build their own slashtag generation systems to avoid URL collisions and to match their application needs.
There are plans to support destination-aware slashtag generation, like Rebrandly Dashboard use to propose, in 2018.

## Can I customize the slashtag on links I create?
Of course, you can set a value for `slashtag` field when [creating a new link](doc:create-a-new-link).
Mind that you cannot edit a link's slashtag once the link is created.
## Are client integrations supposed to save the link ID to be able to get/edit/delete the link afterward?
Not necessarily. By properly using filters of [List of links](doc:list-links) endpoint, you can uniquely fetch a specific link when you know in advance in which workspace it was created, and when you know at least the short URL itself.
Double check example in [Getting link details](doc:get-link-details), you can exploit it to build a clean integration which does not need to store anything on your model about Rebrandly IDs.
## Is it possible to fetch a link if you only know its destination URL?
No. In Rebrandly you can rebrand a given destination URL many times with many different branded domains and slashtags, this is the reason why you cannot fetch links by destination URL.
If your system is in need to fetch by destination URL (e.g. blog posts sharing), we recommend you to use *hashing* techniques to choose your slashtag when you create the link: if you can correspond every destination URL to a specific hash code, you can always easily fetch the right link by means of calculating the hash of the destination URL.
## Does Rebrandly API support bulk link creation?
No. There is no possibility yet to create/edit or delete links in batch.
There are plans to support them in 2018.
## How to configure different behaviors for slashtag autogeneration?
Unfortunately, there is no API support to interact with slashtag generation.
API clients are supposed to build their own slashtag generation systems to avoid URL collisions and to match their application needs.
There are plans to support destination-aware slashtag generation, like Rebrandly Dashboard use to propose, in 2018.