# Go2 — Full LLM Corpus

> Short links your AI agent can call.

Go2 is the link toolkit your AI agent calls. One MCP install gives any agent runtime a complete short-URL platform: create branded links, capture click-by-click analytics, attribute every click back to the (agent_id, run_id, tool_call_id, actor_id) that produced it, and control link lifecycle (expire, single-use, revoke). Built on Cloudflare Workers + D1 + KV. Open source (AGPL). Humans get a dashboard; agents get the tools.

Index file: https://go2.gg/llms.txt
OpenAPI: https://go2.gg/openapi.json
MCP: https://mcp.go2.gg/mcp

================================================================================
## Concepts
================================================================================

### link
A short URL with destination, expiry, geo/device targeting, password gating, click cap, and optional agent attribution context.

### click
A single redirect event with geo, device, browser, OS, referrer, bot detection, uniqueness, and any agent attribution captured at redirect time.

### agent_id
Stable identifier for the agent that created or invoked the link (e.g. claude-code, cursor, gpt-5-task-runner).

### agent_run_id
Per-execution identifier so you can attribute every click back to the specific agent run that produced the link.

### agent_actor_id
Optional end-user / persona identifier for the human the agent acted on behalf of.

### agent_tool_call_id
Optional MCP tool-call id captured at click time so individual tool invocations resolve to clicks.

================================================================================
## REST endpoints
================================================================================

### POST /api/v1/links
Create a tracked short link. Accepts agent attribution context inline.
Scopes: `links:write`

### GET /api/v1/links
List links for the authenticated org, paginated and searchable.
Scopes: `links:read`

### GET /api/v1/links/{id}
Fetch a single link by id.
Scopes: `links:read`

### PATCH /api/v1/links/{id}
Update destination, expiry, click limit, targeting, or agent attribution.
Scopes: `links:write`

### DELETE /api/v1/links/{id}
Archive a link. Existing redirects return 410.
Scopes: `links:write`

### GET /api/v1/agent-attribution
Stream of clicks filtered by agent_id / agent_run_id / link_id.
Scopes: `attribution:read`

### GET /api/v1/agent-attribution/summary
Click rollup grouped by agent_id or agent_run_id.
Scopes: `attribution:read`

### GET /api/v1/agent-attribution/runs
Distinct agent runs with click counts and first/last timestamps.
Scopes: `attribution:read`

### GET /api/v1/analytics/{linkId}
Per-link analytics: geo, device, browser, OS, referrer breakdowns.
Scopes: `analytics:read`

### POST /api/v1/qr
Generate a QR code (PNG or SVG) for a link.
Scopes: `links:read`

### GET /api/v1/api-keys
List API keys for the authenticated organization.
Scopes: `*`

### POST /api/v1/api-keys
Provision a new API key. Plaintext returned once at creation time.
Scopes: `*`

### GET /api/v1/webhooks
List outgoing webhook subscriptions.
Scopes: `webhooks:read`

### POST /api/v1/webhooks
Subscribe a URL to events such as click, link.created, qr.scanned.
Scopes: `webhooks:write`

### GET /api/v1/usage
Current-period usage counters: links created, clicks, custom domains.
Scopes: `*`

================================================================================
## MCP tools
================================================================================

### create_link
Category: links
Create a short link.

### list_links
Category: links
List links for the authenticated org.

### get_link
Category: links
Fetch a single link by id.

### update_link
Category: links
Update an existing link.

### delete_link
Category: links
Archive a link.

### bulk_create_links
Category: links
Create many links in one call.

### get_analytics
Category: links
Per-link analytics roll-up.

### track_agent_link
Category: attribution
Create a link and stamp it with agent_id, agent_run_id, agent_actor_id.

### get_run_attribution
Category: attribution
Click stream for a given agent_run_id / agent_id / link.

### list_agent_runs
Category: attribution
Distinct agent runs with click counts and first/last timestamps.

### create_revocable_link
Category: lifecycle
Create a single-use link that 410s after one click.

### create_expiring_link
Category: lifecycle
Create a link with TTL in minutes.

### revoke_run_links
Category: lifecycle
Archive every link associated with a given agent_run_id.

### search_docs
Category: docs
Search Go2 documentation.

### get_doc
Category: docs
Fetch a documentation page by slug.

### list_docs
Category: docs
Enumerate documentation pages.

================================================================================
## Install (any MCP client)
================================================================================

Claude Code:
```
claude mcp add go2 -- npx -y go2-mcp-server@latest --api-key "$GO2_API_KEY"
```

Claude Desktop / Cursor / Windsurf — add to the client's MCP config:
```json
{
  "mcpServers": {
    "go2": {
      "command": "npx",
      "args": ["-y", "go2-mcp-server@latest"],
      "env": {
        "GO2_API_KEY": "go2_xxx",
        "GO2_AGENT_ID": "claude-desktop",
        "GO2_AGENT_RUN_ID": "set-per-conversation"
      }
    }
  }
}
```

Remote MCP (OAuth 2.1): https://mcp.go2.gg/mcp

================================================================================
## Common questions an LLM might be asked
================================================================================

### How do I create a tracked link with agent attribution?
POST /api/v1/links with body {"destinationUrl": "...", "agentId": "...", "agentRunId": "..."}. From an MCP client, call the track_agent_link tool. Agent context falls back to GO2_AGENT_* env vars if not passed explicitly.

### Which agent run drove a click?
GET /api/v1/agent-attribution?agentRunId=<run_id>. Or call the get_run_attribution MCP tool. Returns the click stream with agent_id, agent_run_id, agent_actor_id, agent_tool_call_id per click.

### List every distinct agent run with click counts?
GET /api/v1/agent-attribution/runs. Or call the list_agent_runs MCP tool. Returns (agent_id, agent_run_id, clicks, firstClickAt, lastClickAt) tuples sorted by lastClickAt.

### Group clicks by agent_id over a time window?
GET /api/v1/agent-attribution/summary?groupBy=agent_id&since=24h. Pass groupBy=agent_run_id for per-run rollups.

### Revoke every link a specific agent run created?
Call the revoke_run_links MCP tool with {"agentRunId": "<run_id>"}. Returns the count of links archived. Existing redirects start returning 410 Gone immediately.

### Create a single-use or short-TTL link?
Use the create_revocable_link or create_expiring_link MCP tools. Both stamp the link with the ambient agent context so attribution still works.

### What's the auth model?
Bearer API keys (Authorization: Bearer go2_...) or OAuth 2.1 access tokens. API keys are minted at /dashboard/developer/keys and are shown once. OAuth uses PKCE with dynamic client registration (RFC 7591).

### How do I pass agent context at click time (not link-create time)?
Append short query keys to the short URL: ?ag=<agent_id>&ar=<agent_run_id>&at=<tool_call_id>&au=<actor_id>. They're stripped before the destination redirect. Or send x-agent-* request headers if you control the click origin.

================================================================================
## OpenAPI specification
================================================================================

(Live spec at https://go2.gg/openapi.json — fetch failed at build time.)

================================================================================
## Documentation pages
================================================================================

================================================================================
# API Overview

URL: https://go2.gg/docs/api/overview
Section: API
Description: Introduction to the Go2 REST API.


The Go2 API is a REST API that allows you to programmatically manage links, domains, and analytics. All endpoints use JSON for request and response bodies.

## Base URL

```
https://api.go2.gg/api/v1
```

For local development:

```
http://localhost:8787/api/v1
```

## Authentication

Most API endpoints require authentication using an API key. Include your key in the `Authorization` header:

```bash
curl https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Creating an API Key

1. Log in to your Go2 dashboard
2. Go to **Settings → API Keys**
3. Click **"Create New API Key"**
4. Give it a name and select permissions
5. Copy the key (it won't be shown again)

### API Key Permissions

| Permission | Description |
|------------|-------------|
| `links:read` | View links |
| `links:write` | Create, update, delete links |
| `domains:read` | View domains |
| `domains:write` | Add, verify, delete domains |
| `analytics:read` | View click analytics |

## Response Format

All responses follow a consistent format:

### Success Response

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 100,
    "hasMore": true
  }
}
```

### Error Response

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid URL format",
    "details": { ... }
  }
}
```

## HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `201` | Created |
| `204` | No Content (successful delete) |
| `400` | Bad Request - Invalid input |
| `401` | Unauthorized - Missing or invalid API key |
| `402` | Payment Required - Plan limit reached |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found |
| `409` | Conflict - Resource already exists |
| `429` | Too Many Requests - Rate limited |
| `500` | Internal Server Error |

## Rate Limiting

API requests are rate-limited based on your plan:

| Plan | Rate Limit |
|------|------------|
| Free | 60 requests/minute |
| Pro | 300 requests/minute |
| Business | 1,000 requests/minute |
| Enterprise | Custom |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200
```

## Pagination

List endpoints support pagination via query parameters:

```bash
GET /links?page=2&perPage=50
```

| Parameter | Default | Max | Description |
|-----------|---------|-----|-------------|
| `page` | 1 | - | Page number |
| `perPage` | 20 | 100 | Items per page |

## Endpoints

### Links

- `GET /links` - List all links
- `POST /links` - Create a new link
- `GET /links/:id` - Get a link by ID
- `PATCH /links/:id` - Update a link
- `DELETE /links/:id` - Delete (archive) a link
- `GET /links/:id/stats` - Get link analytics

### Domains

- `GET /domains` - List all domains
- `POST /domains` - Add a new domain
- `GET /domains/:id` - Get domain details
- `DELETE /domains/:id` - Remove a domain
- `POST /domains/:id/verify` - Verify domain ownership

### Usage

- `GET /usage` - Get current usage stats

## SDKs

Official SDKs are coming soon:

- JavaScript/TypeScript
- Python
- Go
- PHP

## Webhooks

Go2 can send webhook notifications for link events. See [Webhooks](/docs/api/webhooks) for details.

## Quick Start Examples

### Create Your First Link

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/my-page"
  }'
```

### Get All Links

```bash
curl https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Get Link Analytics

```bash
curl https://api.go2.gg/api/v1/links/lnk_abc123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Using the SDK

```typescript
import { Go2 } from '@go2/sdk';

const go2 = new Go2({ apiKey: 'YOUR_API_KEY' });

// Create a link
const link = await go2.links.create({
  destinationUrl: 'https://example.com/product',
  slug: 'my-product',
  title: 'Product Page'
});

console.log(`Created: ${link.shortUrl}`);

// Get analytics
const stats = await go2.links.stats(link.id);
console.log(`Clicks: ${stats.totalClicks}`);
```

## Common Patterns

### Bulk Link Creation

```typescript
const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];

const links = await Promise.all(
  urls.map(url => go2.links.create({ destinationUrl: url }))
);

console.log(`Created ${links.length} links`);
```

### Link Expiration Management

```typescript
// Create link that expires in 30 days
const expiresAt = new Date();
expiresAt.setDate(expiresAt.getDate() + 30);

