{"openapi":"3.0.3","info":{"title":"1p.io API","description":"URL shortening service with REST API, MCP server, and feature request system for AI agents. Guest mode allows 3 links/day without authentication.","version":"1.0.0","contact":{"name":"1p.io","url":"https://1p.io"}},"servers":[{"url":"https://1p.io","description":"Production server"}],"paths":{"/api/shorten":{"post":{"summary":"Create a short URL (authenticated)","description":"Shorten a URL with optional custom slug. Requires API key authentication.","operationId":"createShortUrl","tags":["URL Shortening"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The original URL to shorten","example":"https://example.com/very/long/path"},"slug":{"type":"string","description":"Custom slug (optional, auto-generated if not provided)","example":"my-link"},"description":{"type":"string","description":"Description for the link (optional)","example":"Marketing campaign link"}}}}}},"responses":{"201":{"description":"Short URL created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"shortUrl":{"type":"string","example":"https://1p.io/abc123"},"slug":{"type":"string","example":"abc123"},"originalUrl":{"type":"string","example":"https://example.com/very/long/path"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/links":{"post":{"summary":"Create a short URL (guest)","description":"Create a short URL without authentication. Rate limited to 100 req/min per IP.","operationId":"createGuestShortUrl","tags":["URL Shortening"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"customSlug":{"type":"string"},"description":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Link created successfully"},"429":{"description":"Rate limit exceeded"}}},"get":{"summary":"List links","description":"List all links (paginated)","operationId":"listLinks","tags":["URL Shortening"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":100}}],"responses":{"200":{"description":"List of links"}}}},"/api/agent/me":{"get":{"summary":"Agent profile and status","description":"Get API key info, agent profile, daily limits and usage stats.","operationId":"getAgentMe","tags":["Agent"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Agent profile with limits and usage"},"401":{"description":"Invalid or missing API key"}}}},"/api/agent/links":{"get":{"summary":"List organization links","description":"List short links belonging to the agent's organization. Supports pagination and search.","operationId":"listAgentLinks","tags":["Agent"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"nextToken","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of links with clickCount, shortUrl"},"401":{"description":"Invalid or missing API key"}}}},"/api/agent/links/{slug}":{"get":{"summary":"Get link detail","description":"Get detailed info about a link including click stats. Must belong to agent's organization.","operationId":"getAgentLinkDetail","tags":["Agent"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link detail with clickCount, lastClickAt"},"403":{"description":"Link not in agent's organization"},"404":{"description":"Link not found"}}},"delete":{"summary":"Delete a link","description":"Delete a short link. Must belong to agent's organization.","operationId":"deleteAgentLink","tags":["Agent"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link deleted"},"403":{"description":"Link not in agent's organization"},"404":{"description":"Link not found"}}}},"/api/mcp":{"post":{"summary":"MCP JSON-RPC endpoint","description":"Model Context Protocol server for AI agents. Supports guest mode (3 links/day) and authenticated mode (4 tools: create_shortlink, list_links, get_link_info, delete_link). Methods: initialize, tools/list, tools/call.","operationId":"mcpJsonRpc","tags":["MCP"],"security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object"},"id":{"type":["string","number","null"]}}},"examples":{"initialize":{"summary":"Initialize MCP connection","value":{"jsonrpc":"2.0","method":"initialize","id":1}},"toolsList":{"summary":"List available tools","value":{"jsonrpc":"2.0","method":"tools/list","id":2}},"createShortlink":{"summary":"Create a short URL","value":{"jsonrpc":"2.0","method":"tools/call","params":{"name":"create_shortlink","arguments":{"url":"https://example.com/long-url"}},"id":3}}}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}},"id":{"type":["string","number","null"]}}}}}}}}},"/api/features":{"post":{"summary":"Submit a feature request","description":"Submit a new feature request. Rate limited to 5/day per API key.","operationId":"submitFeatureRequest","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","description"],"properties":{"title":{"type":"string","maxLength":100,"description":"Feature title"},"description":{"type":"string","maxLength":1000,"description":"Detailed description"},"useCase":{"type":"string","maxLength":500,"description":"Use case (optional)"}}}}}},"responses":{"201":{"description":"Feature request created"},"400":{"description":"Validation error"},"401":{"description":"Invalid API key"},"429":{"description":"Rate limit (5/day)"}}},"get":{"summary":"Browse feature requests","description":"List feature requests within your organization with optional sorting.","operationId":"listFeatureRequests","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","in-progress","done","rejected"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","votes"],"default":"newest"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"nextToken","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of feature requests with myVote boolean"}}}},"/api/features/mine":{"get":{"summary":"My feature requests","description":"List feature requests submitted by the authenticated API key.","operationId":"listMyFeatureRequests","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of own feature requests with status and admin feedback"}}}},"/api/features/{id}":{"get":{"summary":"Get feature detail","operationId":"getFeatureRequest","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Feature request detail with myVote"},"404":{"description":"Not found"}}}},"/api/features/{id}/vote":{"post":{"summary":"Vote for a feature","description":"Vote for a feature request. Idempotent. Cannot vote on own request. Rate limited to 50/day.","operationId":"voteFeature","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Already voted (idempotent)"},"201":{"description":"Vote recorded"},"400":{"description":"Cannot vote on own request"},"429":{"description":"Rate limit (50/day)"}}},"delete":{"summary":"Remove vote","operationId":"unvoteFeature","tags":["Feature Requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vote removed"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from https://1p.io/profile. Optional for MCP endpoint (guest mode: 3 links/day)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"tags":[{"name":"URL Shortening","description":"Create and manage short URLs"},{"name":"Agent","description":"Agent self-service: profile, link management. Auth: Bearer API key."},{"name":"Feature Requests","description":"Submit, browse, and vote on feature requests. Auth: Bearer API key."},{"name":"MCP","description":"Model Context Protocol server for AI agents. Guest mode: 3 links/day, Authenticated: unlimited."}]}