# pti.to — Complete AI & Developer Reference Documentation

> High-performance URL shortening, dynamic vector QR codes, click intelligence, and Model Context Protocol (MCP) server for autonomous agents.

---

## 1. System Overview & Architecture
`pti.to` is an enterprise-grade links platform designed for single-digit millisecond redirection latency, real-time click stream analytics, and autonomous integration with AI agents, LLM applications, and developer workflows.

- **Production Domain**: `https://pti.to`
- **API Gateway Base URL**: `https://api.pti.to`
- **Development Sandbox**: `https://api.dev.pti.to`
- **Protocol**: HTTPS / REST / JSON-RPC 2.0 (MCP)

---

## 2. Authentication & Authorization

All API endpoints (except public specifications and health checks) require an API Key or Cognito JWT Bearer token in the `Authorization` header.

```http
Authorization: Bearer bns_live_your_api_key
X-Org-Id: org_abc123
```

### Permission Scopes
| Scope | Description |
| :--- | :--- |
| `links:read` | Read short links, metadata, and generate QR codes |
| `links:write` | Create, update, duplicate, and delete short links |
| `analytics:read` | Query click counts, timeseries, referrers, and device breakdown |
| `org:admin` | Manage API keys, custom domains, webhooks, and team roles |

---

## 3. Model Context Protocol (MCP) Server

`pti.to` runs a native Model Context Protocol (MCP) JSON-RPC 2.0 server at:
`POST https://api.pti.to/api/v1/mcp`

### Supported RPC Methods
- `initialize`: Protocol negotiation (v2024-11-05), server information, and capabilities.
- `ping`: Liveness check.
- `tools/list`: Lists all available agent tools with full JSON Schema specifications.
- `tools/call`: Executes a tool with provided arguments and returns structured text or resource output.
- `resources/list`: Lists live organization data resources (`ptito://links`, `ptito://analytics/overview`, `ptito://system/health`).
- `resources/read`: Reads data from a specific URI resource.
- `prompts/list`: Lists built-in prompt templates (`campaign-link-builder`, `performance-analysis`, `qr-brand-kit`).
- `prompts/get`: Retrieves a populated prompt template.

### MCP Tools List
1. `shorten_url(targetUrl, slug?, title?, tags?, password?, expiresAt?, expiredFallbackUrl?, clickLimit?, utmParams?, deviceTargeting?, geoTargeting?, domain?)`
2. `get_link(linkId)`
3. `list_links(tag?, limit?)`
4. `update_link(linkId, targetUrl?, title?, tags?, status?, expiresAt?)`
5. `delete_link(linkId)`
6. `get_link_analytics(linkId, days?)`
7. `get_org_overview()`
8. `generate_qr_code(linkId, format?, fgColor?, bgColor?, dotStyle?, cornerStyle?)`
9. `create_api_key(name, scopes, expiresInDays?)`
10. `list_custom_domains()`