const link = await go2.links.create({
  destinationUrl: 'https://example.com/promo',
  expiresAt: expiresAt.toISOString()
});
```

### Geo-Targeted Links

```typescript
const link = await go2.links.create({
  destinationUrl: 'https://example.com/default',
  geoTargets: {
    US: 'https://example.com/us',
    GB: 'https://example.com/uk',
    DE: 'https://example.com/de'
  }
});
```

## Error Handling

Always handle errors appropriately:

```typescript
try {
  const link = await go2.links.create({
    destinationUrl: 'https://example.com'
  });
} catch (error) {
  if (error.code === 'SLUG_EXISTS') {
    console.error('Slug already in use');
  } else if (error.code === 'LIMIT_REACHED') {
    console.error('Plan limit reached');
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Rate Limiting Best Practices

- Implement exponential backoff for retries
- Cache responses when possible
- Batch operations when creating multiple links
- Monitor rate limit headers

```typescript
// Example with retry logic
async function createLinkWithRetry(destinationUrl: string, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await go2.links.create({ destinationUrl });
    } catch (error) {
      if (error.status === 429 && i < retries - 1) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}
```

## Next Steps

- [Links API Reference](/docs/api/links) - Create and manage short links
- [Domains API Reference](/docs/api/domains) - Add custom domains
- [Analytics API Reference](/docs/api/analytics) - Access click data
- [Webhooks Guide](/docs/api/webhooks) - Real-time event notifications
- [Integration Guides](/docs/integrations) - Connect with Zapier, Make, Slack

================================================================================
# Short Links

URL: https://go2.gg/docs/features/links
Section: Features
Description: Create and manage short links with Go2.


Go2 makes it easy to create short, memorable links that redirect to any URL. This guide covers all the features available for link management.

## Creating Links

### From the Dashboard

1. Log in to your Go2 dashboard
2. Click **"Create New Link"** or press `Ctrl/Cmd + K`
3. Paste your destination URL
4. (Optional) Customize the settings
5. Click **"Create"**

### From the API

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl": "https://example.com/my-page"}'
```

## Custom Slugs

By default, Go2 generates a random 6-character slug. You can specify a custom slug:

- **Length**: 1-50 characters
- **Characters**: Letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_)
- **Case-sensitive**: `MyLink` and `mylink` are different slugs

### Reserved Slugs

Some slugs are reserved for system use:

- `api`, `app`, `admin`, `dashboard`
- `login`, `register`, `logout`
- `health`, `status`, `ping`

## Link Settings

### Title & Description

Add a title and description to organize your links. These are visible in your dashboard and help with searching.

### Tags

Apply tags to categorize links:

```json
{
  "tags": ["marketing", "summer-2024", "social"]
}
```

Filter links by tag in the dashboard or API.

### Expiration

Set an expiration date after which the link will stop redirecting:

```json
{
  "expiresAt": "2024-12-31T23:59:59Z"
}
```

Expired links return a 410 Gone response.

### Click Limits

Limit how many times a link can be clicked:

```json
{
  "clickLimit": 1000
}
```

Once the limit is reached, the link returns a 410 Gone response.

### Password Protection

Protect links with a password. Visitors will see a password prompt before being redirected:

```json
{
  "password": "secretcode123"
}
```

Passwords are hashed and never stored in plain text.

## UTM Parameters

Automatically append UTM parameters to your destination URLs:

```json
{
  "utmSource": "twitter",
  "utmMedium": "social",
  "utmCampaign": "summer-sale"
}
```

This transforms:
- Input: `https://example.com/page`
- Output: `https://example.com/page?utm_source=twitter&utm_medium=social&utm_campaign=summer-sale`

## Geo Targeting

Redirect visitors to different URLs based on their country:

```json
{
  "destinationUrl": "https://example.com/global",
  "geoTargets": {
    "US": "https://example.com/us",
    "GB": "https://example.com/uk",
    "DE": "https://example.com/de",
    "FR": "https://example.com/fr"
  }
}
```

Visitors from unlisted countries go to the default destination URL.

## Device Targeting

Redirect based on device type:

```json
{
  "destinationUrl": "https://example.com",
  "deviceTargets": {
    "mobile": "https://m.example.com",
    "tablet": "https://tablet.example.com"
  }
}
```

### App Deep Links

For mobile apps, set platform-specific deep links:

```json
{
  "destinationUrl": "https://example.com/app",
  "iosUrl": "myapp://product/123",
  "androidUrl": "intent://product/123#Intent;scheme=myapp;package=com.myapp;end"
}
```

Go2 detects the operating system and redirects accordingly.

## Link Preview Customization

Customize how your link appears when shared on social media:

```json
{
  "ogTitle": "Check out this amazing product!",
  "ogDescription": "The best product you'll ever find.",
  "ogImage": "https://example.com/og-image.png"
}
```

These settings control the Open Graph meta tags on the link preview page.

## Bulk Operations

### Bulk Create

Create multiple links at once via the API:

```bash
curl -X POST https://api.go2.gg/api/v1/links/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {"destinationUrl": "https://example.com/page1"},
      {"destinationUrl": "https://example.com/page2"},
      {"destinationUrl": "https://example.com/page3"}
    ]
  }'
```

### Bulk Delete

Archive multiple links:

```bash
curl -X DELETE https://api.go2.gg/api/v1/links/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["lnk_abc123", "lnk_def456"]}'
```

## Link Analytics

Every link automatically tracks:

- **Total clicks** and unique visitors
- **Geographic distribution** by country and city
- **Device types** (mobile, desktop, tablet)
- **Browsers** and operating systems
- **Referrer sources**
- **Click timeline**

View analytics in the dashboard or via the API.

## Archiving vs Deleting

- **Archive**: Soft delete. Link stops redirecting but data is preserved. Can be restored.
- **Delete**: Permanent removal. Cannot be undone.

From the dashboard, you can toggle archived links visibility.

## Best Practices

1. **Use descriptive slugs**: `summer-sale` is better than `abc123`
2. **Set expiration dates**: Clean up old campaign links
3. **Apply tags**: Makes filtering and organization easier
4. **Monitor analytics**: Track what's working
5. **Use custom domains**: Builds brand trust

## Next Steps

- [Custom Domains](/docs/features/domains) - Brand your short links
- [Analytics](/docs/features/analytics) - Deep dive into tracking
- [QR Codes](/docs/features/qr-codes) - Generate scannable codes


================================================================================
# Introduction

URL: https://go2.gg/docs/introduction
Description: Welcome to the Go2 documentation.


Go2 is an edge-native URL shortener built on Cloudflare's global network. With sub-10ms redirects from 310+ edge locations worldwide, Go2 is the fastest way to shorten, share, and track your links.

## Why Go2?

- **⚡ Blazing Fast** - Edge-native redirects in under 10ms globally
- **🌍 Custom Domains** - Use your own branded domains with automatic SSL
- **📊 Real-Time Analytics** - Track clicks, locations, devices, and referrers
- **🔗 Smart Links** - Geo-targeting, device targeting, and deep linking
- **🔒 Privacy-First** - No cookies, no cross-site tracking, GDPR compliant
- **🛠️ Developer-Friendly** - Full REST API with comprehensive documentation

## Core Features

| Feature | Description |
|---------|-------------|
| Short Links | Create short, memorable links instantly |
| Custom Domains | Brand your links with your own domain |
| Analytics | Real-time click tracking and insights |
| QR Codes | Generate dynamic QR codes for any link |
| Link Management | Tags, expiration, password protection |
| API Access | Programmatic link management |

## Architecture

Go2 is built entirely on Cloudflare's developer platform:

- **Cloudflare Workers** - Serverless functions running at the edge
- **Cloudflare KV** - Low-latency key-value storage for fast lookups
- **Cloudflare D1** - SQLite database for link and user management
- **Analytics Engine** - Real-time click analytics at scale

This architecture means zero cold starts, automatic scaling, and global performance.

## Getting Started

Ready to create your first short link? Head over to the [Quick Start](/docs/quickstart) guide to get set up.

## Need Help?

- Check the documentation sidebar for detailed guides
- [Contact support](/contact) for direct assistance
- Follow us on [Twitter](https://x.com/BuildWithRakesh) for updates


================================================================================
# TypeScript SDK

URL: https://go2.gg/docs/sdks/typescript
Section: SDKs
Description: Official TypeScript SDK for the Go2 API.


The official TypeScript SDK for the Go2 API. Full type definitions, autocomplete support, and comprehensive documentation.

## Installation

```bash
npm install @go2/sdk
# or
pnpm add @go2/sdk
# or
yarn add @go2/sdk
```

## Quick Start

```typescript
import { Go2 } from '@go2/sdk';

// Initialize with your API key
const go2 = new Go2({
  apiKey: 'go2_your_api_key',
});

// Create a short link
const link = await go2.links.create({
  destinationUrl: 'https://example.com/very/long/path',
  slug: 'my-link',
});

console.log(link.shortUrl); // https://go2.gg/my-link
```

## Configuration

```typescript
const go2 = new Go2({
  // Required: Your API key
  apiKey: 'go2_xxx',
  
  // Optional: Custom API URL (for self-hosted)
  baseUrl: 'https://api.go2.gg',
  
  // Optional: Request timeout in milliseconds
  timeout: 30000,
});
```

## Resources

The SDK provides access to all Go2 API resources:

| Resource | Description |
|----------|-------------|
| `go2.links` | Create and manage short links |
| `go2.domains` | Manage custom domains |
| `go2.webhooks` | Configure webhooks |
| `go2.galleries` | Link-in-Bio pages |
| `go2.qr` | QR code generation |

## Links

### Create a Link

```typescript
const link = await go2.links.create({
  destinationUrl: 'https://example.com',
  slug: 'custom-slug',         // optional
  title: 'My Link',            // optional
  password: 'secret',          // optional
  expiresAt: '2025-12-31',     // optional
  utmSource: 'twitter',        // optional
  utmMedium: 'social',         // optional
  utmCampaign: 'launch',       // optional
});
```

### List Links

```typescript
const { data, meta } = await go2.links.list({
  page: 1,
  perPage: 20,
  search: 'marketing',  // optional
});

console.log(`Showing ${data.length} of ${meta.total} links`);
```

### Get Link Analytics

```typescript
const stats = await go2.links.stats('lnk_abc123', {
  period: '7d',  // '24h', '7d', '30d', '90d', 'all'
});

console.log(`Total clicks: ${stats.totalClicks}`);
console.log(`Unique clicks: ${stats.uniqueClicks}`);

// Top countries
stats.clicksByCountry.forEach(({ country, clicks }) => {
  console.log(`${country}: ${clicks}`);
});
```

## Webhooks

### Create a Webhook

```typescript
const webhook = await go2.webhooks.create({
  name: 'Analytics Pipeline',
  url: 'https://your-server.com/webhooks/go2',
  events: ['click', 'link.created', 'link.deleted'],
});

// IMPORTANT: Store the secret securely - it's only shown once!
console.log('Webhook secret:', webhook.secret);
```

### Test a Webhook

```typescript
const result = await go2.webhooks.test('wh_abc123');

if (result.success) {
  console.log(`Success! Response time: ${result.duration}ms`);
} else {
  console.log(`Failed: ${result.response}`);
}
```

## Galleries (Link-in-Bio)

### Create a Bio Page

```typescript
const gallery = await go2.galleries.create({
  slug: 'johndoe',
  title: 'John Doe',
  bio: 'Developer, creator, coffee enthusiast',
  theme: 'gradient',
  socialLinks: [
    { platform: 'twitter', url: 'https://twitter.com/johndoe' },
    { platform: 'github', url: 'https://github.com/johndoe' },
  ],
});
```

### Add Items

```typescript
// Add a link
await go2.galleries.addItem(gallery.id, {
  type: 'link',
  title: 'My Portfolio',
  url: 'https://johndoe.dev',
  iconName: 'Globe',
});

// Add a section header
await go2.galleries.addItem(gallery.id, {
  type: 'header',
  title: 'Projects',
});

// Publish when ready
await go2.galleries.publish(gallery.id, true);
```

## QR Codes

### Generate QR Code

```typescript
const qr = await go2.qr.generate({
  url: 'https://go2.gg/my-link',
  size: 512,
  foregroundColor: '#1a365d',
  backgroundColor: '#FFFFFF',
  cornerRadius: 10,
  errorCorrection: 'H',  // High - best for logos
});

// qr.svg contains the SVG markup
```

### Save QR Code with Tracking

```typescript
const qr = await go2.qr.create({
  name: 'Business Card QR',
  url: 'https://go2.gg/vcard',
  linkId: 'lnk_abc123',  // Link to track scans
});

// Later, check scan count
const updated = await go2.qr.get(qr.id);
console.log(`Scans: ${updated.scanCount}`);
```

## Error Handling

```typescript
import { Go2, Go2Error } from '@go2/sdk';

const go2 = new Go2({ apiKey: 'go2_xxx' });

try {
  const link = await go2.links.create({
    destinationUrl: 'not-a-valid-url',
  });
} catch (error) {
  if (error instanceof Go2Error) {
    console.error('Go2 API Error:');
    console.error(`  Message: ${error.message}`);
    console.error(`  Code: ${error.code}`);
    console.error(`  Status: ${error.status}`);
    
    if (error.code === 'VALIDATION_ERROR') {
      console.error('  Details:', error.details);
    }
  } else {
    // Network or other error
    throw error;
  }
}
```

### Error Codes

| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Invalid input data |
| `NOT_FOUND` | Resource not found |
| `FORBIDDEN` | Insufficient permissions |
| `RATE_LIMITED` | Too many requests |
| `TIMEOUT` | Request timed out |
| `NETWORK_ERROR` | Connection failed |

## TypeScript Types

All types are exported for use in your applications:

```typescript
import type {
  Link,
  CreateLinkInput,
  LinkStats,
  Domain,
  Webhook,
  Gallery,
  GalleryItem,
  QRCode,
} from '@go2/sdk';

// Use in your functions
async function createCampaignLink(
  campaign: string
): Promise<Link> {
  return go2.links.create({
    destinationUrl: `https://example.com/${campaign}`,
    utmCampaign: campaign,
  });
}
```

## Next Steps

- [API Reference](/docs/api/overview) - Full API documentation
- [Webhooks Guide](/docs/api/webhooks) - Set up real-time events
- [Examples](https://github.com/rakesh1002/go2.gg/tree/main/examples) - Code examples


================================================================================
# Links API

URL: https://go2.gg/docs/api/links
Section: API
Description: Create, manage, and track short links via the API.


The Links API allows you to programmatically create and manage short links.

## Create a Link

Create a new short link.

```
POST /links
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `destinationUrl` | string | Yes | The target URL to redirect to |
| `slug` | string | No | Custom slug (auto-generated if not provided) |
| `domain` | string | No | Custom domain (uses default if not provided) |
| `title` | string | No | Link title for organization |
| `description` | string | No | Link description |
| `tags` | string[] | No | Tags for filtering |
| `password` | string | No | Password to protect the link |
| `expiresAt` | string | No | ISO 8601 expiration date |
| `clickLimit` | number | No | Maximum number of clicks allowed |
| `geoTargets` | object | No | Country-specific redirect URLs |
| `deviceTargets` | object | No | Device-specific redirect URLs |
| `iosUrl` | string | No | iOS app deep link URL |
| `androidUrl` | string | No | Android app deep link URL |

