# pti.to AI & Developer Context

> High-performance URL shortening, dynamic QR code studio, link intelligence, and Model Context Protocol (MCP) server for AI agents and developer applications.

## Overview
pti.to is a modern, privacy-first links and QR platform built for high-throughput edge redirection, real-time click stream intelligence, custom vanity domains, and autonomous AI Agent workflows.

## Authentication
API keys use the `Bearer` token scheme in the HTTP `Authorization` header:
```http
Authorization: Bearer bns_live_your_api_key
X-Org-Id: org_your_organization_id
```

### Permission Scopes
- `links:read`: View short links, metadata, and QR codes.
- `links:write`: Create, update, duplicate, and delete short links.
- `analytics:read`: Query click streams, timeseries, referrers, and device breakdown.
- `org:admin`: Provision API keys, manage custom domains, webhooks, and team access.

## Core API Endpoints
- Base URL: `https://api.pti.to`
- `POST /api/v1/links`: Create a short link (accepts `targetUrl`, `slug`, `tags`, `password`, `expiresAt`, `utmParams`, `deviceTargeting`, `geoTargeting`).
- `GET /api/v1/links`: List short links with tag filter and limit.
- `GET /api/v1/links/{id}`: Retrieve link details.
- `PUT /api/v1/links/{id}`: Update target URL, status, expiry, or tags.
- `DELETE /api/v1/links/{id}`: Permanently delete a short link.
- `GET /api/v1/links/{id}/qr`: Generate SVG or PNG Data URL QR code.
- `GET /api/v1/links/{id}/analytics`: Retrieve click statistics (days=1..90).
- `GET /api/v1/analytics/overview`: Organization-wide aggregate click intelligence.
- `GET /api/v1/domains`: List connected custom branded domains.
- `POST /api/v1/domains`: Connect a new vanity domain.
- `GET /api/v1/health`: Operational health check.

## Model Context Protocol (MCP) Server
- **Endpoint**: `https://api.pti.to/api/v1/mcp`
- **Protocol**: JSON-RPC 2.0
- **Supported Methods**: `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`

### Agent MCP Tools
1. `shorten_url`: Shortens a destination URL with custom options.
2. `get_link`: Retrieves short link details.
3. `list_links`: Queries workspace links.
4. `update_link`: Updates link configuration.
5. `delete_link`: Deletes a link.
6. `get_link_analytics`: Queries click metrics and audience breakdown.
7. `get_org_overview`: Workspace-level performance overview.
8. `generate_qr_code`: Renders custom vector or raster QR code.
9. `create_api_key`: Provisions scoped API keys.
10. `list_custom_domains`: Inspects custom domains and SSL verification.

### Claude Desktop Configuration
```json
{
  "mcpServers": {
    "ptito": {
      "command": "npx",
      "args": ["-y", "@ptito/mcp-server"],
      "env": {
        "PTITO_API_KEY": "bns_live_your_key_here"
      }
    }
  }
}
```

## Machine-Readable Resources
- Full Guide & Schemas: https://pti.to/llms-full.txt
- OpenAPI 3.1.0 Specification: https://api.pti.to/api/v1/openapi.json
- AI Plugin Manifest: https://pti.to/.well-known/ai-plugin.json
- Interactive Docs: https://pti.to/docs