Bitly

Register an already-uploaded image for use on a Bitly Site (e.g. as an avatar, background, or image block). You must upload the image and obtain its image_guid and URL first; this associates it with the site for a given use. Returns the image's URL and GUID to reference in appearance or content updates.

bitly_create_site_image

Delete a short link permanently. This operation removes unedited short links (non-customized links only) and cannot be undone. The short link must not have overrides, be part of campaigns, have deeplinks, or be used in a page. Only group administrators can delete short links.

bitly_delete_short_link

Deactivate (delete) a Bitly Site. This takes the live site down. To only throw away unpublished edits while keeping the live site, use bitly_discard_site_draft instead.

bitly_delete_site

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 (which also deletes the blocks inside it). Fetch the block's ID with bitly_get_site. The change is a draft; publish it with bitly_publish_site.

bitly_delete_site_block

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. Inspect a site's redirects with bitly_get_site (response_format 'json').

bitly_delete_site_redirect

Discard a Bitly Site's unpublished draft, reverting in-progress edits back to the currently published version. The live site is unaffected. To take the whole site down, use bitly_delete_site.

bitly_discard_site_draft

Export link or QR data as CSV. Always use response_format="json". Returns a download-card payload (filename, row_count, truncated, columns) — do not paste CSV, base64, or data_uri into chat; tell the user the file is ready to download. Dates: use unix_from_date and unix_to_date as YYYY-MM-DD (UTC); the server converts to timestamps. For relative ranges (e.g. "last 30 days", "this month"), derive dates from system context. Choose export_type by what the user asked for: link_engagements_timeseries — one CSV row per calendar day (never monthly). REQUIRED when the user says daily, by day, each day, per day, time series, engagements over time, or any daily metrics export — even without an explicit date range. Never use link_engagements_batch for those. One known link: bitlinks=["domain.com/backhalf"] (fully qualified short URL). Multiple links: filter (tags, destination, domain, query, etc.) for dashboard link-performance columns (Date, Short Link, Destination, Clicks, QR Scans, Button Clicks, Total Engagements) — one row per link per day. For link_engagements_timeseries always set unix_from_date and unix_to_date: use the user's range if given; otherwise default to the last 30 days from system context. link_engagements_batch — one row per link with period totals (Link, Title, clicks/scans/button_clicks for the whole range). Use only for summary tables with no daily breakdown (e.g. "total engagements per link"). links_list — link metadata CSV (filter required; optional include_metrics). qr_codes_list — QR metadata CSV (filter required; optional include_metrics). For link_engagements_timeseries and link_engagements_batch: provide bitlinks OR filter, not both. For link_engagements_timeseries, always pass unix_from_date/unix_to_date (default last 30 days if the user did not specify a range). For link_engagements_batch and list exports, omitting dates falls back to the tier max-history window. Filter tips: filter.destination (hostname, hostname/path, or path) for "links pointing to destination.com" — prefer over filter.query; filter.tags for tag-based sets; filter.query for free-text search on title/tags/URLs. Row caps: up to 200 matched links for engagement exports (bitlinks list or filter resolution); if truncated is true, only the first 200 links were included — say the export is partial and ask the user to narrow filter (tags, destination, domain, dates, campaign, query) or split bitlinks into batches of 200 or fewer. If the API returns EXPORT_TOO_LARGE, the link×day grid exceeds the inline limit — ask the user to narrow the date range or filter to fewer links. Do not state or infer a total match count. For links_list/qr_codes_list with include_metrics, cap is 200 rows; without metrics, 1000. Do not auto-retry bitly_export_data — wait for the user.

bitly_export_data

Get one custom domain's setup state and settings: verification status ('pending', 'ok', or 'error') with any verification error, attached groups, and, once verified, HTTPS/HSTS, redirect, and SSL certificate details. Works for domains still being set up, so use it to check whether a newly added domain has verified yet. Requires membership in a group the domain is attached to, or an admin role in the owning organization.

bitly_get_custom_domain_details

