Skip to main content
BitlyDeveloper
Start Now

MCP Tools Reference

A concise, skimmable catalog of Bitly MCP tools.

bitly_create_short_link - Create a compact, shareable link with advanced customization options

Parameters:

long_url (optional; required if bitlink_id not provided)
bitlink_id (optional; existing short link to add a custom back-half to)
domain (optional)
group_guid (optional)
title (optional)
tags (optional; string[])
keyword (optional; custom back-half for the short link)
dynamic_routing (optional; object[]; up to 10 rules; send visitors to different destinations by country, region, device, or OS)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Shorten https://example.com/very-long-product-page-url"

"Create a short link for https://example.com/spring-sale titled 'Spring Sale 2024' tagged 'marketing' and 'seasonal' using our custom domain"

"Create a custom short link bit.ly/summer-sale for https://example.com/sale"

bitly_create_short_link_with_qr - Create a short link and a QR Code that encodes it in a single step (one approval covers both)

Parameters:

group_guid (required)
bitlink_id (optional; existing short link to encode; required if long_url not provided)
long_url (optional; required if bitlink_id not provided)
domain (optional)
title (optional; used for the short link)
tags (optional; string[])
keyword (optional; custom back-half for the short link)
dynamic_routing (optional; object[]; up to 10 rules; applied to the short link)
qr_title (optional; defaults to the link title when omitted)
archived (optional; boolean)
render_customizations (optional; object; QR appearance)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Create a short link and matching QR Code for https://example.com/event in my marketing group"

"Make bit.ly/summer-sale for https://example.com/sale and generate a QR Code titled 'Summer Sale Flyer'"

bitly_get_short_link_details - Get complete short link details (title, destination, created, creator, tags, custom domains)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show me the full details for bit.ly/ABC123"

bitly_update_short_link - Update destination URL, title, archive state, tags, or dynamic routing rules

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
long_url (optional)
title (optional)
archived (optional; boolean)
tags (optional; string[])
dynamic_routing (optional; object[]; up to 10 rules; replaces all existing rules, pass [] to remove them)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Archive bit.ly/ABC123"

"Update bit.ly/ABC123 with title 'Updated Campaign Link' and tags 'Q1-2024' and 'email-campaign'"

"Change the destination of bit.ly/ABC123 to https://example.com/new-page"

bitly_delete_short_link - Permanently delete a short link (unedited links only)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Delete bit.ly/ABC123 permanently"

bitly_get_link_destination - Look up where a short link points: its destination long URL plus basic metadata (works for any bitlink, including links you do not own)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"What URL does bit.ly/ABC123 point to?"

Analytics

Analytics are served by three tools, one per subject. Each takes a dimension that selects the report: a facet breakdown (e.g. countries, cities, devices) or over_time (a time series). The single-link and QR Code tools also offer summary (totals); group analytics instead offers top (best-performing links) and has no group-level summary — for an overall group count, total the over_time series.

bitly_get_link_analytics - Analytics for a single short link

over_time and summary report click counts; engagements and engagements_summary report the same time ranges with a clicks/scans/button-clicks breakdown.

agentic_traffic breaks down clicks from AI agents and assistants (ChatGPT, Claude, ...) by agent. These are counted separately from clicks, so they are not a subset of the click totals.

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
dimension (required; countries | cities | devices | referrers | referring_domains | over_time | summary | engagements | engagements_summary | agentic_traffic)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Which countries clicked bit.ly/ABC123 in the last 7 days?"

"Show me metrics over time for bit.ly/ABC123"

"How many total engagements has bit.ly/ABC123 received?"

"Which AI agents have been visiting bit.ly/ABC123?"

bitly_get_group_analytics - Analytics across all links in a group (workspace)

Takes a dataset selecting what to measure. Valid dimensions depend on the dataset:

DatasetDimensions
agentic_trafficsummary
clickscountries, cities, device_os, referrers, over_time, top
engagementscountries, cities, devices, referrers, referring_networks, over_time, top
qr_scanscountries, cities, over_time, top

devices is device form factor (mobile, desktop, ...); device_os is operating system (iOS, Android, Windows, ...).

agentic_traffic counts clicks from AI agents and assistants. It always returns a fixed 90-day total and ignores unit, units, and unit_reference.

Parameters:

group_guid (required)
dataset (required; agentic_traffic | clicks | engagements | qr_scans)
dimension (required; countries | cities | devices | device_os | referrers | referring_networks | over_time | summary | top; see matrix above)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Break down my group's QR scans by city"

"What are my top performing links this week?"

"How have my group's clicks trended over the last 30 days?"

"How much of my traffic came from AI agents?"