### Claude Desktop Integration (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "ptito": {
      "command": "npx",
      "args": ["-y", "@ptito/mcp-server"],
      "env": {
        "PTITO_API_KEY": "bns_live_your_secret_key"
      }
    }
  }
}
```

---

## 4. REST API Reference

### POST /api/v1/links
Create a new shortened link.
**Request Body**:
```json
{
  "targetUrl": "https://example.com/products/ai-assistant",
  "slug": "ai-assistant",
  "title": "AI Assistant Launch",
  "tags": ["AI", "Launch", "Product"],
  "utmParams": {
    "source": "twitter",
    "medium": "social",
    "campaign": "launch_2026"
  },
  "deviceTargeting": {
    "iosUrl": "https://apps.apple.com/app/id123456",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.example.app"
  },
  "expiresAt": "2026-12-31T23:59:59Z",
  "expiredFallbackUrl": "https://example.com/fallback"
}
```
**Response (201 Created)**:
```json
{
  "link": {
    "id": "link_a1b2c3d4e5",
    "orgId": "org_default",
    "slug": "ai-assistant",
    "targetUrl": "https://example.com/products/ai-assistant",
    "title": "AI Assistant Launch",
    "status": "ACTIVE",
    "clicks": 0,
    "createdAt": "2026-08-27T16:00:00Z"
  }
}
```

### GET /api/v1/links
List all short links in the current workspace.
Query parameters: `tag` (optional string), `limit` (optional integer, max 200).

### GET /api/v1/links/{id}
Retrieve full configuration and click counters for a link.

### PUT /api/v1/links/{id}
Update properties of an existing link.
```json
{
  "targetUrl": "https://example.com/products/ai-assistant-v2",
  "status": "ACTIVE"
}
```

### DELETE /api/v1/links/{id}
Permanently delete a short link.

### GET /api/v1/links/{id}/qr
Generate dynamic vector SVG or raster Data URL QR code.
Query parameters: `format` (`svg` or `dataUrl`), `fgColor` (hex code), `bgColor` (hex code), `dotStyle` (`square`, `rounded`, `dots`, `classy`), `cornerStyle` (`square`, `rounded`, `extra-rounded`).

### GET /api/v1/links/{id}/analytics
Fetch click streams and aggregated traffic metrics.
Query parameters: `days` (default 30, max 90).
**Response (200 OK)**:
```json
{
  "totalClicks": 12480,
  "uniqueVisitors": 9820,
  "referrers": [
    { "referrer": "twitter.com", "clicks": 5400, "percentage": 43.2 },
    { "referrer": "google.com", "clicks": 3200, "percentage": 25.6 }
  ],
  "devices": [
    { "device": "mobile", "clicks": 7500, "percentage": 60.1 },
    { "device": "desktop", "clicks": 4980, "percentage": 39.9 }
  ],
  "countries": [
    { "country": "US", "countryName": "United States", "clicks": 6200 },
    { "country": "GB", "countryName": "United Kingdom", "clicks": 1800 }
  ],
  "timeseries": [
    { "date": "2026-08-26", "clicks": 480 }
  ]
}
```

---

## 5. Code Integration Examples

### TypeScript / Node.js
```typescript
import { PtitoAgentClient } from '@bonsai/core';

const ptito = new PtitoAgentClient({
  apiKey: process.env.PTITO_API_KEY!
});

// Shorten a link
const link = await ptito.shorten({
  targetUrl: 'https://example.com/promo',
  slug: 'summer-special',
  tags: ['Agent', 'Promo']
});

console.log('Short URL:', link.shortUrl);
```

### Python
```python
import requests

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

payload = {
    "targetUrl": "https://example.com/release",
    "slug": "v2-release",
    "tags": ["Python", "Automated"]
}

res = requests.post("https://api.pti.to/api/v1/links", json=payload, headers=HEADERS)
data = res.json()
print("Short Link created:", data["link"]["slug"])
```

### LangChain Tools (TypeScript)
```typescript
import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';
import { PtitoAgentClient } from '@bonsai/core';

const client = new PtitoAgentClient({ apiKey: process.env.PTITO_API_KEY! });

export const shortenUrlTool = new DynamicStructuredTool({
  name: 'shorten_url',
  description: 'Create a branded short link with pti.to',
  schema: z.object({
    targetUrl: z.string().url(),
    slug: z.string().optional()
  }),
  func: async ({ targetUrl, slug }) => {
    const res = await client.shorten({ targetUrl, slug });
    return `Short link created: ${res.shortUrl}`;
  }
});
```

---

## 6. Webhooks & Event Subscriptions
`pti.to` can dispatch real-time HMAC SHA-256 signed JSON payloads for events:
- `link.created`: When a new short link is created.
- `link.clicked`: Every time a visitor accesses a link.
- `link.expired`: When a link crosses its expiration timestamp.
- `link.limit_reached`: When a link reaches its maximum click ceiling.

Signature header: `X-Ptito-Signature: t=1756310000,v1=9a8b7c...`

---

## 7. Machine-Readable Endpoints
- OpenAPI 3.1.0 JSON: `https://api.pti.to/api/v1/openapi.json`
- LLMs Index: `https://pti.to/llms.txt`
- Full LLMs Context: `https://pti.to/llms-full.txt`
- AI Plugin Manifest: `https://pti.to/.well-known/ai-plugin.json`