### Example Request

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/my-landing-page",
    "slug": "summer-sale",
    "title": "Summer Sale Campaign",
    "tags": ["marketing", "summer-2024"],
    "expiresAt": "2024-09-01T00:00:00Z"
  }'
```

### Example Response

```json
{
  "success": true,
  "data": {
    "id": "lnk_abc123",
    "shortUrl": "https://go2.gg/summer-sale",
    "destinationUrl": "https://example.com/my-landing-page",
    "slug": "summer-sale",
    "domain": "go2.gg",
    "title": "Summer Sale Campaign",
    "tags": ["marketing", "summer-2024"],
    "hasPassword": false,
    "expiresAt": "2024-09-01T00:00:00Z",
    "clickCount": 0,
    "createdAt": "2024-06-01T10:30:00Z",
    "updatedAt": "2024-06-01T10:30:00Z"
  }
}
```

## List Links

Retrieve all links for your account.

```
GET /links
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | number | 1 | Page number |
| `perPage` | number | 20 | Items per page (max 100) |
| `search` | string | - | Search by slug, URL, or title |
| `domain` | string | - | Filter by domain |
| `tag` | string | - | Filter by tag |
| `archived` | boolean | false | Include archived links |
| `sort` | string | "created" | Sort by: created, clicks, updated |

### Example Request

```bash
curl "https://api.go2.gg/api/v1/links?perPage=10&sort=clicks" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json
{
  "success": true,
  "data": [
    {
      "id": "lnk_abc123",
      "shortUrl": "https://go2.gg/summer-sale",
      "destinationUrl": "https://example.com/my-landing-page",
      "clickCount": 1542,
      "createdAt": "2024-06-01T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 10,
    "total": 47,
    "hasMore": true
  }
}
```

## Get a Link

Retrieve a single link by ID.

```
GET /links/:id
```

### Example Request

```bash
curl https://api.go2.gg/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Update a Link

Update an existing link.

```
PATCH /links/:id
```

### Request Body

All fields from `POST /links` are supported, plus:

| Field | Type | Description |
|-------|------|-------------|
| `isArchived` | boolean | Archive or restore the link |

### Example Request

```bash
curl -X PATCH https://api.go2.gg/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/updated-page",
    "tags": ["marketing", "summer-2024", "updated"]
  }'
```

## Delete a Link

Archive a link (soft delete). The link will no longer redirect.

```
DELETE /links/:id
```

### Example Request

```bash
curl -X DELETE https://api.go2.gg/api/v1/links/lnk_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `204 No Content` on success.

## Get Link Analytics

Retrieve detailed analytics for a link.

```
GET /links/:id/stats
```

### Example Request

```bash
curl https://api.go2.gg/api/v1/links/lnk_abc123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json
{
  "success": true,
  "data": {
    "totalClicks": 1542,
    "lastClickedAt": "2024-06-15T14:22:00Z",
    "byCountry": [
      { "country": "US", "count": 823 },
      { "country": "GB", "count": 234 },
      { "country": "DE", "count": 156 }
    ],
    "byDevice": [
      { "device": "desktop", "count": 892 },
      { "device": "mobile", "count": 587 },
      { "device": "tablet", "count": 63 }
    ],
    "byBrowser": [
      { "browser": "Chrome", "count": 756 },
      { "browser": "Safari", "count": 423 },
      { "browser": "Firefox", "count": 189 }
    ],
    "byReferrer": [
      { "referrer": "twitter.com", "count": 412 },
      { "referrer": "facebook.com", "count": 287 },
      { "referrer": "direct", "count": 543 }
    ],
    "overTime": [
      { "date": "2024-06-01", "count": 45 },
      { "date": "2024-06-02", "count": 67 },
      { "date": "2024-06-03", "count": 89 }
    ]
  }
}
```

## Geo Targeting

Create links that redirect to different URLs based on the visitor's country.

```json
{
  "destinationUrl": "https://example.com/default",
  "geoTargets": {
    "US": "https://example.com/us",
    "GB": "https://example.com/uk",
    "DE": "https://example.com/de"
  }
}
```

## Device Targeting

Create links that redirect to different URLs based on the visitor's device.

```json
{
  "destinationUrl": "https://example.com/default",
  "deviceTargets": {
    "mobile": "https://m.example.com",
    "tablet": "https://tablet.example.com"
  },
  "iosUrl": "https://apps.apple.com/app/myapp",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp"
}
```

## Advanced Examples

### Create Link with UTM Parameters

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/product",
    "slug": "summer-sale-2024",
    "utmSource": "email",
    "utmMedium": "newsletter",
    "utmCampaign": "summer-sale",
    "utmTerm": "promo",
    "utmContent": "cta-button"
  }'
```

### Create Password-Protected Link

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/premium-content",
    "slug": "exclusive-access",
    "password": "secure123",
    "title": "Premium Content Access"
  }'
```

### Create Link with Expiration

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/flash-sale",
    "slug": "flash-sale",
    "expiresAt": "2024-12-31T23:59:59Z",
    "clickLimit": 1000
  }'
```

### Create Link with Geo + Device Targeting

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/default",
    "slug": "smart-link",
    "geoTargets": {
      "US": "https://example.com/us",
      "GB": "https://example.com/uk",
      "DE": "https://example.com/de"
    },
    "deviceTargets": {
      "mobile": "https://m.example.com",
      "tablet": "https://tablet.example.com"
    },
    "iosUrl": "https://apps.apple.com/app/myapp",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp"
  }'
```

### Bulk Create Links

```bash
# Create multiple links in a loop
for url in "https://example.com/page1" "https://example.com/page2" "https://example.com/page3"; do
  curl -X POST https://api.go2.gg/api/v1/links \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destinationUrl\": \"$url\"}"
done
```

### Using with JavaScript/TypeScript

```typescript
import { Go2 } from '@go2/sdk';

const go2 = new Go2({ apiKey: 'YOUR_API_KEY' });

// Create a link
const link = await go2.links.create({
  destinationUrl: 'https://example.com/product',
  slug: 'summer-sale',
  title: 'Summer Sale Campaign',
  tags: ['marketing', 'summer-2024'],
  utmSource: 'email',
  utmCampaign: 'summer-sale'
});

console.log(`Created: ${link.shortUrl}`);

// Get analytics
const stats = await go2.links.stats(link.id);
console.log(`Total clicks: ${stats.totalClicks}`);
```

### Using with Python

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.go2.gg/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a link
response = requests.post(
    f"{BASE_URL}/links",
    headers=headers,
    json={
        "destinationUrl": "https://example.com/product",
        "slug": "summer-sale",
        "title": "Summer Sale Campaign"
    }
)

link = response.json()["data"]
print(f"Created: {link['shortUrl']}")

# Get analytics
stats_response = requests.get(
    f"{BASE_URL}/links/{link['id']}/stats",
    headers=headers
)
stats = stats_response.json()["data"]
print(f"Total clicks: {stats['totalClicks']}")
```

## Error Codes

| Code | Description |
|------|-------------|
| `SLUG_RESERVED` | The requested slug is reserved |
| `SLUG_EXISTS` | The slug is already in use on this domain |
| `INVALID_URL` | The destination URL is invalid |
| `LIMIT_REACHED` | You've reached your plan's link limit |
| `DOMAIN_NOT_VERIFIED` | The custom domain hasn't been verified |
| `INVALID_EXPIRATION` | The expiration date is in the past |
| `PASSWORD_TOO_SHORT` | Password must be at least 4 characters |


================================================================================
# Custom Domains

URL: https://go2.gg/docs/features/domains
Section: Features
Description: Use your own branded domain for short links.


Custom domains let you use your own branded domain for short links instead of `go2.gg`. This builds trust with your audience and reinforces your brand identity.

## Why Use a Custom Domain?

- **Brand Recognition**: `your.link/sale` is more memorable than `go2.gg/xyz123`
- **Trust**: Users are more likely to click links from domains they recognize
- **Professionalism**: Shows you've invested in your link infrastructure
- **Analytics**: Track performance across your branded links

## Adding a Custom Domain

### Step 1: Add the Domain

1. Go to **Dashboard → Domains**
2. Click **"Add Domain"**
3. Enter your domain (e.g., `link.example.com`)
4. Click **"Add"**

### Step 2: Configure DNS

Go2 will display the required DNS records. Add these to your DNS provider:

#### Verification Record (TXT)

```
Name: _go2.link.example.com
Type: TXT
Value: go2-verify=abc123def456
```

#### Redirect Record (CNAME)

```
Name: link.example.com
Type: CNAME
Value: cname.go2.gg
```

### Step 3: Verify Ownership

1. Wait 5-10 minutes for DNS propagation
2. Click **"Verify Domain"** in your dashboard
3. Go2 will check the TXT record automatically

Once verified, your domain is ready to use!

## SSL Certificates

Go2 automatically provisions SSL certificates for your custom domains using Cloudflare's edge certificates. No configuration required.

- **Automatic provisioning**: SSL is set up within minutes
- **Auto-renewal**: Certificates never expire
- **Full encryption**: All traffic is HTTPS

## Domain Settings

### Default Redirect URL

Set where visitors go when they visit your domain without a path:

```
https://link.example.com → https://example.com
```

Configure in **Dashboard → Domains → [Your Domain] → Settings**.

### Not Found URL

Set a custom 404 page for invalid slugs:

```
https://link.example.com/invalid → https://example.com/404
```

## Using Custom Domains

Once verified, select your custom domain when creating links:

### Dashboard

Choose your domain from the dropdown when creating a new link.

### API

Specify the `domain` field:

```json
{
  "destinationUrl": "https://example.com/landing",
  "domain": "link.example.com",
  "slug": "summer-sale"
}
```

Result: `https://link.example.com/summer-sale`

## Multiple Domains

You can add multiple custom domains based on your plan:

| Plan | Custom Domains |
|------|----------------|
| Free | 1 |
| Pro | 5 |
| Business | 20 |
| Enterprise | Unlimited |

Use different domains for different purposes:

- `link.example.com` - General marketing
- `get.example.com` - Product downloads
- `join.example.com` - Event registrations

## DNS Providers

Here's how to configure DNS with popular providers:

### Cloudflare

1. Log in to Cloudflare Dashboard
2. Select your domain
3. Go to **DNS → Records**
4. Add the TXT and CNAME records
5. Ensure the CNAME is **proxied** (orange cloud)

### GoDaddy

1. Log in to GoDaddy
2. Go to **My Products → DNS**
3. Click **Add** for each record
4. Enter the Name, Type, and Value

### Namecheap

1. Log in to Namecheap
2. Go to **Domain List → Manage**
3. Click **Advanced DNS**
4. Add both records

### Google Domains

1. Log in to Google Domains
2. Select your domain
3. Go to **DNS → Custom records**
4. Add the TXT and CNAME records

## Troubleshooting

### Domain Won't Verify

- **Wait longer**: DNS propagation can take up to 48 hours
- **Check records**: Ensure the TXT record is exactly as shown
- **Remove quotes**: Some providers add quotes around TXT values

Use a tool like [DNS Checker](https://dnschecker.org) to verify propagation.

### SSL Certificate Issues

- **Wait**: Certificate provisioning takes up to 15 minutes
- **Clear cache**: Hard refresh or try incognito mode
- **Check CNAME**: Ensure the CNAME points to `cname.go2.gg`

### Links Not Redirecting

- **Verify domain**: Ensure the domain shows "Verified" in your dashboard
- **Check CNAME**: The redirect depends on the CNAME record
- **SSL**: Make sure you're using HTTPS

## Removing a Domain

1. Go to **Dashboard → Domains**
2. Click the domain you want to remove
3. Click **"Delete Domain"**
4. Confirm the deletion

**Warning**: This will break all links using that domain.

## Best Practices

1. **Use a subdomain**: `link.example.com` is better than `example.com`
2. **Keep it short**: Shorter domains = shorter links
3. **Be memorable**: Choose something easy to type
4. **Set up 404**: Provide a helpful fallback page
5. **Monitor verification**: Renew verification if DNS changes

## Next Steps

- [Short Links](/docs/features/links) - Create branded short links
- [Analytics](/docs/features/analytics) - Track domain performance
- [API Reference](/docs/api/domains) - Manage domains via API


================================================================================
# Quick Start

URL: https://go2.gg/docs/quickstart
Description: Create your first short link in minutes.


This guide will help you get started with Go2, whether you're using the web dashboard or the API.

## Option 1: Web Dashboard (No Code)

The fastest way to get started is through our web dashboard.

### Step 1: Create an Account

1. Go to [go2.gg/register](/register)
2. Sign up with your email or OAuth provider
3. Verify your email address

### Step 2: Create Your First Link

1. From the dashboard, click **"Create New Link"**
2. Paste your destination URL
3. (Optional) Customize the slug, add expiration, or set a password
4. Click **"Create"**

Your short link is ready! Share it anywhere.

### Step 3: Track Performance

Click on any link in your dashboard to see:

- Total clicks and unique visitors
- Geographic distribution
- Device and browser breakdown
- Referrer sources
- Click history over time

## Option 2: API Integration

For developers who want programmatic access, Go2 provides a full REST API.

### Step 1: Get Your API Key

1. Go to **Dashboard → Settings → API Keys**
2. Click **"Create New API Key"**
3. Copy your key (it won't be shown again)

### Step 2: Create a Link via API

```bash
curl -X POST https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/my-long-url",
    "slug": "my-link"
  }'
```

Response:

```json
{
  "success": true,
  "data": {
    "id": "abc123",
    "shortUrl": "https://go2.gg/my-link",
    "destinationUrl": "https://example.com/my-long-url",
    "slug": "my-link",
    "clickCount": 0,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

### Step 3: Retrieve Link Analytics

```bash
curl https://api.go2.gg/api/v1/links/abc123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Option 3: Public Link Creation (No Auth)

For quick links without signing up, you can use our public endpoint:

```bash
curl -X POST https://api.go2.gg/api/v1/public/links \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://example.com/my-long-url"
  }'
```

Note: Public links have limited features and are rate-limited.

## Next Steps

Now that you've created your first link, explore more features:

- [Add a Custom Domain](/docs/features/domains) - Brand your links
- [Enable Analytics](/docs/features/analytics) - Track your link performance
- [Create QR Codes](/docs/features/qr-codes) - Generate scannable codes
- [API Reference](/docs/api/reference) - Full API documentation

## Troubleshooting

### Link Not Redirecting

- Verify the destination URL is valid and accessible
- Check if the link has expired or reached its click limit
- Ensure the slug doesn't conflict with reserved words

### API Errors

- Verify your API key is valid and not expired
- Check you're using the correct HTTP method
- Review the error response for specific details

### Need More Help?

- Check the [FAQ](/docs/faq)
- [Contact support](/contact)


================================================================================
# Analytics

URL: https://go2.gg/docs/features/analytics
Section: Features
Description: Track clicks, locations, devices, and more.


Go2 provides real-time analytics for every short link. Track how your links perform with detailed insights into clicks, geography, devices, and referrers.

## Overview Dashboard

Your analytics dashboard shows:

- **Total clicks** across all links
- **Click trend** over time
- **Top performing links**
- **Geographic distribution**
- **Device breakdown**

Access it from **Dashboard → Analytics**.

## Link-Level Analytics

Click on any link to see detailed statistics:

### Click Count

- **Total clicks**: All-time click count
- **Unique visitors**: Deduplicated by IP (anonymized)
- **Today's clicks**: Real-time count
- **Trend**: Comparison to previous period

### Geographic Data

See where your clicks come from:

- **By country**: Top countries by click volume
- **By city**: City-level breakdown (Pro+ plans)
- **Map visualization**: Interactive world map

### Device Analytics

Understand your audience's devices:

- **Device type**: Mobile, desktop, tablet
- **Operating system**: iOS, Android, Windows, macOS, Linux
- **Browser**: Chrome, Safari, Firefox, Edge, etc.

### Referrer Sources

See where traffic originates:

- **Social media**: Twitter, Facebook, LinkedIn, etc.
- **Search engines**: Google, Bing, DuckDuckGo
- **Direct**: No referrer (direct link)
- **Other websites**: Any referring domain

### Timeline

View clicks over time:

- **Hourly**: Last 24 hours
- **Daily**: Last 30 days
- **Weekly**: Last 12 weeks
- **Monthly**: Last 12 months

## Real-Time Analytics

Go2 uses Cloudflare Analytics Engine to provide near-real-time data. Clicks appear in your dashboard within seconds.

## Privacy-First Design

We prioritize user privacy:

- **No cookies**: We don't use tracking cookies
- **IP anonymization**: IPs are hashed for geolocation, never stored
- **No cross-site tracking**: We only track clicks on your links
- **GDPR compliant**: By design, not by checkbox

## API Access

Retrieve analytics programmatically:

```bash
curl https://api.go2.gg/api/v1/links/lnk_abc123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes all metrics:

```json
{
  "success": true,
  "data": {
    "totalClicks": 1542,
    "lastClickedAt": "2024-06-15T14:22:00Z",
    "byCountry": [...],
    "byDevice": [...],
    "byBrowser": [...],
    "byReferrer": [...],
    "overTime": [...]
  }
}
```

## Exporting Data

Export your analytics data:

### CSV Export

1. Go to **Dashboard → Analytics**
2. Select the date range
3. Click **"Export"** → **"CSV"**

### API Bulk Export

```bash
curl "https://api.go2.gg/api/v1/analytics/export?from=2024-01-01&to=2024-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o analytics.csv
```

## Filtering & Segments

Filter your analytics by:

- **Date range**: Custom time periods
- **Domain**: Specific custom domain
- **Tag**: Links with specific tags
- **Country**: Geographic filter

## Comparing Links

Compare performance of multiple links:

1. Select links in the dashboard
2. Click **"Compare"**
3. View side-by-side metrics

## Webhooks for Real-Time Events

Get notified of clicks in real-time:

```json
{
  "event": "link.clicked",
  "data": {
    "linkId": "lnk_abc123",
    "timestamp": "2024-06-15T14:22:00Z",
    "country": "US",
    "device": "mobile",
    "browser": "Safari"
  }
}
```

Set up webhooks in **Dashboard → Settings → Webhooks**.

## Analytics by Plan

| Feature | Free | Pro | Business |
|---------|------|-----|----------|
| Basic analytics | ✓ | ✓ | ✓ |
| Geographic data | ✓ | ✓ | ✓ |
| Device breakdown | ✓ | ✓ | ✓ |
| Referrer tracking | ✓ | ✓ | ✓ |
| City-level data | - | ✓ | ✓ |
| Data retention | 30 days | 1 year | 2 years |
| Export | CSV | CSV, JSON | CSV, JSON, API |
| Real-time webhooks | - | ✓ | ✓ |

## Integrations

Connect Go2 analytics to other tools:

- **Google Analytics**: UTM parameter auto-append
- **Zapier**: Trigger workflows on clicks
- **Slack**: Get click notifications
- **Custom webhooks**: Send data anywhere

## Best Practices

1. **Use UTM parameters**: Track campaigns in your analytics platform
2. **Tag your links**: Group links for easier analysis
3. **Set up webhooks**: React to clicks in real-time
4. **Export regularly**: Keep local backups of your data
5. **Monitor trends**: Watch for unusual patterns

## Next Steps

- [Short Links](/docs/features/links) - Create trackable links
- [Custom Domains](/docs/features/domains) - Brand your links
- [API Reference](/docs/api/overview) - Access data programmatically


================================================================================
# Project Structure

URL: https://go2.gg/docs/structure
Description: Understanding the monorepo structure and package organization.


Go2 uses a monorepo structure with pnpm workspaces and Turborepo for build orchestration.

## Directory Overview

```
├── apps/
│   ├── api/              # Hono API (Cloudflare Workers)
│   └── web/              # Next.js Frontend
├── content/
│   ├── blog/             # MDX blog posts
│   └── docs/             # MDX documentation
├── packages/
│   ├── analytics/        # PostHog integration
│   ├── auth/             # Authentication & RBAC
│   ├── config/           # Configuration & feature flags
│   ├── db/               # Database & Drizzle ORM
│   ├── email/            # React Email templates
│   ├── logger/           # Logging & Sentry
│   ├── payments/         # Stripe integration
│   └── ui/               # Shared UI components
├── infra/
│   ├── cloudflare/       # Wrangler configs
│   └── stripe/           # Stripe products
└── scripts/              # Setup & utility scripts
```

## Apps

### apps/web

The Next.js frontend application using the App Router.

### apps/api

The Hono API running on Cloudflare Workers with routes for links, domains, and analytics.

## Packages

Each package is self-contained with its own package.json, tsconfig.json, and src/index.ts.

| Package | Purpose |
|---------|---------|
| @repo/config | Environment, site config, pricing, feature flags |
| @repo/auth | Authentication utilities |
| @repo/db | Database schemas (links, domains, clicks) |
| @repo/payments | Stripe subscription integration |
| @repo/email | Email templates |
| @repo/ui | Shared UI components |

## Configuration Files

| File | Purpose |
|------|---------|
| pnpm-workspace.yaml | Workspace definition |
| turbo.json | Build pipeline |
| tsconfig.base.json | Shared TypeScript config |
| biome.json | Linting and formatting |
| env.example | Environment variables template |


================================================================================
# Webhooks API

URL: https://go2.gg/docs/api/webhooks
Section: API
Description: Receive real-time notifications when events occur in your Go2 account.


Webhooks allow you to receive real-time HTTP POST notifications when events occur in your Go2 account, such as link clicks, creations, and updates.

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/webhooks` | List all webhooks |
| `POST` | `/webhooks` | Create a new webhook |
| `GET` | `/webhooks/:id` | Get webhook details |
| `PATCH` | `/webhooks/:id` | Update a webhook |
| `DELETE` | `/webhooks/:id` | Delete a webhook |
| `POST` | `/webhooks/:id/test` | Send a test event |
| `GET` | `/webhooks/:id/deliveries` | Get delivery history |
| `POST` | `/webhooks/:id/rotate-secret` | Rotate signing secret |

## Create Webhook

```bash
curl -X POST https://api.go2.gg/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Click Tracker",
    "url": "https://your-server.com/webhooks/go2",
    "events": ["click", "link.created"]
  }'
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | A friendly name for the webhook |
| `url` | string | Yes | The HTTPS URL to receive events |
| `events` | string[] | Yes | Array of events to subscribe to |

### Response

```json
{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "name": "Click Tracker",
    "url": "https://your-server.com/webhooks/go2",
    "events": ["click", "link.created"],
    "secret": "whsec_xxxx...",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

> **Warning:** The signing secret is only shown once when the webhook is created. Store it securely!

## Event Types

| Event | Description |
|-------|-------------|
| `click` | A short link was clicked |
| `link.created` | A new link was created |
| `link.updated` | A link was updated |
| `link.deleted` | A link was deleted |
| `domain.verified` | A custom domain was verified |
| `qr.scanned` | A QR code was scanned |
| `*` | Subscribe to all events |

## Webhook Payload

All webhook payloads follow this structure:

```json
{
  "event": "click",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    // Event-specific data
  }
}
```

### Click Event

```json
{
  "event": "click",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "linkId": "lnk_abc123",
    "slug": "my-link",
    "domain": "go2.gg",
    "destinationUrl": "https://example.com",
    "country": "US",
    "city": "San Francisco",
    "device": "mobile",
    "browser": "Chrome",
    "os": "iOS",
    "referrer": "https://twitter.com"
  }
}
```

### Link Created Event

```json
{
  "event": "link.created",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "id": "lnk_abc123",
    "slug": "my-link",
    "domain": "go2.gg",
    "destinationUrl": "https://example.com",
    "shortUrl": "https://go2.gg/my-link",
    "createdBy": "user_xyz"
  }
}
```

## Signature Verification

Every webhook request includes headers for verification:

```
X-Webhook-ID: wh_abc123
X-Webhook-Event: click
X-Webhook-Signature: sha256=...
X-Webhook-Timestamp: 2024-01-01T12:00:00Z
```

### Verifying Signatures

Always verify webhook signatures to ensure requests are from Go2:

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/go2', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const { event, data } = req.body;
  
  switch (event) {
    case 'click':
      console.log('Link clicked:', data.linkId);
      break;
    case 'link.created':
      console.log('Link created:', data.shortUrl);
      break;
  }
  
  res.status(200).send('OK');
});
```

## Retry Policy

If your endpoint doesn't respond with a 2xx status code, we'll retry the delivery:

- **1st retry**: 5 seconds after initial failure
- **2nd retry**: 30 seconds after 1st retry
- **3rd retry**: 2 minutes after 2nd retry
- **4th retry**: 10 minutes after 3rd retry
- **5th retry**: 1 hour after 4th retry

After 10 consecutive failures, the webhook is automatically disabled. You can re-enable it from the dashboard.

## Best Practices

1. **Respond quickly**: Return a 200 status within 10 seconds. Process events asynchronously.
2. **Handle duplicates**: Use the `X-Webhook-ID` header to deduplicate events.
3. **Verify signatures**: Always verify the `X-Webhook-Signature` header.
4. **Use HTTPS**: Webhook URLs must use HTTPS for security.
5. **Test first**: Use the test endpoint to verify your integration before going live.

## Delivery History

View recent deliveries for debugging:

```bash
curl https://api.go2.gg/api/v1/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response includes status codes, response times, and any error messages.


================================================================================
# Galleries API (Link-in-Bio)

URL: https://go2.gg/docs/api/galleries
Section: API
Description: Create and manage Link-in-Bio pages with the Galleries API.


The Galleries API lets you create and manage Link-in-Bio pages programmatically.

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/galleries` | List all galleries |
| `POST` | `/galleries` | Create a new gallery |
| `GET` | `/galleries/:id` | Get gallery with items |
| `PATCH` | `/galleries/:id` | Update gallery |
| `DELETE` | `/galleries/:id` | Delete gallery |
| `POST` | `/galleries/:id/publish` | Publish/unpublish |
| `POST` | `/galleries/:id/items` | Add item |
| `PATCH` | `/galleries/:id/items/:itemId` | Update item |
| `DELETE` | `/galleries/:id/items/:itemId` | Delete item |
| `PATCH` | `/galleries/:id/items/reorder` | Reorder items |

## Create Gallery

```bash
curl -X POST https://api.go2.gg/api/v1/galleries \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "myprofile",
    "title": "John Doe",
    "bio": "Creator, developer, coffee enthusiast",
    "theme": "gradient"
  }'
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | URL slug (e.g., "myprofile" for go2.gg/bio/myprofile) |
| `domain` | string | No | Custom domain (default: go2.gg) |
| `title` | string | No | Display name |
| `bio` | string | No | Short biography (max 500 chars) |
| `avatarUrl` | string | No | Profile picture URL |
| `theme` | string | No | Theme name: default, minimal, gradient, dark, neon |
| `socialLinks` | array | No | Array of social profile links |

### Response

```json
{
  "success": true,
  "data": {
    "id": "gal_abc123",
    "slug": "myprofile",
    "domain": "go2.gg",
    "title": "John Doe",
    "bio": "Creator, developer, coffee enthusiast",
    "theme": "gradient",
    "isPublished": false,
    "url": "https://go2.gg/bio/myprofile",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

## Add Gallery Items

Add links, headers, dividers, and embeds to your gallery:

```bash
curl -X POST https://api.go2.gg/api/v1/galleries/gal_abc123/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "link",
    "title": "My Website",
    "url": "https://example.com"
  }'
```

### Item Types

| Type | Description | Required Fields |
|------|-------------|-----------------|
| `link` | Clickable link | `title`, `url` |
| `header` | Section header | `title` |
| `divider` | Visual separator | None |
| `embed` | Video/audio embed | `embedType`, `embedData` |
| `image` | Image block | `thumbnailUrl` |

### Link Item

```json
{
  "type": "link",
  "title": "My Website",
  "url": "https://example.com",
  "iconName": "Globe",
  "thumbnailUrl": "https://example.com/icon.png"
}
```

### Header Item

```json
{
  "type": "header",
  "title": "Social Links"
}
```

### Embed Item (YouTube)

```json
{
  "type": "embed",
  "title": "Latest Video",
  "embedType": "youtube",
  "embedData": {
    "videoId": "dQw4w9WgXcQ"
  }
}
```

## Themes

Available themes for your gallery:

| Theme | Description |
|-------|-------------|
| `default` | Clean white background with subtle shadows |
| `minimal` | Simple, text-focused design |
| `gradient` | Vibrant gradient background |
| `dark` | Dark mode with light text |
| `neon` | Black background with neon accents |
| `custom` | Use custom CSS |

## Custom Styling

For the `custom` theme, you can provide custom CSS:

```bash
curl -X PATCH https://api.go2.gg/api/v1/galleries/gal_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "custom",
    "customCss": ".bio-page { background: linear-gradient(45deg, #ff6b6b, #4ecdc4); }"
  }'
```

## Publish/Unpublish

Galleries are unpublished by default. Publish when ready:

```bash
curl -X POST https://api.go2.gg/api/v1/galleries/gal_abc123/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isPublished": true}'
```

## Reorder Items

Change the order of items:

```bash
curl -X PATCH https://api.go2.gg/api/v1/galleries/gal_abc123/items/reorder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["item_3", "item_1", "item_2"]
  }'
```

## Public Access

Published galleries are accessible without authentication:

```bash
curl https://api.go2.gg/api/v1/public/galleries/go2.gg/myprofile
```

This returns the gallery data for rendering, excluding private fields.


================================================================================
# QR Codes API

URL: https://go2.gg/docs/api/qr-codes
Section: API
Description: Generate and manage customizable QR codes.


Create, customize, and track QR codes for any URL.

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/qr/generate` | Generate QR code (no auth) |
| `GET` | `/qr` | List saved QR codes |
| `POST` | `/qr` | Save a QR code config |
| `GET` | `/qr/:id` | Get QR code details |
| `PATCH` | `/qr/:id` | Update QR code |
| `DELETE` | `/qr/:id` | Delete QR code |
| `GET` | `/qr/:id/download` | Download QR code image |

## Generate QR Code

Generate a QR code without authentication (public endpoint):

```bash
curl -X POST https://api.go2.gg/api/v1/qr/generate \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://go2.gg/my-link",
    "size": 256,
    "foregroundColor": "#000000",
    "backgroundColor": "#FFFFFF",
    "cornerRadius": 10,
    "errorCorrection": "M",
    "format": "svg"
  }'
```

### Request Body

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `url` | string | Required | URL to encode |
| `size` | number | 256 | Size in pixels (64-2048) |
| `foregroundColor` | string | #000000 | Hex color for modules |
| `backgroundColor` | string | #FFFFFF | Hex color for background |
| `cornerRadius` | number | 0 | Module corner radius (0-50) |
| `errorCorrection` | string | M | L, M, Q, or H |
| `format` | string | svg | svg or png |

### Error Correction Levels

| Level | Recoverable | Use Case |
|-------|-------------|----------|
| L | 7% | Small, simple QR codes |
| M | 15% | General use (default) |
| Q | 25% | Moderate damage tolerance |
| H | 30% | QR codes with logos |

### Response

For SVG format, the response is the raw SVG content with `Content-Type: image/svg+xml`.

For other formats:

```json
{
  "success": true,
  "data": {
    "svg": "<svg ...>",
    "format": "svg",
    "size": 256,
    "url": "https://go2.gg/my-link"
  }
}
```

## Save QR Code

Save a QR code configuration for tracking and easy access:

```bash
curl -X POST https://api.go2.gg/api/v1/qr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Card QR",
    "url": "https://go2.gg/contact",
    "size": 512,
    "foregroundColor": "#1a365d",
    "backgroundColor": "#FFFFFF"
  }'
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "qr_abc123",
    "name": "Business Card QR",
    "url": "https://go2.gg/contact",
    "size": 512,
    "foregroundColor": "#1a365d",
    "backgroundColor": "#FFFFFF",
    "scanCount": 0,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

## Download QR Code

Download a saved QR code as an image:

```bash
curl https://api.go2.gg/api/v1/qr/qr_abc123/download?format=svg \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o qr-code.svg
```

## Linking to Short Links

For scan tracking, link your QR code to a Go2 short link:

```bash
curl -X POST https://api.go2.gg/api/v1/qr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product QR",
    "url": "https://go2.gg/product",
    "linkId": "lnk_abc123"
  }'
