{ "openapi": "3.1.0", "info": { "title": "pti.to API & Agent Platform", "version": "1.2.0", "description": "High-performance URL shortening, dynamic QR code studio, link intelligence, and Model Context Protocol (MCP) server for AI agents and developer applications.\n\nWebsite: https://pti.to", "contact": { "name": "pti.to Support", "email": "support@pti.to", "url": "https://pti.to/docs" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://api.pti.to", "description": "Production API Gateway" }, { "url": "https://api.dev.pti.to", "description": "Development Sandbox" } ], "tags": [ { "name": "AI & MCP", "description": "Model Context Protocol (MCP) and agent discovery endpoints" }, { "name": "Links", "description": "URL shortening, management, deep linking, and targeting" }, { "name": "QR Codes", "description": "Dynamic vector and raster QR code generation" }, { "name": "Analytics", "description": "Real-time click streams, geographical, and device intelligence" }, { "name": "Domains", "description": "Custom branded domain management and DNS verification" }, { "name": "API Keys", "description": "Programmatic access keys with granular scopes" }, { "name": "Webhooks", "description": "Real-time event subscriptions and testing" }, { "name": "System", "description": "Health checks and operational diagnostics" } ], "paths": { "/api/v1/mcp": { "post": { "tags": [ "AI & MCP" ], "summary": "Model Context Protocol (MCP) JSON-RPC 2.0 Server", "description": "Execute MCP tools, read MCP resources, or fetch prompt templates using standard JSON-RPC 2.0 protocol.", "operationId": "handleMcpRpc", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "Successful JSON-RPC 2.0 Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } } } }, "get": { "tags": [ "AI & MCP" ], "summary": "Get MCP Server Capabilities & Manifest", "description": "Inspect available tools, resources, prompts, and protocol version of the pti.to MCP Server.", "operationId": "getMcpInfo", "responses": { "200": { "description": "MCP Server Information", "content": { "application/json": { "schema": { "type": "object", "properties": { "serverInfo": { "type": "object" }, "protocolVersion": { "type": "string" }, "capabilities": { "type": "object" }, "tools": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/api/v1/links": { "get": { "tags": [ "Links" ], "summary": "List Short Links", "description": "Retrieve a list of short links for the organization with optional tag filtering and pagination.", "operationId": "listLinks", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filter by category tag" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Max records to return" }, { "name": "X-Org-Id", "in": "header", "schema": { "type": "string" }, "description": "Organization context ID" } ], "responses": { "200": { "description": "List of links", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "total": { "type": "integer" } } } } } } } }, "post": { "tags": [ "Links" ], "summary": "Create Short Link", "description": "Generate a new short URL with custom slug, tags, expiration, UTM parameters, geo/device targeting, and password protection.", "operationId": "createLink", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "X-Org-Id", "in": "header", "schema": { "type": "string" }, "description": "Organization context ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLinkInput" } } } }, "responses": { "201": { "description": "Link created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/Link" } } } } } } } } }, "/api/v1/links/{id}": { "get": { "tags": [ "Links" ], "summary": "Get Link by ID", "description": "Retrieve detailed configuration and statistics for a specific short link.", "operationId": "getLink", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Link unique ID" } ], "responses": { "200": { "description": "Link details", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/Link" } } } } } } } }, "put": { "tags": [ "Links" ], "summary": "Update Link", "description": "Update destination URL, title, tags, expiry date, or status of an existing short link.", "operationId": "updateLink", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkInput" } } } }, "responses": { "200": { "description": "Link updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/Link" } } } } } } } }, "delete": { "tags": [ "Links" ], "summary": "Delete Link", "description": "Permanently remove a short link.", "operationId": "deleteLink", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Link deleted successfully" } } } }, "/api/v1/links/{id}/qr": { "get": { "tags": [ "QR Codes" ], "summary": "Generate QR Code for Link", "description": "Generate dynamic vector (SVG) or raster (Data URL) QR code for a short link.", "operationId": "generateLinkQr", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "svg", "dataUrl" ], "default": "svg" } }, { "name": "fgColor", "in": "query", "schema": { "type": "string" }, "description": "Hex color code (e.g. \"059669\")" }, { "name": "bgColor", "in": "query", "schema": { "type": "string" }, "description": "Hex color code (e.g. \"ffffff\")" }, { "name": "dotStyle", "in": "query", "schema": { "type": "string", "enum": [ "square", "rounded", "dots", "classy" ] } } ], "responses": { "200": { "description": "Generated QR Code", "content": { "image/svg+xml": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object", "properties": { "dataUrl": { "type": "string" }, "shortUrl": { "type": "string" } } } } } } } } }, "/api/v1/links/{id}/analytics": { "get": { "tags": [ "Analytics" ], "summary": "Get Link Click Analytics", "description": "Fetch click volume, timeseries data, top referrers, devices, operating systems, and countries.", "operationId": "getLinkAnalytics", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90 } } ], "responses": { "200": { "description": "Analytics summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAnalyticsSummary" } } } } } } }, "/api/v1/analytics/overview": { "get": { "tags": [ "Analytics" ], "summary": "Get Organization Analytics Overview", "description": "Aggregate metrics across all links in the organization.", "operationId": "getOrgOverview", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Organization overview metrics" } } } }, "/api/v1/keys": { "get": { "tags": [ "API Keys" ], "summary": "List API Keys", "operationId": "listApiKeys", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "List of active API keys" } } }, "post": { "tags": [ "API Keys" ], "summary": "Create API Key", "operationId": "createApiKey", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresInDays": { "type": "integer" } }, "required": [ "name", "scopes" ] } } } }, "responses": { "201": { "description": "API Key generated" } } } }, "/api/v1/domains": { "get": { "tags": [ "Domains" ], "summary": "List Custom Domains", "operationId": "listDomains", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "List of custom branded domains" } } }, "post": { "tags": [ "Domains" ], "summary": "Add Custom Domain", "operationId": "addDomain", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "Domain registered" } } } }, "/api/v1/health": { "get": { "tags": [ "System" ], "summary": "System Health & Latency Check", "operationId": "getHealth", "responses": { "200": { "description": "Operational status of services and databases" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key (bns_live_...)", "description": "Pass your API Key in the Authorization header: `Bearer bns_live_your_key`" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Cognito User ID Token" } }, "schemas": { "JsonRpcRequest": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string", "description": "e.g. \"tools/list\", \"tools/call\", \"resources/list\"" }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] }, "JsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object" } } } }, "required": [ "jsonrpc", "id" ] }, "CreateLinkInput": { "type": "object", "properties": { "targetUrl": { "type": "string", "format": "uri", "description": "Destination URL (http:// or https://)" }, "slug": { "type": "string", "description": "Custom short alias (2-64 chars)" }, "title": { "type": "string", "description": "Descriptive title" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "password": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiredFallbackUrl": { "type": "string", "format": "uri" }, "clickLimit": { "type": "integer" }, "utmParams": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } } }, "deviceTargeting": { "type": "object", "properties": { "iosUrl": { "type": "string", "format": "uri" }, "androidUrl": { "type": "string", "format": "uri" }, "desktopUrl": { "type": "string", "format": "uri" } } }, "geoTargeting": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "domain": { "type": "string" } }, "required": [ "targetUrl" ] }, "UpdateLinkInput": { "type": "object", "properties": { "targetUrl": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "Link": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "slug": { "type": "string" }, "targetUrl": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "clicks": { "type": "integer" }, "domain": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "LinkAnalyticsSummary": { "type": "object", "properties": { "totalClicks": { "type": "integer" }, "uniqueVisitors": { "type": "integer" }, "referrers": { "type": "array", "items": { "type": "object" } }, "devices": { "type": "array", "items": { "type": "object" } }, "countries": { "type": "array", "items": { "type": "object" } }, "browsers": { "type": "array", "items": { "type": "object" } }, "timeseries": { "type": "array", "items": { "type": "object" } } } } } } }