# Za.gl — Full API Reference

> Za.gl is a free URL shortener, pastebin, and landing page creator. No signup required.

All endpoints accept `Content-Type: application/json` via POST.
Base URL: `https://za.gl`

---

## POST /api/shorten

Create a shortened URL.

### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| originalUrl | string | yes | URL to shorten (max 2000 chars). Protocol auto-added if missing. |
| customAlias | string | no | Custom short code (3-50 chars, `[a-zA-Z0-9-_]`). Must be unique. |
| title | string | no | Title (max 200 chars) |
| description | string | no | Description (max 500 chars) |
| password | string | no | Password protection (4-100 chars) |
| expiresAt | string | no | Expiration date (ISO 8601) |
| expiresInMinutes | number | no | Expires in N minutes (1-525600) |
| expiresInHours | number | no | Expires in N hours (1-8760) |
| expiresInDays | number | no | Expires in N days (1-365) |
| waitTimer | number | no | Wait seconds before redirect (0-300) |
| maxClicks | number | no | Max allowed clicks (1-1000000) |
| email | string | no | Email for access notification |
| utmSource | string | no | UTM source (max 100) |
| utmMedium | string | no | UTM medium (max 100) |
| utmCampaign | string | no | UTM campaign (max 100) |
| utmTerm | string | no | UTM term (max 100) |
| utmContent | string | no | UTM content (max 100) |
| generateQR | boolean | no | Generate QR code |
| qrStyle | string | no | QR style: default, rounded, dots |

### Response

```json
{
  "success": true,
  "message": "URL shortened successfully",
  "data": {
    "shortUrl": "https://za.gl/abc123",
    "alias": "abc123",
    "originalUrl": "https://example.com/long/path",
    "title": "",
    "hasPassword": false,
    "isActive": true,
    "expiresAt": null,
    "hits": 0,
    "waitTimer": 0,
    "created": "2025-04-16T10:00:00.000Z",
    "authToken": "zagl_...",
    "newAuthToken": "zagl_..."
  }
}
```

### Errors

- 400: Invalid URL, validation error, or redirect loop (cannot shorten za.gl URLs)
- 409: Custom alias already taken
- 429: Rate limit (10 requests/minute) or monthly API quota exceeded

### Rate Limit

10 requests per 60 seconds per client IP.

---

## POST /api/paste

Create a paste with optional syntax highlighting.

### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| content | string | yes | Paste content (1-500000 chars) |
| title | string | no | Title (max 200 chars) |
| language | string | no | Syntax highlighting language (see list below) |
| visibility | number | no | 1 = public (default), 0 = private |
| password | string | no | Password protection (4-100 chars) |
| expiresAt | string | no | Expiration date (ISO 8601) |
| email | string | no | Email for access notification |

### Supported Languages

text, javascript, typescript, python, java, csharp, cpp, c, php, ruby, go, rust, swift, kotlin, html, css, xml, json, yaml, markdown, sql, bash, powershell, dockerfile, nginx

### Response

```json
{
  "success": true,
  "message": "Paste created successfully",
  "data": {
    "slug": "abcd1234",
    "url": "https://za.gl/p/abcd1234",
    "title": null,
    "language": "python",
    "visibility": 1,
    "expiresAt": null,
    "totalViews": 0,
    "created": "2025-04-16T10:00:00.000Z",
    "authToken": "zagl_...",
    "newAuthToken": "zagl_..."
  }
}
```

### Errors

- 400: Missing content or invalid JSON
- 429: Monthly API quota exceeded

---

## POST /api/landing

Create a landing page with custom HTML, CSS, and JavaScript.

### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| title | string | yes | Page title (1-200 chars) |
| description | string | no | Meta description (max 500 chars) |
| content | string | no | HTML content (max 1000000 chars) |
| customCss | string | no | Custom CSS (max 100000 chars) |
| customJs | string | no | Custom JavaScript (max 100000 chars) |
| isPublic | boolean | no | Public visibility (default: true) |

### Response

```json
{
  "success": true,
  "message": "Landing page created successfully",
  "data": {
    "slug": "my-page",
    "url": "https://za.gl/c/my-page",
    "title": "My Page",
    "meta_desc": null,
    "visibility": 1,
    "totalViews": 0,
    "created": "2025-04-16T10:00:00.000Z",
    "authToken": "zagl_...",
    "newAuthToken": "zagl_..."
  }
}
```

### Errors

- 400: Missing title or invalid JSON
- 429: Monthly API quota exceeded

---

## Authentication

All endpoints work without authentication. When no auth token is provided, an anonymous user account is automatically created and the response includes a `newAuthToken` field. Save this token to manage your content later.

To use a saved token, send it as a Bearer token:

```
Authorization: Bearer zagl_...
```

## Error Format

All error responses follow this structure:

```json
{
  "success": false,
  "error": "Error description"
}
```

---

## MCP Server

Za.gl provides a remote MCP (Model Context Protocol) server for AI assistant integration.

### Endpoint

```
https://za.gl/api/mcp
```

### Configure (Claude Desktop)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zagl": {
      "type": "streamable-http",
      "url": "https://za.gl/api/mcp"
    }
  }
}
```

### Configure (Claude Code)

```bash
claude mcp add --transport http zagl https://za.gl/api/mcp
```

### Configure (VS Code / Copilot)

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "zagl": {
      "type": "streamable-http",
      "url": "https://za.gl/api/mcp"
    }
  }
}
```

### Available Tools

- `shorten_url` — Shorten a URL with optional custom alias, password, expiration, and wait timer
- `create_paste` — Create a paste with syntax highlighting for 25 languages
- `create_landing_page` — Create a landing page with custom HTML, CSS, and JavaScript