```

When linked, QR scans are tracked in your link analytics.

## Dynamic vs Static QR Codes

| Type | Behavior |
|------|----------|
| **Static** | URL is encoded directly. Cannot be changed. |
| **Dynamic** | Points to a Go2 short link. Destination can be updated anytime. |

Use dynamic QR codes (with `linkId`) when you might need to change the destination after printing.

## Best Practices

1. **Use high error correction** (Q or H) if adding a logo
2. **Test scannability** before printing at final size
3. **Maintain contrast** between foreground and background
4. **Use dynamic QR codes** for printed materials
5. **Track scans** by linking to Go2 short links


================================================================================
# Authentication

URL: https://go2.gg/docs/api/authentication
Description: Learn how to authenticate with the Go2 API using API keys.


The Go2 API uses API keys to authenticate requests. You can view and manage your API keys in the [dashboard](/dashboard/api-keys).

## API Keys

Your API key carries many privileges, so be sure to keep it secure. Don't share your API key in publicly accessible areas such as GitHub, client-side code, or public repositories.

### Creating an API Key

1. Go to [Dashboard > API Keys](/dashboard/api-keys)
2. Click "Create API Key"
3. Give your key a descriptive name
4. Copy the key immediately - you won't be able to see it again

### Using Your API Key

Include your API key in the `Authorization` header of all requests:

```bash
curl https://api.go2.gg/api/v1/links \
  -H "Authorization: Bearer go2_your_api_key_here"
```

### API Key Format

Go2 API keys follow this format:

```
go2_[random_characters]
```

The `go2_` prefix makes it easy to identify Go2 API keys in your code.

## Rate Limiting

API requests are rate limited based on your plan:

| Plan | Requests per minute |
|------|---------------------|
| Free | 60 |
| Pro | 300 |
| Business | 1000 |
| Enterprise | Custom |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704067200
```

## Error Responses

Authentication errors return a `401 Unauthorized` status:

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}
```

## Best Practices

1. **Use environment variables** - Never hardcode API keys in your code
2. **Rotate keys regularly** - Create new keys periodically and revoke old ones
3. **Use separate keys** - Use different keys for development and production
4. **Monitor usage** - Check your API key usage in the dashboard


================================================================================
# Plans & Limits

URL: https://go2.gg/docs/guides/plans-and-limits
Description: Pricing tiers, monthly quotas, and how Go2 enforces them across the API, MCP server, and dashboard.


Go2's plan ladder is built around the idea that **developer primitives should be free**. Every plan — including Free — ships with the full REST API, the MCP server, per-run agent attribution, and webhooks-grade analytics. The paid tiers buy you volume, team features, and org-grade security; they don't unlock the API.

If you're integrating, this page is the source of truth for what each plan can do and what limits you'll hit.

## At a glance

| | **Free** | **Pro** | **Business** | **Scale** |
| - | - | - | - | - |
| Price | $0 | $9 / mo | $49 / mo | usage-based |
| Tracked links per month | 100 | 2,000 | 20,000 | metered |
| Attributed clicks per month | 5,000 | 100,000 | 500,000 | metered |
| Custom domains | 1 | 5 | 25 | unlimited |
| Team seats | 1 | 3 | 10 | unlimited |
| Analytics retention | 30 days | 1 year | 2 years | 5 years |
| Free-tier link auto-expiry | 60 days | never | never | never |
| **REST API + OpenAPI spec** | ✓ | ✓ | ✓ | ✓ |
| **MCP server (stdio + remote)** | ✓ | ✓ | ✓ | ✓ |
| **Per-run agent attribution** | ✓ | ✓ | ✓ | ✓ |
| API rate limit | 100 req/min | 1,000 req/min | 3,000 req/min | 10,000 req/min |
| Webhooks · pixels · geo & device targeting | — | ✓ | ✓ | ✓ |
| Link expiration · password protection · cloaking | — | ✓ | ✓ | ✓ |
| Folders | — | 5 | 25 | unlimited |
| Tags | 5 | 25 | unlimited | unlimited |
| Bio pages | — | 1 | 10 | 100 |
| A/B testing + conversion tracking | — | — | ✓ | ✓ |
| SAML SSO + audit logs + RBAC | — | — | ✓ | ✓ |
| Support | community | priority email | dedicated + 99.9% SLA | priority engineering |

## What's free, forever

These features stay on Free regardless of plan:

- **REST API** — full CRUD over links, clicks, QR codes, organizations. OpenAPI spec at `/api/openapi.json`.
- **MCP server** — `stdio` for Claude Desktop / Cursor / local agents, plus the remote Streamable-HTTP transport at `mcp.go2.gg/mcp` for hosted clients (Claude.ai, ChatGPT custom GPTs, Perplexity).
- **Agent attribution** — every link can carry `agent_id`, `agent_run_id`, and `agent_actor_id`. Carried through to every click, queryable per run.
- **Edge redirects** — sub-10ms redirect latency on all plans.
- **QR codes** — branded with your logo, colors, and corner styles, with scan tracking.

If you're an indie developer or running a hackathon project, you can ship a real agent on Free without ever upgrading.

## When you'll need to upgrade

The first ceiling most teams hit is one of:

1. **You blow past 100 new links per month** — common once an agent loop starts auto-creating links. Pro at $9 takes you to 2,000.
2. **You want webhooks** — for "ping me when a click hits this link." Pro and above.
3. **You need a second seat** — Pro covers 3 collaborators; Business covers 10 with role-based access.
4. **You need SSO or audit logs** — Business only. Required by most enterprise procurement.

## How limits are enforced

**Tracked links per month** — counted at link-creation time. The `/api/v1/links` endpoint returns a `403` with `code: "LINK_LIMIT_EXCEEDED"` once you cross your plan's `linksPerMonth` for the current calendar month. Resets on the 1st.

**Attributed clicks per month** — counted on the click side. The redirect itself never blocks; we always serve the destination. Past your plan limit, individual click events stop being recorded in the `clicks` table (the link's `clickCount` rollup still increments). The dashboard meter shows the breach so you know to upgrade.

**Free-tier link retention** — every link created on Free gets `policy_expires_at = createdAt + 60 days` stamped automatically. After that the redirect returns `410 Gone` with reason `free-tier retention (60 days)`. Upgrading clears the stamp on every link the org owns. See [`apps/api/src/lib/retention.ts`](https://github.com/Rakesh1002/go2gg/blob/main/apps/api/src/lib/retention.ts).

**API rate limits** — enforced at the edge by a Cloudflare Durable Object. Exceeding returns `429` with `Retry-After`. The window is per-minute, per API key. Bursting is fine; sustained traffic above the plan limit throttles.

**Custom domain quotas** — checked on `POST /api/v1/domains`. Once you hit your limit, you'll get `403` with `code: "DOMAIN_LIMIT_REACHED"` and a link to upgrade.

## Programmatic plan checks

The same limits power the dashboard, the API, and the MCP server. If you're writing your own agent and want to know your current usage:

```bash
curl https://api.go2.gg/api/v1/usage \
  -H "Authorization: Bearer $GO2_API_KEY"
```

Returns:

```json
{
  "data": {
    "plan": "free",
    "status": "active",
    "linksThisMonth":         { "current": 18, "limit": 100,  "percentage": 18 },
    "trackedClicksThisMonth": { "current": 412, "limit": 5000, "percentage": 8.24 },
    "domains":                { "current": 0,  "limit": 1,   "percentage": 0 },
    "teamMembers":            { "current": 1,  "limit": 1,   "percentage": 100 }
  }
}
```

The `planLimits` object that drives all of this lives in [`packages/config/src/pricing.ts`](https://github.com/Rakesh1002/go2gg/blob/main/packages/config/src/pricing.ts) — single source of truth for both the API quota gates and the marketing pricing page.

## Scale tier

Above 500K attributed clicks per month, you graduate to Scale, which is usage-based at **$0.40 per 1,000 agent-attributed events** with volume discounts beyond 10M events. Scale also unlocks:

- 5-year analytics retention
- Custom event meter (extend the `clicks` schema with your own dimensions)
- Priority engineering support
- AGPL self-host or commercial license ($5K/yr for closed-source use)

If you expect to ship more than a million events a month, [contact sales](/contact?plan=scale) — we'll size the contract to your actual traffic.

## Self-hosting

Go2 is licensed AGPL-3.0. You can self-host the entire stack on your own Cloudflare account — one `wrangler deploy` for the API, one for the web app, no usage fees. The catch is the AGPL: any modifications you ship publicly need to be open-sourced. If that's a problem, the Scale-tier commercial license ($5K/yr) buys you closed-source rights.

See [`SELF_HOSTING.md`](https://github.com/Rakesh1002/go2gg/blob/main/SELF_HOSTING.md) for the full setup walk-through.

## Frequently asked questions

**Do I need a paid plan to use the API?** No. Free includes the full REST API and MCP server. The only difference paid plans make is the per-minute rate ceiling (100 / 1,000 / 3,000 / 10,000 req/min from Free → Scale).

**What happens when I hit a monthly limit?** Link creation returns `403`; existing links keep redirecting normally. Clicks past the cap stop being recorded individually but the rollup count still increments — your existing dashboards don't break.

**Do limits prorate when I upgrade mid-month?** Yes. Upgrading lifts you to the new ceiling immediately, against the same calendar-month counter you've already accumulated.

**Can I downgrade?** Yes, at any time. Existing links above the lower-tier link cap stay live; you just can't create new ones until next month or until you delete some.

**Do you charge for retired/archived links?** No. Only active (non-archived, non-expired) links count toward `linksPerMonth`.

**Where does free-tier auto-expiry kick in?** 60 days after a link's `createdAt`. The redirect handler then returns `410 Gone`. Upgrade to clear the stamp on every existing link the org owns.


================================================================================
# UTM Parameter Tracking

URL: https://go2.gg/docs/guides/utm-tracking
Description: Learn how to use UTM parameters to track campaign performance.


UTM (Urchin Tracking Module) parameters help you track the effectiveness of your marketing campaigns. Go2 makes it easy to add and manage UTM parameters on your short links.

## What are UTM Parameters?

UTM parameters are tags added to URLs that help you track:

- **Source** (`utm_source`): Where the traffic comes from (e.g., twitter, newsletter)
- **Medium** (`utm_medium`): The marketing medium (e.g., social, email, cpc)
- **Campaign** (`utm_campaign`): The specific campaign name
- **Term** (`utm_term`): Paid search keywords
- **Content** (`utm_content`): Differentiate similar content or links

## Adding UTM Parameters

### Via Dashboard

When creating or editing a link, expand the "UTM Parameters" section:

1. Enter your UTM values in the provided fields
2. The parameters will be automatically appended to your destination URL

### Via API

```typescript
const link = await go2.links.create({
  destinationUrl: 'https://example.com/landing-page',
  utmSource: 'twitter',
  utmMedium: 'social',
  utmCampaign: 'summer-2024',
  utmContent: 'hero-cta',
});
```

The resulting destination URL will be:
```
https://example.com/landing-page?utm_source=twitter&utm_medium=social&utm_campaign=summer-2024&utm_content=hero-cta
```

## Best Practices

### Be Consistent

Use consistent naming conventions across your organization:

| Do | Don't |
|----|-------|
| `twitter` | `Twitter`, `tw`, `tweet` |
| `email` | `Email`, `newsletter`, `mail` |
| `cpc` | `paid`, `ppc`, `ads` |

### Use Lowercase

Always use lowercase for UTM parameters to avoid duplicate entries in analytics:

```
✅ utm_source=facebook
❌ utm_source=Facebook
```

### Be Descriptive but Concise

Campaign names should be identifiable but not overly long:

```
✅ utm_campaign=summer-sale-2024
❌ utm_campaign=summer-sale-promotional-campaign-for-new-products-2024
```

## Tracking in Analytics

### Google Analytics

UTM-tagged links automatically appear in Google Analytics under:

1. **Acquisition → All Traffic → Source/Medium**
2. **Acquisition → Campaigns → All Campaigns**

### Go2 Analytics

Go2 captures UTM parameters in click events, allowing you to:

- Filter link analytics by campaign
- Compare performance across sources
- Track which content drives the most clicks

## Common UTM Combinations

### Social Media

```
utm_source=twitter
utm_medium=social
utm_campaign=product-launch
```

### Email Marketing

```
utm_source=newsletter
utm_medium=email
utm_campaign=weekly-digest
utm_content=top-story
```

### Paid Advertising

```
utm_source=google
utm_medium=cpc
utm_campaign=brand-awareness
utm_term=url+shortener
```

### Influencer Campaigns

```
utm_source=creator-name
utm_medium=influencer
utm_campaign=holiday-2024
```


================================================================================
# Make (Integromat) Integration

URL: https://go2.gg/docs/integrations/make
Description: Automate Go2 workflows with Make's visual automation platform.


Automate Go2 link management with Make's powerful visual automation platform.

## Overview

Make (formerly Integromat) is a visual automation platform that lets you connect Go2 to hundreds of apps and create complex multi-step workflows.

**Key Features**:
- Visual workflow builder (no coding required)
- Advanced data transformation
- Error handling and retries
- Scheduled scenarios
- Webhook support

## Getting Started

### 1. Create a Make Account

[Sign up for Make](https://www.make.com/en/register) (free plan available with 1,000 operations/month).

### 2. Get Your Go2 API Key

1. Log in to your Go2 dashboard
2. Go to **Settings → API Keys**
3. Create a new API key
4. Copy the key for Make

### 3. Add Go2 Module to Make

1. Create a new scenario in Make
2. Click **"Add a module"**
3. Search for "Go2" or "HTTP" module
4. Configure the connection

## Using HTTP Module

Since Make doesn't have a native Go2 module yet, use the HTTP module:

### Configuration

**Base URL**: `https://api.go2.gg/api/v1`

