{ "openapi": "3.1.0", "info": { "title": "A6 Paid Short-Link API", "version": "1.2.0", "description": "Active paid members only. Create and query owned short links, aggregated traffic dimensions and paginated visit records. API keys are server credentials, not browser cookies. Detailed tracking starts at detailed_tracking_since; unknown historical geography is not fabricated. All creation modes require DeepSeek Flash risk review. Financial content and suspected phishing are rejected; unreadable or inconclusive pages and unavailable review pause creation without model fallback. The same original URL may be shortened again with a distinct unique code." }, "servers": [ { "url": "https://a6.cm/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] }, "ShortLink": { "type": "object", "properties": { "id": { "type": "integer" }, "short_code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" }, "short_url": { "type": "string", "format": "uri" }, "original_url": { "type": "string", "format": "uri" }, "remark": { "type": "string" }, "expire_at": { "type": [ "string", "null" ], "description": "Local server date/time, YYYY-MM-DD HH:mm:ss, or null." }, "max_clicks": { "type": [ "integer", "null" ], "minimum": 1 }, "click_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": [ "string", "null" ], "description": "Local server date/time, YYYY-MM-DD HH:mm:ss, or null." } }, "required": [ "id", "short_code", "short_url", "original_url", "remark", "expire_at", "max_clicks", "click_count", "created_at" ] }, "AnalyticsRange": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "timezone": { "type": "string", "const": "Asia/Shanghai" }, "interval": { "type": "string", "enum": [ "day", "hour" ] } }, "required": [ "from", "to", "timezone", "interval" ] }, "VisitSummary": { "type": "object", "properties": { "visits": { "type": "integer", "minimum": 0, "description": "Successfully recorded detailed visits within the requested range, including detected bots." }, "unique_visitors_estimate": { "type": "integer", "minimum": 0, "description": "Distinct per-link HMAC IP identities within the range. Estimated visitors, not people; includes bots." }, "bot_visits": { "type": "integer", "minimum": 0 }, "geolocated_visits": { "type": "integer", "minimum": 0 }, "identified_visits": { "type": "integer", "minimum": 0, "description": "Visits with a usable HMAC IP identity. Missing identity is not counted as a unique visitor." }, "all_time_click_count": { "type": "integer", "minimum": 0, "description": "Legacy-compatible lifetime link counter, not restricted to the requested range; can include visits before detailed tracking." }, "non_bot_visits": { "type": "integer", "minimum": 0 }, "first_visit_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_visit_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "visits", "unique_visitors_estimate", "bot_visits", "geolocated_visits", "identified_visits", "all_time_click_count", "non_bot_visits", "first_visit_at", "last_visit_at" ] }, "DimensionGroup": { "type": "object", "properties": { "value": { "type": "string" }, "visits": { "type": "integer", "minimum": 0 } }, "required": [ "value", "visits" ] }, "CountryGroup": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Two-letter country/territory code; ZZ means unknown." }, "visits": { "type": "integer", "minimum": 0 }, "name": { "type": "string" } }, "required": [ "value", "visits", "name" ] }, "LocationGroup": { "type": "object", "properties": { "country_code": { "type": "string" }, "country_name": { "type": "string" }, "region": { "type": "string", "description": "IP-based region when provided by trusted CDN; otherwise empty." }, "city": { "type": "string", "description": "IP-based city when provided by trusted CDN; otherwise empty." }, "visits": { "type": "integer", "minimum": 0 } }, "required": [ "country_code", "country_name", "region", "city", "visits" ] }, "Visit": { "type": "object", "properties": { "id": { "type": "integer" }, "visited_at": { "type": "string", "format": "date-time" }, "country_code": { "type": "string" }, "country_name": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "device": { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot", "unknown" ] }, "browser": { "type": "string" }, "os": { "type": "string" }, "is_bot": { "type": "boolean" }, "referrer_host": { "type": "string", "description": "Hostname only, without URL path or parameters. direct_or_unknown means absent or unrecognized." } }, "required": [ "id", "visited_at", "country_code", "country_name", "region", "city", "device", "browser", "os", "is_bot", "referrer_host" ] }, "LinkStats": { "type": "object", "properties": { "short_code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" }, "range": { "$ref": "#/components/schemas/AnalyticsRange" }, "summary": { "$ref": "#/components/schemas/VisitSummary" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/CountryGroup" } }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionGroup" } }, "browsers": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionGroup" } }, "operating_systems": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionGroup" } }, "referrers": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionGroup" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationGroup" } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "description": "YYYY-MM-DD for day; ISO 8601 +08:00 hour start for hour." }, "visits": { "type": "integer", "minimum": 0 }, "unique_visitors_estimate": { "type": "integer", "minimum": 0 } }, "required": [ "period", "visits", "unique_visitors_estimate" ] } }, "detailed_tracking_since": { "type": "string", "format": "date-time" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "short_code", "range", "summary", "countries", "devices", "browsers", "operating_systems", "referrers", "locations", "timeline", "detailed_tracking_since", "notes" ] }, "VisitPage": { "type": "object", "properties": { "short_code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" }, "range": { "$ref": "#/components/schemas/AnalyticsRange" }, "visits": { "type": "array", "items": { "$ref": "#/components/schemas/Visit" } }, "next_before_id": { "type": [ "integer", "null" ], "description": "Pass as before_id for the next page while keeping the link and date range unchanged. null means no further page." } }, "required": [ "short_code", "range", "visits", "next_before_id" ] }, "AccountLimits": { "type": "object", "properties": { "creates_per_minute": { "type": "integer", "const": 60 }, "api_creates_per_day": { "type": "integer", "const": 1000 }, "requests_per_minute": { "type": "integer", "const": 120 }, "risk_checks_per_minute": { "type": "integer", "const": 60 }, "risk_checks_per_day": { "type": "integer", "const": 1000 }, "risk_cache_seconds": { "type": "integer", "const": 300 } }, "required": [ "creates_per_minute", "api_creates_per_day", "requests_per_minute", "risk_checks_per_minute", "risk_checks_per_day", "risk_cache_seconds" ], "description": "Paid account limits. Creates and API request limits remain distinct from risk-review checks. Risk cache is at most 300 seconds; cache hits across requests still count toward risk-review allowance." } } }, "paths": { "/links": { "post": { "operationId": "createShortLink", "summary": "Create an owned short link", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9._:-]{8,80}$" } }, { "name": "X-A6-Client", "in": "header", "schema": { "type": "string", "enum": [ "agent" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 4096 }, "custom_code": { "type": "string", "pattern": "^[A-Za-z0-9]{1,20}$" }, "expire_days": { "type": "integer", "minimum": 0, "maximum": 36500, "description": "0 or omitted means no expiration." }, "max_clicks": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "0 or omitted means unlimited." }, "remark": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/ShortLink" } }, "required": [ "success", "data" ] } } } }, "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/ShortLink" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Code or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "PAID_REQUIRED: inactive or expired membership; LINK_BLOCKED: financial or suspected phishing content rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "paidRequired": { "value": { "success": false, "error": { "code": "PAID_REQUIRED", "message": "仅有效付费会员可以调用。" } } }, "linkBlocked": { "value": { "success": false, "error": { "code": "LINK_BLOCKED", "message": "金融类或疑似钓鱼内容暂不支持生成短链接。" } } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "SAFETY_UNAVAILABLE: risk review unavailable, no new link created; or INTERNAL_ERROR for another temporary server failure. Retry with the same idempotency key after backoff; never skip review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "safetyUnavailable": { "value": { "success": false, "error": { "code": "SAFETY_UNAVAILABLE", "message": "链接审查暂不可用，请稍后重试。" } } } } } } }, "422": { "description": "LINK_REVIEW_REQUIRED: target page cannot be read or review is inconclusive. No new link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "LINK_REVIEW_REQUIRED", "message": "暂时无法完成链接审查，请核对目标页面后再提交。" } } } } } }, "description": "Every new API or Agent link requires DeepSeek Flash risk review, like ordinary and AI website creation. Banking, payment, lending, wealth management, stocks, foreign exchange, insurance, funds, cryptocurrency and other financial content, plus suspected phishing, are rejected. Unreadable pages or inconclusive results return LINK_REVIEW_REQUIRED without creating a link. Review outages return SAFETY_UNAVAILABLE without creating a link; never bypass review or silently switch models. Review is based on content accessible at assessment time and does not certify future destination safety. Same target URLs may create distinct short links; short codes remain unique across current and legacy records. Destination edits, standalone AI analysis and existing-link redirects also require review. A valid result can be cached up to 300 seconds; redirects without a valid allow result are blocked and do not count as successful visits. Dynamic JavaScript, region/User-Agent cloaking and content changes within cache validity limit detection. Use a request timeout of at least 45 seconds; on 503 retry with the same idempotency key using exponential backoff and jitter, not once per second. Paid risk-review limits are 60/minute and 1000/UTC day per user; cross-request cache hits count, while analysis+creation within one request share a check." }, "get": { "operationId": "listShortLinks", "summary": "List owned links", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "before_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Owned links ordered by descending ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShortLink" } }, "next_before_id": { "type": [ "integer", "null" ] } }, "required": [ "success", "data", "next_before_id" ] } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid membership required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/{short_code}": { "get": { "operationId": "getShortLink", "summary": "Get one owned short link", "parameters": [ { "name": "short_code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" } } ], "responses": { "200": { "description": "Owned link", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/ShortLink" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Not found or not owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid membership required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "getApiAccount", "summary": "Current paid status and limits", "responses": { "200": { "description": "Paid account limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "paid": { "const": true }, "premium_expiry": { "type": [ "string", "null" ], "description": "Membership expiry in local server date/time, or null for lifetime." }, "limits": { "$ref": "#/components/schemas/AccountLimits" } }, "required": [ "paid", "premium_expiry", "limits" ] } }, "required": [ "success", "data" ] } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid membership required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/{short_code}/stats": { "get": { "operationId": "getLinkStats", "summary": "Query traffic summary, country/territory, device, browser, OS, referrer and daily/hourly trends for an owned link", "description": "Paid and owned links only. Up to 90 inclusive days; hourly grouping up to 7 days. Detailed dimensions cover successfully recorded visits after detailed_tracking_since. Lifetime click count includes legacy history. Unique visitors are estimated from HMAC IP identities; bot classification is heuristic. Groups return at most the top 100 items. Raw visitor IP and User-Agent are never returned. Empty timeline periods are included as zero.", "parameters": [ { "name": "short_code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive start date in Asia/Shanghai; defaults to six days before today." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive end date in Asia/Shanghai; defaults to today. Cannot be later than today. Maximum range 90 days." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "day", "hour" ], "default": "day" }, "description": "Stats timeline grouping. hour requires a range of at most 7 days. Accepted and echoed on visits as well." } ], "responses": { "200": { "description": "Owned link traffic data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/LinkStats" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid parameters, date, range, interval or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid membership required or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Link not found or not owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/links/{short_code}/visits": { "get": { "operationId": "listLinkVisits", "summary": "List individual visit times and dimensions for an owned link", "description": "Paid and owned links only. Descending visit ID; cursor is data.next_before_id. Keep link and date range unchanged across pages. Country ZZ and empty region/city mean unavailable. No raw visitor IP or User-Agent. Detailed records only start when tracking was deployed.", "parameters": [ { "name": "short_code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,20}$" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive start date in Asia/Shanghai; defaults to six days before today." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive end date in Asia/Shanghai; defaults to today. Cannot be later than today. Maximum range 90 days." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "day", "hour" ], "default": "day" }, "description": "Stats timeline grouping. hour requires a range of at most 7 days. Accepted and echoed on visits as well." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "before_id", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807 }, "description": "Exclusive visit ID cursor from data.next_before_id; omit for the first page." } ], "responses": { "200": { "description": "Page of owned link visits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/VisitPage" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Invalid parameters, date, range, interval or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API Key missing, invalid or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Paid membership required or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Link not found or not owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }