canonical: https://jentic.com/apis/bitly.com/bitly

# Bitly API

Bitly is the long-running link management platform that shortens URLs, generates QR codes, and reports on click-level analytics. Bitly publishes its own OpenAPI document at `https://dev.bitly.com/v4/v4.json`; the spec behind this page is a curated, agent-optimized Jentic variant that covers the link, QR and analytics subset agents ask for most, kept validated and agent-ready. The v4 REST API covers Bitlinks (shorten and expand), groups and organizations (account hierarchy), branded short domains, campaigns, custom Bitlinks, and per-Bitlink analytics broken down by country, city, device, and referrer. Authentication is a Bearer access token generated in your Bitly account settings. Bitly is a paid, tiered product, so check your plan before you build: per its pricing page campaigns and city-level and device-level click data start at the Premium tier, a complimentary custom domain starts at Growth, and the monthly API-request allowance runs from 1,000 on Free to 50,000 on Premium.

## For AI agents

Shorten URLs, generate QR codes, and pull per-link click analytics on Bitly's v4 API. 45 endpoints, Bearer token authentication.

## Scope

Does not run paid ads, build or manage Bitly landing pages, or send email - use for short-link creation, QR codes, and click analytics only.

## Capabilities

- Shorten a long URL to a Bitlink via POST /v4/shorten
- Expand an existing Bitlink back to its long URL via POST /v4/expand
- Read total clicks and click summary for a Bitlink via GET /v4/bitlinks/{bitlink}/clicks and /clicks/summary
- Break down clicks by country, city, device, or referrer for a single Bitlink (Bitly gates city-level and device-level data to its Premium tier)
- Create and update campaigns and channels, update groups and group preferences, and read organizations and branded short domains (BSDs), which this spec exposes read-only
- Create a QR code for an existing Bitlink or a standalone long URL via POST /v4/qr-codes, which returns the QR code's metadata

## Use cases

### Trackable short links for marketing campaigns

Marketing teams shorten campaign destination URLs through /v4/shorten so each channel gets a distinct Bitlink with its own click count. The shorten body takes long_url plus an optional domain and group_guid, so the same call can mint the Bitlink on a branded short domain; campaign membership is set separately through the campaigns endpoints. Per-Bitlink analytics endpoints then split traffic by country, city, device, and referrer, giving the team the attribution detail they need without standing up their own tracking pipeline. Bitly gates campaigns and city-level and device-level data to its Premium tier and a complimentary custom domain to Growth, so match the plan to the attribution depth you need.

Example prompt: POST /v4/shorten with the campaign destination URL and the campaign group, then read /v4/bitlinks/{bitlink}/clicks/summary after 24 hours

### QR codes for offline-to-online journeys

Brands generate QR codes from short links so that a printed asset (a poster, a receipt, a product label) becomes a measurable channel. POST /v4/qr-codes creates the code from either an existing bitlink_id or a standalone long_url and returns its metadata, including the qr_code_id you store alongside the placement. Where the code points at a Bitlink, Bitly reports scans in that Bitlink's engagements endpoints, which count clicks and scans together. The pairing turns offline placements into measurable traffic without a separate QR vendor.

Example prompt: Create a Bitlink for the destination URL, then POST /v4/qr-codes with its bitlink_id as the destination and return the qr_code_id plus the Bitlink id

### Click analytics ingestion for dashboards

Analytics teams pull per-Bitlink click data into a warehouse so they can join it with downstream conversion events. The /v4/bitlinks/{bitlink}/clicks, /v4/bitlinks/{bitlink}/clicks/summary, /countries, /cities, /devices, and /referrers endpoints provide the raw numbers. Size the job against the monthly allowance on your plan rather than against the number of links you own: Bitly's pricing page puts the API-request allowance at 1,000 per month on Free and 50,000 per month on Premium, and GET /v4/organizations/{organization_guid}/plan_limits reports the current figures for the account.

Example prompt: For each Bitlink in the campaign group, pull /clicks/summary and /countries for the last 30 days and write to the analytics warehouse

### Agent integration via Jentic for short-link generation

An AI agent that needs to produce a trackable short link calls Jentic with the intent 'shorten a url with tracking'. Jentic returns the Bitly /v4/shorten operation with its input schema, and injects the Bearer token at execution. The agent never sees the raw token, so a chat session can hand a Bitlink back to the user without exposing the credential.

Example prompt: Search Jentic for 'shorten a url with tracking', load the /v4/shorten schema, and execute with the user's long URL and group_guid

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v4/shorten | Shorten a long URL into a Bitlink |
| POST | /v4/expand | Expand a Bitlink back to its long URL |
| GET | /v4/bitlinks/{bitlink} | Retrieve a Bitlink and its metadata |
| GET | /v4/bitlinks/{bitlink}/clicks | Read click data points for a Bitlink |
| GET | /v4/bitlinks/{bitlink}/clicks/summary | Read the aggregate click count for a Bitlink over a window |
| GET | /v4/bitlinks/{bitlink}/countries | Break clicks down by country |
| GET | /v4/bitlinks/{bitlink}/devices | Break clicks down by device type |
| GET | /v4/bitlinks/{bitlink}/referrers | Break clicks down by referring domain |

## Key resources