**Headers**:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Common Scenarios

### Scenario 1: Auto-Shorten Links from Google Sheets

**Use Case**: Automatically create short links when URLs are added to a spreadsheet.

**Setup**:
1. **Trigger**: Google Sheets → "Watch Rows"
2. **Action**: HTTP → "Make a Request"
   - Method: `POST`
   - URL: `https://api.go2.gg/api/v1/links`
   - Headers: `Authorization: Bearer YOUR_API_KEY`
   - Body:
     ```json
     {
       "destinationUrl": "{{1.URL}}",
       "slug": "{{1.Slug}}",
       "title": "{{1.Title}}"
     }
     ```
3. **Action**: Google Sheets → "Update a Row"
   - Update row with short URL from response

### Scenario 2: Monitor Link Clicks and Alert Slack

**Use Case**: Get notified in Slack when links exceed a click threshold.

**Setup**:
1. **Trigger**: Schedule → "Schedule"
   - Run every hour
2. **Action**: HTTP → "Make a Request"
   - Method: `GET`
   - URL: `https://api.go2.gg/api/v1/links`
   - Query: `?perPage=100`
3. **Filter**: Filter array
   - Condition: `clickCount > 1000`
4. **Action**: HTTP → "Make a Request" (for each filtered link)
   - Method: `GET`
   - URL: `https://api.go2.gg/api/v1/links/{{id}}/stats`
5. **Action**: Slack → "Create a Message"
   - Format message with link stats

### Scenario 3: Sync Links to Airtable

**Use Case**: Keep a database of all your links in Airtable.

**Setup**:
1. **Trigger**: Webhook → "Custom webhook"
   - Set up webhook in Go2 dashboard
2. **Action**: Airtable → "Create a Record"
   - Map webhook data to Airtable fields:
     - `Short URL`: `{{webhook.link.shortUrl}}`
     - `Destination`: `{{webhook.link.destinationUrl}}`
     - `Clicks`: `{{webhook.link.clickCount}}`
     - `Created`: `{{webhook.link.createdAt}}`

### Scenario 4: Bulk Link Creation from CSV

**Use Case**: Import hundreds of links from a CSV file.

**Setup**:
1. **Trigger**: Google Drive → "Watch Files"
   - Filter: File name contains "links.csv"
2. **Action**: Google Drive → "Download a File"
3. **Action**: CSV → "Parse CSV"
4. **Iterator**: Process each row
5. **Action**: HTTP → "Make a Request"
   - Method: `POST`
   - URL: `https://api.go2.gg/api/v1/links`
   - Body: Map CSV columns to API fields
6. **Action**: Google Sheets → "Add a Row"
   - Log results

## Advanced Workflows

### Multi-Step with Error Handling

```
1. Trigger: New email
2. Extract URLs (Text parser)
3. Router: Split into multiple paths
   ├─ Path 1: Create link (HTTP)
   ├─ Path 2: Check if exists (HTTP GET)
   └─ Path 3: Error handling
4. Aggregator: Combine results
5. Action: Send summary email
```

### Data Transformation

Use Make's data transformation tools:

- **Text parser**: Extract URLs from email/text
- **Set variables**: Store reusable values
- **Aggregator**: Combine multiple API responses
- **Router**: Conditional logic based on data

## Webhook Integration

### Setting Up Go2 Webhooks in Make

1. **Create Webhook Module**:
   - Add "Webhooks" → "Custom webhook"
   - Copy the webhook URL

2. **Configure in Go2**:
   - Go to Dashboard → Webhooks
   - Create new webhook
   - Paste Make webhook URL
   - Select events: `click`, `link.created`

3. **Process in Make**:
   - Webhook receives JSON payload
   - Parse data with JSON parser
   - Route to different actions based on event type

**Example Webhook Payload Processing**:

```javascript
// In Make's JSON parser
{
  "event": "{{webhook.event}}",
  "linkId": "{{webhook.link.id}}",
  "shortUrl": "{{webhook.link.shortUrl}}",
  "clickCountry": "{{webhook.click.country}}",
  "clickDevice": "{{webhook.click.device}}"
}
```

## Tips & Best Practices

1. **Use Aggregators**: Combine multiple API calls efficiently
2. **Set Variables**: Store API key and base URL as variables
3. **Error Handling**: Always add error handling routes
4. **Rate Limiting**: Add delays for bulk operations
5. **Testing**: Use Make's "Run once" feature to test scenarios
6. **Scheduling**: Use schedule module for periodic checks

## Rate Limits

Make scenarios respect Go2 API rate limits:

- **Free Plan**: 60 requests/minute
- **Pro Plan**: 300 requests/minute
- **Business Plan**: 1,000 requests/minute

Add delays between operations if needed.

## Troubleshooting

### Connection Errors

- Verify API key is correct
- Check base URL: `https://api.go2.gg/api/v1`
- Ensure headers are properly formatted

### Data Mapping Issues

- Use Make's data mapper to preview data
- Check JSON structure matches API response
- Verify field names match exactly

### Rate Limiting

- Add delays between operations
- Use aggregators to batch requests
- Upgrade Go2 plan for higher limits

## Resources

