# Bitly

> Shorten URLs, manage Bitlinks and read click metrics via the Bitly v4 API.

Lets an agent manage short links with Bitly - shorten long URLs, expand and
update Bitlinks, and read click metrics broken down by time, country and
referrer.

## What it can do

| Method | What it does |
| --- | --- |
| `bitly_shorten` | Shorten a long URL into a Bitlink. WRITE - confirm first. |
| `bitly_bitlink_get` | Get a Bitlink's details. |
| `bitly_bitlink_update` | Update a Bitlink (title, tags, archive, destination). WRITE - confirm first. |
| `bitly_expand` | Expand a Bitlink to its long URL. |
| `bitly_bitlinks_by_group` | List Bitlinks in a group (paginated, searchable). |
| `bitly_clicks_summary` | Get total click count for a Bitlink over time. |
| `bitly_clicks_by_country` | Get clicks broken down by country. |
| `bitly_clicks_by_referrer` | Get clicks broken down by referrer. |
| `bitly_groups_list` | List groups the token can access. |
| `bitly_group_get` | Get one group's details. |
| `bitly_custom_bitlink_create` | Create a custom branded Bitlink keyword. WRITE - confirm first. |
| `bitly_request` | Generic passthrough to any other v4 endpoint. |

Bitlink ids are given without a scheme, e.g. `bit.ly/abc123`.

## How to get credentials

This connector uses an **access token** (Bearer).

1. Sign in to [Bitly](https://app.bitly.com).
2. Open **Settings -> API** ([app.bitly.com/settings/api](https://app.bitly.com/settings/api/)).
3. Enter your password and click **Generate token**.
4. Copy the token and paste it into FlyMyAI.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `BITLY_API_KEY` | Bitly -> Settings -> API -> Generate token |

## Troubleshooting

- **`401 Unauthorized`** - the token is wrong or revoked. Generate a new one.
- **`403 Forbidden`** - the action needs a paid plan (e.g. custom Bitlinks,
  branded domains) or your account lacks access to that group.
- **`404 Not Found`** - check the Bitlink id format (`bit.ly/abc123`, no scheme)
  or the group GUID; list groups first with `bitly_groups_list`.
- **`429 Too Many Requests`** - you hit the rate limit; retry after a short
  backoff.

## Links

- [Bitly API token page](https://app.bitly.com/settings/api/)
- [Bitly API reference](https://dev.bitly.com/api-reference)