Gets a list of custom domains that can be used for link shortening. This is the member view: only verified domains, across every organization and group, with no setup state. To see an organization's domains with their verification status and settings (including domains still being set up), use bitly_get_organization_custom_domains.

bitly_get_custom_domains

Get full details and destination-override history for a custom-keyword short link — a link with a custom back-half such as 'bit.ly/summer-sale'. Returns the underlying link's metadata plus each destination the keyword has pointed to over time. Use this when the link has a custom keyword and you need its override history. The link MUST be a custom-keyword link — a plain auto-generated link fails with NOT_CUSTOM_BITLINK; for those, use bitly_get_short_link_details instead.

bitly_get_custom_link_details

Get analytics across all links in a group (workspace). Use this when the user asks about overall performance or top-performing links, rather than one specific link. For a single link use bitly_get_link_analytics; for a single QR code's scans use bitly_get_qr_code_analytics. Choose a dataset — 'clicks', 'engagements' (clicks + QR scans + button clicks), 'qr_scans', or 'agentic_traffic' (clicks from AI agents and assistants) — and a dimension: a facet breakdown, 'over_time' (time series), 'top' (best performing links), or 'summary' (a total). There is no group-level total/summary dimension: for an overall count over a period use 'over_time' and total the returned series; for a single link's total use bitly_get_link_analytics with dimension 'summary'. Valid dimensions per dataset — agentic_traffic: summary; clicks: cities, countries, device_os, over_time, referrers, top; engagements: cities, countries, devices, over_time, referrers, referring_networks, top; qr_scans: cities, countries, over_time, top. 'devices' is device form factor (mobile, desktop, ...) and 'device_os' is operating system (iOS, Android, Windows, ...). Notes: for datasets 'engagements' and 'qr_scans' the raw JSON keys counts as 'clicks' even though the values are engagements/scans; for dataset 'clicks' with dimension 'referrers' the v4 API returns engagement counts, not clicks alone; dataset 'agentic_traffic' always covers a fixed 90-day window and ignores the unit/units/unit_reference parameters.

bitly_get_group_analytics