bitly_get_qr_code_analytics - Scan analytics for a single QR Code

Parameters:

qrcode_id (required)
dimension (required; countries | cities | device_os | browsers | over_time | summary)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"What operating systems scanned QR Code QR123456?"

"How many total scans does QR Code QR123456 have?"

QR Codes

bitly_create_qr_code - Create a new QR Code for a link

Parameters:

group_guid (required)
title (optional)
long_url (optional; destination to encode; required if bitlink_id not provided)
bitlink_id (optional; existing short link to encode; required if long_url not provided)
domain (optional)
archived (optional; boolean)
render_customizations (optional; object; foreground/background colors, gradients, frame, dot pattern)
expiration_at (optional; ISO 8601 "YYYY-MM-DDTHH:MM:SS+0000"; long_url-backed QR Codes only, on entitled accounts)
dynamic_routing (optional; object[]; up to 10 rules; decoupled (long_url-backed) QR Codes only)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Create a QR Code for bit.ly/ABC123 called 'Event Registration'"

"Create a QR Code for bit.ly/ABC123 titled 'Event Registration' in my marketing group"

"Create a QR Code for bit.ly/ABC123 with a blue foreground and white background"

bitly_get_qr_code - Get QR Code metadata

Parameters:

qrcode_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show details for QR Code QR123456"

bitly_get_qr_code_image - Return a QR Code's image as a base64 data URI (not a URL). Most agent UIs cannot render raw image data, so to view or download the image prefer the QR Code details page returned by bitly_get_qr_code and bitly_create_qr_code.

Parameters:

qrcode_id (required)
format (optional; svg | png; default "svg")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Get the raw image data for QR Code QR123456 as a PNG"

bitly_update_qr_code - Update a QR Code's title, customizations, expiration, archived status, or dynamic routing rules

Parameters:

qrcode_id (required)
title (optional)
archived (optional; boolean)
render_customizations (optional; object; foreground/background colors, gradients, frame, dot pattern)
expiration_at (optional; ISO 8601 "YYYY-MM-DDTHH:MM:SS+0000"; pass "" to remove an existing expiration)
dynamic_routing (optional; object[]; up to 10 rules; decoupled (long_url-backed) QR Codes only)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Update QR Code QR123456 with title 'Updated Event QR' and archive it"

"Recolor QR Code QR123456 with a red foreground"

bitly_get_group_qr_codes - List QR Codes in a group with filtering and pagination

Parameters:

group_guid (required)
query (optional; search term)
archived (optional; on | off | both)
size (optional; results per page)
search_after (optional; pagination cursor from the previous response)
has_dynamic_routing (optional; on | off | both; filter to QR Codes with or without routing rules)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show QR Codes in group Bg123def456 that contain 'event'"

User & Organization

bitly_get_user - Get the authenticated user's profile

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"Show my user profile"

bitly_get_organizations - List organizations the user can access

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"List all organizations I can access"

bitly_get_groups - List groups (workspaces); optionally filter by organization

Parameters:

organization_guid (optional)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show all my groups"

bitly_get_group_details - Get a group's details, including its custom domains

Parameters:

group_guid (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Get details for group Bg123def456"

bitly_get_group_preferences - Get a group's preferences, including the default domain used when creating links for the group

Parameters:

group_guid (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"What is the default domain for group Bg123def456?"

"Show the preferences for my marketing group"

bitly_get_group_short_links - List links in a group with rich filtering

Parameters:

group_guid (required)
size (optional; results per page)
search_after (optional; pagination cursor from the previous response)
query (optional; search term)
tag (optional; string[]; links must carry every tag listed (AND))
created_before (optional; Unix timestamp)
created_after (optional; Unix timestamp)
archived (optional; on | off | both)
has_dynamic_routing (optional; on | off | both; filter to links with or without routing rules)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show links in group Bg123def456"

"Get the first 20 links in group Bg123def456 tagged 'campaign' created after 2024-01-01 (exclude archived)"

bitly_get_group_short_links_sorted - List group links sorted by performance

Parameters:

group_guid (required)
sort (required; clicks)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show top-performing links in group Bg123def456 by clicks over the last 30 days"

Custom Domains

bitly_get_custom_domains - List custom domains available to the user

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"What custom domains can I use for shortening links?"

bitly_get_custom_link_details - Get custom link metadata and override history

Parameters:

custom_bitlink (required; a custom-keyword link, e.g. 'example.ly/spring-sale')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show details for example.ly/spring-sale"

Bulk Uploads

bitly_bulk_upload_validate - Validate a bulk upload request and obtain a signed URL for uploading a .CSV or .XLSX file

Parameters:

filename (required)
upload_type (required; "link", "qr_code", or "coupled_link")
group_guid (optional)
domain (optional)
template_id (optional; required for "qr_code" and "coupled_link"; "QTDTmplWLogo" or "QTDTmplNLogo")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Bulk upload links.csv into group Bg123def456"

"Bulk create QR Codes from qr-batch.xlsx using the no-logo template"

bitly_bulk_upload_file - Upload a file to the signed URL returned by bitly_bulk_upload_validate

Parameters:

upload_url (required; signed URL from the validate step)
headers (required; object; headers from the validate step)
file_content (required)
content_type (optional)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Upload the validated bulk file to complete the bulk request"

Data Export

bitly_export_data - Export link or QR data as a CSV, returned inline as a downloadable file

Parameters:

group_guid (required)
export_type (required; "link_engagements_timeseries", "link_engagements_batch", "links_list", or "qr_codes_list")
bitlinks (optional; string[]; fully qualified bitlinks; for the engagement exports)
unix_from_date (optional; "YYYY-MM-DD" UTC; required for "link_engagements_timeseries")
unix_to_date (optional; "YYYY-MM-DD" UTC)
include_metrics (optional; boolean; for "links_list" and "qr_codes_list" only)
filter (optional; object; required for "links_list" and "qr_codes_list")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Export a CSV of all links in group Bg123def456"

"Export daily click totals for bit.ly/ABC123 over the last 30 days"

Bitly Sites

Bitly Sites are link-in-bio landing pages (microsites) reachable at a short URL. Newly created sites and edits are drafts until published with bitly_publish_site. Site analytics are served by a single bitly_get_site_analytics tool that takes a dataset and a dimension.

bitly_create_site - Create a new, empty Bitly Site (link-in-bio page) for a group at a short URL

The new site is a draft with no blocks. Add content with bitly_create_site_block, style it with bitly_update_site_appearance, then publish it with bitly_publish_site.

Parameters:

group_guid (required)
uri (required; keyword ('mysite'), 'domain/keyword', or full 'domain/m/keyword'; '/m/' is added automatically and a bare keyword assumes bit.ly)
display_name (optional; defaults to a system value when omitted)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Create a Bitly Site at bit.ly/mysite in group Bg123def456"

bitly_get_site - Get a Bitly Site's configuration: URL, status, display name, description, button count, and attached QR Code

Parameters:

site_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show the details for site M1234567890"

bitly_get_group_sites - List the Bitly Sites in a group with URL filtering and pagination

Parameters:

group_guid (required)
sites_url_param (optional; filter by URL substring)
size (optional; results per page (default 50, max 100))
search_after (optional; pagination cursor from the previous response)
response_format (optional; "text" (default) or "json")

Usage Examples:

"List the Bitly Sites in group Bg123def456"

bitly_update_site - Update a Bitly Site's URI, display name, description, or attach a QR Code

Only the fields you send change; a present empty string ("") clears display_name/description. Changing the URI creates a redirect from the old one.

Parameters:

site_id (required)
uri (optional; keyword ('mysite'), 'domain/keyword', or full 'domain/m/keyword'; '/m/' is added automatically and a bare keyword assumes bit.ly)
display_name (optional; pass "" to clear it)
description (optional; pass "" to clear it)
qr_code_id (optional; attach a QR Code created with bitly\_create\_qr\_code; the site must not already have one)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Rename site M1234567890's display name to 'My Links'"

"Attach QR Code QR123456 to site M1234567890"

bitly_delete_site - Deactivate (delete) a Bitly Site, taking the live site down

Parameters:

site_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Delete Bitly Site M1234567890"

bitly_publish_site - Publish a Bitly Site's draft so the current edits go live

Parameters:

site_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Publish site M1234567890"

bitly_discard_site_draft - Discard a Bitly Site's unpublished draft, reverting to the published version

Parameters:

site_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Discard the unpublished draft for site M1234567890"

bitly_clone_site - Clone a live Bitly Site into a new draft at a different URI

Parameters:

site_id (required)
uri (required; keyword, 'domain/keyword', or full 'domain/m/keyword' (must differ from the source); '/m/' is added automatically and a bare keyword assumes bit.ly)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Clone site M1234567890 to bit.ly/mysite-copy"

bitly_get_site_templates - List Bitly Site templates that can be applied to a site, optionally filtered by category

Parameters:

category (optional; e.g. 'Link-in-bio', 'Digital business card', 'Image gallery')
response_format (optional; "text" (default) or "json")

Usage Examples:

"List the available Bitly Site templates"

bitly_apply_site_template - Apply a template's content, appearance, and blocks to a Bitly Site

Parameters:

site_id (required)
template_guid (required; from bitly\_get\_site\_templates)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Apply template Mt123456 to site M1234567890"

bitly_update_site_appearance - Replace a Bitly Site's appearance: theme, layout, fonts, and colors

This is a full replacement (PUT) of the appearance object, so include every field you want set. Fetch the current values with bitly_get_site (response_format "json") first.

Parameters:

site_id (required)
appearance (required; object; theme_id, layout, font, colors, header_appearance, etc.)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Set site M1234567890's background color to #000000 and text color to #FFFFFF"

bitly_create_site_container - Create a container (grid or carousel) on a Bitly Site to group content blocks

Parameters:

site_id (required)
type (required; grid | carousel)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Add a carousel to site M1234567890"

bitly_create_site_block - Add a content block to a Bitly Site: a bitlink button, social icon, YouTube video, image, digital business card, or text block

For a YouTube block, resolve the video with bitly_prevalidate_site_button first. To nest the block, create a container with bitly_create_site_container and pass its ID as parent.

Parameters:

site_id (required)
content_type (required; bitlink | social | youtubeVideo | image | digital_business_card | text_block; block type; grid/carousel containers are created with bitly\_create\_site\_container)
content (required; object; shape depends on content_type)
appearance (optional; object; text_block only)
schedule_start (optional; RFC 3339 timestamp)
schedule_end (optional; RFC 3339 timestamp)
is_active (optional; defaults to true (visible) when omitted)
is_pinned (optional)
parent (optional; container block ID to nest inside)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Add a bitlink button linking to bit.ly/ABC123 titled 'Shop now' to site M1234567890"

bitly_update_site_block - Update an existing content block on a Bitly Site, replacing its content (and text-block appearance)

The block type is taken from the stored block and cannot be changed. Fetch the block's ID with bitly_get_site.

Parameters:

site_id (required)
block_id (required; ID of the block to update; find it with bitly\_get\_site)
content (required; object; shape depends on the block's type)
appearance (optional; object; text_block only)
schedule_start (optional; RFC 3339 timestamp)
schedule_end (optional; RFC 3339 timestamp)
is_active (optional)
is_pinned (optional)
parent (optional; container block ID to nest inside)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Update the text of text block L123456 on site M1234567890"

bitly_delete_site_block - Delete a block of any type from a Bitly Site: a bitlink button, social icon, YouTube video, image, digital business card, text block, or a grid/carousel container

Fetch the block's ID with bitly_get_site.

Parameters:

site_id (required)
block_id (required; ID of the block to delete; find it with bitly\_get\_site)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Delete block L123456 from site M1234567890"

bitly_prevalidate_site_button - Prevalidate button content (a YouTube video) before adding it to a Bitly Site

Returns the resolved video URL, title, and thumbnail to use when creating a youtubeVideo content block with bitly_create_site_block.

Parameters:

site_id (required)
button_type (required; youtubeVideo)
video_id (required; the YouTube video ID to resolve)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Prevalidate YouTube video dQw4w9WgXcQ for site M1234567890"

bitly_create_site_image - Register an already-uploaded image for use on a Bitly Site

Parameters:

site_id (required)
image_guid (required; GUID of the previously uploaded image)
url (required; URL of the uploaded image)
image_use (required; how the image is used (avatar, background, etc.))
crop (optional; JSON-encoded crop rectangle)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Register uploaded image Img123 as the avatar for site M1234567890"

bitly_delete_site_redirect - Delete a redirect from a Bitly Site

Redirects are created automatically when a site's URI changes (see bitly_update_site); this removes one, identified by its old domain and keyword.

Parameters:

site_id (required)
domain (required; the redirect's domain, e.g. 'bit.ly')
keyword (required; the redirect's keyword (path after the domain))
response_format (optional; "text" (default) or "json")

Usage Examples:

"Delete the redirect bit.ly/old-uri from site M1234567890"

bitly_get_site_analytics - Analytics for a single Bitly Site

Takes a dataset selecting what to measure. Valid dimensions depend on the dataset: page_views (countries, cities, devices, referrers, over_time, summary); button_clicks (countries, cities, devices, over_time, top); dbc_downloads (over_time); overview (summary); link_performance (summary).

Parameters:

site_id (required)
dataset (required; button_clicks | dbc_downloads | link_performance | overview | page_views)
dimension (required; countries | cities | devices | referrers | over_time | summary | top)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"How many page views did site M1234567890 get in the last 7 days?"

"Which countries viewed site M1234567890?"

"What are the top-performing buttons on site M1234567890?"