{
  "openapi": "3.1.0",
  "info": {
    "title": "pik.li API",
    "version": "1.0.0",
    "summary": "URL shortener API: links, statistics, tags, domains, webhooks.",
    "description": "REST API of pik.li (InCloud S.r.l.). Authenticate with an API key created in the dashboard (Settings → API & keys), sent as `Authorization: Bearer pk_live_…` or `X-API-Key`. Every error uses the shape `{ \"error\": { \"code\", \"message\", \"details\" }, \"request_id\" }`; `message` is localized through `Accept-Language` (en, it, zh, ar, ru, fr, de, es, pt-BR). Authenticated responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; a 429 adds `Retry-After`. Human documentation: https://pik.li/help",
    "contact": { "name": "pik.li support", "email": "support@pik.li", "url": "https://pik.li/help" },
    "termsOfService": "https://pik.li/terms"
  },
  "servers": [ { "url": "https://pik.li/api/v1", "description": "Production" } ],
  "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ],
  "tags": [
    { "name": "service", "description": "Liveness and quotas" },
    { "name": "account", "description": "The authenticated account" },
    { "name": "links", "description": "Short links" },
    { "name": "stats", "description": "Account-level statistics" },
    { "name": "tags", "description": "Tags" },
    { "name": "domains", "description": "Domains usable by the account" },
    { "name": "webhooks", "description": "Webhooks (Premium and Business plans)" }
  ],
  "paths": {
    "/ping": {
      "get": {
        "tags": [ "service" ], "operationId": "ping", "summary": "Liveness check (no authentication)", "security": [],
        "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "type": "string" }, "version": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "docs": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" } } } } } } }
      }
    },
    "/limits": {
      "get": {
        "tags": [ "service" ], "operationId": "getLimits", "summary": "Quotas left for the account",
        "responses": { "200": { "description": "Quotas", "headers": { "$ref": "#/components/headers/RateLimitHeaders" }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Limits" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/me": {
      "get": {
        "tags": [ "account" ], "operationId": "getMe", "summary": "Profile, plan, limits, usage and the key in use",
        "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/links": {
      "get": {
        "tags": [ "links" ], "operationId": "listLinks", "summary": "List and search links",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search in slug, title and destination" },
          { "name": "tag", "in": "query", "schema": { "type": "string" } },
          { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated; every tag must be present" },
          { "name": "domain", "in": "query", "schema": { "type": "string" }, "description": "Hostname from /domains" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "disabled", "review", "expired" ] } },
          { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "all", "active_24h", "created_today", "expiring", "moderated", "review", "disabled", "expired", "protected" ] } },
          { "name": "within_days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 7 }, "description": "With view=expiring" },
          { "name": "created_after", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 date or date-time" },
          { "name": "created_before", "in": "query", "schema": { "type": "string" } },
          { "name": "clicked_after", "in": "query", "schema": { "type": "string" }, "description": "Last human click at or after" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "recent", "oldest", "clicks", "alpha", "expiring", "last_clicked" ], "default": "recent" } },
          { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }
        ],
        "responses": { "200": { "description": "Links", "headers": { "X-Total-Count": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      },
      "post": {
        "tags": [ "links" ], "operationId": "createLink", "summary": "Create a link",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkInput" } } } },
        "responses": { "201": { "description": "Created", "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "\"true\" when the response is a replay" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/links/bulk": {
      "post": {
        "tags": [ "links" ], "operationId": "bulkCreateLinks", "summary": "Create up to 10 links per call (100 with the bulk feature)",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/LinkInput" } } } } } } },
        "responses": { "200": { "description": "Per-row result (non-transactional)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/links/generate": {
      "post": {
        "tags": [ "links" ], "operationId": "generateLinks", "summary": "Create `count` links to one destination, all or nothing, as one batch (feature bulk_generate)",
        "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination", "count" ], "properties": { "destination": { "type": "string", "description": "`url` is accepted as a synonym" }, "count": { "type": "integer", "minimum": 2, "description": "The maximum per call is set by pik.li (500 by default); above it the answer is invalid_parameter with details.max" }, "domain": { "type": "string" }, "title_prefix": { "type": "string", "description": "Titles become \"<prefix> 001\", \"<prefix> 002\"…" }, "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Needs the expiry feature" } } } } } },
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string" }, "destination": { "type": "string" }, "created": { "type": "integer" }, "quota_remaining": { "type": [ "integer", "null" ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/links/count": {
      "get": {
        "tags": [ "links" ], "operationId": "countLinks", "summary": "Counters of the account",
        "responses": { "200": { "description": "Counters", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "review": { "type": "integer" }, "disabled": { "type": "integer" }, "moderated": { "type": "integer" }, "expired": { "type": "integer" }, "protected": { "type": "integer" }, "created_today": { "type": "integer" }, "active_24h": { "type": "integer" }, "expiring_7d": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/links/active": {
      "get": {
        "tags": [ "links" ], "operationId": "activeLinks", "summary": "Links clicked in the last N hours",
        "parameters": [ { "name": "hours", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ],
        "responses": { "200": { "description": "Links with clicks in the window, most clicked first", "content": { "application/json": { "schema": { "type": "object", "properties": { "hours": { "type": "integer" }, "since": { "type": "string", "format": "date-time" }, "total_clicks": { "type": "integer" }, "links": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "object", "properties": { "clicks_in_window": { "type": "integer" }, "uniques_in_window": { "type": "integer" } } } ] } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }
      }
    },
    "/links/lookup": {
      "get": {
        "tags": [ "links" ], "operationId": "lookupLink", "summary": "Resolve a short URL (or domain + slug) to a link",
        "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string", "format": "uri" } }, { "name": "domain", "in": "query", "schema": { "type": "string" } }, { "name": "slug", "in": "query", "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/links/{id}": {
      "parameters": [ { "$ref": "#/components/parameters/LinkId" } ],
      "get": { "tags": [ "links" ], "operationId": "getLink", "summary": "Link details", "responses": { "200": { "description": "Link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "patch": {
        "tags": [ "links" ], "operationId": "updateLink", "summary": "Update a link",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkUpdate" } } } },
        "responses": { "200": { "description": "Updated link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } }
      },
      "delete": { "tags": [ "links" ], "operationId": "deleteLink", "summary": "Delete a link", "responses": { "204": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/links/{id}/disable": {
      "post": { "tags": [ "links" ], "operationId": "disableLink", "summary": "Pause a link", "parameters": [ { "$ref": "#/components/parameters/LinkId" } ], "responses": { "200": { "description": "Link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/links/{id}/enable": {
      "post": { "tags": [ "links" ], "operationId": "enableLink", "summary": "Re-enable a paused link", "parameters": [ { "$ref": "#/components/parameters/LinkId" } ], "responses": { "200": { "description": "Link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Disabled by moderation (link_blocked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }
    },
    "/links/{id}/stats": {
      "get": {
        "tags": [ "links" ], "operationId": "linkStats", "summary": "Statistics of one link",
        "parameters": [ { "$ref": "#/components/parameters/LinkId" }, { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/Interval" } ],
        "responses": { "200": { "description": "Statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkStats" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/links/{id}/clicks": {
      "get": {
        "tags": [ "links" ], "operationId": "linkClicks", "summary": "Click events of one link (newest first)",
        "parameters": [ { "$ref": "#/components/parameters/LinkId" }, { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "name": "bots", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Include bot traffic" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ],
        "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "clicks": { "type": "array", "items": { "$ref": "#/components/schemas/ClickEvent" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/links/{id}/qr.{format}": {
      "get": {
        "tags": [ "links" ], "operationId": "linkQr", "summary": "QR code of the short URL",
        "parameters": [ { "$ref": "#/components/parameters/LinkId" }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "svg", "png" ] } }, { "name": "size", "in": "query", "schema": { "type": "integer" }, "description": "PNG 128–2048 (default 512), SVG 64–1024 (default 240)" } ],
        "responses": { "200": { "description": "Image", "content": { "image/svg+xml": { "schema": { "type": "string" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/stats": {
      "get": {
        "tags": [ "stats" ], "operationId": "accountStats", "summary": "Account overview: totals, window vs previous, series, breakdowns, top links",
        "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/Interval" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" } ],
        "responses": { "200": { "description": "Overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountStats" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/Unprocessable" } }
      }
    },
    "/stats/timeseries": {
      "get": { "tags": [ "stats" ], "operationId": "statsTimeseries", "summary": "Clicks and uniques per hour or day", "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/Interval" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" } ],
        "responses": { "200": { "description": "Series", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "filters": { "type": "object" }, "interval": { "type": "string", "enum": [ "hour", "day" ] }, "clicks": { "type": "integer" }, "previous_clicks": { "type": "integer" }, "delta_pct": { "type": [ "number", "null" ] }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesPoint" } } } } } } } } }
    },
    "/stats/referrers": {
      "get": { "tags": [ "stats" ], "operationId": "statsReferrers", "summary": "Top referrer hosts and direct traffic", "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" }, { "$ref": "#/components/parameters/TopLimit" } ],
        "responses": { "200": { "description": "Referrers", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "clicks": { "type": "integer" }, "direct": { "type": "integer" }, "referrers": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } } } } } } } } }
    },
    "/stats/countries": {
      "get": { "tags": [ "stats" ], "operationId": "statsCountries", "summary": "Top countries (cities with Premium)", "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" }, { "$ref": "#/components/parameters/TopLimit" } ],
        "responses": { "200": { "description": "Countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "clicks": { "type": "integer" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "cities": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } } } } } } } } }
    },
    "/stats/devices": {
      "get": { "tags": [ "stats" ], "operationId": "statsDevices", "summary": "Devices, browsers, OS and languages", "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" }, { "$ref": "#/components/parameters/TopLimit" } ],
        "responses": { "200": { "description": "Breakdowns", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "clicks": { "type": "integer" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "browsers": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "os": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } } } } } } } } }
    },
    "/stats/top": {
      "get": { "tags": [ "stats" ], "operationId": "statsTop", "summary": "Most clicked links of the window", "parameters": [ { "$ref": "#/components/parameters/Period" }, { "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }, { "$ref": "#/components/parameters/StatsDomain" }, { "$ref": "#/components/parameters/StatsTag" }, { "$ref": "#/components/parameters/Bots" }, { "$ref": "#/components/parameters/TopLimit" } ],
        "responses": { "200": { "description": "Top links", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "$ref": "#/components/schemas/Window" }, "clicks": { "type": "integer" }, "links": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Link" }, { "type": "object", "properties": { "clicks_in_window": { "type": "integer" }, "uniques_in_window": { "type": "integer" } } } ] } } } } } } } } }
    },
    "/tags": {
      "get": { "tags": [ "tags" ], "operationId": "listTags", "summary": "Tags with the number of links and clicks", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "links": { "type": "integer" }, "clicks": { "type": "integer" } } } }, "total": { "type": "integer" } } } } } } } }
    },
    "/domains": {
      "get": { "tags": [ "domains" ], "operationId": "listDomains", "summary": "Domains usable by the account",
        "responses": { "200": { "description": "Domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "default": { "type": [ "string", "null" ] }, "custom_domains": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } } } }
    },
    "/webhooks": {
      "get": { "tags": [ "webhooks" ], "operationId": "listWebhooks", "summary": "Webhooks of the account", "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } },
      "post": { "tags": [ "webhooks" ], "operationId": "createWebhook", "summary": "Create a webhook (secret returned once)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } },
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "$ref": "#/components/responses/Unprocessable" } } }
    },
    "/webhooks/{id}": {
      "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ],
      "get": { "tags": [ "webhooks" ], "operationId": "getWebhook", "summary": "Webhook with its last 20 deliveries", "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "patch": { "tags": [ "webhooks" ], "operationId": "updateWebhook", "summary": "Update url, events or active", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } },
      "delete": { "tags": [ "webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook", "responses": { "204": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/webhooks/{id}/test": {
      "post": { "tags": [ "webhooks" ], "operationId": "testWebhook", "summary": "Queue a ping delivery", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "event": { "type": "string" }, "webhook_id": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer pk_live_…" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "headers": {
      "RateLimitHeaders": { "description": "X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix time)", "schema": { "type": "string" } }
    },
    "parameters": {
      "LinkId": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
      "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
      "PerPage": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "`limit` is accepted as an alias" },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 128 }, "description": "Same key within 24 h replays the first response (Idempotent-Replayed: true)" },
      "Period": { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "1y", "all" ] }, "description": "Ignored when from/to are given. Clamped to the plan retention." },
      "From": { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 date or date-time" },
      "To": { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "ISO 8601 date or date-time (default now)" },
      "Interval": { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day" ] }, "description": "Default: hour up to 48 h, otherwise day; hour allowed up to 7 days" },
      "StatsDomain": { "name": "domain", "in": "query", "schema": { "type": "string" }, "description": "Hostname from /domains" },
      "StatsTag": { "name": "tag", "in": "query", "schema": { "type": "string" } },
      "Bots": { "name": "bots", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Include bot traffic" },
      "TopLimit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
    },
    "responses": {
      "BadRequest": { "description": "bad_request, invalid_json, invalid_parameter, bulk_empty, bulk_too_many, idempotency_key_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "PaymentRequired": { "description": "feature_required, quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "api_disabled, email_unconfirmed, account_blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unprocessable": { "description": "invalid (details.fields, details.messages), domain_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "rate_limited; Retry-After header", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object", "required": [ "error", "request_id" ],
        "properties": {
          "error": { "type": "object", "required": [ "code", "message" ], "properties": {
            "code": { "type": "string", "enum": [ "unauthorized", "account_blocked", "email_unconfirmed", "api_disabled", "forbidden", "feature_required", "quota_exceeded", "not_found", "link_blocked", "conflict", "invalid", "domain_not_allowed", "bad_request", "invalid_json", "invalid_parameter", "bulk_empty", "bulk_too_many", "idempotency_key_invalid", "rate_limited" ] },
            "message": { "type": "string", "description": "Localized (Accept-Language)" },
            "details": { "type": "object", "additionalProperties": true },
            "docs_url": { "type": "string", "format": "uri", "description": "The explanation of this code on the documentation page, in the language of the message" } } },
          "request_id": { "type": "string" }
        }
      },
      "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "type": [ "integer", "null" ] }, "prev_page": { "type": [ "integer", "null" ] } } },
      "Link": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "short_url": { "type": "string", "format": "uri" }, "slug": { "type": "string" }, "domain": { "type": "string" },
          "target_url": { "type": "string", "format": "uri" }, "target_host": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] },
          "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled", "expired", "deleted" ] },
          "moderation": { "type": "string", "enum": [ "pending", "allowed", "review", "disabled" ] }, "active": { "type": "boolean", "description": "Redirects right now" }, "expired": { "type": "boolean" },
          "password_protected": { "type": "boolean" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "last_clicked_at": { "type": [ "string", "null" ], "format": "date-time" },
          "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_clicks": { "type": [ "integer", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] },
          "utm": { "type": [ "object", "null" ], "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } } },
          "preview_url": { "type": "string", "format": "uri" }, "qr_url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "LinkInput": {
        "type": "object", "required": [ "url" ],
        "properties": {
          "url": { "type": "string", "format": "uri", "description": "Destination (http/https). `target_url` is accepted as an alias" }, "title": { "type": "string", "maxLength": 160 }, "description": { "type": "string" },
          "tags": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "description": "Comma-separated" } ] }, "domain": { "type": "string", "description": "Hostname from /domains (default: the account default)" },
          "slug": { "type": "string", "description": "Premium+" }, "password": { "type": "string", "description": "Premium+" }, "expires_at": { "type": "string", "format": "date-time", "description": "Premium+" }, "max_clicks": { "type": "integer", "description": "Premium+" },
          "utm_source": { "type": "string", "description": "Premium+" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_term": { "type": "string" }, "utm_content": { "type": "string" }
        }
      },
      "LinkUpdate": { "allOf": [ { "$ref": "#/components/schemas/LinkInput" } ], "required": [] },
      "BulkResult": {
        "type": "object",
        "properties": {
          "created": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } },
          "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "url": { "type": [ "string", "null" ] }, "error": { "$ref": "#/components/schemas/Error/properties/error" } } } },
          "summary": { "type": "object", "properties": { "requested": { "type": "integer" }, "created": { "type": "integer" }, "failed": { "type": "integer" }, "quota_remaining": { "type": "integer" }, "max_items": { "type": "integer" } } }
        }
      },
      "Window": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "days": { "type": "integer" }, "interval": { "type": "string" }, "period": { "type": "string" }, "clamped": { "type": "boolean" }, "retention_days": { "type": "integer" }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } } } },
      "SeriesPoint": { "type": "object", "properties": { "at": { "type": "string", "description": "Date (day) or date-time (hour)" }, "clicks": { "type": "integer" }, "uniques": { "type": "integer" } } },
      "BreakdownRow": { "type": "object", "description": "One key (referrer, country, city, device, browser, os, language) plus clicks and share (%)", "properties": { "clicks": { "type": "integer" }, "share": { "type": "number" } }, "additionalProperties": { "type": "string" } },
      "PeriodStats": { "type": "object", "properties": { "clicks": { "type": "integer" }, "uniques": { "type": "integer" }, "links_clicked": { "type": "integer" }, "clicks_per_link": { "type": "number" } } },
      "LinkStats": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "short_url": { "type": "string" }, "clicks": { "type": "integer", "description": "All-time" }, "unique": { "type": "integer" }, "period_days": { "type": "integer" }, "period_clicks": { "type": "integer" },
          "window": { "$ref": "#/components/schemas/Window" },
          "period": { "type": "object", "properties": { "clicks": { "type": "integer" }, "uniques": { "type": "integer" }, "bots": { "type": "integer" } } },
          "previous": { "type": "object", "properties": { "clicks": { "type": "integer" }, "uniques": { "type": "integer" }, "delta_pct": { "type": [ "number", "null" ] } } },
          "series": { "type": "array", "description": "Legacy [at, clicks] pairs", "items": { "type": "array" } },
          "timeseries": { "type": "object", "properties": { "interval": { "type": "string" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesPoint" } } } },
          "countries": { "type": "object", "additionalProperties": { "type": "integer" } }, "devices": { "type": "object", "additionalProperties": { "type": "integer" } }, "browsers": { "type": "object", "additionalProperties": { "type": "integer" } },
          "os": { "type": "object", "additionalProperties": { "type": "integer" } }, "languages": { "type": "object", "additionalProperties": { "type": "integer" } }, "referrers": { "type": "object", "additionalProperties": { "type": "integer" } },
          "cities": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Premium+" }, "hourly": { "type": "object", "additionalProperties": { "type": "integer" } }
        }
      },
      "AccountStats": {
        "type": "object",
        "properties": {
          "window": { "$ref": "#/components/schemas/Window" }, "filters": { "type": "object" },
          "totals": { "type": "object", "properties": { "links": { "type": "integer" }, "active_links": { "type": "integer" }, "clicks": { "type": "integer" }, "unique_clicks": { "type": "integer" }, "clicks_today": { "type": "integer" }, "links_active_24h": { "type": "integer" }, "links_created_in_window": { "type": "integer" } } },
          "period": { "$ref": "#/components/schemas/PeriodStats" },
          "previous": { "allOf": [ { "$ref": "#/components/schemas/PeriodStats" }, { "type": "object", "properties": { "delta_pct": { "type": [ "number", "null" ] }, "uniques_delta_pct": { "type": [ "number", "null" ] } } } ] },
          "timeseries": { "type": "object", "properties": { "interval": { "type": "string" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesPoint" } } } },
          "referrers": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "direct": { "type": "integer" },
          "countries": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } },
          "browsers": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "os": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } },
          "top_links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }
        }
      },
      "ClickEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "occurred_at": { "type": "string", "format": "date-time" }, "ip": { "type": "string", "description": "Visitor's IP address with the host part hidden: the first three octets of an IPv4 (151.78.52.•••), the first three groups of an IPv6 (2a01:4f8:c0c::•••). Omitted for clicks recorded before the address was kept." }, "country": { "type": [ "string", "null" ] }, "region": { "type": "string", "description": "Premium+" }, "city": { "type": "string", "description": "Premium+" }, "device": { "type": [ "string", "null" ] }, "browser": { "type": [ "string", "null" ] }, "os": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "referrer_host": { "type": [ "string", "null" ] }, "referrer": { "type": "string", "description": "Premium+" }, "bot": { "type": "boolean" }, "unique": { "type": "boolean" } } },
      "Domain": { "type": "object", "properties": { "id": { "type": "integer" }, "hostname": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "kind": { "type": "string", "enum": [ "system", "custom" ] }, "min_plan": { "type": "string", "enum": [ "free", "premium", "business" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "default": { "type": "boolean" } } },
      "Me": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" }, "username": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "confirmed": { "type": "boolean" }, "locale": { "type": "string" },
          "plan": { "type": "string" }, "plan_name": { "type": "string" }, "interval": { "type": "string" }, "plan_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "api_enabled": { "type": "boolean" },
          "features": { "type": "array", "items": { "type": "string" } },
          "limits": { "type": "object", "properties": { "links_per_day": { "type": "integer" }, "links_per_month": { "type": "integer" }, "clicks_per_month": { "type": "integer" }, "retention_days": { "type": "integer" }, "link_ttl_days": { "type": "integer" }, "custom_domains": { "type": "integer" }, "api_rpm": { "type": "integer" } } },
          "usage": { "type": "object", "properties": { "links_today": { "type": "integer" }, "links_this_month": { "type": "integer" }, "clicks_this_month": { "type": "integer" }, "links_quota_used": { "type": "integer" }, "links_quota_limit": { "type": "integer" }, "links_total": { "type": "integer" } } },
          "api_key": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "requests_count": { "type": "integer" } } },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Limits": {
        "type": "object",
        "properties": {
          "plan": { "type": "string" }, "plan_name": { "type": "string" },
          "links": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "day", "month" ] }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" }, "today": { "type": "integer" }, "this_month": { "type": "integer" }, "per_day": { "type": "integer" }, "per_month": { "type": "integer" } } },
          "clicks": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } } },
          "rate_limit": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "period_seconds": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" } } },
          "api_keys": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } },
          "custom_domains": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } },
          "bulk": { "type": "object", "properties": { "max_items": { "type": "integer" } } },
          "retention_days": { "type": "integer" }, "link_ttl_days": { "type": "integer" }, "features": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "link.created", "link.clicked", "link.disabled", "link.deleted" ] } }, "active": { "type": "boolean" }, "failures_count": { "type": "integer" }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signature_header": { "type": "string", "const": "X-Pikli-Signature" }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "event": { "type": "string" }, "response_code": { "type": [ "integer", "null" ] }, "attempts": { "type": "integer" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } },
      "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "description": "Comma-separated" } ] }, "active": { "type": "boolean" } } }
    }
  }
}