Get specific group information and details by group GUID. Returns comprehensive group metadata including name, organization, role, creation dates, custom domains (BSDs), and status. Use this to get detailed information about a specific group rather than listing all groups. Its custom-domain list is also used to pick a short domain when creating links (see bitly_get_group_preferences for the group's preferred domain).

bitly_get_group_details

Get a group's preferences, including its default (preferred) short domain. Use this when deciding which domain to shorten a link to: check the group's preferred domain here first, then fall back to bitly_get_group_details for the group's full list of available custom domains.

bitly_get_group_preferences

List the QR codes in a group, with search, archived-status and dynamic-routing filters, and pagination. Use this to browse a group's QR codes or to find one by title or destination when you don't have its ID. Note: QR codes backed by an existing short link (coupled) appear here. bitly_update_qr_code can still change their title, archived status and visual customizations, and dynamic routing must be set on the underlying link with bitly_update_short_link instead. Expiration is not supported on coupled QR codes at all.

bitly_get_group_qr_codes

Get links in a specific group with filtering and pagination. Returns a list of links belonging to the specified group, with support for search, filtering by tags, and pagination. Use this to browse, search, or manage links within a workspace. For links ranked by click performance instead, use bitly_get_group_short_links_sorted.

bitly_get_group_short_links

Get a group's links ranked by click performance, with per-link metrics and time-series data. Use this when the user wants their best- (or worst-) performing links in a group, e.g. 'show my top links this month'. To browse or search a group's links without ranking them, use bitly_get_group_short_links instead.

bitly_get_group_short_links_sorted

List the Bitly Sites (link-in-bio pages / microsites) in a group (workspace), with URL filtering and pagination. Use this to browse a group's sites or find one by URL when you don't have its site ID. A Bitly Site is a landing page of buttons/links reachable at a short URL; manage an individual site with bitly_get_site, bitly_create_site, and bitly_update_site.

bitly_get_group_sites

Get all groups (workspaces) that the authenticated user has access to across all organizations. Groups are collections of links and users within an organization. This tool shows group names, IDs, roles, custom domains, and organization associations.

bitly_get_groups

Get analytics for a single short link. Use this when the user asks how one specific link is performing. The dimension selects the report: a breakdown by countries, cities, devices (form factor), referrers, or referring_domains; 'over_time' for a click time series; 'summary' for total click counts; 'engagements'/'engagements_summary' for the same reports with a clicks/scans/button-clicks breakdown; or 'agentic_traffic' for a breakdown of clicks from AI agents and assistants (ChatGPT, Claude, ...) by agent. Agentic traffic is counted separately from clicks, so it is not a subset of the click totals. For analytics across every link in a group (workspace), or top-performing links, use bitly_get_group_analytics. For a single QR code's scans, use bitly_get_qr_code_analytics.

bitly_get_link_analytics

Look up where a short link points: returns its destination long URL plus basic fields (creation time, link ID, and any dynamic-routing destination URLs). Works for any bitlink, including links you don't own. Use this when the user just wants a short link's destination or to verify where it redirects. For full owned-link metadata (tags, creator, campaigns, QR codes, routing rule conditions), use bitly_get_short_link_details instead.

bitly_get_link_destination

List the custom domains of an organization with their setup state: verification status ('pending', 'ok', or 'error'), attached groups, and, once verified, HTTPS/HSTS and redirect settings. Includes domains still being set up. Requires an organization admin; without organization_guid it lists the domains of every organization the caller administers. Use this to check on a domain setup or to review an organization's domain configuration. For the plain list of domains the user can shorten with, use bitly_get_custom_domains instead.

bitly_get_organization_custom_domains

Get all organizations that the authenticated user has access to. Returns organization details including organization ID, name, tier information, role, creation/modification dates, and associated custom domains, also known as branded short domains (BSDs). Use this to understand organizational context and access permissions.

bitly_get_organizations

Get full details for a QR code by its ID: title, destination URL, group, type, archived status, and dynamic routing rules. Use this when you have a QR code ID and need its metadata or current routing. To find QR codes when you don't have an ID, list them with bitly_get_group_qr_codes.

bitly_get_qr_code

Get scan analytics for a single QR code. Use this when the user asks how one specific QR code is performing. The dimension selects the report: a breakdown by countries, cities, device_os (operating system), or browsers; 'over_time' for a time series of scans; or 'summary' for total scan counts. For a single link's clicks/engagements use bitly_get_link_analytics; for QR scans across a whole group use bitly_get_group_analytics with dataset 'qr_scans'.

bitly_get_qr_code_analytics

Return a QR code's image as a base64 data URI (SVG default, or PNG). Most agent UIs cannot render raw image data, so prefer directing the user to the QR code's details page (included in bitly_get_qr_code and bitly_create_qr_code responses) to download the image. Only call this tool if you are certain you can process raw base64 image data.

bitly_get_qr_code_image

Get complete metadata for a short link in your account: title, destination URL, creation time, creator, tags, custom domains, campaign and QR-code IDs, deeplinks, and dynamic routing rules. Use this when you need full details about a link you own. For a lightweight destination-only lookup of any bitlink (including links you don't own), use bitly_get_link_destination instead. For a custom-keyword link's override history, use bitly_get_custom_link_details.

bitly_get_short_link_details

Get a Bitly Site's full configuration by its site ID: URL, status, display name, description, button count, attached QR code, and whether it has unpublished changes. To find a site ID, list a group's sites with bitly_get_group_sites.

bitly_get_site

Get analytics for a single Bitly Site (link-in-bio page). Use this when the user asks how a site is performing. Choose a dataset — 'page_views' (visits to the site), 'button_clicks' (clicks on the site's buttons/links), 'dbc_downloads' (digital business card downloads), 'overview' (a page-views + button-clicks rollup), or 'link_performance' (per-button click totals) — and a dimension: a facet breakdown (countries, cities, devices, referrers), 'over_time' (time series), 'summary' (a total), or 'top' (most-clicked buttons). Valid dimensions per dataset — button_clicks: cities, countries, devices, over_time, top; dbc_downloads: over_time; link_performance: summary; overview: summary; page_views: cities, countries, devices, over_time, referrers, summary. For a single short link's clicks use bitly_get_link_analytics; for a whole group use bitly_get_group_analytics.

bitly_get_site_analytics

List Bitly Site templates that can be applied to a site, optionally filtered by category. Use this to discover a template_guid, then apply it with bitly_apply_site_template.

bitly_get_site_templates

Get authenticated user information including profile details, email addresses, 2FA status, and default group. Provides user context for other operations.

bitly_get_user

Prevalidate button content before adding it to a Bitly Site. Currently supports YouTube videos: given a video_id, it returns the resolved video URL, title, and thumbnail to use when creating a 'youtubeVideo' content block with bitly_create_site_block.

bitly_prevalidate_site_button

Publish a Bitly Site's draft so the current edits go live. Newly created sites and edits are drafts until published. Use bitly_get_site to check whether a site has unpublished changes.

bitly_publish_site

Update a verified custom domain's settings: where the bare domain and unknown paths redirect, and HTTPS/HSTS behavior. Only the fields you send change; omitted fields are left as-is. Requires an admin of the owning organization; a domain that is not yet verified returns CUSTOM_DOMAIN_NOT_VERIFIED, so wait for verification rather than retrying. To attach the domain to a group use bitly_update_group; to make it a group's default use bitly_update_group_preferences.

bitly_update_custom_domain

Rename a group (workspace) or change which custom domains it can shorten links with. The 'bsds' list REPLACES the group's current custom domains: to add one, first read the current list with bitly_get_group_details and pass it back with the new domain appended; omitting a domain the group has today detaches it. Only verified domains of the group's organization can be attached (see bitly_get_organization_custom_domains). Only the fields you send change. Requires a group admin. To make an attached domain the group's default for new links, use bitly_update_group_preferences.

bitly_update_group

Set a group's default (preferred) short domain, used when a link is created for the group without an explicit domain. The domain must be 'bit.ly' or a custom domain already attached to the group (see bitly_get_group_details; attach one with bitly_update_group). Requires a group admin. Use this as the last step of a custom domain setup once the domain is verified.

bitly_update_group_preferences

Update an existing QR code's title, visual customizations, archived status, expiration, or dynamic routing rules. Use this to restyle a QR code, archive/unarchive it, or change its routing. Dynamic routing is only supported on QR codes with a long_url destination (decoupled); for a QR backed by an existing short link (coupled), set routing on the link via bitly_update_short_link instead. Rules you send replace all existing rules.

bitly_update_qr_code

Update an existing short link's destination URL, title, tags, or archived status, or set its dynamic routing rules. Use this to change where a link points, rename it, add or remove tags, archive/unarchive it, or configure routing by country, region, device, or OS. For a QR code that is backed by an existing short link (coupled), set the QR's routing here on the link — not on the QR via bitly_update_qr_code. Dynamic routing rules you send replace all existing rules; send an empty array to clear them.

bitly_update_short_link

Update a Bitly Site's URI, display name, description, or attach a QR code. Only the fields you send change; omitted fields are left as-is, and a present empty string ('') clears display_name/description. Changing the URI creates a redirect from the old one. To attach a QR code: create it first with bitly_create_qr_code, then pass its qr_code_id here (a site can only be attached to one QR code).

bitly_update_site

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 appearance with bitly_get_site (response_format 'json') first to see the existing values. The change is a draft; publish it with bitly_publish_site.

bitly_update_site_appearance

Update an existing block on a Bitly Site, replacing its content (and appearance for text blocks). For a bitlink button, the content object can change its destination, title, or description; for other blocks it depends on the block type. The block type is taken from the stored block, so it cannot be changed. Fetch the block's ID with bitly_get_site. The change is a draft; publish it with bitly_publish_site.

bitly_update_site_block