- **Bitlinks** — Shorten, expand, retrieve, and update Bitlinks; read per-Bitlink analytics
- **Custom Bitlinks** — Manage Bitlinks with custom back-halves on a branded short domain
- **Groups** — Manage the group hierarchy that Bitlinks belong to
- **Organizations** — Read organization records, shorten counts, and plan limits
- **Campaigns** — Group Bitlinks into campaigns for aggregate reporting (Premium tier and above)
- **BSDs** — List the branded short domains available as the host of custom Bitlinks
- **QR Codes** — Create a QR code for a Bitlink or a long URL and read back its metadata

## Why Jentic

- **Setup:** Wiring the Bitly API by hand means generating an access token in your Bitly settings, building the bearer Authorization header, targeting the api-ssl.bitly.com host, and threading the right group_guid through its v4 link and analytics calls yourself. Through Jentic you install once, import Bitly from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Bitly puts the bitlink in the URL path (/bitlinks/{bitlink}/clicks), so a rule can pin your agent to one bitlink: it can read clicks and country and device breakdowns for that link and nothing else. You choose the operations it may call, so link creation with POST /v4/shorten is not included unless you add it.
- **Credential handling:** Your Bitly bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'shorten a URL with tracking' or 'get Bitly click analytics', and Jentic returns the matching v4 operation with its input and response schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **TinyURL API** — Lightweight URL shortener with simpler analytics than Bitly.
- **Rebrandly** — Branded link management with strong custom-domain support.
- **Short.io** — Custom-domain short links and click analytics.

## FAQ

### Does Bitly publish an official OpenAPI spec for the Bitly API?

Yes. Bitly links an OpenAPI 3.0 document from its own API reference, at https://dev.bitly.com/v4/v4.json, covering 78 paths and 94 operations. The spec behind this page is a curated, agent-optimized Jentic variant of 45 of those operations, narrowed to the link, QR and analytics calls agents ask for most and kept validated against the live API; when you need an operation outside that subset, take it from Bitly's document. To get started, install Jentic One, the self-hosted execution layer, from its GitHub repo (`https://github.com/jentic/jentic-one`).

### What authentication does the Bitly API use?

Bitly v4 uses HTTP Bearer tokens. Each call sets Authorization: Bearer {token} on the request, using the generic access token you generate in your Bitly account settings under API. Bitly's authentication docs additionally describe OAuth 2.0 flows for acting on behalf of an end user, which neither this spec nor Bitly's own OpenAPI document declares, so treat OAuth as documented but undeclared. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at execution time, so agents never hold the credential.

### Can I shorten a URL with the Bitly API?

Yes. POST /v4/shorten accepts a long_url and an optional group_guid in the body and returns a Bitlink. Pass a domain field to mint the Bitlink on a branded short domain instead of bit.ly.

### What are the rate limits for the Bitly API?

Bitly's rate-limits documentation describes two families. Platform limits apply to every account regardless of subscription plan: per-hour, per-minute and per-IP ceilings on each endpoint, with the per-minute limit set at one-tenth of the hourly one, plus a maximum of five concurrent connections from a single IP address. Plan limits are a monthly allowance, which Bitly's pricing page puts at 1,000 API requests per month on Free rising to 50,000 on Premium. Crossing either returns 429. Bitly's documented way to read your own current figures is the API itself, via GET /v4/organizations/{organization_guid}/plan_limits. Source: https://dev.bitly.com/docs/getting-started/rate-limits.

### How do I get click analytics for a Bitlink through Jentic?

Install Jentic One (self-hosted), import Bitly from the API Directory, then search Jentic for 'get bitly click analytics', load the /v4/bitlinks/{bitlink}/clicks/summary operation, and execute with the Bitlink id. Jentic injects the Bearer token at execution time.

### Can I generate a QR code from a Bitlink?

Yes. POST /v4/qr-codes creates a QR code from either an existing bitlink_id or a standalone long_url and returns the code's metadata, including its qr_code_id. Where the code points at a Bitlink, Bitly counts scans alongside clicks in that Bitlink's engagements endpoints, GET /v4/bitlinks/{bitlink}/engagements and /engagements/summary. Retrieving the rendered image is an operation in Bitly's own OpenAPI document rather than in this curated spec.

### Can I limit what my agent is allowed to do with the Bitly API?

Yes. Because Jentic One is self-hosted, your own rules decide which Bitly operations and credentials your agent may use. Since Bitly puts the bitlink in the URL path, such as /v4/bitlinks/{bitlink}/clicks, you can pin the agent to a single link so it only reads that link's click summary and its country, device, and referrer breakdowns. You choose the operations it may call, so link creation with POST /v4/shorten stays off unless you explicitly add it.

### Is there a Bitly MCP server?

Yes. Bitly runs a first-party MCP server at https://api-ssl.bitly.com/v4/mcp, documented in its own developer docs with OAuth 2.1 or a Bitly API token, and its pricing page lists Bitly MCP on every plan. You can also connect the Bitly API directly through Jentic: your agent gets this spec's full 45-endpoint surface without loading another server's tool definitions into its context, your Bitly token is stored encrypted by your own Jentic One instance and injected at call time rather than pasted into an MCP client config file, and your rules decide which operations the agent may call. Connecting the next API after Bitly is an import, not another install and authorisation setup.