- [Make Documentation](https://www.make.com/en/help)
- [Go2 API Documentation](/docs/api/overview)
- [Make Community](https://community.make.com/)

## Example Templates

### Template 1: Email Link Shortener

**Trigger**: Gmail new email  
**Action**: Extract URLs → Create Go2 links → Reply with short links

### Template 2: Social Media Link Tracker

**Trigger**: Schedule (hourly)  
**Action**: Get all links → Filter high performers → Post to Slack

### Template 3: CRM Link Sync

**Trigger**: Go2 webhook (link.created)  
**Action**: Create record in HubSpot/Salesforce

## Need Help?

- [Make Support](https://www.make.com/en/help)
- [Go2 API Docs](/docs/api/overview)
- [Make Community Forum](https://community.make.com/)


================================================================================
# MCP Server for AI Assistants

URL: https://go2.gg/docs/integrations/mcp
Description: Connect Go2 to Claude, ChatGPT, and other AI assistants using MCP.


The Go2 MCP (Model Context Protocol) server enables AI assistants like Claude to manage your short links through natural language.

## What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI assistants to connect to external tools and services. With the Go2 MCP server, you can:

- Create short links by describing what you want
- Get analytics summaries in plain language
- Manage links without leaving your AI chat

## Installation

```bash
npm install -g @go2/mcp-server
```

Or use npx without installing:

```bash
npx @go2/mcp-server --api-key go2_xxx
```

## Setup with Claude Desktop

1. Get your API key from [Dashboard → API Keys](/dashboard/api-keys)

2. Edit your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "go2": {
      "command": "npx",
      "args": ["@go2/mcp-server", "--api-key", "go2_xxx"]
    }
  }
}
```

3. Restart Claude Desktop

4. You should now see "Go2" in Claude's available tools

## Available Commands

Once connected, you can ask Claude to:

### Create Links

> "Create a short link for https://example.com/my-long-article-about-something-interesting"

Claude will create the link and return the short URL.

### Get Analytics

> "How many clicks did my 'summer-sale' link get this week?"

> "Show me my top performing links"

### Manage Links

> "Update my 'promo' link to point to the new landing page"

> "Archive all links older than 30 days"

### Bulk Operations

> "Create short links for these 5 URLs: [list of URLs]"

## Environment Variables

Instead of passing the API key as an argument, you can set environment variables:

```bash
export GO2_API_KEY=go2_xxx
export GO2_API_URL=https://api.go2.gg  # optional
```

Then run without arguments:

```bash
npx @go2/mcp-server
```

## Available Tools

The MCP server exposes these tools to AI assistants:

| Tool | Description |
|------|-------------|
| `create_link` | Create a new short link |
| `list_links` | List existing links with filtering |
| `get_link` | Get details of a specific link |
| `update_link` | Update a link's properties |
| `delete_link` | Delete a link |
| `get_analytics` | Get analytics for a link |
| `bulk_create_links` | Create multiple links at once |

## Security

- Your API key is stored locally in the Claude Desktop config
- All communication uses HTTPS
- The MCP server has read/write access based on your API key permissions

## Troubleshooting

### Claude doesn't show Go2 tools

1. Verify your config file syntax is valid JSON
2. Restart Claude Desktop completely
3. Check the Claude logs for error messages

### Authentication errors

1. Verify your API key is correct
2. Check the key hasn't expired
3. Ensure the key has the required permissions

### Rate limiting

If you're hitting rate limits, consider:
- Upgrading your plan for higher limits
- Batching operations where possible
- Adding delays between bulk operations


================================================================================
# Slack Integration

URL: https://go2.gg/docs/integrations/slack
Description: Get real-time notifications about your links in Slack.


Get instant notifications about link clicks, creations, and analytics directly in your Slack workspace.

## Overview

Connect Go2 to Slack to:
- Receive notifications when links are clicked
- Get daily/weekly analytics summaries
- Create links from Slack messages
- Track campaign performance in channels

## Method 1: Webhooks (Recommended)

The easiest way to integrate Go2 with Slack is using webhooks.

### Setup

1. **Create Slack Incoming Webhook**:
   - Go to [Slack Apps](https://api.slack.com/apps)
   - Create a new app or use existing
   - Go to "Incoming Webhooks"
   - Activate incoming webhooks
   - Add new webhook to workspace
   - Copy the webhook URL (looks like: `https://hooks.slack.com/services/XXX/YYY/ZZZ`)

2. **Configure Go2 Webhook**:
   - Go to Go2 Dashboard → Webhooks
   - Click "Create Webhook"
   - Name: "Slack Notifications"
   - URL: Paste your Slack webhook URL
   - Events: Select `click`, `link.created`, `link.updated`
   - Click "Create"

3. **Test**:
   - Create a test link in Go2
   - You should see a notification in Slack

### Webhook Payload Format

Go2 sends webhooks in this format. You can customize the Slack message format:

```json
{
  "event": "click",
  "link": {
    "id": "lnk_abc123",
    "shortUrl": "https://go2.gg/summer-sale",
    "destinationUrl": "https://example.com/product",
    "title": "Summer Sale Campaign"
  },
  "click": {
    "country": "US",
    "device": "mobile",
    "referrer": "twitter.com",
    "timestamp": "2024-06-15T14:22:00Z"
  }
}
```

### Custom Slack Message Format

Use Slack's Block Kit to format messages. Here's an example webhook handler:

```javascript
// Example: Node.js webhook handler
app.post('/slack-webhook', async (req, res) => {
  const { event, link, click } = req.body;
  
  const slackMessage = {
    blocks: [
      {
        type: "header",
        text: {
          type: "plain_text",
          text: `🔗 Link Clicked: ${link.title || link.shortUrl}`
        }
      },
      {
        type: "section",
        fields: [
          {
            type: "mrkdwn",
            text: `*Short URL:*\n${link.shortUrl}`
          },
          {
            type: "mrkdwn",
            text: `*Destination:*\n${link.destinationUrl}`
          },
          {
            type: "mrkdwn",
            text: `*Country:*\n${click.country || 'Unknown'}`
          },
          {
            type: "mrkdwn",
            text: `*Device:*\n${click.device || 'Unknown'}`
          }
        ]
      },
      {
        type: "context",
        elements: [
          {
            type: "mrkdwn",
            text: `From: ${click.referrer || 'Direct'} • ${new Date(click.timestamp).toLocaleString()}`
          }
        ]
      }
    ]
  };
  
  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(slackMessage)
  });
  
  res.sendStatus(200);
});
```

## Method 2: Slack App (Advanced)

For more advanced features, create a Slack app:

### Features

- **Slash Commands**: `/go2 create https://example.com`
- **Interactive Buttons**: Create links from message actions
- **Modals**: Rich link creation forms
- **Shortcuts**: Quick link creation from sidebar

### Setup Steps

1. **Create Slack App**:
   - Go to [Slack API](https://api.slack.com/apps)
   - Click "Create New App"
   - Choose "From scratch"
   - Name: "Go2 Link Manager"
   - Select your workspace

2. **Add Slash Command**:
   - Go to "Slash Commands"
   - Create new command: `/go2`
   - Request URL: Your server endpoint
   - Description: "Create and manage Go2 short links"

3. **Add Bot Token Scopes**:
   - `chat:write` - Send messages
   - `commands` - Handle slash commands
   - `links:write` - Create links (if needed)

4. **Install App**:
   - Go to "Install App"
   - Install to workspace
   - Copy Bot User OAuth Token

### Example Slash Command Handler

```javascript
// Handle /go2 create <url>
app.post('/slack/commands', async (req, res) => {
  const { text, user_id, response_url } = req.body;
  
  if (text.startsWith('create ')) {
    const url = text.replace('create ', '');
    
    // Create link via Go2 API
    const response = await fetch('https://api.go2.gg/api/v1/links', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${GO2_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ destinationUrl: url })
    });
    
    const { data: link } = await response.json();
    
    // Send response to Slack
    res.json({
      response_type: 'in_channel',
      text: `✅ Created: ${link.shortUrl}`,
      blocks: [
        {
          type: "section",
          text: {
            type: "mrkdwn",
            text: `*Link Created*\n<${link.shortUrl}|${link.shortUrl}> → ${link.destinationUrl}`
          }
        }
      ]
    });
  }
});
```

## Common Use Cases

### 1. Daily Analytics Summary

Send a daily summary of link performance:

```javascript
// Run daily via cron
const links = await fetchGo2Links();
const summary = {
  totalClicks: links.reduce((sum, link) => sum + link.clickCount, 0),
  topLinks: links.sort((a, b) => b.clickCount - a.clickCount).slice(0, 5)
};

await sendSlackMessage({
  text: `📊 Daily Link Summary\nTotal Clicks: ${summary.totalClicks}\nTop Links:\n${summary.topLinks.map(l => `• ${l.shortUrl}: ${l.clickCount} clicks`).join('\n')}`
});
```

### 2. High-Performance Alerts

Notify when a link exceeds a threshold:

```javascript
// In webhook handler
if (link.clickCount > 1000) {
  await sendSlackMessage({
    text: `🚀 Link Milestone!\n${link.shortUrl} just hit ${link.clickCount} clicks!`,
    channel: '#marketing'
  });
}
```

### 3. Campaign Tracking

Track campaign performance in dedicated channels:

```javascript
// Route notifications by campaign tag
if (link.tags.includes('summer-sale')) {
  await sendSlackMessage({
    text: `Summer Sale link clicked: ${link.shortUrl}`,
    channel: '#summer-campaign'
  });
}
```

## Message Formatting Tips

### Use Block Kit

Slack's Block Kit provides rich formatting:

```json
{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Link Analytics"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Total Clicks:* 1,234\n*Top Country:* US\n*Top Device:* Mobile"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {
            "type": "plain_text",
            "text": "View Dashboard"
          },
          "url": "https://go2.gg/dashboard"
        }
      ]
    }
  ]
}
```

### Use Emojis

Make messages more engaging:
- 🔗 Link created
- 👆 Link clicked
- 📊 Analytics
- 🚀 Milestone reached
- ⚠️ Alert

## Security

### Verify Webhook Signatures

Always verify webhook signatures from Go2:

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

### Store Secrets Securely

- Use environment variables for API keys
- Never commit secrets to git
- Use Slack's signing secret for app verification

## Troubleshooting

### Not Receiving Notifications

1. Check webhook URL is correct
2. Verify webhook is active in Go2 dashboard
3. Check Slack app permissions
4. Review webhook delivery logs in Go2

### Formatting Issues

1. Use Slack's Block Kit Builder: https://app.slack.com/block-kit-builder
2. Test message format before deploying
3. Check Slack API version compatibility

### Rate Limiting

- Slack has rate limits (Tier 1: 1 req/sec)
- Batch notifications if needed
- Use Slack's response_url for delayed responses

## Resources

- [Slack API Documentation](https://api.slack.com/)
- [Slack Block Kit Builder](https://app.slack.com/block-kit-builder)
- [Go2 Webhooks Documentation](/docs/api/webhooks)
- [Go2 API Documentation](/docs/api/overview)

## Example Templates

### Template 1: Simple Click Notifications

```javascript
// Minimal webhook handler
app.post('/slack', async (req, res) => {
  const { link, click } = req.body;
  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    body: JSON.stringify({
      text: `🔗 ${link.shortUrl} clicked from ${click.country}`
    })
  });
  res.sendStatus(200);
});
```

### Template 2: Rich Analytics Dashboard

Create a Slack message with interactive buttons and formatted analytics data.

### Template 3: Campaign Tracker

Track multiple campaigns with dedicated channels and formatted reports.


================================================================================
# Zapier Integration

URL: https://go2.gg/docs/integrations/zapier
Description: Connect Go2 to 6,000+ apps with Zapier automation.


Connect Go2 to thousands of apps and automate your link management workflows.

## Overview

With Zapier, you can automatically create short links, track clicks, and sync data between Go2 and your favorite tools like:

- **CRM**: Salesforce, HubSpot, Pipedrive
- **Email**: Gmail, Mailchimp, SendGrid
- **Social Media**: Twitter, LinkedIn, Facebook
- **E-commerce**: Shopify, WooCommerce, Stripe
- **Analytics**: Google Analytics, Mixpanel
- **And 6,000+ more apps**

## Getting Started

### 1. Create a Zapier Account

If you don't have one, [sign up for Zapier](https://zapier.com/sign-up) (free plan available).

### 2. Get Your Go2 API Key

1. Log in to your Go2 dashboard
2. Go to **Settings → API Keys**
3. Click **"Create New API Key"**
4. Copy the key (you'll need it for Zapier)

### 3. Connect Go2 to Zapier

1. Go to [Zapier's Go2 integration page](https://zapier.com/apps/go2/integrations)
2. Click **"Connect Go2"**
3. Enter your API key when prompted
4. Test the connection

## Common Zaps

### Create Short Links from New Emails

**Trigger**: New email in Gmail  
**Action**: Create short link in Go2

**Use Case**: Automatically shorten links in incoming emails and add them to your link library.

**Setup**:
1. Choose Gmail as trigger → "New Email"
2. Choose Go2 as action → "Create Link"
3. Map email content to `destinationUrl`
4. Optionally add tags like `["email", "incoming"]`

### Post Short Links to Social Media

**Trigger**: New link created in Go2  
**Action**: Post to Twitter/LinkedIn

**Use Case**: Automatically share new links on social media when created.

**Setup**:
1. Choose Go2 as trigger → "New Link Created"
2. Choose Twitter as action → "Create Tweet"
3. Map `shortUrl` to tweet content
4. Add link title as tweet text

### Track Link Clicks in Google Sheets

**Trigger**: Link clicked in Go2  
**Action**: Add row to Google Sheets

**Use Case**: Maintain a spreadsheet of all link clicks for reporting.

**Setup**:
1. Choose Go2 as trigger → "Link Clicked"
2. Choose Google Sheets as action → "Create Spreadsheet Row"
3. Map click data: date, country, device, referrer

### Sync Links to CRM

**Trigger**: New link created in Go2  
**Action**: Create record in Salesforce/HubSpot

**Use Case**: Track marketing campaigns in your CRM.

**Setup**:
1. Choose Go2 as trigger → "New Link Created"
2. Choose your CRM as action → "Create Record"
3. Map link data to CRM fields

### Send Slack Notifications for High-Performing Links

**Trigger**: Link clicks exceed threshold  
**Action**: Send Slack message

**Use Case**: Get notified when a link goes viral.

**Setup**:
1. Choose Go2 as trigger → "Link Clicks" (with filter)
2. Choose Slack as action → "Send Channel Message"
3. Format message with link stats

## Advanced Workflows

### Multi-Step Zap: Email → Link → Social Media → Analytics

1. **Trigger**: New email in Gmail
2. **Action**: Extract URLs from email body
3. **Action**: Create short link in Go2 for each URL
4. **Action**: Post to Twitter with short link
5. **Action**: Log to Google Sheets

### Conditional Logic

Use Zapier's filters to create conditional workflows:

- **If** link clicks > 1000 → Send Slack notification
- **If** link expires → Archive in CRM
- **If** link from specific domain → Add special tag

## Webhook Integration

For more advanced automation, use Go2 webhooks with Zapier's Webhooks by Zapier:

1. Set up a webhook in Go2 dashboard
2. Use Zapier's "Catch Hook" trigger
3. Process webhook payload in your Zap

**Example Webhook Payload**:

```json
{
  "event": "click",
  "link": {
    "id": "lnk_abc123",
    "shortUrl": "https://go2.gg/summer-sale",
    "destinationUrl": "https://example.com/product"
  },
  "click": {
    "country": "US",
    "device": "mobile",
    "referrer": "twitter.com",
    "timestamp": "2024-06-15T14:22:00Z"
  }
}
```

## Tips & Best Practices

1. **Use Filters**: Add filters to avoid processing unwanted links
2. **Batch Operations**: Use Zapier's built-in delays for bulk operations
3. **Error Handling**: Set up error notifications for failed Zaps
4. **Testing**: Always test your Zaps with sample data first
5. **Rate Limits**: Be aware of Zapier's rate limits (varies by plan)

## Troubleshooting

### Connection Issues

- Verify your API key is correct
- Check API key permissions
- Ensure your Go2 account is active

### Missing Data

- Check field mapping in Zap steps
- Verify trigger conditions are met
- Review Zap history for errors

### Rate Limiting

- Upgrade Zapier plan for higher limits
- Add delays between steps
- Use filters to reduce trigger frequency

## Resources

- [Zapier Go2 Integration](https://zapier.com/apps/go2/integrations)
- [Zapier Documentation](https://zapier.com/help)
- [Go2 API Documentation](/docs/api/overview)

## Need Help?

- Check [Zapier's support](https://zapier.com/help)
- Review [Go2 API docs](/docs/api/overview)
- Contact Go2 support for API-specific questions


================================================================================
Generated: 2026-08-15T22:59:06.231Z
Total docs: 19